> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voker.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Voker Python SDK

## Installation

<CodeGroup>
  ```bash pip theme={null}
  pip install voker
  ```

  ```bash uv theme={null}
  uv add voker
  ```

  ```bash poetry theme={null}
  poetry add voker
  ```
</CodeGroup>

<Note>
  Make sure to set the environment variable `VOKER_API_KEY`.
</Note>

## 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.

<Badge>Method</Badge> `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.

<Badge>Method</Badge> `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.

<Badge>Method</Badge> `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.

<Badge>Method</Badge> `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]` |                                   |

<Badge>Method</Badge> `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.

<Badge>Method</Badge> `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` |             |

<Badge>Method</Badge> `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.

<Badge>Method</Badge> `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` |             |

<Badge>Method</Badge> `get`

Get an agent.

**Parameters:**

| Name         | Type  | Description |
| ------------ | ----- | ----------- |
| `agent_name` | `str` |             |

**Returns:**

| Type    | Description |
| ------- | ----------- |
| `Agent` |             |

##### ApiClient\_Events

Access [events](/concepts/events) related endpoints.

<Badge>Method</Badge> `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.

<Badge>Method</Badge> `create`

Create a fingerprint.

See [Fingerprints](/concepts/events#fingerprints) for more information.

**Returns:**

| Type          | Description |
| ------------- | ----------- |
| `Fingerprint` |             |

##### ApiClient\_People

Access [people](/concepts/people) related endpoints.

<Badge>Method</Badge> `get`

Retrieve a [person](/concepts/people).

**Parameters:**

| Name        | Type  | Description |
| ----------- | ----- | ----------- |
| `person_id` | `str` |             |

**Returns:**

| Type     | Description |
| -------- | ----------- |
| `Person` |             |

<Badge>Method</Badge> `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` |             |

<Badge>Method</Badge> `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`               |             |