Tracking Long Running Agent Conversations

Related concepts: People, Sessions If you have long running agents in production, i.e. an agent that handles many conversation turns with a single user, you’ve probably experienced issues keeping track of quality, simply because there are so many messages to follow. This cookbook walks you through tracking long running agents in Voker, so you can get the insights you need to optimize your agent without reading through every message.

What you’ll build

Attribute every session to a specific person, so you can get insights into how each user behaves across all their sessions
An interactive Session Timeline that provides an overview of paths within a long running session, allowing you to investigate parts of a conversation without reading every turn

Jump to results

Pre-requisites

An existing agent implementation (Python 3.10+ or Node.js 20+)
Voker API key (get one here)

Implementation

Python
TypeScript

Step 1: Project setup

Install the Voker SDK for Python and add your API key.

pip install voker

uv add voker

poetry add voker

Add your Voker API key to your .env file.

VOKER_API_KEY=your_voker_api_key_here

To obtain your Voker API key, sign up for a free Voker account here. You will be taken to the setup page where you can copy the value.

Screenshot of the Voker API key setup page — Navigate to the Voker dashboard to find your API key

Step 2: Set Voker parameters in LLM calls

In your project, swap the import for your LLM provider and add these parameters to your LLM calls:

voker_session, groups events into the same session
voker_agent, identifies the agent making the event
voker_agent_version, sets an initial agent version
voker_person, attributes the event to a specific person.

When you provide a person ID on an event, Voker attaches the event to that person. If the person already exists, the event is added to them instead of creating a duplicate person.

OpenAI
Anthropic
Gemini

from openai import OpenAI  
from voker.ai.provider_openai import OpenAI  

client = OpenAI()

client.chat.completions.create(
    voker_session="test-session-1",          
    voker_agent="my-agent",                  
    voker_agent_version="v1.0",              
    voker_person="person-1",                 
    model="gpt-4.1-mini",
    messages=[
        {
            "role": "system",
            "content": "... your current system prompt here ...",
        }
    ],
)

from anthropic import Anthropic  
from voker.ai.provider_anthropic import Anthropic  

client = Anthropic()

client.messages.create(
    voker_session="test-session-1",          
    voker_agent="my-agent",                  
    voker_agent_version="v1.0",              
    voker_person="person-1",                 
    model="claude-haiku-4-5",
    messages=[
        {
            "role": "user",
            "content": "... your current system prompt here ...",
        }
    ],
    max_tokens=1024,
)

from google.genai import Client  
from voker.ai.provider_gemini import Client  

client = Client()

client.models.generate_content(
    voker_session="test-session-1",          
    voker_agent="my-agent",                  
    voker_agent_version="v1.0",              
    voker_person="person-1",                 
    model="gemini-2.5-flash",
    contents="... your current system prompt ...",
)

Step 3: Make an LLM call and view in dashboard

Make an LLM call with the new parameters. Then go back to Voker, reload the page, and navigate to the People tab.Locate your person by typing their unique Person ID into the search bar, or find them in the list by their Person ID.

Screenshot of the People tab on the Voker platform — Navigate to 'People' in the sidebar

Click on the person to view their details page, where you can see their session history along with aggregate data across those sessions.

Screenshot of the Person details page on the Voker platform — Click a person to open their details page and view their session history

Step 1: Project setup

Install the Voker SDK for TypeScript and add your API key.

npm install @voker/voker

pnpm add @voker/voker

bun add @voker/voker

yarn add @voker/voker

Add your Voker API key to your .env file.

VOKER_API_KEY=your_voker_api_key_here

To obtain your Voker API key, sign up for a free Voker account here. You will be taken to the setup page where you can copy the value.

Step 2: Set Voker parameters in LLM calls

In your project, swap the import for your LLM provider and add these parameters to your LLM calls:

vokerSession, groups events into the same session
vokerAgent, identifies the agent making the event
vokerAgentVersion, sets an initial agent version
vokerPerson, attributes the event to a specific person.

When you provide a person ID on an event, Voker attaches the event to that person. If the person already exists, the event is added to them instead of creating a duplicate person.

OpenAI
Anthropic
Gemini

import { OpenAI } from 'openai'; 
import { OpenAI } from '@voker/voker/ai/provider-openai'; 

const client = new OpenAI();

await client.chat.completions.create({
    vokerSession: 'test-session-1',      
    vokerAgent: 'my-agent',              
    vokerAgentVersion: 'v1.0',           
    vokerPerson: 'person-1',             
    model: 'gpt-4.1-mini',
    messages: [
        {
            role: 'system',
            content: '... your current system prompt here ...',
        },
    ],
});

import Anthropic from '@anthropic-ai/sdk'; 
import { Anthropic } from '@voker/voker/ai/provider-anthropic'; 

const client = new Anthropic();

await client.messages.create({
    vokerSession: 'test-session-1',      
    vokerAgent: 'my-agent',              
    vokerAgentVersion: 'v1.0',           
    vokerPerson: 'person-1',             
    model: 'claude-haiku-4-5',
    messages: [
        {
            role: 'user',
            content: '... your current system prompt here ...',
        },
    ],
    max_tokens: 1024,
});

import { GoogleGenAI } from '@google/genai'; 
import { GoogleGenAI } from '@voker/voker/ai/provider-gemini'; 

const client = new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY! });

await client.models.generateContent({
    vokerSession: 'test-session-1',      
    vokerAgent: 'my-agent',              
    vokerAgentVersion: 'v1.0',           
    vokerPerson: 'person-1',             
    model: 'gemini-2.5-flash',
    contents: '... your current system prompt ...',
});

Step 3: Make an LLM call and view in dashboard

Click on the person to view their details page, where you can see their session history along with aggregate data across those sessions.

What you’ll get

Voker gives you two views: a session path timeline splitting a long session into manageable paths, and what it tracks about a person across all of their sessions.

Session path timeline

Open a session from the person’s session history to view its Session Timeline. The timeline breaks a long session into session paths, providing an overview how the agent traversed the conversation.

Screenshot of the session detail page on the Voker platform, with the Session Timeline highlighted — A session's detail page, with the Session Timeline called out

Hover over a session path to see how many turns it comprises.

Screenshot of hovering over a session path in the Session Timeline on the Voker platform — Hover over a session path to see how many turns it comprises

Click a session path to jump straight to that point in the conversation, without scrolling through every turn to find it.

Screenshot of clicking a session path in the Session Timeline on the Voker platform — Click a session path to jump straight to that point in the conversation

What Voker tracks about a person

Open a person from the People tab to see their session history. Three of the things it tracks describe the person across their sessions: Most used agent: the agent this person uses most. Use this as the first place to look when they report a problem, since it’s their primary agent.

Screenshot of the person details page on the Voker platform, with most used agent highlighted — Most used agent on the person details page

Common intent categories: their recurring intents, grouped across sessions. Use this to find what a person relies on your agent for.

Screenshot of the person details page on the Voker platform, with common intent categories highlighted — Common intent categories on the person details page

Behavioral summary: an AI-generated read of how this person behaves and what they want, grounded in their real intents and sessions. Use this as a quick way to get up to speed when researching or troubleshooting their conversations.

Screenshot of the person details page on the Voker platform, with the behavioral summary highlighted — Behavioral summary on the person details page

The person details page also shows agent performance metrics like resolution rate and correction rate, which are covered more in depth in Agent Version Tracking.

Cookbooks

Quick Start Recipes

Tracking Long Running Agent Conversations

What you’ll build

Pre-requisites

Implementation

Step 1: Project setup

Step 2: Set Voker parameters in LLM calls

Step 3: Make an LLM call and view in dashboard

Step 1: Project setup

Step 2: Set Voker parameters in LLM calls

Step 3: Make an LLM call and view in dashboard

What you’ll get

Session path timeline

What Voker tracks about a person

​What you’ll build

​Pre-requisites

​Implementation

​Step 1: Project setup

​Step 2: Set Voker parameters in LLM calls

​Step 3: Make an LLM call and view in dashboard

​Step 1: Project setup

​Step 2: Set Voker parameters in LLM calls

​Step 3: Make an LLM call and view in dashboard

​What you’ll get

​Session path timeline

​What Voker tracks about a person

What you’ll build

Pre-requisites

Implementation

Step 1: Project setup

Step 2: Set Voker parameters in LLM calls

Step 3: Make an LLM call and view in dashboard

Step 1: Project setup

Step 2: Set Voker parameters in LLM calls

Step 3: Make an LLM call and view in dashboard

What you’ll get

Session path timeline

What Voker tracks about a person