> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voker.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Optimize Agents with Version Tracking
Related concepts: [Agent](/concepts/agents#agents), [Agent Version](/concepts/agents#agent-versions)
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](#what-you’ll-get)
## Pre-requisites
* An existing agent implementation (Python 3.10+ or Node.js 20+)
* Voker API key (get one [here](https://app.voker.ai/signup))
* OpenAI API key (get one [here](https://platform.openai.com/api-keys))
## Implementation
### Step 1: Project setup
Install the Voker SDK for Python and add your API key.
```bash pip theme={null}
pip install voker
```
```bash uv theme={null}
uv add voker
```
```bash poetry theme={null}
poetry add voker
```
Add your Voker API key to your `.env` file.
```bash theme={null}
VOKER_API_KEY=your_voker_api_key_here
```
To obtain your Voker API key, sign up for a free Voker account [here](https://app.voker.ai/sign-up). 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:
* `voker_session`, groups calls into the same session
* `voker_agent`, identifies the [agent](/concepts/agents#agents) making the call
* `voker_agent_version`, sets an initial [agent version](/concepts/agents#agent-versions)
```python theme={null}
from openai import OpenAI # [!code --]
from voker.ai.provider_openai import OpenAI # [!code ++]
client = OpenAI()
client.chat.completions.create(
voker_session="test-session-1", # [!code ++]
voker_agent="my-agent", # [!code ++]
voker_agent_version="v1.0", # [!code ++]
model="gpt-4.1-mini",
messages=[
{
"role": "system",
"content": "... your current system prompt here ...",
}
],
)
```
```python theme={null}
from anthropic import Anthropic # [!code --]
from voker.ai.provider_anthropic import Anthropic # [!code ++]
client = Anthropic()
client.messages.create(
voker_session="test-session-1", # [!code ++]
voker_agent="my-agent", # [!code ++]
voker_agent_version="v1.0", # [!code ++]
model="claude-haiku-4-5",
messages=[
{
"role": "user",
"content": "... your current system prompt here ...",
}
],
max_tokens=1024,
)
```
```python theme={null}
from google.genai import Client # [!code --]
from voker.ai.provider_gemini import Client # [!code ++]
client = Client()
client.models.generate_content(
voker_session="test-session-1", # [!code ++]
voker_agent="my-agent", # [!code ++]
voker_agent_version="v1.0", # [!code ++]
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](https://app.voker.ai), 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 `voker_agent_version` field and update the `voker_session` field for your next call.
```python theme={null}
from voker.ai.provider_openai import OpenAI
client = OpenAI()
client.chat.completions.create(
voker_session="test-session-2", # [!code ++]
voker_agent="my-agent",
voker_agent_version="v2.0", # [!code ++]
model="gpt-4.1-mini",
messages=[
{
"role": "system",
"content": "... YOUR UPDATED SYSTEM PROMPT ...", # [!code ++]
}
],
)
```
```python theme={null}
from voker.ai.provider_anthropic import Anthropic
client = Anthropic()
client.messages.create(
voker_session="test-session-2", # [!code ++]
voker_agent="my-agent",
voker_agent_version="v2.0", # [!code ++]
model="claude-haiku-4-5",
messages=[
{
"role": "user",
"content": "... YOUR UPDATED SYSTEM PROMPT ...", # [!code ++]
}
],
max_tokens=1024,
)
```
```python theme={null}
from voker.ai.provider_gemini import Client
client = Client()
client.models.generate_content(
voker_session="test-session-2", # [!code ++]
voker_agent="my-agent",
voker_agent_version="v2.0", # [!code ++]
model="gemini-2.5-flash",
contents="... YOUR UPDATED SYSTEM PROMPT ...", # [!code ++]
)
```
### Step 1: Project setup
Install the Voker SDK for TypeScript and add your API key.
```bash npm theme={null}
npm install @voker/voker
```
```bash pnpm theme={null}
pnpm add @voker/voker
```
```bash bun theme={null}
bun add @voker/voker
```
```bash yarn theme={null}
yarn add @voker/voker
```
Add your Voker API key to your `.env` file.
```bash theme={null}
VOKER_API_KEY=your_voker_api_key_here
```
To obtain your Voker API key, sign up for a free Voker account [here](https://app.voker.ai/sign-up). 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](/concepts/agents#agents) making the call
* `vokerAgentVersion`, sets an initial [agent version](/concepts/agents#agent-versions)
```typescript theme={null}
import { OpenAI } from 'openai'; // [!code --]
import { OpenAI } from '@voker/voker/ai/provider-openai'; // [!code ++]
const client = new OpenAI();
await client.chat.completions.create({
vokerSession: 'test-session-1', // [!code ++]
vokerAgent: 'my-agent', // [!code ++]
vokerAgentVersion: 'v1.0', // [!code ++]
model: 'gpt-4.1-mini',
messages: [
{
role: 'system',
content: '... your current system prompt here ...',
},
],
});
```
```typescript theme={null}
import Anthropic from '@anthropic-ai/sdk'; // [!code --]
import { Anthropic } from '@voker/voker/ai/provider-anthropic'; // [!code ++]
const client = new Anthropic();
await client.messages.create({
vokerSession: 'test-session-1', // [!code ++]
vokerAgent: 'my-agent', // [!code ++]
vokerAgentVersion: 'v1.0', // [!code ++]
model: 'claude-haiku-4-5',
messages: [
{
role: 'user',
content: '... your current system prompt here ...',
},
],
max_tokens: 1024,
});
```
```typescript theme={null}
import { GoogleGenAI } from '@google/genai'; // [!code --]
import { GoogleGenAI } from '@voker/voker/ai/provider-gemini'; // [!code ++]
const client = new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY! });
await client.models.generateContent({
vokerSession: 'test-session-1', // [!code ++]
vokerAgent: 'my-agent', // [!code ++]
vokerAgentVersion: 'v1.0', // [!code ++]
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](https://app.voker.ai), 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.
```typescript theme={null}
import { OpenAI } from '@voker/voker/ai/provider-openai';
const client = new OpenAI();
await client.chat.completions.create({
vokerSession: 'test-session-2', // [!code ++]
vokerAgent: 'my-agent',
vokerAgentVersion: 'v2.0', // [!code ++]
model: 'gpt-4.1-mini',
messages: [
{
role: 'system',
content: '... YOUR UPDATED SYSTEM PROMPT ...', // [!code ++]
},
],
});
```
```typescript theme={null}
import { Anthropic } from '@voker/voker/ai/provider-anthropic';
const client = new Anthropic();
await client.messages.create({
vokerSession: 'test-session-2', // [!code ++]
vokerAgent: 'my-agent',
vokerAgentVersion: 'v2.0', // [!code ++]
model: 'claude-haiku-4-5',
messages: [
{
role: 'user',
content: '... YOUR UPDATED SYSTEM PROMPT ...', // [!code ++]
},
],
max_tokens: 1024,
});
```
```typescript theme={null}
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', // [!code ++]
vokerAgent: 'my-agent',
vokerAgentVersion: 'v2.0', // [!code ++]
model: 'gemini-2.5-flash',
contents: '... YOUR UPDATED SYSTEM PROMPT ...', // [!code ++]
});
```
### 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](https://app.voker.ai) 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.
***
* Version history of your agent
