> ## 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 TypeScript SDK

## Installation

<CodeGroup>
  ```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
  ```
</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:

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

<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 |
| ----------- | --------------------------- | ----------- |
| `agentName` | `string`                    |             |
| `payload`   | `CreateAgentVersionPayload` |             |

##### 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 |
| --------- | -------------------- | ----------- |
| `payload` | `CreateAgentPayload` |             |

##### VokerClient\_Events

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

<Badge>Method</Badge> `create`

Create a new [event](/concepts/events).

**Parameters:**

| Name      | Type                       | Description |
| --------- | -------------------------- | ----------- |
| `payload` | `ClientCreateEventPayload` |             |

##### 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 |
| --------- | --------------------- | ----------- |
| `payload` | `CreatePersonPayload` |             |

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

<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 |
| ----------- | --------------------------- | ----------- |
| `agentName` | `string`                    |             |
| `payload`   | `CreateAgentVersionPayload` |             |

**Returns:**

| Type                    | Description |
| ----------------------- | ----------- |
| `Promise<AgentVersion>` |             |

<Badge>Method</Badge> `get`

Get an agent version.

**Parameters:**

| Name               | Type     | Description |
| ------------------ | -------- | ----------- |
| `agentName`        | `string` |             |
| `agentVersionName` | `string` |             |

**Returns:**

| Type                    | Description |
| ----------------------- | ----------- |
| `Promise<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 |
| --------- | -------------------- | ----------- |
| `payload` | `CreateAgentPayload` |             |

**Returns:**

| Type             | Description |
| ---------------- | ----------- |
| `Promise<Agent>` |             |

<Badge>Method</Badge> `get`

Get an agent.

**Parameters:**

| Name        | Type     | Description |
| ----------- | -------- | ----------- |
| `agentName` | `string` |             |

**Returns:**

| Type             | Description |
| ---------------- | ----------- |
| `Promise<Agent>` |             |

##### ApiClient\_Events

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

<Badge>Method</Badge> `create`

Create a new [event](/concepts/events).

**Parameters:**

| Name      | Type                 | Description |
| --------- | -------------------- | ----------- |
| `payload` | `CreateEventPayload` |             |

##### ApiClient\_Fingerprints

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

<Badge>Method</Badge> `create`

Create a fingerprint.

See [Creating a Fingerprint](/concepts/events#creating-a-fingerprint) for more information.

**Returns:**

| Type                   | Description |
| ---------------------- | ----------- |
| `Promise<Fingerprint>` |             |

##### ApiClient\_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 |
| --------- | --------------------- | ----------- |
| `payload` | `CreatePersonPayload` |             |

**Returns:**

| Type              | Description |
| ----------------- | ----------- |
| `Promise<Person>` |             |

<Badge>Method</Badge> `get`

Get a person.

**Parameters:**

| Name       | Type     | Description |
| ---------- | -------- | ----------- |
| `personId` | `string` |             |

**Returns:**

| Type              | Description |
| ----------------- | ----------- |
| `Promise<Person>` |             |

<Badge>Method</Badge> `update`

Update a person.

**Parameters:**

| Name       | Type                  | Description |
| ---------- | --------------------- | ----------- |
| `personId` | `string`              |             |
| `payload`  | `UpdatePersonPayload` |             |

**Returns:**

| Type              | Description |
| ----------------- | ----------- |
| `Promise<Person>` |             |

### 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<string, any>` |                                                                                                                                                                                                                            |

#### 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<string, any>` |                                                                                                                                                                                                                            |
| `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<string, string> \| 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<string, any> \| undefined` |             |

#### UpdatePersonPayload

Update a person.

##### Fields

| Name         | Type                  | Description |
| ------------ | --------------------- | ----------- |
| `properties` | `Record<string, any>` |             |

#### 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<string, any> \| null` |             |
| `createdAt`  | `Date`                        |             |