Optimize Agents with Version Tracking

Related concepts: Agent, Agent Version Agents constantly need updates to their prompts, tools and configuration to meet evolving user expectations. This cookbook walks you through how to add version tracking to your agents.

What you’ll build

Detect breaking changes or improvements in agent performance
Measure the impact of engineering effort on agent optimization (resolution rate + cost per resolution)

Jump to results

Pre-requisites

An existing agent implementation (Python 3.10+ or Node.js 20+)
Voker API key (get one here)
OpenAI 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 calls into the same session
voker_agent, identifies the agent making the call
voker_agent_version, sets an initial agent version

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",              
    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",              
    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",              
    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 Agent tab.You should see your agent listed with the specified version.

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

Click on the agent to view the details page. You will see the session and version information for the call you just made, along with any associated metrics.

Screenshot of the Agent details page on the Voker platform — Navigate to 'Agents' in the sidebar and click into the agent to view sessions in the 'Sessions' tab

Step 4: Modify your agent configuration and increment version

In your codebase, update your agent prompt, tools or configuration. Increment the voker_agent_version field and update the voker_session field for your next call.

OpenAI
Anthropic
Gemini

from voker.ai.provider_openai import OpenAI

client = OpenAI()

client.chat.completions.create(
    voker_session="test-session-2",          
    voker_agent="my-agent",
    voker_agent_version="v2.0",              
    model="gpt-4.1-mini",
    messages=[
        {
            "role": "system",
            "content": "... YOUR UPDATED SYSTEM PROMPT ...", 
        }
    ],
)

from voker.ai.provider_anthropic import Anthropic

client = Anthropic()

client.messages.create(
    voker_session="test-session-2",          
    voker_agent="my-agent",
    voker_agent_version="v2.0",              
    model="claude-haiku-4-5",
    messages=[
        {
            "role": "user",
            "content": "... YOUR UPDATED SYSTEM PROMPT ...", 
        }
    ],
    max_tokens=1024,
)

from voker.ai.provider_gemini import Client

client = Client()

client.models.generate_content(
    voker_session="test-session-2",          
    voker_agent="my-agent",
    voker_agent_version="v2.0",              
    model="gemini-2.5-flash",
    contents="... YOUR UPDATED SYSTEM PROMPT ...", 
)

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 calls into the same session
vokerAgent, identifies the agent making the call
vokerAgentVersion, sets an initial agent version

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',           
    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',           
    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',           
    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 Agent tab.You should see your agent listed with the specified version.

Click on the agent to view the details page. You will see the session and version information for the call you just made, along with any associated metrics.

Step 4: Modify your agent configuration and increment version

In your codebase, update your agent prompt, tools or configuration. Increment the vokerAgentVersion field and update the vokerSession field for your next call.

OpenAI
Anthropic
Gemini

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

const client = new OpenAI();

await client.chat.completions.create({
    vokerSession: 'test-session-2',      
    vokerAgent: 'my-agent',
    vokerAgentVersion: 'v2.0',           
    model: 'gpt-4.1-mini',
    messages: [
        {
            role: 'system',
            content: '... YOUR UPDATED SYSTEM PROMPT ...', 
        },
    ],
});

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

const client = new Anthropic();

await client.messages.create({
    vokerSession: 'test-session-2',      
    vokerAgent: 'my-agent',
    vokerAgentVersion: 'v2.0',           
    model: 'claude-haiku-4-5',
    messages: [
        {
            role: 'user',
            content: '... YOUR UPDATED SYSTEM PROMPT ...', 
        },
    ],
    max_tokens: 1024,
});

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-2',      
    vokerAgent: 'my-agent',
    vokerAgentVersion: 'v2.0',           
    model: 'gemini-2.5-flash',
    contents: '... YOUR UPDATED SYSTEM PROMPT ...', 
});

Step 5: Make a new LLM call and compare performance

Make another LLM call with the updated configuration. Then go back to the agent details page in the Voker dashboard. You should see the new session with the updated version.

Now as you make changes to your agent, Voker will keep track of how those changes impact your agent performance and user experience. Use these insights to continuously optimize your agent over time.

What you’ll get

Overview of all Intent Categories for your agent, along with their resolution and correction rates. Filter by Agent Version to compare performance across changes and identify which ones led to improvements or potential regressions.

Screenshot of the Agent details page on the Voker platform - Intent Categories tab — Navigate to the 'Intent Categories' tab in the agent details page to view performance metrics by intent category

Version history of your agent

Screenshot of the Agent details page on the Voker platform - Versions tab — Navigate to the 'Versions' tab in the agent details page to view a history of all versions of your agent.

Cookbooks

Quick Start Recipes

Optimize Agents with Version Tracking

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 4: Modify your agent configuration and increment version

Step 1: Project setup

Step 2: Set Voker parameters in LLM calls

Step 3: Make an LLM call and view in dashboard

Step 4: Modify your agent configuration and increment version

Step 5: Make a new LLM call and compare performance

What you’ll get

​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 4: Modify your agent configuration and increment version

​Step 1: Project setup

​Step 2: Set Voker parameters in LLM calls

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

​Step 4: Modify your agent configuration and increment version

​Step 5: Make a new LLM call and compare performance

​What you’ll get

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 4: Modify your agent configuration and increment version

Step 1: Project setup

Step 2: Set Voker parameters in LLM calls

Step 3: Make an LLM call and view in dashboard

Step 4: Modify your agent configuration and increment version

Step 5: Make a new LLM call and compare performance

What you’ll get