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 client.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"
    }
  }
);

​
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 Naming Philosophy: Think of session paths as conceptual groupings rather than chronological order. Requests with the same path represent the same “type” of work, even if they happen at different times. Example: In a code review agent, all “security check” requests get the same path (/review/security) whether they happen early or late in the analysis. This lets you see patterns in the duration distribution chart - all security checks will be colored the same, showing you when they typically occur and how long they take. Path Structure Rules:
  • Start with / (forward slash)
  • Use / to separate levels: /parent/child/grandchild
  • Keep names descriptive: /analyze_request/fetch_data/process_results
  • Group by function, not by time - same conceptual work = same path
How Hierarchy Works: 
"/conversation"                    // Root level
"/conversation/initial_question"   // Child of conversation  
"/conversation/followup"          // Another child of conversation
"/conversation/followup/clarify"  // Child of followup
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 a high-level grouping that makes it easy to filter and organize similar types of sessions in the dashboard. 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
Purpose:
  • Quick filtering - Filter dashboard to show only “Customer Support” sessions
  • High-level organization - Group alike sessions for easy comparison
  • Performance analysis - Compare metrics across the same session type

​
Configuration Reference

​
Required Headers

​
Helicone-Session-Id
string
required
Unique identifier for the session. Use UUIDs to avoid conflicts.Example: "550e8400-e29b-41d4-a716-446655440000"
​
Helicone-Session-Path
string
required
Path representing the trace hierarchy using / syntax. Shows parent-child relationships.Example: "/abstract" or "/parent/child"
​
Helicone-Session-Name
string
required
Human-readable name for the session type. Groups similar workflows together.Example: "Course Plan" or "Customer Support"

​
Common Patterns

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

const client = new OpenAI({
  baseURL: "https://ai-gateway.helicone.ai",
  apiKey: process.env.HELICONE_API_KEY,
});

const sessionId = randomUUID();

// Initial feature request
const response1 = await client.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 client.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 client.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

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