Installation
Set the VOKER_API_KEY environment variable to your API key before using the SDK. You can find your key in the Voker dashboard under settings.
Quick start
Replace your existing LLM provider import with the Voker-wrapped version. No other code changes are required.
from openai import OpenAI
from voker.ai.provider_openai import OpenAI
client = OpenAI()
client.chat.completions.create(
voker_agent="customer-support-agent", # required
voker_session="user-session-1", # required
model="gpt-4.1-mini",
messages=[{"role": "user", "content": "Hello, world!"}],
)
voker_agent parameter identifies which agent handled the request. The voker_session parameter ties the call to a specific session. Both are required for Voker to associate the event with the correct agent and session in your dashboard.
For provider-specific setup guides, see OpenAI, Anthropic, and Gemini.
Python SDK Reference
VokerClient
The Voker Client provides a way to create an 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.
Class VokerClient
| Field | Type | Description |
|---|
events | VokerClient_Events | Create events tied to sessions, agents, and people. |
people | VokerClient_People | Create and update person records. |
agents | VokerClient_Agents | Create agent records. |
agent_versions | VokerClient_AgentVersions | Create agent version records. |
close() - Waits for all pending background requests to complete and shuts down the worker thread. Call this before your process exits to avoid dropped events.
Class VokerClient_Agents
create(agent_name: str, description: Optional[str]) - Creates an agent with the given name. If the agent already exists, the call is a no-op.
Class VokerClient_AgentVersions
create(agent_name: str, agent_version_name: str, description: Optional[str]) - Creates a new version under the specified agent.
Class VokerClient_Events
create(event_name: str, properties: EventProperties, session: str, agent: Optional[str], agent_version: Optional[str], person: Optional[str]) - Enqueues an event for background delivery. session is required; all other association fields are optional.
Class VokerClient_People
create(person_id: str, properties: dict[str, Any]) - Creates a person record with the given ID and properties. If the person already exists, the call is a no-op.
update(person_id: str, properties: dict) - Merges the provided properties into an existing person record.
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.
Class ApiClient
| Field | Type | Description |
|---|
events | ApiClient_Events | Create events directly via the API. |
people | ApiClient_People | Get, create, and update person records. |
fingerprints | ApiClient_Fingerprints | Create anonymous fingerprint identifiers. |
agents | ApiClient_Agents | Create and fetch agent records. |
agent_versions | ApiClient_AgentVersions | Create and fetch agent version records. |
ApiClient_Agents
create(agent_name: str, description: Optional[str]) -> Agent - Creates and returns a new agent.
get(agent_name: str) -> Agent - Returns the agent with the given name.
Class ApiClient_AgentVersions
create(agent_name: str, agent_version_name: str, description: Optional[str]) -> AgentVersion - Creates and returns a new version under the given agent.
get(agent_name: str, agent_version_name: str) -> AgentVersion - Returns the specified agent version.
Class ApiClient_Events
create(event_name: str, properties: EventProperties, session: str, fingerprint_id: str, agent: Optional[str], agent_version: Optional[str], person: Optional[str]) - Creates an event. Unlike VokerClient_Events, this method requires a fingerprint_id.
Class ApiClient_Fingerprints
create() -> Fingerprint - Generates and returns a new anonymous fingerprint identifier.
Class ApiClient_People
get(person_id: str) -> Person - Returns the person with the given ID.
create(person_id: str, properties: dict[str, Any]) -> Person - Creates and returns a new person.
update(person_id: str, properties: dict) -> Person - Merges properties into an existing person and returns the updated record.
Types
These Python data classes are returned by ApiClient methods.
Agent
Represents an AI agent registered in Voker.
| Field | Type | Description |
|---|
agent_name | str | Unique identifier name for the agent. |
description | str | None | Optional human-readable description. |
agent_number | int | Auto-assigned numeric identifier. |
created_at | datetime | Timestamp when the agent was created. |
deprecated_at | datetime | None | Timestamp when the agent was deprecated, if ever. |
AgentVersion
Represents a specific version of an agent.
| Field | Type | Description |
|---|
agent_version_name | str | Unique name for this version within the agent. |
description | str | None | Optional description. |
agent_version_number | int | Auto-assigned numeric identifier. |
created_at | datetime | Timestamp when the version was created. |
deprecated_at | datetime | None | Timestamp when the version was deprecated, if ever. |
Fingerprint
An anonymous identifier used to track activity without a known person ID.
| Field | Type | Description |
|---|
fingerprint_id | str | Unique fingerprint value. |
Person
Represents a user or entity tracked in Voker.
| Field | Type | Description |
|---|
person_id | str | Your application’s identifier for this person. |
properties | dict[str, Any] | None | Arbitrary key-value metadata. |
created_at | datetime | Timestamp when the person was first created. |
