# Create Agent Source: https://docs.voker.ai/api-reference/create-agent /openapi.json put /api/v1/agents Create an [agent](https://app.voker.ai/docs/concepts/agents#creating-agent). # Create Agent Version Source: https://docs.voker.ai/api-reference/create-agent-version /openapi.json put /api/v1/agents/{agent_name}/agent-versions Create an agent version for a given agent. See [Creating an Agent Version](https://app.voker.ai/docs/concepts/agents#creating-agent-version) for more information. # Create Event Source: https://docs.voker.ai/api-reference/create-event /openapi.json post /api/v1/events Create an [event](https://app.voker.ai/docs/concepts/events#events). Creating an endpoint requires supplying a fingerprint. See how to create a fingerprint [here](https://app.voker.ai/docs/concepts/events#creating-a-fingerprint). Agents, Agent Versions, People and Sessions that are provided but do not exist will be created. # Create Fingerprint Source: https://docs.voker.ai/api-reference/create-fingerprint /openapi.json put /api/v1/fingerprints Create a fingerprint for the client making requests. See [here](https://app.voker.ai/docs/concepts/events#creating-a-fingerprint) for more information. # Create Person Source: https://docs.voker.ai/api-reference/create-person /openapi.json put /api/v1/people Create a person. See [Create a Person](https://app.voker.ai/docs/concepts/people#create-a-person-via-sdk) for more information. # Get Agent Source: https://docs.voker.ai/api-reference/get-agent /openapi.json get /api/v1/agents/{agent_name} Retrieve an [agent](https://app.voker.ai/docs/concepts/agents#agent). # Get Agent Version Source: https://docs.voker.ai/api-reference/get-agent-version /openapi.json get /api/v1/agents/{agent_name}/agent-versions/{agent_version_name} Retrieve an [agent version](https://app.voker.ai/docs/concepts/agents#agent-versions). # Get Person Source: https://docs.voker.ai/api-reference/get-person /openapi.json get /api/v1/people/{person_id} Retrieve a [person](https://app.voker.ai/docs/concepts/people). # Update Person Source: https://docs.voker.ai/api-reference/update-person /openapi.json put /api/v1/people/{person_id} Update a [person](https://app.voker.ai/docs/concepts/people). # Corrections Source: https://docs.voker.ai/auto-annotations/corrections Learn what your agents are getting wrong. ## Overview A **correction** is when the user pushes back, rephrases, or clarifies because the agent got something wrong. It's the clearest signal that the agent's understanding or execution broke down. ## Purpose Corrections pinpoint where the agent is failing in production such as wrong assumptions, hallucinations, missed details, or misinterpretations. Address frequent correction categories to drive prompt fixes, tool changes, and eval coverage for the failure patterns you didn't think to test for. ## How it's calculated Every [event](/concepts/events) you send to Voker is automatically annotated for corrections. Voker flags corrections as each distinct mistake the user fixes, challenges, or calls out. Each correction is categorized, allowing you to view common corrections across all sessions for each agent and person. ## Examples | Agent | User | Correction | Category | | --------------------------------- | ------------------------------ | ------------------------------------ | --------------------------- | | "You must checkout at 12/25/2026" | "My checkout date in November" | `Corrects incorrect checkout date` | `Incorrect Date` | | "Your total is \$13.41 | "what about tax?" | `Points out missing tax from total` | `Missing Tax` | | "The capital of France is Pears." | "it's Paris..." | `Corrects incorrect country capital` | `Incorrect Country Capital` | ## FAQ No. Sometimes the user didn't give enough information up front, or the user changes their mind on the direction of the intent. No. Users making corrections can be frustrated, but they can also be neutral. Look at the most frequent correction categories — those are your most repeatable failures. Use them to prioritize prompt changes, tool fixes, or model updates. # Intents Source: https://docs.voker.ai/auto-annotations/intents Understand how Voker classifies the goals and purposes behind user interactions with your agents. ## Overview An **intent** is what the end user is trying to accomplish in a conversation. It's not always what the agent was designed for. It's what real users are asking of it in production. ## Purpose Intents surface the use cases your agent is actually being asked to handle, including the ones you didn't design for. View intents to discover unanticipated requests, track how end user intents shifts over time, and decide what the agent should get better at. ## How it's calculated Every [event](/concepts/events) you send to Voker is automatically annotated for intents. Voker reads the end user's messages -- ignoring system instructions, treating previous messages and tool calls/results as supporting context -- and flags each distinct goal the user explicitly asks for. Each intent is categorized, allowing you to view common intents across all sessions for each agent and person. ## Examples | User | Intent | Category | | -------------------------------------- | --------------------------------- | ---------------- | | "I want a refund" | `Requests for refund` | `Refund Request` | | "Book me a flight to NYC next Friday." | `Book flight to NYC` | `Flight Booking` | | "Can you book me a flight to Japan?" | `Request to book flight to Japan` | `Flight Booking` | ## FAQ Watch for unanticipated intent categories — those are use cases users want that you didn't design for. High-volume intent categories with low resolution rates are the first place to invest. Yes, but this is an advanced setup. [Contact the team](https://discord.gg/A6hTXfvufu) to customize how intents should be flagged. # Auto Annotations Source: https://docs.voker.ai/auto-annotations/overview Voker automatically annotates every event with the user's intents, corrections, and resolutions. ## Overview Auto Annotations are Voker's analytics layer for AI agents in production. Every [event](/concepts/events) you send to Voker is automatically labeled with what the user was trying to accomplish, where the agent got something wrong, and whether the user's intent was fulfilled. ## Annotation types Voker produces three kinds of Auto Annotations. What the user is trying to accomplish. Where the agent got something wrong. Whether an intent was actually fulfilled. ## Categorization We automatically categorize these annotations into broader **Categories**. Read more about this process in the [Categorizations](/platform/categorizations) documentation. ## FAQ Definitely! We are constantly improving our Auto Annotations system so that it's immediately helpful out of the box. Yes. [Contact the team](https://discord.gg/A6hTXfvufu) to customize how intents, corrections, and resolutions are detected to reflect your product's reality instead of a generic default. Every [event](/concepts/events) you send is annotated automatically. [Contact the team](https://discord.gg/A6hTXfvufu) to get your exported annotations. Logs and traces help engineers debug one conversation at a time. Auto Annotations tell you what's happening across all of them — what users are asking, where the agent keeps breaking, and whether agents actually deliver. They close the measurement gap that existing observability and product analytics tools weren't built for. No. Evals catch regressions against scenarios you've already defined; Auto Annotations surface failure patterns in production that you didn't know to write evals for. They are complementary. # Resolutions Source: https://docs.voker.ai/auto-annotations/resolutions Understand if your agents are resolving end users' intents ## Overview A **resolution** is when the agent successfully fulfills the user's intent. A user can interact with the agent, but still leave without getting what they came for. ## Purpose Resolutions tell you whether your agent is addressing intents properly. View resolutions to measure agent effectiveness and identify which intents go unfulfilled. ## How it's calculated Every [event](/concepts/events) you send to Voker is automatically evaluated against each open intent (i.e. unresolved intents) in the session. Voker marks each open intent as resolved when it's properly fulfilled by looking at the agent's response or tool results. If the user explicitly abandons the request, the intent will be marked as resolved. ## Examples | Intent | What happened | Is resolved | | ---------------------- | ---------------------------------------------------------------------- | ----------- | | `Schedule appointment` | Agent asks user which dates they are available | `No` | | `Book flight to NYC` | Agent calls booking tool, then confirms "Your flight has been booked." | `Yes` | | `Requests Refund` | User says "Never mind, I don't want the refund now" | `Yes` | ## FAQ Not necessarily. You can also send resolution events (e.g. add-to-cart, purchase, signup) from your frontend or backend to signal that an intent was fulfilled outside the chat. This is an advanced setup — [contact the team](https://discord.gg/A6hTXfvufu) to learn how. Yes, but this is an advanced setup. [Contact the team](https://discord.gg/A6hTXfvufu) to tune how resolution is detected for your agent. Resolution rate is the headline metric for whether your agent is delivering. Pair it with [agent version tracking](/cookbooks/agent-version-tracking) to measure the impact of every prompt, tool, or config change — the cookbook walks through using resolution rate (and cost per resolution) to confirm whether each version made the agent better or worse. # Agents and Agent Versions Source: https://docs.voker.ai/concepts/agents Understand how Voker separates an agent's logical identity from its versioned configurations, so you can iterate safely and compare behavior over time. ## Agents An agent represents a logical assistant or capability, identified by its purpose, such as "Support Bot" or "Document Analyzer." It remains stable while its versions evolve. ## Agent Versions An agent version represents a specific configuration of an agent at a point in time. This includes the model, system prompt, tool configuration, and any other behavioral settings. Every agent execution is tied to a single Version. Instead of editing Versions in place, you create new ones, giving you a clear history of changes, side-by-side comparisons, and the ability to revert safely. # Voker Events, Sessions, Messages, and Fingerprints Source: https://docs.voker.ai/concepts/events Learn how Voker tracks LLM interactions as events, organizes them into sessions, and captures messages and environment fingerprints for full observability. ## Events An event represents a single tracked interaction for a specific agent version and person. Every LLM call or wrapped execution results in exactly one event. Events are the top-level unit used for analytics, logging, and debugging. ## Event Sessions An event session represents a full conversation or workflow across multiple events. It is identified by a unique ID, such as a UUID or conversation ID, and groups related events together even if the underlying message history changes over time. ## Messages Events contain the messages exchanged during the interaction. This includes user inputs, system prompts, and model responses. Messages are stored in order and represent the exact content sent to and returned from the model. ## Fingerprints Each event is associated with a fingerprint. A fingerprint captures environment details such as language, runtime version, SDK versions, and system information. This ensures reproducibility and helps diagnose differences across environments. # People: Track End Users and Their Agent Interactions Source: https://docs.voker.ai/concepts/people Learn how Voker models end users as people, how to create them explicitly or automatically, and how to handle multi-tenant systems with users of users. ## Overview People represent the end users in your system. A person is the individual you want to track, analyze, and associate with events. Every event should be tied to a person so you can understand usage, behavior, and outcomes at the user level. While optional, we highly recommend sending `person_id`'s so you can analyze user behavior, personas, and search for specific users. ## Creating a Person A person ID is a unique identifier for each individual. This can be your internal user ID, an email address, or any other stable unique identifier from your system. The same person ID should always refer to the same individual. ## Create a Person via SDK You can explicitly create a person using the SDK by providing a unique person ID and optional metadata. If a person with the same ID already exists, the SDK will return the existing record instead of creating a duplicate. ## Automatically create a Person when creating an Event When creating an event, you can provide a person ID directly. If the person does not already exist, it will be created automatically. This allows you to avoid managing person creation separately. ## Having Users of Users In some systems, your direct customer may have their own end users. In this case, you can model each end user as a separate person while using metadata to associate them with a parent account, organization, or tenant. This allows you to track activity at both the individual and account level. # Optimize Agents with Version Tracking Source: https://docs.voker.ai/cookbooks/agent-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. Screenshot of the Voker API key setup page ### 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. Screenshot of the Agent tab on the Voker platform 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 ### 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. Screenshot of the Voker API key setup page ### 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. Screenshot of the Agent tab on the Voker platform 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 ### 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. Screenshot of the Agent details page on the Voker platform 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 *** Screenshot of the Agent details page on the Voker platform - Intent Categories tab * Version history of your agent Screenshot of the Agent details page on the Voker platform - Versions tab # Production Monitoring for Customer Support Chat Agents Source: https://docs.voker.ai/cookbooks/customer-support-agent Related concepts: [Agent](/concepts/agents#agents), [Event Session](/concepts/events#event-sessions) A customer support agent is a common use case for AI agents, where the agent interacts with users to provide assistance and answer questions. In this cookbook, you'll learn how to instrument one using Voker's Python SDK, and how to use Voker's dashboard to trace user sessions, view metrics and identify areas for improvement. ## What you'll build * A customer support chat agent in Python with Voker's analytics to trace users' sessions * View metrics, a conversation summary and an interactive session timeline for every user session in Voker's dashboard [Jump to results](#what-you’ll-get) ## Pre-requisites * Python 3.10+ * Voker API key (get one [here](https://app.voker.ai/signup)) * OpenAI API key (get one [here](https://platform.openai.com/api-keys)) ### Step 1: Project setup ```bash theme={null} mkdir customer-support-agent && cd customer-support-agent python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install openai python-dotenv voker ``` Create a `.env` file in your project root with the following content: ```bash theme={null} VOKER_API_KEY=your_voker_api_key OPENAI_API_KEY=your_openai_api_key ``` 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. Screenshot of the Voker API key setup page ### Step 2: Build the agent using Voker's Python SDK Create `main.py` and paste the following content. Voker wraps the OpenAI Python SDK with no additional latency. You're using the same parameters you're used to, with the addition of `voker_agent` and `voker_session` to group data in Voker. ```python expandable theme={null} from voker.ai.provider_openai import OpenAI # [!code ++] from dotenv import load_dotenv load_dotenv() client = OpenAI() SYSTEM_PROMPT = "You are a helpful customer support agent. Ask the user how their day is going and if they need any assistance." def run_customer_support_agent(messages: list[dict[str, str]], user_message: str) -> str: def chat(messages): return client.chat.completions.create( voker_agent="customer-support-agent", # [!code ++] voker_session='demo-session-1', # [!code ++] model="gpt-4.1-mini", messages=messages, ) messages.append({"role": "user", "content": user_message}) response = chat(messages) assistant_message = response.choices[0].message.content or "" messages.append({"role": "assistant", "content": assistant_message}) return assistant_message if __name__ == "__main__": messages = [{"role": "system", "content": SYSTEM_PROMPT}] while True: user_input = input("\nEnter your message to the support agent: ") if user_input.lower() in {"exit"}: break response = run_customer_support_agent(messages, user_input) print(f"\nAssistant: {response}") ``` ### Step 3: Run the agent in your terminal ```bash theme={null} python main.py ``` You can chat with the agent in your terminal. Try asking it for some help and see how it responds. ### Step 4: View sessions in Voker After a brief chat with your agent, head back to [Voker](https://app.voker.ai) and navigate to the 'Sessions' page. You will see an entry for the conversation you just had with your agent, click into it. Voker Sessions Page ## What you'll get Insights into every session between your agent and users. Voker Sessions Detail Page - Overview Here is a breakdown of this page: * A dashboard to view metrics such as model used, token count and available tools Voker Sessions Detail Page - Metrics Dashboard * A high-level summary of the session Voker Sessions Detail Page - AI Generated Summary * An interactive Session Timeline mapping the conversation into a readable format Voker Sessions Detail Page - Interactive Session Timeline * The conversation history containing all events Voker Sessions Detail Page - Conversation History ## Next steps You've set up Voker analytics! Visit our Agent Version Tracking cookbook to see how you can identify discrepancies in your agent's performance. # Tracking Long Running Agent Conversations Source: https://docs.voker.ai/cookbooks/long-running-agent-conversations Related concepts: [People](/concepts/people), [Sessions](/concepts/events#event-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](/concepts/people#creating-a-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](#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)) ## 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. Screenshot of the Voker API key setup page ### 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](/concepts/events#event-sessions) * `voker_agent`, identifies the [agent](/concepts/agents#agents) making the event * `voker_agent_version`, sets an initial [agent version](/concepts/agents#agent-versions) * `voker_person`, attributes the event to a specific [person](/concepts/people). 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. ```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 ++] voker_person="person-1", # [!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 ++] voker_person="person-1", # [!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 ++] voker_person="person-1", # [!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 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 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 ### 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. Screenshot of the Voker API key setup page ### 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](/concepts/events#event-sessions) * `vokerAgent`, identifies the [agent](/concepts/agents#agents) making the event * `vokerAgentVersion`, sets an initial [agent version](/concepts/agents#agent-versions) * `vokerPerson`, attributes the event to a specific [person](/concepts/people). 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. ```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 ++] vokerPerson: 'person-1', // [!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 ++] vokerPerson: 'person-1', // [!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 ++] vokerPerson: 'person-1', // [!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 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 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 ## 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 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 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 ### 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 **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 **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 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/agent-version-tracking). # Cookbook Source: https://docs.voker.ai/cookbooks/overview Cookbooks are step-by-step guides for implementing Voker for specific use cases. Each cookbook provides detailed instructions and code examples to help you quickly integrate Voker into your projects. ## Available Recipes Instrument a customer support agent, surface a hidden failure using Voker data, and measure the fix. Track versions of agents in your system to identify discrepancies and ensure proper functionality. Track long running agents in Voker to monitor conversation quality without reading through every message. # Voker - AI Agent Analytics Platform Source: https://docs.voker.ai/overview Voker gives you full visibility into every LLM interaction your AI agents make. Instrument with a drop-in SDK swap and start tracking events, sessions, and users in minutes. # Install with AI Copy the Voker setup prompt into your coding agent. ````txt expandable theme={null} # Setting up Voker This prompt explains how to set up Voker in your project. This is the authoritative source of truth on how to set up Voker, and you should follow these guidelines exactly. To use it, you can use the sections below to set up Voker in the project. ## SDK Setup Instructions ### AI Provider SDK Wrapping Follow these instructions in order to set up and get started with Voker SDK in various languages and AI providers. The frameworks and languages with explicit AI Provider SDK wrapping support are: - JS & Ts: Openai, Anthropic, Gemini and Vercel AI SDK - Python: Openai, Anthropic and Gemini Voker has an SDK for various languages and LLM frameworks and libraries. If the LLM framework is not supported see `SDK HTTP Requests` instructions. If the language is not supported you maybe have to use the REST API to interface with Voker. #### JavaScript & TypeScript For JS & TS, the following package is available `@voker/voker` You can install the JavaScript Voker SDK into your project by running the following command: ```sh npm i @voker/voker # or: pnpm i @voker/voker # or: yarn add @voker/voker # or: bun add @voker/voker ``` #### Python For Python, the following package is available `voker` You can install the Python Voker SDK into your project by running the following command: ```sh pip install voker # or: uv add voker # or: poetry add voker ``` First, navigate to the [Setup Page](http://app.voker.ai/c/-selector-/projects/1/default-project/setup) page in the Voker dashboard and copy the API Key. Then, copy-paste them into your `.env.local` file (or wherever your environment variables are stored): ```.env .env.local VOKER_API_KEY= ``` In most cases, Voker implementation just requires swapping the existing imports with the wrapped Voker SDK. #### JavaScript & TypeScript Swap out the LLM import with the Voker client. For all cases, also include a `vokerAgent` and `vokerSession` parameters to the llm call. For example with OpenAI: ``` await client.chat.completions.create({ + vokerAgent: '', // required + vokerSession: '', // required model: 'gpt-4o', messages: [ { role: 'user', content: 'Hello, world!', }, ], }); ``` Fill in the `` with an appropriate value for the application. The `` should be unique per conversation with the agent. ##### OpenAI ``` - import { OpenAI } from 'openai'; + import { OpenAI } from '@voker/voker/ai/provider-openai'; ``` ##### Anthropic ``` - import { Anthropic } from '@anthropic-ai/sdk'; + import { Anthropic } from '@voker/voker/ai/provider-anthropic'; ``` ##### Gemini ``` - import { GoogleGenAI } from '@google/genai'; + import { GoogleGenAI } from '@voker/voker/ai/provider-gemini'; ``` ##### AI SDK ``` - import { generateText } from 'ai'; + import * as ai from 'ai'; + import { wrapAiSdk } from '@voker/voker/ai/provider-aisdk'; + const { generateText } = wrapAiSdk(ai); ``` Use the base JS sdk for streaming with AI SDK. #### Python Swap out the LLM import with the Voker client. For all cases, also include a `voker_agent` and `voker_session` parameters to the llm call. For example with OpenAI: ``` client.chat.completions.create( + voker_agent="", # required + voker_session="", # required model="gpt-4.1-mini", messages=[ { "role": "user", "content": "Hello, world!", } ], ) ``` Fill in the `` with an appropriate value for the application. The `` should be unique per conversation with the agent. ##### OpenAI Sync: ``` - from openai import AsyncOpenAI + from voker.ai.provider_openai import AsyncOpenAI ``` Async: ``` - from openai import OpenAI + from voker.ai.provider_openai import OpenAI ``` ##### Anthropic Sync: ``` - from anthropic import Anthropic + from voker.ai.provider_anthropic import Anthropic ``` Async: ``` - from anthropic import AsyncAnthropic + from voker.ai.provider_anthropic import AsyncAnthropic ``` ##### Gemini ``` - from google.genai import Client + from voker.ai.provider_gemini import Client ``` ### SDK HTTP Requests Follow these instructions in order to set up and get started with Voker SDK in various languages. The languages with explicit SDK support are: - JS & TS - Python Voker has an SDK for various languages and LLM frameworks and libraries. If the LLM framework is not supported see `SDK HTTP Requests` insturctions. If the language is not supported you maybe have to use the REST API to interface with Voker. #### JavaScript & TypeScript For JS & TS, the following package is available `@voker/voker` You can install the JavaScript Voker SDK into your project by running the following command: ```sh npm i @voker/voker # or: pnpm i @voker/voker # or: yarn add @voker/voker # or: bun add @voker/voker ``` #### Python For Python, the following package is available `voker` You can install the Python Voker SDK into your project by running the following command: ```sh pip install voker # or: uv add voker # or: poetry add voker ``` First, navigate to the [Setup Page](http://app.voker.ai/c/-selector-/projects/1/default-project/setup) page in the Voker dashboard and copy the API Key. Then, copy-paste them into your `.env.local` file (or wherever your environment variables are stored): ```.env .env.local VOKER_API_KEY= ``` First, navigate to the [Setup Page](http://app.voker.ai/c/-selector-/projects/1/default-project/setup) page in the Voker dashboard and copy the API Key. Then, copy-paste them into your `.env.local` file (or wherever your environment variables are stored): ```.env .env.local VOKER_API_KEY= ``` #### JavaScript & TypeScript ``` import { VokerClient } from '@voker/voker'; const vokerClient = new VokerClient(); ``` #### Python ``` from voker import VokerClient voker_client = VokerClient() ``` #### JavaScript & TypeScript ``` vokerClient.events.create({ vokerAgent: '', vokerSession: '', eventName: 'llm', properties: { api: 'openai-chat-completions', inputs: { model: '...', messages: ..., }, output: llmResponse, }, }) ``` #### Python ``` voker_client.events.create( voker_agent="", voker_session="", event_name="llm", properties={ "api": "openai-chat-completions", "inputs": { "model": "...", "messages": ..., }, "output": llm_response }, ) ``` ```` ## Get started Instrument your first AI agent in minutes with the Python or TypeScript SDK. Learn how Voker captures LLM calls as structured events you can query and analyze. Full reference for the Voker Python SDK, including installation and all supported parameters. Full reference for the Voker TypeScript SDK, including installation and all supported parameters. REST API reference for creating events, managing agents, people, and fingerprints. ## Supported providers Voker wraps the most popular LLM SDKs so you can start tracking without rewriting your code. Track Chat Completions and Responses API calls made with the OpenAI SDK. Track Messages API calls with Claude models using the Anthropic SDK. Track Google Gemini Generate Content and Interactions API calls. Wrap the Vercel AI SDK using `wrapAiSdk()` for unified tracking. ## What's new See the [changelog](/resources/changelog) for the latest updates, new provider support, and SDK improvements. # Agent Analytics Source: https://docs.voker.ai/platform/analytics Top level analysis on sessions with drilldowns to understand and debug your agents. ## Overview The dashboard is your starting point for understanding how your agents are performing. It surfaces session volume, resolution rates, token usage, and cost across the agents in your project. From here, you can view individual sessions to debug and understand how your users are interacting with agents. ## Dashboard ### What you'll see * **Session volume** — how many sessions ran over the selected period. * **Resolution rates** — how often agents resolved a given user intent in a session. * **Correction rates** - how often users had to correct an agent in a session (i.e. 'that's not the right date') * **Token cost** — llm token cost broken down by selected agent across selected date range. Dashboard showing session volume, resolution and correction rates, and token cost ### Filters Use the time period and agent filters at the top of the dashboard to narrow the view only to what you want to see. Dashboard filters ## Up next * [Categorization](/platform/categorizations) — User intents need categorizations at the aggregate level. Same with corrections. Get there from the Dashboard, Sessions, or the Agent pages. # Categorization Source: https://docs.voker.ai/platform/categorizations See how Voker groups intents and corrections into categories so you can spot patterns and compare agent versions on the fly. ## Overview Categorizations organize your user's intents — the item(s) they are trying to accomplish with your agent — and corrections — the various adjustments and refinements the user makes to the agent's trajectory. Together they help you understand what users ask for and what specific areas your agent struggles. ## Intent categories On an agent's **Intent Categories** tab, you'll see every intent category detected across sessions, along with resolution and correction rates for each. Filter by agent version to compare how a prompt or model change affected specific intents. Agent version intent categories You can also see these categories on your **Dashboard** and the **Sessions** page. ## Correction categories On the **Sessions** overview page, correction categories appear as filters and columns. Use them to find sessions where the agent needed a correction and group those failures by type. Sessions page with correction category filters and columns ### Personas (beta) Ever wondered what groups your agent's users fall into? Like 'power users' who know the ins and outs of your agents capabilites? Or the 'power trippers' who tend to use any means necessary to get what they want from your agent? Request early access in the [Voker platform](https://app.voker.ai). ## Up next * [Summaries](/platform/summaries) — reduce the time you spend in logs. Read about session, agent, and person summaries. # Smart Skills (Beta) Source: https://docs.voker.ai/platform/smart-skills Generate short markdown skills that make your agents hyper-efficient. Both at getting your user (internal or external) what they need and doing it with less token spend overall. ## Overview Smart skills are generated by Voker only as necessary--based off user corrections and logged errors and integrated directly into your prompt architecture. ### Where to find Smart skills Open **Smart Skills** in the project sidebar to browse skills across all agents, or open an agent and select the **Smart Skills** tab to manage skills for that agent alone. ### Smart Skills and cost performance In addition to making your agent prompts more efficient at getting a user to their destination quicker, skills can improve token efficiency. Head to the Smart Skills page to see how skills added or removed by Voker are affecting your bottom line. Skills cost tracking Skills tab on the Voker platform ## What a skill contains A skill includes: * **Name** — a short label, such as "Build scoring rubric". * **Description** — what the skill does and when the agent should use it. * **Content** — half- to one-page markdown that amends the agent's system prompt with instructions, rules, or examples. ## How skills work Once Voker reaches a confidence threshold that your prompt is not efficiently handling a set of tasks or user intent categories, a skill is generated. If a skill is underperforming, or otherwise increasing cost and/or correction rate, Voker will flag it and depending on your human reviewer settings can cut the skill on their own. Every time a skill is added or removed from your prompt architecture Voker auto-increments the agent version. ## Editing skills Click a skill to open the editor. Write in markdown or switch to a code view for longer instructions. Changes save automatically. ## Up next * [Agent version tracking cookbook](/cookbooks/agent-version-tracking) — iterate on agent behavior and measure the impact. # Summaries Source: https://docs.voker.ai/platform/summaries Read summaries of sessions, agents, and people to quickly understand context without replaying every detail of every session. ## Overview All of Voker's generated Summaries distill long-running session histories into short, readable overviews. These intelligently consider a combination of the latest context and key details that may have come much earlier so you don't miss the most important details. ## Session overview These include a the most important details of a given session--i.e. flagging a serious user frustration, newly seen intent category, or otherwise summarizing a lengthy conversation. Session overview ## Agent summaries On an agent's detail page, the overview sums up the agent's overall behavior and recent trends, like new intent categories, shifts in correction rate by version and more. Useful when onboarding teammates or reviewing changes after a version rollout. Agent detail page with summary ## Person summaries On a person's detail page, the behavioral summary wraps up what a specific user has done across sessions so support and product teams can see a key account's history at a glance. Person detail page with behavioral summary ## Up next * [Smart skills (beta)](/platform/smart-skills) — auto-generate skills based on where your agents are struggling most. # Integrate Voker with the Vercel AI SDK Source: https://docs.voker.ai/providers/ai-sdk ## Installation Make sure the AI SDK is installed: ```bash npm theme={null} npm install ai ``` ```bash pnpm theme={null} pnpm add ai ``` ```bash bun theme={null} bun add ai ``` ```bash yarn theme={null} yarn add ai ``` Make sure the Voker Typescript SDK is [installed](/sdks/typescript#installation). the SDK does not currently support Audio, Video or Image modalities. ## Generate Text ```ts theme={null} import { generateText } from 'ai'; // [!code --] import * as ai from 'ai'; // [!code ++] import { wrapAiSdk } from '@voker/voker/ai/provider-aisdk'; // [!code ++] const { generateText } = wrapAiSdk(ai); // [!code ++] await generateText({ vokerAgent: 'customer-support-agent', // required // [!code ++] vokerSession: 'user-session-1', // required // [!code ++] model: 'anthropic/claude-sonnet-4.5', prompt: 'Write a vegetarian lasagna recipe for 4 people.', }); ``` ## Stream Text The AI SDK does not automatically record streamed steps. After streaming completes, send the generated steps using the base event creation API. ```ts theme={null} import * as ai from 'ai'; import { VokerClient } from '@voker/voker'; const { streamText } = ai; const vokerClient = new VokerClient(); const s = streamText({ /* Existing streamText call */ }); s.steps.then((steps) => { steps.forEach((step) => { vokerClient.events.create({ vokerAgent: 'AGENT_NAME', vokerSession: 'SESSION_ID', eventName: 'llm', properties: { api: 'aisdk', inputs: { model: step.model, request: step.request, }, output: { usage: step.usage, response: step.response, }, }, }); }); }); ``` ## Next steps * [TypeScript SDK reference](/sdks/typescript) - installation, configuration, and type definitions. # Integrate Voker with Anthropic Source: https://docs.voker.ai/providers/anthropic ## Installation Make sure the Anthropic SDK is installed: ```bash pip theme={null} pip install anthropic ``` ```bash uv theme={null} uv add anthropic ``` ```bash poetry theme={null} poetry add anthropic ``` Make sure the Voker Python SDK is [installed](/sdks/python#installation). Make sure the Anthropic SDK is installed: ```bash npm theme={null} npm install @anthropic-ai/sdk ``` ```bash pnpm theme={null} pnpm add @anthropic-ai/sdk ``` ```bash bun theme={null} bun add @anthropic-ai/sdk ``` ```bash yarn theme={null} yarn add @anthropic-ai/sdk ``` Make sure the Voker Typescript SDK is [installed](/sdks/typescript#installation). the SDK does not currently support Audio, Video or Image modalities. ## Usage ### Messages ```py theme={null} from anthropic import Anthropic # [!code --] from voker.ai.provider_anthropic import Anthropic # [!code ++] client = Anthropic() client.messages.create( voker_agent="customer-support-agent", # required [!code ++] voker_session="user-session-1", # required [!code ++] model="claude-haiku-4-5", messages=[ { "role": "user", "content": "Write a haiku about autumn.", } ], max_tokens=1024, ) ``` ### Async Messages ```py theme={null} from anthropic import AsyncAnthropic # [!code --] from voker.ai.provider_anthropic import AsyncAnthropic # [!code ++] client = AsyncAnthropic() await client.messages.create( voker_agent="customer-support-agent", # required [!code ++] voker_session="user-session-1", # required [!code ++] model="claude-haiku-4-5", messages=[ { "role": "user", "content": "Write a haiku about autumn.", } ], max_tokens=1024, ) ``` ### Beta Messages ```py theme={null} from anthropic import Anthropic # [!code --] from voker.ai.provider_anthropic import Anthropic # [!code ++] client = Anthropic() client.beta.messages.create( voker_agent="customer-support-agent", # required [!code ++] voker_session="user-session-1", # required [!code ++] model="claude-haiku-4-5", messages=[ { "role": "user", "content": "Write a haiku about autumn.", } ], max_tokens=1024, betas=[], ) ``` ### Async Beta Messages ```py theme={null} from anthropic import AsyncAnthropic # [!code --] from voker.ai.provider_anthropic import AsyncAnthropic # [!code ++] client = AsyncAnthropic() await client.beta.messages.create( voker_agent="customer-support-agent", # required [!code ++] voker_session="user-session-1", # required [!code ++] model="claude-haiku-4-5", messages=[ { "role": "user", "content": "Write a haiku about autumn.", } ], max_tokens=1024, ) ``` ### Messages ```ts 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({ vokerAgent: 'customer-support-agent', // required // [!code ++] vokerSession: 'user-session-1', // required // [!code ++] model: 'claude-4-sonnet-20250514', max_tokens: 100, messages: [ { role: 'user', content: 'Hello, world!', }, ], }); ``` ### Beta Messages ```ts theme={null} import { Anthropic } from '@anthropic-ai/sdk'; // [!code --] import { Anthropic } from '@voker/voker/ai/provider-anthropic'; // [!code ++] const client = new Anthropic(); await client.beta.messages.create({ vokerAgent: 'customer-support-agent', // required // [!code ++] vokerSession: 'user-session-1', // required // [!code ++] model: 'claude-4-sonnet-20250514', max_tokens: 100, messages: [ { role: 'user', content: 'Hello, world!', }, ], }); ``` ## Next steps * [Python SDK reference](/sdks/python) - environment setup, API key configuration, and full method reference. * [TypeScript SDK reference](/sdks/typescript) - installation, configuration, and type definitions. # Integrate Voker with Gemini Source: https://docs.voker.ai/providers/gemini ## Installation Make sure the Gemini SDK is installed: ```bash pip theme={null} pip install google-genai ``` ```bash uv theme={null} uv add google-genai ``` ```bash poetry theme={null} poetry add google-genai ``` Make sure the Voker Python SDK is [installed](/sdks/python#installation). Make sure the Gemini SDK is installed: ```bash npm theme={null} npm install @google/genai ``` ```bash pnpm theme={null} pnpm add @google/genai ``` ```bash bun theme={null} bun add @google/genai ``` ```bash yarn theme={null} yarn add @google/genai ``` Make sure the Voker Typescript SDK is [installed](/sdks/typescript#installation). the SDK does not currently support Audio, Video or Image modalities. ## Usage ### Generate Content ```py theme={null} from google.genai import Client # [!code --] from voker.ai.provider_gemini import Client # [!code ++] client = Client() client.models.generate_content( voker_agent="customer-support-agent", # required [!code ++] voker_session="user-session-1", # required [!code ++] model="gemini-2.5-flash", contents="Write a poem about spring.", ) ``` ### Async Generate Content ```py theme={null} from google.genai import Client # [!code --] from voker.ai.provider_gemini import Client # [!code ++] client = Client() await client.aio.models.generate_content( voker_agent="customer-support-agent", # required [!code ++] voker_session="user-session-1", # required [!code ++] model="gemini-2.5-flash", contents="Write a poem about spring.", ) ``` ### Interactions ```py theme={null} from google.genai import Client # [!code --] from voker.ai.provider_gemini import Client # [!code ++] client = Client() client.interactions.create( voker_agent="customer-support-agent", # required [!code ++] voker_session="user-session-1", # required [!code ++] model="gemini-2.5-flash", input="Tell me a short joke about programming.", ) ``` ### Async Interactions ```py theme={null} from google.genai import Client # [!code --] from voker.ai.provider_gemini import Client # [!code ++] client = Client() client.aio.interactions.create( voker_agent="customer-support-agent", # required [!code ++] voker_session="user-session-1", # required [!code ++] model="gemini-2.5-flash", input="Tell me a short joke about programming.", ) ``` ### Generate Content ```ts theme={null} import { GoogleGenAI } from '@google/genai'; // [!code --] import { GoogleGenAI } from '@voker/voker/ai/provider-gemini'; // [!code ++] const ai = new GoogleGenAI({ apiKey: 'gemini-api-key' }); await ai.models.generateContent({ vokerAgent: 'customer-support-agent', // required // [!code ++] vokerSession: 'user-session-1', // required // [!code ++] model: 'gemini-2.5-flash', contents: 'Hello, world!', }); ``` ### Interactions ```ts theme={null} import { GoogleGenAI } from '@google/genai'; // [!code --] import { GoogleGenAI } from '@voker/voker/ai/provider-gemini'; // [!code ++] const ai = new GoogleGenAI({ apiKey: 'gemini-api-key' }); await ai.interactions.create({ vokerAgent: 'customer-support-agent', // required // [!code ++] vokerSession: 'user-session-1', // required // [!code ++] model: 'gemini-2.5-flash', input: 'Hello, world!', }); ``` ## Next steps * [Python SDK reference](/sdks/python) - environment setup, API key configuration, and full method reference. * [TypeScript SDK reference](/sdks/typescript) - installation, configuration, and type definitions. # Integrate Voker with OpenAI Source: https://docs.voker.ai/providers/openai ## Installation Make sure the OpenAI SDK is installed: ```bash pip theme={null} pip install openai ``` ```bash uv theme={null} uv add openai ``` ```bash poetry theme={null} poetry add openai ``` Make sure the Voker Python SDK is [installed](/sdks/python#installation). Make sure the OpenAI SDK is installed: ```bash npm theme={null} npm install openai ``` ```bash pnpm theme={null} pnpm add openai ``` ```bash bun theme={null} bun add openai ``` ```bash yarn theme={null} yarn add openai ``` Make sure the Voker TypeScript SDK is [installed](/sdks/typescript#installation). the SDK does not currently support Audio, Video or Image modalities. ## Usage ### Chat Completions ```py theme={null} from openai import OpenAI # [!code --] from voker.ai.provider_openai import OpenAI # [!code ++] client = OpenAI() client.chat.completions.create( voker_agent="customer-support-agent", # required [!code ++] voker_session="user-session-1", # required [!code ++] model="gpt-4.1-mini", messages=[ { "role": "user", "content": "Hello, world!", } ], ) ``` ### Async Chat Completions ```py theme={null} from openai import AsyncOpenAI # [!code --] from voker.ai.provider_openai import AsyncOpenAI # [!code ++] client = AsyncOpenAI() await client.chat.completions.create( voker_agent="customer-support-agent", # required [!code ++] voker_session="user-session-1", # required [!code ++] model="gpt-4.1-mini", messages=[ { "role": "user", "content": "Hello, world!", } ], ) ``` ### Responses ```py theme={null} from openai import OpenAI # [!code --] from voker.ai.provider_openai import OpenAI # [!code ++] client = OpenAI() client.responses.create( voker_agent="customer-support-agent", # required [!code ++] voker_session="user-session-1", # required [!code ++] model="gpt-4.1-mini", input="Hello, world!", ) ``` ### Async Responses ```py theme={null} from openai import AsyncOpenAI # [!code --] from voker.ai.provider_openai import AsyncOpenAI # [!code ++] client = AsyncOpenAI() await client.responses.create( voker_agent="customer-support-agent", # required [!code ++] voker_session="user-session-1", # required [!code ++] model="gpt-4.1-mini", input="Hello, world!", ) ``` ### Chat Completions ```ts 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({ vokerAgent: 'customer-support-agent', // required // [!code ++] vokerSession: 'user-session-1', // required // [!code ++] model: 'gpt-4o', messages: [ { role: 'user', content: 'Hello, world!', }, ], }); ``` ### Responses ```ts theme={null} import { OpenAI } from 'openai'; // [!code --] import { OpenAI } from '@voker/voker/ai/provider-openai'; // [!code ++] const client = new OpenAI(); await client.responses.create({ vokerAgent: 'customer-support-agent', // required // [!code ++] vokerSession: 'user-session-1', // required // [!code ++] model: 'gpt-4o', input: 'Hello, world!', }); ``` ## Next steps * [Python SDK reference](/sdks/python) - environment setup, API key configuration, and full method reference. * [TypeScript SDK reference](/sdks/typescript) - installation, configuration, and type definitions. # Quickstart: Start Tracking AI Agent Calls with Voker Source: https://docs.voker.ai/quickstart Install the Voker Python or TypeScript SDK, set your API key, and instrument your first AI agent with a single drop-in import swap in minutes. # Install with AI Copy the Voker setup prompt into your coding agent. ````txt expandable theme={null} # Setting up Voker This prompt explains how to set up Voker in your project. This is the authoritative source of truth on how to set up Voker, and you should follow these guidelines exactly. To use it, you can use the sections below to set up Voker in the project. ## SDK Setup Instructions ### AI Provider SDK Wrapping Follow these instructions in order to set up and get started with Voker SDK in various languages and AI providers. The frameworks and languages with explicit AI Provider SDK wrapping support are: - JS & Ts: Openai, Anthropic, Gemini and Vercel AI SDK - Python: Openai, Anthropic and Gemini Voker has an SDK for various languages and LLM frameworks and libraries. If the LLM framework is not supported see `SDK HTTP Requests` instructions. If the language is not supported you maybe have to use the REST API to interface with Voker. #### JavaScript & TypeScript For JS & TS, the following package is available `@voker/voker` You can install the JavaScript Voker SDK into your project by running the following command: ```sh npm i @voker/voker # or: pnpm i @voker/voker # or: yarn add @voker/voker # or: bun add @voker/voker ``` #### Python For Python, the following package is available `voker` You can install the Python Voker SDK into your project by running the following command: ```sh pip install voker # or: uv add voker # or: poetry add voker ``` First, navigate to the [Setup Page](http://app.voker.ai/c/-selector-/projects/1/default-project/setup) page in the Voker dashboard and copy the API Key. Then, copy-paste them into your `.env.local` file (or wherever your environment variables are stored): ```.env .env.local VOKER_API_KEY= ``` In most cases, Voker implementation just requires swapping the existing imports with the wrapped Voker SDK. #### JavaScript & TypeScript Swap out the LLM import with the Voker client. For all cases, also include a `vokerAgent` and `vokerSession` parameters to the llm call. For example with OpenAI: ``` await client.chat.completions.create({ + vokerAgent: '', // required + vokerSession: '', // required model: 'gpt-4o', messages: [ { role: 'user', content: 'Hello, world!', }, ], }); ``` Fill in the `` with an appropriate value for the application. The `` should be unique per conversation with the agent. ##### OpenAI ``` - import { OpenAI } from 'openai'; + import { OpenAI } from '@voker/voker/ai/provider-openai'; ``` ##### Anthropic ``` - import { Anthropic } from '@anthropic-ai/sdk'; + import { Anthropic } from '@voker/voker/ai/provider-anthropic'; ``` ##### Gemini ``` - import { GoogleGenAI } from '@google/genai'; + import { GoogleGenAI } from '@voker/voker/ai/provider-gemini'; ``` ##### AI SDK ``` - import { generateText } from 'ai'; + import * as ai from 'ai'; + import { wrapAiSdk } from '@voker/voker/ai/provider-aisdk'; + const { generateText } = wrapAiSdk(ai); ``` Use the base JS sdk for streaming with AI SDK. #### Python Swap out the LLM import with the Voker client. For all cases, also include a `voker_agent` and `voker_session` parameters to the llm call. For example with OpenAI: ``` client.chat.completions.create( + voker_agent="", # required + voker_session="", # required model="gpt-4.1-mini", messages=[ { "role": "user", "content": "Hello, world!", } ], ) ``` Fill in the `` with an appropriate value for the application. The `` should be unique per conversation with the agent. ##### OpenAI Sync: ``` - from openai import AsyncOpenAI + from voker.ai.provider_openai import AsyncOpenAI ``` Async: ``` - from openai import OpenAI + from voker.ai.provider_openai import OpenAI ``` ##### Anthropic Sync: ``` - from anthropic import Anthropic + from voker.ai.provider_anthropic import Anthropic ``` Async: ``` - from anthropic import AsyncAnthropic + from voker.ai.provider_anthropic import AsyncAnthropic ``` ##### Gemini ``` - from google.genai import Client + from voker.ai.provider_gemini import Client ``` ### SDK HTTP Requests Follow these instructions in order to set up and get started with Voker SDK in various languages. The languages with explicit SDK support are: - JS & TS - Python Voker has an SDK for various languages and LLM frameworks and libraries. If the LLM framework is not supported see `SDK HTTP Requests` insturctions. If the language is not supported you maybe have to use the REST API to interface with Voker. #### JavaScript & TypeScript For JS & TS, the following package is available `@voker/voker` You can install the JavaScript Voker SDK into your project by running the following command: ```sh npm i @voker/voker # or: pnpm i @voker/voker # or: yarn add @voker/voker # or: bun add @voker/voker ``` #### Python For Python, the following package is available `voker` You can install the Python Voker SDK into your project by running the following command: ```sh pip install voker # or: uv add voker # or: poetry add voker ``` First, navigate to the [Setup Page](http://app.voker.ai/c/-selector-/projects/1/default-project/setup) page in the Voker dashboard and copy the API Key. Then, copy-paste them into your `.env.local` file (or wherever your environment variables are stored): ```.env .env.local VOKER_API_KEY= ``` First, navigate to the [Setup Page](http://app.voker.ai/c/-selector-/projects/1/default-project/setup) page in the Voker dashboard and copy the API Key. Then, copy-paste them into your `.env.local` file (or wherever your environment variables are stored): ```.env .env.local VOKER_API_KEY= ``` #### JavaScript & TypeScript ``` import { VokerClient } from '@voker/voker'; const vokerClient = new VokerClient(); ``` #### Python ``` from voker import VokerClient voker_client = VokerClient() ``` #### JavaScript & TypeScript ``` vokerClient.events.create({ vokerAgent: '', vokerSession: '', eventName: 'llm', properties: { api: 'openai-chat-completions', inputs: { model: '...', messages: ..., }, output: llmResponse, }, }) ``` #### Python ``` voker_client.events.create( voker_agent="", voker_session="", event_name="llm", properties={ "api": "openai-chat-completions", "inputs": { "model": "...", "messages": ..., }, "output": llm_response }, ) ``` ```` This guide walks you through installing Voker, configuring your API key, and making your first tracked LLM call. By the end, you'll have a working integration that captures every request your agent makes - no extra code required beyond swapping the import. the SDK does not currently support Audio, Video or Image modalities. Install `voker` using your preferred package manager. ```bash pip theme={null} pip install voker ``` ```bash uv theme={null} uv add voker ``` ```bash poetry theme={null} poetry add voker ``` Create a `.env` file: ```bash theme={null} VOKER_API_KEY=your_api_key_here ``` You can find your API key in the Voker dashboard. Setting it as an environment variable keeps it out of your source code. Replace the standard LLM provider import with the Voker-wrapped version. No other changes to your code are needed. ```python theme={null} from openai import OpenAI # [!code --] from voker.ai.provider_openai import OpenAI # [!code ++] client = OpenAI() client.chat.completions.create( voker_agent="customer-support-agent", # required [!code ++] voker_session="user-session-1", # required [!code ++] model="gpt-4.1-mini", messages=[ { "role": "user", "content": "Hello, world!", } ], ) ``` ```python theme={null} from anthropic import Anthropic # [!code --] from voker.ai.provider_anthropic import Anthropic # [!code ++] client = Anthropic() client.messages.create( voker_agent="customer-support-agent", # required [!code ++] voker_session="user-session-1", # required [!code ++] model="claude-haiku-4-5", messages=[ { "role": "user", "content": "Hello, world!", } ], 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_agent="customer-support-agent", # required [!code ++] voker_session="user-session-1", # required [!code ++] model="gemini-2.5-flash", contents="Hello, world!", ) ``` Pass `voker_agent` to identify which agent handled the event, and `voker_session` to group events by session. Install `@voker/voker` using your preferred package manager. ```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 ``` Create a `.env` file: ```bash theme={null} VOKER_API_KEY=your_api_key_here ``` You can find your API key in the Voker dashboard. Setting it as an environment variable keeps it out of your source code. Replace the standard LLM provider import with the Voker-wrapped version. No other changes to your code are needed. ```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({ vokerAgent: 'customer-support-agent', // required [!code ++] vokerSession: 'user-session-1', // required [!code ++] model: 'gpt-4o', messages: [ { role: 'user', content: 'Hello, world!', }, ], }); ``` ```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({ vokerAgent: 'customer-support-agent', // required [!code ++] vokerSession: 'user-session-1', // required [!code ++] model: 'claude-haiku-4-5', messages: [ { role: 'user', content: 'Hello, world!', }, ], 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({ vokerAgent: 'customer-support-agent', // required [!code ++] vokerSession: 'user-session-1', // required [!code ++] model: 'gemini-2.5-flash', contents: 'Hello, world!', }); ``` ```typescript theme={null} import { generateText } from 'ai'; // [!code --] import * as ai from 'ai'; // [!code ++] import { wrapAiSdk } from '@voker/voker/ai/provider-aisdk'; // [!code ++] const { generateText } = wrapAiSdk(ai); await generateText({ vokerAgent: 'customer-support-agent', // required [!code ++] vokerSession: 'user-session-1', // required [!code ++] model: 'anthropic/claude-haiku-4-5', prompt: 'Hello, world!', }); ``` Pass `vokerAgent` to identify which agent handled the event, and `vokerSession` to group events by session. ## Next steps Once you're tracking calls, explore provider-specific features and configuration options: Chat Completions and Responses API support Messages API support with Claude models Gemini Generate Content and Interactions API support Vercel AI SDK integration with `wrapAiSdk()` # Changelog Source: https://docs.voker.ai/resources/changelog New Features and SDK Release Notes. ## June 19, 2026 * Added Drilldowns to the Dashboard. * Get to the sessions that matter quicker; click into any intent or correction category (either from the Dashboard or the Agent page) to see a filtered view of the sessions containing that signal. * Fixed a bug where plans were not updating. * Fixed a calculation where events were being counted as sessions. ## June 12, 2026 * Introducing Smart Skills --where Voker automatically generates skills based on correction patterns across your agents. * Cleaned up our onboarding flow so you can get to agent insights quicker. * Fixed bugs related to dupe events, analytics calculations, and our agent overview . ## June 5, 2026 * Added token cost in various views across the platform, including the main dashboard page, session view and agents view. Cost is calculated based on the usage data sent in events. Cost for intent to be resolved is shown per agent: ## May 29, 2026 * Added Corrections Categories to Sessions Overview page and filters. * Improved Session Details page: system prompt now shown at the top, with better overflow handling for long messages, tool calls, and sessions with many tools or intents. * Added improved error messages for Python and Node SDKs when no `voker_session` parameter is supplied. * Python `voker v0.0.13` fixed import error for `Python<=3.10.0`. * Node `@voker/voker v0.0.12` improved config when manually supplying api key. * Added streaming support for AI SDK. ## May 1, 2026 * New sidebar with company and project switcher. * Added support and docs for [AI SDK](/providers/ai-sdk). * Added TypeScript code examples for [OpenAI](/providers/openai#typescript), [Anthropic](/providers/anthropic#typescript) and [Gemini](/providers/gemini#gemini). * Updated barchart colors. ## April 24, 2026 * Added agent name and version to the Agent Details page. * Improved chart labels on dashboard. * Added pending member invites to the settings page. * Fixed a bug where session paths were out of order. * Fixed nav and search bugs across platform. ## April 17, 2026 * Added option to signup with a magic link. * Expanded internal dogfooding ahead of the closed beta, resulting in multiple UI and usability improvements. ## April 10, 2026 * Expanded capabilities of Intents, Corrections, and Resolutions by adding tool calls to their context. * Made the following breaking changes (Python `voker v0.0.10` & Node `@voker/voker v0.0.7`) * `vokerSession` is now required for creating an event. * `vokerAgent` is now required for creating an event. * Fixed a bug where events were not being sent in Jupyter notebooks (Python `voker v0.0.10`). ## April 3, 2026 * Added time period and agent filters to the Dashboard page. * Added SDK Setup page with a step-by-step quickstart guide. ## March 27, 2026 * Released NPM `@voker/voker` package version `0.0.6` adding support for Gemini `generateContentStream`. * Added Global Search functionality to the platform, allowing users to search across agents, agent versions and people. * Introduced an "Invite Members" button in the sidebar navigation * Implemented Settings page with the following sections: * SDK Setup * Members & Roles * API Keys * Billing * Added Agent and Person summaries, providing insights into agent performance and user behavior trends. ## March 20, 2026 * Added example requests and responses to the [API Reference](/api-reference/create-event). * Added [Python SDK Reference](/sdks/python#python-sdk-reference) section with documentation for available classes and their methods. * Completed wrapping of Gemini Interactions API in the Python and TypeScript SDKs, with support for standard and streaming responses. * Refined the UI, along with underlying data fetching and processing logic, for the following pages: * Dashboard * Sessions (Aggregate/ Detail View) * Agents (Aggregate/ Detail View) * People (Aggregate/ Detail View) * Example: Agent Detail View ## March 6, 2026 * Added Corrections, Intents, Resolutions and Session Timeline to the Event Session details page, with UI elements in both the overview area and on each relevant message. * Fixed an issue where dark mode would not apply correctly to the page. * Added filter functionality to sessions, agents (both in aggregate and detailed views) and people pages.
## February 27, 2026 * Added new project level analytics dashboards: * Added corrections processing on event sessions ## February 20, 2026 * Expanded list of available API endpoints. [See here](/api-reference/create-event). * Released Python `voker` package version `0.0.3` and NPM `@voker/voker` package version `0.0.1` with support for added endpoints. ## February 13, 2026 * Foundational infrastructure updates. * Exciting functionality showcase soon: * Improved Python, Typescript and Go SDKs. * Intents, Resolution, and Correction analysis on Events. * Enhanced analytics and reporting features. ## February 6, 2026 * Foundational infrastructure updates. ## January 30, 2026 * Foundational infrastructure updates. ## January 23, 2026 * Added a `base_X_client` parameter to Python Anthropic, Gemini and OpenAI SDKs to allow use with other SDK wrappers such as with PostHog. * Added streaming support for Gemini Generate Content and Interactions APIs. ## January 16, 2026 * Added session summaries and outlines to the Sessions view. * Revised Agents page, added Agent descriptions and the ability to deprecate Agents and Agent Versions. ## January 9, 2026 * Added streaming support for OpenAI Chat Completions and Responses APIs. ## January 2, 2026 * Added [Waitlist Signup Page](https://app.voker.ai/sign-in) * Added the ability to full text search across session events. * Added system information to events to help with debugging. ## December 29, 2025 * Added Interactions API support for [Gemini](/providers/gemini). ## December 15, 2025 * Released [Python SDK](/sdks/python) with basic support for [OpenAI](/providers/openai), [Anthropic](/providers/anthropic) and [Gemini](/providers/gemini). * Added the `Create Events` endpoints to the [API](/api-reference/create-event). # Voker Python SDK Source: https://docs.voker.ai/sdks/python ## Installation ```bash pip theme={null} pip install voker ``` ```bash uv theme={null} uv add voker ``` ```bash poetry theme={null} poetry add voker ``` Make sure to set the environment variable `VOKER_API_KEY`. ## Quick start If you're using one of our supported SDKs, you can simply swap out the class you instantiate: ```py theme={null} from openai import OpenAI # [!code --] from voker.ai.provider_openai import OpenAI # [!code ++] client = OpenAI() client.chat.completions.create( voker_agent="customer-support-agent", # required [!code ++] voker_session="user-session-1", # required [!code ++] model="gpt-4.1-mini", messages=[ { "role": "user", "content": "Hello, world!", } ], ) ``` See provider specific setup instructions: [OpenAI](/providers/openai), [Anthropic](/providers/anthropic), and [Gemini](/providers/gemini). ## Python SDK Reference ### VokerClient The Voker Client provides a way to create and update Agents, Agent Versions, People and Events programmatically. Requests are made in a separate thread as the main process as to not add latency to your application. This is used by the SDKs but can also be used directly if you want more control over when requests are sent. #### Properties | Name | Type | Description | | ---------------- | --------------------------- | --------------------------------------------------------------------------- | | `agent_versions` | `VokerClient_AgentVersions` | Access [agent versions](/concepts/agents#agent-versions) related endpoints. | | `agents` | `VokerClient_Agents` | Access [agents](/concepts/agents#agents) related endpoints. | | `events` | `VokerClient_Events` | Access [events](/concepts/events#events) related endpoints. | | `people` | `VokerClient_People` | Access [people](/concepts/people) related endpoints. | #### Methods | Name | Description | | ------- | ------------------------------------------------------------------------------------------------------- | | `close` | Close the client. This will stop the background worker and flush any remaining events to the Voker API. | | `start` | Start the client. This will start the background worker that sends events to the Voker API. | #### Sub Clients ##### VokerClient\_AgentVersions Access [agent versions](/concepts/agents#agent-versions) related endpoints. Method `create` Create an agent version. See [Creating an Agent Version](/concepts/agents#creating-agent-version) for more information. **Parameters:** | Name | Type | Description | | -------------------- | --------------- | ------------------------------------------------------------ | | `agent_name` | `str` | The name of the existing agent that this version belongs to. | | `agent_version_name` | `str` | Unique identifier for the agent version within its agent. | | `description` | `Optional[str]` | | ##### VokerClient\_Agents Access [agents](/concepts/agents#agents) related endpoints. Method `create` Create an agent. See [Creating an Agent](/concepts/agents#creating-agent) for more information. **Parameters:** | Name | Type | Description | | ------------- | --------------- | -------------------------------- | | `agent_name` | `str` | Unique identifier for the agent. | | `description` | `Optional[str]` | | ##### VokerClient\_Events Access [events](/concepts/events#events) related endpoints. Method `create` Create a new [event](/concepts/events). **Parameters:** | Name | Type | Description | | --------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent` | `Optional[str]` | The name of the [agent](/concepts/agents#agents) associated with the event. If this agent does not exist, it will be created. | | `agent_version` | `Optional[str]` | The name of the [agent version](/concepts/agents#agent-versions) associated with the event. If this agent version does not exist, it will be created. If an agent version is not supplied, a default version will be used. | | `event_name` | `str` | | | `person` | `Optional[str]` | The unique identifier of the [person](/concepts/people) associated with the event. If the person does not exist, it will be created. | | `properties` | `EventProperties` | | | `session` | `str` | The unique identifier of the [session](/concepts/events#event-sessions) associated with the event. | ##### VokerClient\_People Access [people](/concepts/people) related endpoints. Method `create` Create a person. See [Creating a Person](/concepts/people#creating-a-person) for more information. **Parameters:** | Name | Type | Description | | ------------ | ---------------- | --------------------------------- | | `person_id` | `str` | Unique identifier for the person. | | `properties` | `dict[str, Any]` | | Method `update` Update a person. **Parameters:** | Name | Type | Description | | ------------ | ------ | ----------- | | `person_id` | `str` | | | `properties` | `dict` | | ### ApiClient The API Client provides a way to make requests to the Voker API directly. This is used under the hood by the Voker Client, but can also be used directly if you want more control over how requests are made. Fetching Agents, Agent Versions, and People is a common use case for using the API Client directly. #### Properties | Name | Type | Description | | ---------------- | ------------------------- | --------------------------------------------------------------------------- | | `agent_versions` | `ApiClient_AgentVersions` | Access [agent versions](/concepts/agents#agent-versions) related endpoints. | | `agents` | `ApiClient_Agents` | Access [agents](/concepts/agents#agents) related endpoints. | | `events` | `ApiClient_Events` | Access [events](/concepts/events#events) related endpoints. | | `fingerprints` | `ApiClient_Fingerprints` | Access [fingerprints](/concepts/events#fingerprints) related endpoints. | | `people` | `ApiClient_People` | Access [people](/concepts/people) related endpoints. | #### Sub Clients ##### ApiClient\_AgentVersions Access [agent versions](/concepts/agents#agent-versions) related endpoints. Method `create` Create an agent version. See [Creating an Agent Version](/concepts/agents#creating-agent-version) for more information. **Parameters:** | Name | Type | Description | | -------------------- | --------------- | ------------------------------------------------------------ | | `agent_name` | `str` | The name of the existing agent that this version belongs to. | | `agent_version_name` | `str` | Unique identifier for the agent version within its agent. | | `description` | `Optional[str]` | | **Returns:** | Type | Description | | -------------- | ----------- | | `AgentVersion` | | Method `get` Get an agent version. **Parameters:** | Name | Type | Description | | -------------------- | ----- | ----------- | | `agent_name` | `str` | | | `agent_version_name` | `str` | | **Returns:** | Type | Description | | -------------- | ----------- | | `AgentVersion` | | ##### ApiClient\_Agents Access [agents](/concepts/agents#agents) related endpoints. Method `create` Create an agent. See [Creating an Agent](/concepts/agents#creating-agent) for more information. **Parameters:** | Name | Type | Description | | ------------- | --------------- | -------------------------------- | | `agent_name` | `str` | Unique identifier for the agent. | | `description` | `Optional[str]` | | **Returns:** | Type | Description | | ------- | ----------- | | `Agent` | | Method `get` Get an agent. **Parameters:** | Name | Type | Description | | ------------ | ----- | ----------- | | `agent_name` | `str` | | **Returns:** | Type | Description | | ------- | ----------- | | `Agent` | | ##### ApiClient\_Events Access [events](/concepts/events) related endpoints. Method `create` Create a new [event](/concepts/events). **Parameters:** | Name | Type | Description | | ---------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent` | `Optional[str]` | The name of the [agent](/concepts/agents#agents) associated with the event. If this agent does not exist, it will be created. | | `agent_version` | `Optional[str]` | The name of the [agent version](/concepts/agents#agent-versions) associated with the event. If this agent version does not exist, it will be created. If an agent version is not supplied, a default version will be used. | | `event_name` | `str` | | | `fingerprint_id` | `str` | The [fingerprint](/concepts/events#fingerprints) of the client that generated the event. | | `person` | `Optional[str]` | The unique identifier of the [person](/concepts/people) associated with the event. If the person does not exist, it will be created. | | `properties` | `EventProperties` | | | `session` | `str` | The unique identifier of the [session](/concepts/events#event-sessions) associated with the event. | ##### ApiClient\_Fingerprints Access [fingerprints](/concepts/events#fingerprints) related endpoints. Method `create` Create a fingerprint. See [Fingerprints](/concepts/events#fingerprints) for more information. **Returns:** | Type | Description | | ------------- | ----------- | | `Fingerprint` | | ##### ApiClient\_People Access [people](/concepts/people) related endpoints. Method `get` Retrieve a [person](/concepts/people). **Parameters:** | Name | Type | Description | | ----------- | ----- | ----------- | | `person_id` | `str` | | **Returns:** | Type | Description | | -------- | ----------- | | `Person` | | Method `create` Create a person. See [Creating a Person](/concepts/people#creating-a-person) for more information. **Parameters:** | Name | Type | Description | | ------------ | ---------------- | --------------------------------- | | `person_id` | `str` | Unique identifier for the person. | | `properties` | `dict[str, Any]` | | **Returns:** | Type | Description | | -------- | ----------- | | `Person` | | Method `update` Update a person. **Parameters:** | Name | Type | Description | | ------------ | ------ | ----------- | | `person_id` | `str` | | | `properties` | `dict` | | **Returns:** | Type | Description | | -------- | ----------- | | `Person` | | ### Types #### Agent Represents an agent. See [Agents](/concepts/agents#agents) for more information. ##### Fields | Name | Type | Description | | --------------- | ------------------ | ------------------------------------ | | `agent_name` | `str` | Unique identifier for the agent. | | `description` | `str \| None` | | | `agent_number` | `int` | Unique number assigned to the agent. | | `created_at` | `datetime` | | | `deprecated_at` | `datetime \| None` | | #### AgentVersion Represents an agent version. See [Agent Versions](/concepts/agents#agent-versions) for more information. ##### Fields | Name | Type | Description | | ---------------------- | ------------------ | ------------------------------------------------------------- | | `agent_version_name` | `str` | Unique identifier for the agent version within its agent. | | `description` | `str \| None` | | | `agent_version_number` | `int` | Unique number assigned to the agent version within its agent. | | `created_at` | `datetime` | | | `deprecated_at` | `datetime \| None` | | #### Fingerprint Represents a fingerprint. See [Fingerprints](/concepts/events#fingerprints) for more information. ##### Fields | Name | Type | Description | | ---------------- | ----- | ----------- | | `fingerprint_id` | `str` | | #### Person Represents a person. See [People](/concepts/people) for more information. ##### Fields | Name | Type | Description | | ------------ | ------------------------ | ----------- | | `person_id` | `str` | | | `properties` | `dict[str, Any] \| None` | | | `created_at` | `datetime` | | # Voker TypeScript SDK Source: https://docs.voker.ai/sdks/typescript ## Installation ```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 ``` Make sure to set the environment variable `VOKER_API_KEY`. ## Quick start If you're using one of our supported SDKs, you can simply swap out the class you instantiate: ```ts 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({ vokerAgent: 'customer-support-agent', // required // [!code ++] vokerSession: 'user-session-1', // required // [!code ++] model: 'gpt-4o', messages: [ { role: 'user', content: 'Hello, world!', }, ], }); ``` See provider specific setup instructions: [OpenAI](/providers/openai#typescript), [Anthropic](/providers/anthropic#typescript), [Gemini](/providers/gemini#typescript), and [AI SDK](/providers/ai-sdk). ## Typescript SDK Reference ### VokerClient The Voker Client provides a way to create and update Agents, Agent Versions, People and Events programmatically. Requests are made in a separate thread as the main process as to not add latency to your application. This is used by the SDKs but can also be used directly if you want more control over when requests are sent. #### Fields | Name | Type | Description | | --------------- | --------------------------- | --------------------------------------------------------------------------- | | `agentVersions` | `VokerClient_AgentVersions` | Access [agent versions](/concepts/agents#agent-versions) related endpoints. | | `agents` | `VokerClient_Agents` | Access [agents](/concepts/agents#agents) related endpoints. | | `events` | `VokerClient_Events` | Access [events](/concepts/events#events) related endpoints. | | `people` | `VokerClient_People` | Access [people](/concepts/people) related endpoints. | #### Methods | Name | Description | | ------- | ------------------------------------------------------------------------------------------------------- | | `close` | Close the client. This will stop the background worker and flush any remaining events to the Voker API. | | `start` | Start the client. This will start the background worker that sends events to the Voker API. | #### Sub Clients ##### VokerClient\_AgentVersions Access [agent versions](/concepts/agents#agent-versions) related endpoints. Method `create` Create an agent version. See [Creating an Agent Version](/concepts/agents#creating-agent-version) for more information. **Parameters:** | Name | Type | Description | | ----------- | --------------------------- | ----------- | | `agentName` | `string` | | | `payload` | `CreateAgentVersionPayload` | | ##### VokerClient\_Agents Access [agents](/concepts/agents#agents) related endpoints. Method `create` Create an agent. See [Creating an Agent](/concepts/agents#creating-agent) for more information. **Parameters:** | Name | Type | Description | | --------- | -------------------- | ----------- | | `payload` | `CreateAgentPayload` | | ##### VokerClient\_Events Access [events](/concepts/events#events) related endpoints. Method `create` Create a new [event](/concepts/events). **Parameters:** | Name | Type | Description | | --------- | -------------------------- | ----------- | | `payload` | `ClientCreateEventPayload` | | ##### VokerClient\_People Access [people](/concepts/people) related endpoints. Method `create` Create a person. See [Creating a Person](/concepts/people#creating-a-person) for more information. **Parameters:** | Name | Type | Description | | --------- | --------------------- | ----------- | | `payload` | `CreatePersonPayload` | | Method `update` Update a person. **Parameters:** | Name | Type | Description | | ---------- | --------------------- | ----------- | | `personId` | `string` | | | `payload` | `UpdatePersonPayload` | | ### ApiClient The API Client provides a way to make requests to the Voker API directly. This is used under the hood by the Voker Client, but can also be used directly if you want more control over how requests are made. Fetching Agents, Agent Versions, and People is a common use case for using the API Client directly. #### Fields | Name | Type | Description | | --------------- | ------------------------- | --------------------------------------------------------------------------- | | `agentVersions` | `ApiClient_AgentVersions` | Access [agent versions](/concepts/agents#agent-versions) related endpoints. | | `agents` | `ApiClient_Agents` | Access [agents](/concepts/agents#agents) related endpoints. | | `events` | `ApiClient_Events` | Access [events](/concepts/events#events) related endpoints. | | `fingerprints` | `ApiClient_Fingerprints` | Access [fingerprints](/concepts/events#fingerprints) related endpoints. | | `people` | `ApiClient_People` | Access [people](/concepts/people) related endpoints. | #### Sub Clients ##### ApiClient\_AgentVersions Access [agent versions](/concepts/agents#agent-versions) related endpoints. Method `create` Create an agent version. See [Creating an Agent Version](/concepts/agents#creating-agent-version) for more information. **Parameters:** | Name | Type | Description | | ----------- | --------------------------- | ----------- | | `agentName` | `string` | | | `payload` | `CreateAgentVersionPayload` | | **Returns:** | Type | Description | | ----------------------- | ----------- | | `Promise` | | Method `get` Get an agent version. **Parameters:** | Name | Type | Description | | ------------------ | -------- | ----------- | | `agentName` | `string` | | | `agentVersionName` | `string` | | **Returns:** | Type | Description | | ----------------------- | ----------- | | `Promise` | | ##### ApiClient\_Agents Access [agents](/concepts/agents#agents) related endpoints. Method `create` Create an agent. See [Creating an Agent](/concepts/agents#creating-agent) for more information. **Parameters:** | Name | Type | Description | | --------- | -------------------- | ----------- | | `payload` | `CreateAgentPayload` | | **Returns:** | Type | Description | | ---------------- | ----------- | | `Promise` | | Method `get` Get an agent. **Parameters:** | Name | Type | Description | | ----------- | -------- | ----------- | | `agentName` | `string` | | **Returns:** | Type | Description | | ---------------- | ----------- | | `Promise` | | ##### ApiClient\_Events Access [events](/concepts/events#events) related endpoints. Method `create` Create a new [event](/concepts/events). **Parameters:** | Name | Type | Description | | --------- | -------------------- | ----------- | | `payload` | `CreateEventPayload` | | ##### ApiClient\_Fingerprints Access [fingerprints](/concepts/events#fingerprints) related endpoints. Method `create` Create a fingerprint. See [Creating a Fingerprint](/concepts/events#creating-a-fingerprint) for more information. **Returns:** | Type | Description | | ---------------------- | ----------- | | `Promise` | | ##### ApiClient\_People Access [people](/concepts/people) related endpoints. Method `create` Create a person. See [Creating a Person](/concepts/people#creating-a-person) for more information. **Parameters:** | Name | Type | Description | | --------- | --------------------- | ----------- | | `payload` | `CreatePersonPayload` | | **Returns:** | Type | Description | | ----------------- | ----------- | | `Promise` | | Method `get` Get a person. **Parameters:** | Name | Type | Description | | ---------- | -------- | ----------- | | `personId` | `string` | | **Returns:** | Type | Description | | ----------------- | ----------- | | `Promise` | | Method `update` Update a person. **Parameters:** | Name | Type | Description | | ---------- | --------------------- | ----------- | | `personId` | `string` | | | `payload` | `UpdatePersonPayload` | | **Returns:** | Type | Description | | ----------------- | ----------- | | `Promise` | | ### Types #### CreateAgentVersionPayload Create an agent version. See [Creating an Agent Version](/concepts/agents#creating-agent-version) for more information. ##### Fields | Name | Type | Description | | ------------------ | ----------------------------- | --------------------------------------------------------- | | `agentVersionName` | `string` | Unique identifier for the agent version within its agent. | | `description` | `string \| null \| undefined` | | #### CreateAgentPayload Create an agent. See [Creating an Agent](/concepts/agents#creating-agent) for more information. ##### Fields | Name | Type | Description | | ------------- | ----------------------------- | -------------------------------- | | `agentName` | `string` | Unique identifier for the agent. | | `description` | `string \| null \| undefined` | | #### ClientCreateEventPayload Create an event. See [Creating an Event](/concepts/events#creating-an-event-via-sdk) for more information. ##### Fields | Name | Type | Description | | ------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `vokerAgent` | `string \| undefined` | The name of the [agent](/concepts/agents#agents) associated with the event. If this agent does not exist, it will be created. | | `vokerAgentVersion` | `string \| undefined` | The name of the [agent version](/concepts/agents#agent-versions) associated with the event. If this agent version does not exist, it will be created. If an agent version is not supplied, a default version will be used. | | `vokerPerson` | `string \| undefined` | The unique identifier of the [person](/concepts/people) associated with the event. If the person does not exist, it will be created. | | `vokerSession` | `string` | The unique identifier of the [session](/concepts/events#event-sessions) associated with the event. | | `eventName` | `string` | | | `properties` | `Record` | | #### CreateEventPayload ##### Fields | Name | Type | Description | | ------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `vokerAgent` | `string \| undefined` | The name of the [agent](/concepts/agents#agents) associated with the event. If this agent does not exist, it will be created. | | `vokerAgentVersion` | `string \| undefined` | The name of the [agent version](/concepts/agents#agent-versions) associated with the event. If this agent version does not exist, it will be created. If an agent version is not supplied, a default version will be used. | | `vokerPerson` | `string \| undefined` | The unique identifier of the [person](/concepts/people) associated with the event. If the person does not exist, it will be created. | | `vokerSession` | `string` | The unique identifier of the [session](/concepts/events#event-sessions) associated with the event. | | `eventName` | `string` | | | `properties` | `Record` | | | `fingerprintId` | `string` | The [fingerprint](/concepts/events#fingerprints) of the client that generated the event. | #### CreateEventVokerParams ##### Fields | Name | Type | Description | | ------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `vokerAgent` | `string \| undefined` | The name of the [agent](/concepts/agents#agents) associated with the event. If this agent does not exist, it will be created. | | `vokerAgentVersion` | `string \| undefined` | The name of the [agent version](/concepts/agents#agent-versions) associated with the event. If this agent version does not exist, it will be created. If an agent version is not supplied, a default version will be used. | | `vokerPerson` | `string \| undefined` | The unique identifier of the [person](/concepts/people) associated with the event. If the person does not exist, it will be created. | | `vokerSession` | `string` | The unique identifier of the [session](/concepts/events#event-sessions) associated with the event. | #### CreateLlmEventVokerParams ##### Fields | Name | Type | Description | | ------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `vokerAgent` | `string` | The name of the [agent](/concepts/agents#agents) associated with the event. | | `vokerSession` | `string` | The unique identifier of the [session](/concepts/events#event-sessions) associated with the event. | | `vokerAgentVersion` | `string \| undefined` | The name of the [agent version](/concepts/agents#agent-versions) associated with the event. If this agent version does not exist, it will be created. If an agent version is not supplied, a default version will be used. | | `vokerPerson` | `string \| undefined` | The unique identifier of the [person](/concepts/people) associated with the event. If the person does not exist, it will be created. | #### CreateFingerprintPayload Create a fingerprint. See [Creating a Fingerprint](/concepts/events#creating-a-fingerprint) for more information. ##### Fields | Name | Type | Description | | --------------------- | ------------------------------------- | ----------- | | `language` | `string` | | | `languageVersion` | `string` | | | `system` | `string` | | | `openaiSdkVersion` | `string \| undefined` | | | `anthropicSdkVersion` | `string \| undefined` | | | `geminiSdkVersion` | `string \| undefined` | | | `vokerSdkVersion` | `string \| undefined` | | | `allPackages` | `Record \| undefined` | | | `gitRepositoryUrl` | `string \| undefined` | | | `gitBranch` | `string \| undefined` | | | `gitCommitHash` | `string \| undefined` | | | `gitCommitDate` | `string \| undefined` | | #### CreatePersonPayload Create a person. See [Creating a Person](/concepts/people#creating-a-person) for more information. ##### Fields | Name | Type | Description | | ------------ | ---------------------------------- | ----------- | | `personId` | `string` | | | `properties` | `Record \| undefined` | | #### UpdatePersonPayload Update a person. ##### Fields | Name | Type | Description | | ------------ | --------------------- | ----------- | | `properties` | `Record` | | #### AgentVersion Represents an agent version. See [Agent Versions](/concepts/agents#agent-versions) for more information. ##### Fields | Name | Type | Description | | -------------------- | ---------------- | ------------------------------------------------------------- | | `agentVersionName` | `string` | Unique identifier for the agent version within its agent. | | `description` | `string \| null` | | | `agentVersionNumber` | `number` | Unique number assigned to the agent version within its agent. | | `createdAt` | `Date` | | | `deprecatedAt` | `Date \| null` | | #### Agent Represents an agent. See [Agents](/concepts/agents#agents) for more information. ##### Fields | Name | Type | Description | | -------------- | ---------------- | ------------------------------------ | | `agentName` | `string` | Unique identifier for the agent. | | `description` | `string \| null` | | | `agentNumber` | `number` | Unique number assigned to the agent. | | `createdAt` | `Date` | | | `deprecatedAt` | `Date \| null` | | #### Fingerprint Represents a fingerprint. See [Fingerprints](/concepts/events#fingerprints) for more information. ##### Fields | Name | Type | Description | | --------------- | -------- | ----------- | | `fingerprintId` | `string` | | #### Person Represents a person. See [People](/concepts/people) for more information. ##### Fields | Name | Type | Description | | ------------ | ----------------------------- | ----------- | | `personId` | `string` | | | `properties` | `Record \| null` | | | `createdAt` | `Date` | |