When building AI agents or complex workflows, your application often makes multiple LLM calls, vector database queries, and tool calls to complete a single task. Sessions group these related requests together, letting you trace the entire agent flow from initial user input to final response in one unified view.

​
Why use Sessions

  • Debug AI agent flows: See the entire agent workflow in one view, from initial request to final response
  • Track multi-step conversations: Reconstruct the complete flow of chatbot interactions and complex tasks
  • Analyze performance: Measure outcomes across entire interaction sequences, not just individual requests
Helicone example of a session template for monitoring and managing inputs from requests sent to your AI applications.

Example: A Session creating an outline for a book about space

​
Quick Start

1

Add Session Headers

Include three required headers in your LLM requests:
{
  "Helicone-Session-Id": "unique-session-id",
  "Helicone-Session-Path": "/trace-path", 
  "Helicone-Session-Name": "Session Name"
}
2

Structure Your Paths

Use path syntax to represent parent-child relationships:
"/abstract"                    // Top-level trace
"/abstract/outline"           // Child trace
"/abstract/outline/lesson-1"  // Grandchild trace
3

Make Your Request

Execute your LLM request with the session headers included:
const response = await openai.chat.completions.create(
  { messages: [{ role: "user", content: "Hello" }], model: "gpt-4o-mini" },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/greeting",
      "Helicone-Session-Name": "User Conversation"
    }
  }
);

​
Configuration Options

​
Required Headers

HeaderTypeDescriptionDefaultExample
Helicone-Session-IdstringUnique identifier for the session (recommend UUID)N/A"550e8400-e29b-41d4-a716-446655440000"
Helicone-Session-PathstringPath representing the trace hierarchy using / syntaxN/A"/abstract" or "/parent/child"
Helicone-Session-NamestringHuman-readable name for the sessionN/A"Course Plan"

​
Use Cases

Track a complete code generation workflow with clarifications and refinements:
import { randomUUID } from "crypto";
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://oai.helicone.ai/v1",
  defaultHeaders: {
    "Helicone-Auth": `Bearer ${process.env.HELICONE_API_KEY}`,
  },
});

const sessionId = randomUUID();

// Initial feature request
const response1 = await openai.chat.completions.create(
  {
    messages: [{ role: "user", content: "Create a React component for user authentication with email and password" }],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/request",
      "Helicone-Session-Name": "Code Generation Assistant",
    },
  }
);

// User asks for clarification
const response2 = await openai.chat.completions.create(
  {
    messages: [
      { role: "user", content: "Create a React component for user authentication with email and password" },
      { role: "assistant", content: response1.choices[0].message.content },
      { role: "user", content: "Can you add form validation and error handling?" }
    ],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/request/validation",
      "Helicone-Session-Name": "Code Generation Assistant",
    },
  }
);

// User requests TypeScript version
const response3 = await openai.chat.completions.create(
  {
    messages: [
      { role: "user", content: "Convert this to TypeScript with proper interfaces" }
    ],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/request/validation/typescript",
      "Helicone-Session-Name": "Code Generation Assistant",
    },
  }
);

Complete Session Example

Full JavaScript implementation showing session hierarchy and tracking

​
Understanding Sessions

​
What Sessions Can Track

Sessions can group together all types of requests in your AI workflow:
  • LLM calls - OpenAI, Anthropic, and other model requests
  • Vector database queries - Embeddings, similarity searches, and retrievals
  • Tool calls - Function executions, API calls, and custom tools
  • Any logged request - Anything sent through Helicone’s logging
This gives you a complete view of your AI agent’s behavior, not just the LLM interactions.

​
Session IDs

The session ID is a unique identifier that groups all related requests together. Think of it as a conversation thread ID. What to use:
  • UUIDs (recommended): 550e8400-e29b-41d4-a716-446655440000
  • Unique strings: user_123_conversation_456
Why it matters:
  • Same ID = requests get grouped together in the dashboard
  • Different IDs = separate sessions, even if they’re related
  • Reusing IDs across different workflows will mix unrelated requests
// ✅ Good - unique per conversation
const sessionId = randomUUID(); // Different for each user conversation

// ❌ Bad - reuses same ID
const sessionId = "chat_session"; // All users get mixed together

​
Session Paths

Paths create the hierarchy within your session, showing how requests relate to each other. Path Structure Rules:
  • Start with / (forward slash)
  • Use / to separate levels: /parent/child/grandchild
  • Keep names descriptive: /analyze_request/fetch_data/process_results
How Hierarchy Works: 
"/conversation"                    // Root level
"/conversation/initial_question"   // Child of conversation  
"/conversation/followup"          // Another child of conversation
"/conversation/followup/clarify"  // Child of followup
This creates a tree structure in the dashboard where you can see the flow from initial question → followup → clarification. Path Design Patterns: 
// Workflow pattern - good for AI agents
"/task"
"/task/research" 
"/task/research/web_search"
"/task/generate"

// Conversation pattern - good for chatbots
"/session"
"/session/question_1"
"/session/answer_1" 
"/session/question_2"

// Pipeline pattern - good for data processing
"/process"
"/process/extract"
"/process/transform"
"/process/load"

​
Session Names

The session name is used to group related sessions together in the dashboard. Use the same name for sessions that are part of the same flow or workflow type. Good session names:
  • "Customer Support" - All support sessions use this name
  • "Content Generation" - All content creation sessions use this name
  • "Trip Planning Agent" - All trip planning workflows use this name
Why this matters:
  • Sessions with the same name get grouped together in the dashboard
  • You can filter to see all sessions of a specific type
  • Makes it easy to compare performance across similar workflows

Vector Database Logging

Track vector database queries and embeddings alongside LLM calls

Tool Call Logging

Monitor tool calls and function executions within your agent workflows

Custom Properties

Add metadata to individual requests within sessions

User Metrics

Track user behavior patterns across multiple sessions