Sessions

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

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"
}

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

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

Code Generation Assistant
Pull Request Review
API Documentation Generator

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

import uuid
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://ai-gateway.helicone.ai",
    api_key=os.environ.get("HELICONE_API_KEY"),
)

session_id = str(uuid.uuid4())

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

# User asks for clarification
response2 = client.chat.completions.create(
    model="gpt-4o-mini",
    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?"}
    ],
    extra_headers={
        "Helicone-Session-Id": session_id,
        "Helicone-Session-Path": "/request/validation",
        "Helicone-Session-Name": "Code Generation Assistant",
    }
)

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

Track an automated PR review workflow with multiple analysis steps:

const sessionId = randomUUID();

// Initial PR analysis
const analysis = await client.chat.completions.create(
  { 
    messages: [{ role: "user", content: "Analyze this pull request for code quality and potential issues: [PR diff content]" }],
    model: "gpt-4o-mini" 
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/analysis",
      "Helicone-Session-Name": "PR Review Bot",
    },
  }
);

// Security check
const securityCheck = await client.chat.completions.create(
  { 
    messages: [{ role: "user", content: "Check for security vulnerabilities: SQL injection, XSS, authentication issues" }],
    model: "gpt-4o-mini" 
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/analysis/security",
      "Helicone-Session-Name": "PR Review Bot",
    },
  }
);

// Generate review comments
const reviewComments = await client.chat.completions.create(
  { 
    messages: [{ role: "user", content: "Generate constructive review comments based on analysis" }],
    model: "gpt-4o-mini" 
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/analysis/security/comments",
      "Helicone-Session-Name": "PR Review Bot",
    },
  }
);

Track a multi-step API documentation generation workflow:

const sessionId = randomUUID();

// Analyze API endpoints
const endpoints = await client.chat.completions.create(
  {
    messages: [{ role: "user", content: "Analyze these API routes and extract endpoint information: [code content]" }],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/analyze",
      "Helicone-Session-Name": "API Documentation Generator",
    },
  }
);

// Generate OpenAPI spec
const openApiSpec = await client.chat.completions.create(
  {
    messages: [
      { role: "user", content: "Generate OpenAPI 3.0 specification based on these endpoints" }
    ],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/analyze/openapi",
      "Helicone-Session-Name": "API Documentation Generator",
    },
  }
);

// Create usage examples
const examples = await client.chat.completions.create(
  {
    messages: [{ role: "user", content: "Create code examples for each endpoint in multiple languages" }],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/analyze/openapi/examples",
      "Helicone-Session-Name": "API Documentation Generator",
    },
  }
);

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

Need more help?

Additional questions or feedback? Reach out to help@helicone.ai or schedule a call with us.

Getting Started

AI Gateway

Observability & Analytics

Prompt Management

Legacy Integrations

References

Why use Sessions

Quick Start

Understanding Sessions

What Sessions Can Track

Session IDs

Session Paths

Session Names

Configuration Reference

Required Headers

Common Patterns

Complete Session Example

Vector Database Logging

Tool Call Logging

Custom Properties

User Metrics

​Why use Sessions

​Quick Start

​Understanding Sessions

​What Sessions Can Track

​Session IDs

​Session Paths

​Session Names

​Configuration Reference

​Required Headers

​Common Patterns

Complete Session Example

​Related Features

Vector Database Logging

Tool Call Logging

Custom Properties

User Metrics

Why use Sessions

Quick Start

Understanding Sessions

What Sessions Can Track

Session IDs

Session Paths

Session Names

Configuration Reference

Required Headers

Common Patterns

Related Features