Sessions

Sessions provide a way to group related traces together, making it easier to monitor and debug complex workflows in your LLM applications. By organizing traces into sessions, you can track the entire lifecycle of a user interaction or a multi-step process.

​

Understanding Sessions

A session represents a logical grouping of related traces. A common example is a conversation with a particular user, where each response can be associated with a single trace.

Sessions help you maintain context across multiple traces, making it easier to understand the full picture of your application’s behavior.

​

Creating Sessions

To create a session, include the session information in your telemetry metadata:

import { Puzzlet } from "@puzzlet/sdk";
import { createTemplateRunner } from "@puzzlet/agentmark";

const puzzletClient = new Puzzlet({
  apiKey: process.env.PUZZLET_API_KEY!,
  appId: process.env.PUZZLET_APP_ID!
}, createTemplateRunner);

const tracer = puzzletClient.initTracing();

// Create a unique session ID
const sessionId = 'session-' + Date.now();
const sessionName = 'User Conversation #123';

async function runPrompt() {
  const prompt = await puzzletClient.fetchPrompt("my-prompt.prompt.mdx");
  const props = { someExampleProp: 'someExampleValue' };
  
  // Include session information in telemetry metadata
  const telemetry = {
    isEnabled: true,
    functionId: 'example-function-id',
    metadata: { 
      userId: 'example-user-id', 
      sessionId: sessionId,
      sessionName: sessionName
    }
  };
  
  return await prompt.run(props, { telemetry });
}

// Run multiple prompts in the same session
await runPrompt();
await runPrompt();

// Shutdown tracer when done
await tracer.shutdown();

​

Best Practices

1. Use Consistent Session IDs: Ensure all related traces use the same session ID
2. Provide Descriptive Names: Give sessions meaningful names for easy identification
3. Include Context: Add relevant metadata to help with debugging
4. Limit Session Scope: Keep sessions focused on specific workflows or user interactions
5. Clean Up: For long-running applications, create new sessions periodically rather than having endless sessions