# TypeScript (/en/api-reference/api-ref/server-sdk/typescript)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Full API reference for the Agora Conversational AI TypeScript SDK.

## AgoraClient [#agoraclient]

`AgoraClient` extends the Fern-generated base client with domain pool support for regional URL cycling and three authentication modes. Pass `appId` and `appCertificate` only for the recommended app-credentials mode. The SDK mints fresh REST tokens per request and generates RTC join tokens at session start.

```typescript
import { AgoraClient, Area } from 'agora-agents';
```

### Constructor [#constructor]

```typescript
const client = new AgoraClient(options: AgoraClient.Options);
```

The authentication mode is resolved automatically from the options you provide.

| Option           | Type            | Required | Description                                                             |
| ---------------- | --------------- | -------- | ----------------------------------------------------------------------- |
| `area`           | [`Area`](#area) | Yes      | Region for API routing (`Area.US`, `Area.EU`, `Area.AP`, `Area.CN`)     |
| `appId`          | `string`        | Yes      | Agora App ID                                                            |
| `appCertificate` | `string`        | Yes      | Agora App Certificate. Keep this secret and never expose it client-side |
| `customerId`     | `string`        | No       | Customer ID for Basic Auth                                              |
| `customerSecret` | `string`        | No       | Customer Secret for Basic Auth                                          |
| `authToken`      | `string`        | No       | Pre-built `agora token=<value>` string                                  |
| `timeout`        | `number`        | No       | Request timeout in milliseconds                                         |
| `maxRetries`     | `number`        | No       | Maximum retry attempts                                                  |
| `fetch`          | `typeof fetch`  | No       | Custom fetch implementation for unsupported runtimes                    |

Authentication mode is resolved from the options you provide:

| Options provided                | Resolved [`authMode`](#agoraauthmode) |
| ------------------------------- | ------------------------------------- |
| `customerId` + `customerSecret` | `"basic"`                             |
| `authToken`                     | `"token"`                             |
| Neither                         | `"app-credentials"`                   |

See [Authentication](/en/api-reference/api-ref/conversational-ai/authentication) for details on each mode.

### Properties [#properties]

The following read-only properties are available on any `AgoraClient` instance.

| Property         | Type                              | Description                                                   |
| ---------------- | --------------------------------- | ------------------------------------------------------------- |
| `appId`          | `string`                          | The Agora App ID                                              |
| `appCertificate` | `string`                          | The Agora App Certificate                                     |
| `authMode`       | [`AgoraAuthMode`](#agoraauthmode) | The resolved authentication mode                              |
| `pool`           | `Pool`                            | The underlying domain pool instance used for regional routing |

### Methods [#methods]

The following methods are available in addition to the Fern-generated sub-client methods.

#### `nextRegion()` [#nextregion]

Cycles to the next region prefix in the domain pool. Call this after a request failure to try a different regional endpoint.

```typescript
client.nextRegion();
```

#### `selectBestDomain(signal?)` [#selectbestdomainsignal]

Trigger a manual DNS resolution check to select the best domain suffix. This runs automatically every 30 seconds, but you can call it manually.

```typescript
await client.selectBestDomain();
```

| Parameter | Type          | Description                                   |
| --------- | ------------- | --------------------------------------------- |
| `signal`  | `AbortSignal` | Optional abort signal to cancel the DNS check |

#### `getCurrentURL()` [#getcurrenturl]

Returns the full API URL currently in use as a `string`.

```typescript
const url = client.getCurrentURL();
// Example: 'https://api-us-west-1.agora.io/api/conversational-ai-agent'
```

### Sub-clients [#sub-clients]

`AgoraClient` exposes Fern-generated sub-clients for direct REST API access. You typically do not need these when using the [agentkit layer](#agent).

| Property              | Description                                                     |
| --------------------- | --------------------------------------------------------------- |
| `client.agents`       | Start, stop, update, speak, interrupt, get history, list agents |
| `client.telephony`    | Telephony operations                                            |
| `client.phoneNumbers` | Phone number management                                         |

For full method signatures and request parameters, see the [REST API reference](/en/api-reference/api-ref/conversational-ai/join).

## Agent [#agent]

`Agent` is an immutable configuration object. Each builder method returns a new `Agent` instance — the original is never modified. Define one `Agent` at startup and call `createSession()` on it for each user conversation.

```typescript
import { Agent } from 'agora-agent-sdk';
```

### Constructor [#constructor-1]

```typescript
new Agent(options?: AgentOptions)
```

All options are optional. Use the [builder methods](#builder-methods) to set vendor configuration after construction.

| Option             | Type                  | Default     | Description                                                |
| ------------------ | --------------------- | ----------- | ---------------------------------------------------------- |
| `name`             | `string`              | `undefined` | Agent name, used as the default session name               |
| `instructions`     | `string`              | `undefined` | LLM system prompt                                          |
| `greeting`         | `string`              | `undefined` | First message spoken when the session starts               |
| `failureMessage`   | `string`              | `undefined` | Message spoken when an LLM call fails                      |
| `maxHistory`       | `number`              | `undefined` | Maximum conversation turns kept in LLM context             |
| `turnDetection`    | `TurnDetectionConfig` | `undefined` | Voice activity detection settings                          |
| `interruption`     | `InterruptionConfig`  | `undefined` | Unified interruption control settings                      |
| `sal`              | `SalConfig`           | `undefined` | Selective Attention Locking configuration                  |
| `avatar`           | `AvatarConfig`        | `undefined` | Avatar configuration                                       |
| `advancedFeatures` | `AdvancedFeatures`    | `undefined` | Enable MLLM mode, AI-VAD, and other advanced features      |
| `parameters`       | `SessionParams`       | `undefined` | Session parameters including silence and farewell config   |
| `geofence`         | `GeofenceConfig`      | `undefined` | Regional access restriction                                |
| `labels`           | `Labels`              | `undefined` | Custom key-value labels returned in notification callbacks |
| `rtc`              | `RtcConfig`           | `undefined` | RTC media encryption                                       |
| `fillerWords`      | `FillerWordsConfig`   | `undefined` | Filler words played while waiting for the LLM response     |

### Builder methods [#builder-methods]

All builder methods return a **new** `Agent` instance. The original is never modified.

#### `withLlm(vendor)` [#withllmvendor]

Sets the LLM vendor. Pass an instance of [`OpenAI`](#openai), [`AzureOpenAI`](#azureopenai), [`Anthropic`](#anthropic), or [`Gemini`](#gemini).

```typescript
withLlm(vendor: BaseLLM): Agent<TTSSampleRate>
```

#### `withTts(vendor)` [#withttsvendor]

Sets the TTS vendor. The sample rate type is captured and tracked for [avatar](#avatar-vendors) compatibility.

```typescript
withTts<SR extends number>(vendor: BaseTTS<SR>): Agent<SR>
```

#### `withStt(vendor)` [#withsttvendor]

Sets the STT vendor. Pass an instance of any [STT vendor class](#stt-vendors).

```typescript
withStt(vendor: BaseSTT): Agent<TTSSampleRate>
```

#### `withMllm(vendor)` [#withmllmvendor]

Sets the MLLM vendor for multimodal mode. Pass [`OpenAIRealtime`](#openairealtime), [`GeminiLive`](#geminilive), [`VertexAI`](#vertexai), or [`XaiGrok`](#xaigrok). Calling `withMllm()` automatically sets `mllm.enable = true`. MLLM mode does not require `withTts()` / `withLlm()` / `withStt()`.

<CalloutContainer type="info">
  <CalloutDescription>
    Avatars are only supported with the cascading ASR + LLM + TTS pipeline. If you combine `withMllm()` with `withAvatar()`, the SDK throws an error when `toProperties()` or `session.start()` is called.
  </CalloutDescription>
</CalloutContainer>

```typescript
withMllm(vendor: BaseMLLM): Agent<TTSSampleRate>
```

#### `withAvatar(vendor)` [#withavatarvendor]

Sets the avatar vendor. The `this` constraint enforces at compile time that the agent's TTS sample rate matches the avatar's required rate.

<CalloutContainer type="info">
  <CalloutDescription>
    Requires the cascading ASR + LLM + TTS pipeline. If you combine `withAvatar()` with `withMllm()`, the SDK throws an error when `toProperties()` or `session.start()` is called.
  </CalloutDescription>
</CalloutContainer>

```typescript
withAvatar<RequiredSR extends number>(
  this: Agent<RequiredSR>,
  vendor: BaseAvatar<RequiredSR>
): Agent<RequiredSR>
```

#### `withTurnDetection(config)` [#withturndetectionconfig]

Configures cascading-flow turn detection. Use `config.start_of_speech` and `config.end_of_speech` for SOS/EOS detection. Use `withInterruption()` for interruption behavior and MLLM vendor `turnDetection` for MLLM turn detection.

```typescript
withTurnDetection(config: TurnDetectionConfig): Agent<TTSSampleRate>
```

#### `withInterruption(config)` [#withinterruptionconfig]

Configures unified interruption behavior using the top-level `interruption` object. Use this for `start_of_speech` and `keywords` interruption modes.

```typescript
withInterruption(config: InterruptionConfig): Agent<TTSSampleRate>
```

#### `withInstructions(text)` [#withinstructionstext]

Overrides the LLM system prompt on a new `Agent` instance.

```typescript
withInstructions(instructions: string): Agent<TTSSampleRate>
```

#### `withGreeting(text)` [#withgreetingtext]

Overrides the greeting message on a new `Agent` instance.

```typescript
withGreeting(greeting: string): Agent<TTSSampleRate>
```

#### `withName(name)` [#withnamename]

Overrides the agent name on a new `Agent` instance.

```typescript
withName(name: string): Agent<TTSSampleRate>
```

#### Other builder methods [#other-builder-methods]

The following methods follow the same pattern — each returns a new `Agent` instance with the updated configuration.

| Method                             | Parameter type            | Description                                                                                                                                                    |
| ---------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `withSal(config)`                  | `SalConfig`               | Set Selective Attention Locking configuration                                                                                                                  |
| `withAdvancedFeatures(features)`   | `AdvancedFeatures`        | Set advanced features                                                                                                                                          |
| `withTools(enabled)`               | `boolean`                 | Enable or disable MCP tool invocation                                                                                                                          |
| `withParameters(parameters)`       | `SessionParams`           | Set session parameters                                                                                                                                         |
| `withAudioScenario(audioScenario)` | `ParametersAudioScenario` | Set `parameters.audio_scenario`. Use the exported `AudioScenario` constants for discoverability, for example `agent.withAudioScenario(AudioScenario.Aiserver)` |
| `withFailureMessage(message)`      | `string`                  | Set the message spoken when the LLM fails                                                                                                                      |
| `withMaxHistory(n)`                | `number`                  | Set the maximum conversation history length for the standard LLM pipeline. The v2.7 MLLM core schema does not expose a `max_history` field                     |
| `withGeofence(geofence)`           | `GeofenceConfig`          | Set geofence configuration                                                                                                                                     |
| `withLabels(labels)`               | `Labels`                  | Set custom labels                                                                                                                                              |
| `withRtc(rtc)`                     | `RtcConfig`               | Set RTC configuration                                                                                                                                          |
| `withFillerWords(fillerWords)`     | `FillerWordsConfig`       | Set filler words configuration                                                                                                                                 |

### `createSession(client, options)` [#createsessionclient-options]

Creates an [`AgentSession`](#agentsession) bound to a specific client and channel. Does not start the agent — call [`session.start()`](#start) to join the channel.

```typescript
createSession(
  client: AgoraClient,
  options: SessionOptions,
): AgentSession
```

`SessionOptions` fields:

| Option            | Type                        | Required | Description                                                                                                                                       |
| ----------------- | --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `channel`         | `string`                    | Yes      | Channel name to join                                                                                                                              |
| `agentUid`        | `string`                    | Yes      | The agent's RTC UID                                                                                                                               |
| `remoteUids`      | `string[]`                  | Yes      | Remote user UIDs the agent listens and responds to                                                                                                |
| `name`            | `string`                    | No       | Session name. Defaults to agent name or `agent-{timestamp}`                                                                                       |
| `token`           | `string`                    | No       | Pre-built RTC+RTM token. Omit to auto-generate from app credentials                                                                               |
| `expiresIn`       | `number`                    | No       | Token lifetime in seconds. Only applies when the token is auto-generated. Valid range: 1–86400. Use [`ExpiresIn`](#expiresin) helpers for clarity |
| `idleTimeout`     | `number`                    | No       | Seconds before the agent auto-exits when no audio is detected. `0` disables the timeout                                                           |
| `enableStringUid` | `boolean`                   | No       | Use string UIDs instead of numeric UIDs                                                                                                           |
| `preset`          | `string \| AgentPreset[]`   | No       | Advanced project-specific presets. Use only when Agora provides a specific preset ID for your project. Most applications should leave it unset    |
| `pipelineId`      | `string`                    | No       | Published AI Studio pipeline ID to use as the base configuration                                                                                  |
| `debug`           | `boolean`                   | No       | Log API requests to the console                                                                                                                   |
| `warn`            | `(message: string) => void` | No       | Custom warning logger; pass a no-op to silence warnings                                                                                           |

`preset` is session-scoped because the underlying Agora start/join API applies presets per session, not per reusable `Agent` definition.

When you omit credentials for supported reseller-backed vendor models, AgentKit infers the matching session preset automatically:

* Deepgram STT: `nova-2`, `nova-3`
* OpenAI LLM: `gpt-4o-mini`, `gpt-4.1-mini`, `gpt-5-nano`, `gpt-5-mini`
* OpenAI TTS: `tts-1`
* MiniMax TTS: `speech-2.6-turbo`, `speech-2.8-turbo`

If you provide your own vendor API key for those same models, AgentKit keeps the request in BYOK mode and does not infer a preset.

### Properties [#properties-1]

Read-only properties available on any `Agent` instance.

| Property           | Type                               | Description                           |
| ------------------ | ---------------------------------- | ------------------------------------- |
| `name`             | `string \| undefined`              | Agent name                            |
| `instructions`     | `string \| undefined`              | LLM system prompt                     |
| `greeting`         | `string \| undefined`              | Greeting message                      |
| `failureMessage`   | `string \| undefined`              | Message spoken when LLM fails         |
| `maxHistory`       | `number \| undefined`              | Maximum conversation history length   |
| `llm`              | `LlmConfig \| undefined`           | LLM configuration                     |
| `tts`              | `TtsConfig \| undefined`           | TTS configuration                     |
| `stt`              | `SttConfig \| undefined`           | STT configuration                     |
| `mllm`             | `MllmConfig \| undefined`          | MLLM configuration                    |
| `avatar`           | `AvatarConfig \| undefined`        | Avatar configuration                  |
| `turnDetection`    | `TurnDetectionConfig \| undefined` | Turn detection configuration          |
| `interruption`     | `InterruptionConfig \| undefined`  | Interruption configuration            |
| `sal`              | `SalConfig \| undefined`           | SAL configuration                     |
| `advancedFeatures` | `AdvancedFeatures \| undefined`    | Advanced features                     |
| `parameters`       | `SessionParams \| undefined`       | Session parameters                    |
| `geofence`         | `GeofenceConfig \| undefined`      | Geofence configuration                |
| `labels`           | `Labels \| undefined`              | Custom labels                         |
| `rtc`              | `RtcConfig \| undefined`           | RTC configuration                     |
| `fillerWords`      | `FillerWordsConfig \| undefined`   | Filler words configuration            |
| `config`           | `AgentOptions`                     | Full read-only configuration snapshot |

### `toProperties(opts)` [#topropertiesopts]

Low-level method to convert the agent configuration to the Fern request format. Used internally by `AgentSession.start()`. You typically do not need to call this directly unless building custom request bodies.

```typescript
toProperties(opts): StartAgentsRequest.Properties
```

### Type aliases [#type-aliases]

Public aliases over Fern-generated types include `LlmConfig`, `SttConfig`, `AsrConfig` (= `SttConfig`), `MllmConfig`, `AvatarConfig`, session/conversation types, and think types (`ThinkOnListeningAction`, etc.).

Think value constants: `ThinkOnListeningActionInject`, `ThinkOnListeningActionInterrupt`, `ThinkOnListeningActionIgnore`, `ThinkOnThinkingActionInterrupt`, `ThinkOnThinkingActionIgnore`, `ThinkOnSpeakingActionInterrupt`, `ThinkOnSpeakingActionIgnore`.

## AgentSession [#agentsession]

`AgentSession` manages the full lifecycle of a running agent. Create sessions using [`agent.createSession()`](#createsessionclient-options); do not call the constructor directly.

```typescript
import { AgentSession } from 'agora-agents';
```

### State machine [#state-machine]

A session progresses through the following states:

```text
idle ──► starting ──► running ──► stopping ──► stopped
                         │
                         ▼
                       error
```

| Transition           | Trigger                                              |
| -------------------- | ---------------------------------------------------- |
| `idle → starting`    | `start()` called                                     |
| `starting → running` | API responds with agent ID                           |
| `starting → error`   | API request fails                                    |
| `running → stopping` | `stop()` called                                      |
| `stopping → stopped` | API confirms agent stopped                           |
| `stopping → error`   | Stop request fails and agent was not already stopped |
| `running → error`    | Unrecoverable error during interaction               |

`start()` can also be called from `stopped` or `error` state to restart the session.

### Methods [#methods-1]

The following methods are available on an `AgentSession` instance.

#### `start()` [#start]

Starts the agent session. Generates tokens if not provided, sends the start request, and returns the agent ID. Resolves explicit `preset` values and also infers reseller presets from supported vendor configs when credentials are omitted.

```typescript
start(): Promise<string>
```

* Transitions: `idle` / `stopped` / `error` → `starting` → `running`
* Throws if called in `starting`, `running`, or `stopping` state
* Throws if avatar config is invalid (wrong TTS sample rate)
* Throws if MLLM is enabled together with an enabled avatar — avatars are only supported with the cascading ASR + LLM + TTS pipeline
* Applies explicit `preset` values when provided and sends Agora-managed configuration when supported vendor credentials are omitted
* Fills generic avatar `agora_appid` and `agora_channel` from the session when omitted
* Generates avatar `agora_token` for `HeyGenAvatar`, `LiveAvatarAvatar`, and `GenericAvatar` when `agoraToken` is omitted and the client has an `appCertificate`. Other vendors (`AkoolAvatar`, `AnamAvatar`) never receive an auto-generated token.

#### `stop()` [#stop]

Stops the agent session and removes the agent from the channel. If the agent has already stopped — for example due to idle timeout — resolves silently rather than throwing a 404 error.

```typescript
stop(): Promise<void>
```

* Transitions: `running` → `stopping` → `stopped`
* Throws if called outside `running` state

#### `say(text, options?)` [#saytext-options]

Instructs the agent to speak the given text.

```typescript
say(text: string, options?: SayOptions): Promise<void>
```

| Parameter               | Type                              | Required | Description                                         |
| ----------------------- | --------------------------------- | -------- | --------------------------------------------------- |
| `text`                  | `string`                          | Yes      | The text for the agent to speak                     |
| `options.priority`      | [`SpeakPriority`](#speakpriority) | No       | Message priority                                    |
| `options.interruptable` | `boolean`                         | No       | Whether this message can be interrupted by the user |

* Only valid in `running` state

#### `interrupt()` [#interrupt]

Interrupts the agent's current speech.

```typescript
interrupt(): Promise<void>
```

* Only valid in `running` state

#### `update(config)` [#updateconfig]

Updates the agent configuration mid-session without restarting. Accepts a partial configuration object in REST API format.

```typescript
update(config: AgentConfigUpdate): Promise<void>
```

* Only valid in `running` state

#### `getHistory()` [#gethistory]

Fetches the conversation history for this session. Requires a valid agent ID — `start()` must have been called successfully.

```typescript
getHistory(): Promise<ConversationHistory>
```

#### `getTurns(options?)` [#getturnsoptions]

Fetches turn-by-turn analytics for this session, including start/end events and latency metrics. Requires a valid agent ID and `start()` must have been called successfully.

```typescript
getTurns(options?: GetTurnsOptions): Promise<ConversationTurns>
```

* `options.page_index`: page number, starting from `1`
* `options.page_size`: number of turns per page

#### `getAllTurns(options?)` [#getallturnsoptions]

Fetches all turn analytics pages and merges the `turns` array. Requires a valid agent ID and `start()` must have been called successfully.

```typescript
getAllTurns(options?: Omit<GetTurnsOptions, "page_index">): Promise<ConversationTurns>
```

* Requires a valid `agentId`
* For very long sessions, prefer processing pages with `getTurns()` to avoid holding all turns in memory

#### `getInfo()` [#getinfo]

Fetches current agent metadata from the API. Requires a valid agent ID.

```typescript
getInfo(): Promise<SessionInfo>
```

#### `on(event, handler)` [#onevent-handler]

Subscribes to a session event. Register handlers **before** calling `start()` to avoid missing the `started` event.

```typescript
on<T>(event: AgentSessionEvent, handler: AgentSessionEventHandler<T>): void
```

#### `off(event, handler)` [#offevent-handler]

Unsubscribes a previously registered event handler.

```typescript
off<T>(event: AgentSessionEvent, handler: AgentSessionEventHandler<T>): void
```

### Events [#events]

The session emits the following events. See [`AgentSessionEvent`](#agentsessionevent) and [`AgentSessionEventHandler`](#agentsessioneventhandler) for type details.

| Event       | Payload type          | Description                           |
| ----------- | --------------------- | ------------------------------------- |
| `"started"` | `{ agentId: string }` | Agent successfully joined the channel |
| `"stopped"` | `{ agentId: string }` | Agent left the channel                |
| `"error"`   | `Error`               | An unrecoverable error occurred       |

### Properties [#properties-2]

The following read-only properties are available on any `AgentSession` instance.

| Property | Type             | Description                                                                                             |
| -------- | ---------------- | ------------------------------------------------------------------------------------------------------- |
| `status` | `string`         | Current session state. One of `"idle"`, `"starting"`, `"running"`, `"stopping"`, `"stopped"`, `"error"` |
| `id`     | `string \| null` | Agent ID, populated after `start()` resolves                                                            |
| `agent`  | `Agent`          | The agent configuration this session was created from                                                   |
| `appId`  | `string`         | The Agora App ID for this session                                                                       |
| `raw`    | `AgentsClient`   | Direct access to the Fern-generated `AgentsClient` for advanced operations                              |

#### Using `session.raw` [#using-sessionraw]

Access the generated REST client to call endpoints not yet wrapped:

```typescript
await session.raw.someNewEndpoint({
  appid: session.appId,
  agentId: session.id!,
});
```

You must pass `appid` and `agentId` manually when using raw methods.

### Presets and BYOK [#presets-and-byok]

Prefer configuring vendors on the `Agent` builder. When you omit credentials for supported Agora-managed models, AgentKit sends the matching Agora-managed configuration at session start.

`preset` is an advanced session option for project-specific settings, not for selecting Agora-managed models. Most applications should use the builder instead.

* Omit vendor credentials on the builder for supported Agora-managed models.
* Provide vendor API keys when you want BYOK.
* Pass `preset` on `agent.createSession(...)` only when you need to access specific project-specific settings.

Supported Agora-managed models:

* Deepgram STT: `nova-2`, `nova-3`
* OpenAI LLM: `gpt-4o-mini`, `gpt-4.1-mini`, `gpt-5-nano`, `gpt-5-mini`
* OpenAI TTS: `tts-1`
* MiniMax TTS: `speech-2.6-turbo`, `speech-2.8-turbo`

## Vendors [#vendors]

All vendor classes are imported from `agora-agent-sdk`. Pass vendor instances to the [Agent builder methods](#builder-methods).

### LLM vendors [#llm-vendors]

Use with [`withLlm()`](#withllmvendor).

#### OpenAI [#openai]

```typescript
new OpenAI(options: OpenAIOptions)
```

| Option              | Type                        | Required    | Description                                                                                                  |
| ------------------- | --------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
| `apiKey`            | `string`                    | Usually     | OpenAI API key. Optional for Agora-managed preset models                                                     |
| `model`             | `string`                    | Yes         | Model name, for example `'gpt-4o-mini'`                                                                      |
| `url`               | `string`                    | Conditional | API endpoint URL. Required when `apiKey` is set (BYOK); default `https://api.openai.com/v1/chat/completions` |
| `maxHistory`        | `number`                    | No          | Maximum conversation history to cache                                                                        |
| `temperature`       | `number`                    | No          | Sampling temperature (0.0–2.0)                                                                               |
| `topP`              | `number`                    | No          | Nucleus sampling (0.0–1.0)                                                                                   |
| `maxTokens`         | `number`                    | No          | Maximum tokens to generate                                                                                   |
| `systemMessages`    | `Record<string, unknown>[]` | No          | Additional system messages                                                                                   |
| `greetingMessage`   | `string`                    | No          | Agent greeting message                                                                                       |
| `failureMessage`    | `string`                    | No          | Message spoken when the LLM call fails                                                                       |
| `inputModalities`   | `string[]`                  | No          | Input modalities. Default: `["text"]`                                                                        |
| `outputModalities`  | `string[]`                  | No          | Output modalities                                                                                            |
| `params`            | `Record<string, unknown>`   | No          | Additional LLM parameters passed to the model                                                                |
| `headers`           | `Record<string, string>`    | No          | Custom HTTP headers forwarded to the LLM provider                                                            |
| `vendor`            | `string`                    | No          | Vendor override                                                                                              |
| `mcpServers`        | `Record<string, unknown>[]` | No          | MCP server connections                                                                                       |
| `greetingConfigs`   | `LlmGreetingConfigs`        | No          | Greeting playback configuration                                                                              |
| `templateVariables` | `Record<string, string>`    | No          | Template variables for messages                                                                              |

`apiKey` is optional for the following reseller preset models: `gpt-4o-mini`, `gpt-4.1-mini`, `gpt-5-nano`, `gpt-5-mini`. If `apiKey` is omitted for one of those models, AgentKit infers the matching session preset. This no-key branch is only available with the default OpenAI endpoint and without a custom vendor hint. If `apiKey` is provided, AgentKit uses standard BYOK behavior instead.

#### AzureOpenAI [#azureopenai]

```typescript
new AzureOpenAI(options: AzureOpenAIOptions)
```

| Option              | Type                        | Required    | Description                                                                                      |
| ------------------- | --------------------------- | ----------- | ------------------------------------------------------------------------------------------------ |
| `apiKey`            | `string`                    | Yes         | Azure OpenAI API key                                                                             |
| `model`             | `string`                    | Yes         | Model or deployment name                                                                         |
| `resourceName`      | `string`                    | Conditional | Azure resource name. Required unless `endpoint` is set                                           |
| `endpoint`          | `string`                    | Conditional | Full Azure base URL. Takes precedence over `resourceName`; required unless `resourceName` is set |
| `deploymentName`    | `string`                    | Yes         | Deployment name in Azure                                                                         |
| `apiVersion`        | `string`                    | No          | Azure API version. Default: `'2024-08-01-preview'`                                               |
| `maxHistory`        | `number`                    | No          | Maximum conversation history to cache                                                            |
| `temperature`       | `number`                    | No          | Sampling temperature (0.0–2.0)                                                                   |
| `topP`              | `number`                    | No          | Nucleus sampling (0.0–1.0)                                                                       |
| `maxTokens`         | `number`                    | No          | Maximum tokens to generate                                                                       |
| `systemMessages`    | `Record<string, unknown>[]` | No          | Additional system messages                                                                       |
| `greetingMessage`   | `string`                    | No          | Agent greeting message                                                                           |
| `failureMessage`    | `string`                    | No          | Message spoken when the LLM call fails                                                           |
| `inputModalities`   | `string[]`                  | No          | Input modalities. Default: `["text"]`                                                            |
| `outputModalities`  | `string[]`                  | No          | Output modalities                                                                                |
| `params`            | `Record<string, unknown>`   | No          | Additional LLM parameters                                                                        |
| `headers`           | `Record<string, string>`    | No          | Custom HTTP headers forwarded to the LLM provider                                                |
| `vendor`            | `string`                    | No          | Vendor override. Defaults to `azure`                                                             |
| `mcpServers`        | `Record<string, unknown>[]` | No          | MCP server connections                                                                           |
| `greetingConfigs`   | `LlmGreetingConfigs`        | No          | Greeting playback configuration                                                                  |
| `templateVariables` | `Record<string, string>`    | No          | Template variables for messages                                                                  |

#### Anthropic [#anthropic]

```typescript
new Anthropic(options: AnthropicOptions)
```

| Option              | Type                        | Required | Description                                    |
| ------------------- | --------------------------- | -------- | ---------------------------------------------- |
| `apiKey`            | `string`                    | Yes      | Anthropic API key                              |
| `model`             | `string`                    | Yes      | Model name                                     |
| `url`               | `string`                    | Yes      | Anthropic messages endpoint URL                |
| `maxTokens`         | `number`                    | Yes      | Maximum tokens to generate                     |
| `headers`           | `Record<string, string>`    | Yes      | Request headers, including `anthropic-version` |
| `maxHistory`        | `number`                    | No       | Maximum conversation history to cache          |
| `temperature`       | `number`                    | No       | Sampling temperature (0.0–1.0)                 |
| `topP`              | `number`                    | No       | Nucleus sampling (0.0–1.0)                     |
| `systemMessages`    | `Record<string, unknown>[]` | No       | Additional system messages                     |
| `greetingMessage`   | `string`                    | No       | Agent greeting message                         |
| `failureMessage`    | `string`                    | No       | Message spoken when the LLM call fails         |
| `inputModalities`   | `string[]`                  | No       | Input modalities. Default: `["text"]`          |
| `outputModalities`  | `string[]`                  | No       | Output modalities                              |
| `params`            | `Record<string, unknown>`   | No       | Additional LLM parameters                      |
| `vendor`            | `string`                    | No       | Vendor override                                |
| `mcpServers`        | `Record<string, unknown>[]` | No       | MCP server connections                         |
| `greetingConfigs`   | `LlmGreetingConfigs`        | No       | Greeting playback configuration                |
| `templateVariables` | `Record<string, string>`    | No       | Template variables for messages                |

#### Gemini [#gemini]

```typescript
new Gemini(options: GeminiOptions)
```

| Option              | Type                        | Required | Description                                                                          |
| ------------------- | --------------------------- | -------- | ------------------------------------------------------------------------------------ |
| `apiKey`            | `string`                    | Yes      | Google API key                                                                       |
| `model`             | `string`                    | Yes      | Model name, for example `'gemini-pro'`                                               |
| `url`               | `string`                    | No       | API endpoint URL. Default: `https://generativelanguage.googleapis.com/v1beta/models` |
| `maxHistory`        | `number`                    | No       | Maximum conversation history to cache                                                |
| `temperature`       | `number`                    | No       | Sampling temperature (0.0–2.0)                                                       |
| `topP`              | `number`                    | No       | Nucleus sampling (0.0–1.0)                                                           |
| `topK`              | `number`                    | No       | Top-k sampling                                                                       |
| `maxOutputTokens`   | `number`                    | No       | Maximum output tokens to generate                                                    |
| `systemMessages`    | `Record<string, unknown>[]` | No       | Additional system messages                                                           |
| `greetingMessage`   | `string`                    | No       | Agent greeting message                                                               |
| `failureMessage`    | `string`                    | No       | Message spoken when the LLM call fails                                               |
| `inputModalities`   | `string[]`                  | No       | Input modalities. Default: `["text"]`                                                |
| `outputModalities`  | `string[]`                  | No       | Output modalities                                                                    |
| `params`            | `Record<string, unknown>`   | No       | Additional LLM parameters                                                            |
| `headers`           | `Record<string, string>`    | No       | Custom HTTP headers forwarded to the LLM provider                                    |
| `vendor`            | `string`                    | No       | Vendor override                                                                      |
| `mcpServers`        | `Record<string, unknown>[]` | No       | MCP server connections                                                               |
| `greetingConfigs`   | `LlmGreetingConfigs`        | No       | Greeting playback configuration                                                      |
| `templateVariables` | `Record<string, string>`    | No       | Template variables for messages                                                      |

### Other LLM vendors [#other-llm-vendors]

| Class           | Provider              | Key options                                          |
| --------------- | --------------------- | ---------------------------------------------------- |
| `Groq`          | Groq                  | `apiKey`, `model`, `url`                             |
| `VertexAILLM`   | Google Vertex AI      | `apiKey`, `model`, `projectId`, `location`, `url?`   |
| `AmazonBedrock` | Amazon Bedrock        | `accessKey`, `secretKey`, `region`, `model`          |
| `Dify`          | Dify                  | `apiKey`, `url`, `model`, `user?`, `conversationId?` |
| `CustomLLM`     | OpenAI-compatible LLM | `apiKey`, `model`, `url`                             |

`Groq` and `CustomLLM` share `OpenAI`'s option shape; `VertexAILLM` mirrors `Gemini`. All accept the common LLM fields (`systemMessages`, `greetingMessage`, `failureMessage`, `maxHistory`, `params`, `headers`, etc.).

### TTS vendors [#tts-vendors]

Use with [`withTts()`](#withttsvendor). The `sampleRate` option determines avatar compatibility — see [`withAvatar()`](#withavatarvendor).

#### ElevenLabsTTS [#elevenlabstts]

```typescript
new ElevenLabsTTS<SR extends ElevenLabsSampleRate>(options: ElevenLabsTTSOptions<SR>)
```

| Option                     | Type                               | Required | Description                                 |
| -------------------------- | ---------------------------------- | -------- | ------------------------------------------- |
| `key`                      | `string`                           | Yes      | ElevenLabs API key                          |
| `modelId`                  | `string`                           | Yes      | Model ID, for example `'eleven_flash_v2_5'` |
| `voiceId`                  | `string`                           | Yes      | Voice ID                                    |
| `baseUrl`                  | `string`                           | Yes      | WebSocket base URL                          |
| `sampleRate`               | `16000 \| 22050 \| 24000 \| 44100` | No       | Audio sample rate in Hz                     |
| `optimizeStreamingLatency` | `number`                           | No       | Latency optimization level (0–4)            |
| `stability`                | `number`                           | No       | Voice stability (0.0–1.0)                   |
| `similarityBoost`          | `number`                           | No       | Voice similarity boost (0.0–1.0)            |
| `style`                    | `number`                           | No       | Voice style exaggeration (0.0–1.0)          |
| `useSpeakerBoost`          | `boolean`                          | No       | Enable speaker boost                        |
| `skipPatterns`             | `number[]`                         | No       | Skip patterns for bracketed content         |

#### MicrosoftTTS [#microsofttts]

```typescript
new MicrosoftTTS<SR extends MicrosoftSampleRate>(options: MicrosoftTTSOptions<SR>)
```

| Option         | Type                      | Required | Description                                   |
| -------------- | ------------------------- | -------- | --------------------------------------------- |
| `key`          | `string`                  | Yes      | Azure Speech API key                          |
| `region`       | `string`                  | Yes      | Azure region, for example `'eastus'`          |
| `voiceName`    | `string`                  | Yes      | Voice name, for example `'en-US-JennyNeural'` |
| `sampleRate`   | `16000 \| 24000 \| 48000` | No       | Audio sample rate in Hz                       |
| `speed`        | `number`                  | No       | Speaking rate multiplier                      |
| `volume`       | `number`                  | No       | Audio volume                                  |
| `skipPatterns` | `number[]`                | No       | Skip patterns for bracketed content           |

#### OpenAITTS [#openaitts]

Fixed at 24,000 Hz — no configurable sample rate.

```typescript
new OpenAITTS(options: OpenAITTSOptions)
```

| Option         | Type       | Required | Description                                                                    |
| -------------- | ---------- | -------- | ------------------------------------------------------------------------------ |
| `apiKey`       | `string`   | Usually  | OpenAI API key                                                                 |
| `voice`        | `string`   | Yes      | Voice name: `'alloy'`, `'echo'`, `'fable'`, `'onyx'`, `'nova'`, or `'shimmer'` |
| `model`        | `string`   | No       | Model name. Required (with `apiKey` and `baseUrl`) for BYOK                    |
| `baseUrl`      | `string`   | No       | Endpoint URL. Required (with `apiKey` and `model`) for BYOK                    |
| `instructions` | `string`   | No       | Custom voice instructions                                                      |
| `speed`        | `number`   | No       | Speech speed multiplier                                                        |
| `skipPatterns` | `number[]` | No       | Skip patterns for bracketed content                                            |

`apiKey` is optional only for the reseller-backed `tts-1` preset path. If omitted with `model: 'tts-1'` or no explicit model, AgentKit infers `openai_tts_1`. If provided, the request stays in BYOK mode.

#### CartesiaTTS [#cartesiatts]

```typescript
new CartesiaTTS<SR extends CartesiaSampleRate>(options: CartesiaTTSOptions<SR>)
```

| Option         | Type                                                | Required | Description                                            |
| -------------- | --------------------------------------------------- | -------- | ------------------------------------------------------ |
| `apiKey`       | `string`                                            | Yes      | Cartesia API key                                       |
| `voiceId`      | `string`                                            | Yes      | Voice ID (serialized as `{"mode": "id", "id": "..."}`) |
| `modelId`      | `string`                                            | Yes      | Model ID                                               |
| `baseUrl`      | `string`                                            | No       | WebSocket URL                                          |
| `language`     | `string`                                            | No       | Target language                                        |
| `sampleRate`   | `8000 \| 16000 \| 22050 \| 24000 \| 44100 \| 48000` | No       | Audio sample rate in Hz                                |
| `skipPatterns` | `number[]`                                          | No       | Skip patterns for bracketed content                    |

#### Other TTS vendors [#other-tts-vendors]

| Class          | Key parameters                                                                        |
| -------------- | ------------------------------------------------------------------------------------- |
| `GoogleTTS`    | `key`, `voiceName`, `languageCode?`, `sampleRate?`                                    |
| `AmazonTTS`    | `accessKey`, `secretKey`, `region`, `voiceId`, `engine`                               |
| `DeepgramTTS`  | `apiKey`, `model`, `baseUrl?`, `sampleRate?`, `additionalParams?`                     |
| `HumeAITTS`    | `key`, `voiceId`, `provider`, `configId?`, `baseUrl?`, `speed?`, `trailingSilence?`   |
| `RimeTTS`      | `key`, `speaker`, `modelId`, `baseUrl?`                                               |
| `FishAudioTTS` | `key`, `referenceId`, `backend`                                                       |
| `MiniMaxTTS`   | `key?`, `groupId?`, `model`, `voiceId?`, `url?`                                       |
| `MurfTTS`      | `key`, `voiceId?`, `baseUrl?`, `locale?`, `rate?`, `pitch?`, `model?`, `sampleRate?`  |
| `SarvamTTS`    | `key`, `speaker`, `targetLanguageCode`, `pitch?`, `pace?`, `loudness?`, `sampleRate?` |

For `MiniMaxTTS`, `key` is optional only for reseller-backed models: `speech-2.6-turbo`, `speech-2.8-turbo`. If `key` is omitted for one of those models, AgentKit infers the matching session preset. In that preset-backed path, `groupId`, `voiceId`, and `url` are optional overrides rather than required fields. If `key` is provided, AgentKit uses BYOK.

### STT vendors [#stt-vendors]

Use with [`withStt()`](#withsttvendor).

#### DeepgramSTT [#deepgramstt]

```typescript
new DeepgramSTT(options?: DeepgramSTTOptions)
```

All options are optional.

| Option             | Type                      | Required | Description                                                                |
| ------------------ | ------------------------- | -------- | -------------------------------------------------------------------------- |
| `apiKey`           | `string`                  | No       | Deepgram API key. Optional for `nova-2` and `nova-3` reseller preset usage |
| `model`            | `string`                  | No       | Model name, for example `'nova-2'` or `'enhanced'`                         |
| `language`         | `string`                  | No       | Language code, for example `'en-US'`                                       |
| `keyterm`          | `string`                  | No       | Boost specialized terms and brands                                         |
| `smartFormat`      | `boolean`                 | No       | Enable smart formatting                                                    |
| `punctuation`      | `boolean`                 | No       | Enable punctuation                                                         |
| `additionalParams` | `Record<string, unknown>` | No       | Additional vendor parameters                                               |

For `nova-2` and `nova-3`, omit `apiKey` to use Agora-managed credentials. For all other Deepgram models, `apiKey` is required.

#### Other STT vendors [#other-stt-vendors]

| Class             | Key parameters                                                         |
| ----------------- | ---------------------------------------------------------------------- |
| `SpeechmaticsSTT` | `apiKey`, `language`, `model?`, `uri?`                                 |
| `MicrosoftSTT`    | `key`, `region`, `language`                                            |
| `OpenAISTT`       | `apiKey`, `model?`, `language?`, `prompt?`, `inputAudioTranscription?` |
| `GoogleSTT`       | `projectId`, `location`, `adcCredentialsString`, `language`, `model?`  |
| `AmazonSTT`       | `accessKey`, `secretKey`, `region`, `language`                         |
| `AssemblyAISTT`   | `apiKey`, `language`, `uri?`                                           |
| `AresSTT`         | `additionalParams?`                                                    |
| `SarvamSTT`       | `apiKey`, `language`, `model?`                                         |

For `OpenAISTT`, the serialized configuration requires a transcription `prompt` and `language` — provide them through the `prompt` and `language` options or within `inputAudioTranscription`. `model` defaults to `gpt-4o-mini-transcribe`.

### MLLM vendors [#mllm-vendors]

Use with [`withMllm()`](#withmllmvendor) for multimodal end-to-end audio processing without separate STT or TTS steps. Calling `withMllm()` automatically enables the MLLM module (sets `mllm.enable = true`); the older `advancedFeatures.enable_mllm` flag is deprecated.

#### OpenAIRealtime [#openairealtime]

```typescript
new OpenAIRealtime(options: OpenAIRealtimeOptions)
```

| Option                    | Type                        | Required | Description                                                            |
| ------------------------- | --------------------------- | -------- | ---------------------------------------------------------------------- |
| `apiKey`                  | `string`                    | Yes      | OpenAI API key                                                         |
| `model`                   | `string`                    | No       | Model name, for example `'gpt-4o-realtime-preview'`                    |
| `voice`                   | `string`                    | No       | Voice identifier                                                       |
| `instructions`            | `string`                    | No       | System instructions                                                    |
| `inputAudioTranscription` | `Record<string, unknown>`   | No       | Audio transcription settings                                           |
| `url`                     | `string`                    | No       | WebSocket URL                                                          |
| `greetingMessage`         | `string`                    | No       | Agent greeting message                                                 |
| `failureMessage`          | `string`                    | No       | Message played when the model call fails                               |
| `inputModalities`         | `string[]`                  | No       | Input modalities, for example `['audio']`                              |
| `outputModalities`        | `string[]`                  | No       | Output modalities, for example `['text', 'audio']`                     |
| `messages`                | `Record<string, unknown>[]` | No       | Conversation messages for short-term memory                            |
| `params`                  | `Record<string, unknown>`   | No       | Additional MLLM parameters                                             |
| `turnDetection`           | `MllmTurnDetectionConfig`   | No       | MLLM turn detection configuration; overrides top-level `turnDetection` |

#### GeminiLive [#geminilive]

```typescript
new GeminiLive(options: GeminiLiveOptions)
```

| Option             | Type                        | Required | Description                                                            |
| ------------------ | --------------------------- | -------- | ---------------------------------------------------------------------- |
| `apiKey`           | `string`                    | Yes      | Google API key                                                         |
| `model`            | `string`                    | Yes      | Model name, for example `'gemini-live-2.5-flash'`                      |
| `url`              | `string`                    | No       | WebSocket URL                                                          |
| `instructions`     | `string`                    | No       | System instructions for the model                                      |
| `voice`            | `string`                    | No       | Voice name, for example `'Aoede'` or `'Charon'`                        |
| `affectiveDialog`  | `boolean`                   | No       | Enable affective dialog                                                |
| `proactiveAudio`   | `boolean`                   | No       | Enable proactive audio                                                 |
| `transcribeAgent`  | `boolean`                   | No       | Transcribe agent speech                                                |
| `transcribeUser`   | `boolean`                   | No       | Transcribe user speech                                                 |
| `httpOptions`      | `Record<string, unknown>`   | No       | HTTP options                                                           |
| `greetingMessage`  | `string`                    | No       | Agent greeting message                                                 |
| `failureMessage`   | `string`                    | No       | Message played when the model call fails                               |
| `inputModalities`  | `string[]`                  | No       | Input modalities                                                       |
| `outputModalities` | `string[]`                  | No       | Output modalities                                                      |
| `messages`         | `Record<string, unknown>[]` | No       | Conversation messages for short-term memory                            |
| `additionalParams` | `Record<string, unknown>`   | No       | Additional parameters                                                  |
| `turnDetection`    | `MllmTurnDetectionConfig`   | No       | MLLM turn detection configuration; overrides top-level `turnDetection` |

#### VertexAI [#vertexai]

```typescript
new VertexAI(options: VertexAIOptions)
```

| Option                 | Type                        | Required | Description                                                                    |
| ---------------------- | --------------------------- | -------- | ------------------------------------------------------------------------------ |
| `model`                | `string`                    | Yes      | Model name, for example `'gemini-live-2.5-flash-preview-native-audio-09-2025'` |
| `projectId`            | `string`                    | Yes      | Google Cloud project ID                                                        |
| `location`             | `string`                    | Yes      | Google Cloud location or region                                                |
| `adcCredentialsString` | `string`                    | Yes      | Application Default Credentials JSON string                                    |
| `url`                  | `string`                    | No       | WebSocket URL                                                                  |
| `instructions`         | `string`                    | No       | System instructions for the model                                              |
| `voice`                | `string`                    | No       | Voice name, for example `'Aoede'` or `'Charon'`                                |
| `affectiveDialog`      | `boolean`                   | No       | Enable affective dialog                                                        |
| `proactiveAudio`       | `boolean`                   | No       | Enable proactive audio                                                         |
| `transcribeAgent`      | `boolean`                   | No       | Transcribe agent speech                                                        |
| `transcribeUser`       | `boolean`                   | No       | Transcribe user speech                                                         |
| `httpOptions`          | `Record<string, unknown>`   | No       | HTTP options                                                                   |
| `greetingMessage`      | `string`                    | No       | Agent greeting message                                                         |
| `failureMessage`       | `string`                    | No       | Message played when the model call fails                                       |
| `inputModalities`      | `string[]`                  | No       | Input modalities                                                               |
| `outputModalities`     | `string[]`                  | No       | Output modalities                                                              |
| `messages`             | `Record<string, unknown>[]` | No       | Conversation messages for short-term memory                                    |
| `additionalParams`     | `Record<string, unknown>`   | No       | Additional parameters                                                          |
| `turnDetection`        | `MllmTurnDetectionConfig`   | No       | MLLM turn detection configuration; overrides top-level `turnDetection`         |

#### XaiGrok [#xaigrok]

```typescript
new XaiGrok(options: XaiGrokOptions)
```

| Option             | Type                        | Required | Description                                                            |
| ------------------ | --------------------------- | -------- | ---------------------------------------------------------------------- |
| `apiKey`           | `string`                    | Yes      | xAI API key                                                            |
| `url`              | `string`                    | No       | WebSocket URL (defaults to xAI Realtime API)                           |
| `voice`            | `string`                    | No       | Voice identifier, for example `'eve'`                                  |
| `language`         | `string`                    | No       | Language code                                                          |
| `sampleRate`       | `number`                    | No       | Audio sample rate in Hz                                                |
| `greetingMessage`  | `string`                    | No       | Agent greeting message                                                 |
| `failureMessage`   | `string`                    | No       | Message played when the model call fails                               |
| `inputModalities`  | `string[]`                  | No       | Input modalities                                                       |
| `outputModalities` | `string[]`                  | No       | Output modalities                                                      |
| `messages`         | `Record<string, unknown>[]` | No       | Conversation messages for short-term memory                            |
| `params`           | `Record<string, unknown>`   | No       | Additional xAI parameters                                              |
| `turnDetection`    | `MllmTurnDetectionConfig`   | No       | MLLM turn detection configuration; overrides top-level `turnDetection` |

### Avatar vendors [#avatar-vendors]

Use with [`withAvatar()`](#withavatarvendor). Each avatar vendor requires a specific TTS sample rate enforced at compile time and runtime.

#### HeyGenAvatar [#heygenavatar]

Deprecated. Use [`LiveAvatarAvatar`](#liveavataravatar) for new integrations. `HeyGenAvatar` still works (serializes `vendor: "heygen"`) but emits a deprecation warning. Requires TTS at **24,000 Hz**.

```typescript
new HeyGenAvatar(options: HeyGenAvatarOptions)
```

| Option                | Type                          | Required | Description                                   |
| --------------------- | ----------------------------- | -------- | --------------------------------------------- |
| `apiKey`              | `string`                      | Yes      | HeyGen API key                                |
| `quality`             | `'low' \| 'medium' \| 'high'` | Yes      | Video quality: 360p, 480p, or 720p            |
| `agoraUid`            | `string`                      | Yes      | RTC UID for the avatar stream                 |
| `agoraToken`          | `string`                      | No       | RTC token for avatar authentication           |
| `avatarId`            | `string`                      | No       | HeyGen avatar ID                              |
| `disableIdleTimeout`  | `boolean`                     | No       | Disable idle timeout. Default: `false`        |
| `activityIdleTimeout` | `number`                      | No       | Idle timeout in seconds. Default: `120`       |
| `enable`              | `boolean`                     | No       | Enable or disable the avatar. Default: `true` |

#### AkoolAvatar [#akoolavatar]

Requires TTS at **16,000 Hz**.

```typescript
new AkoolAvatar(options: AkoolAvatarOptions)
```

| Option     | Type      | Required | Description                                   |
| ---------- | --------- | -------- | --------------------------------------------- |
| `apiKey`   | `string`  | Yes      | Akool API key                                 |
| `avatarId` | `string`  | No       | Akool avatar ID                               |
| `enable`   | `boolean` | No       | Enable or disable the avatar. Default: `true` |

#### LiveAvatarAvatar [#liveavataravatar]

Requires TTS at **24,000 Hz**.

```typescript
new LiveAvatarAvatar(options: LiveAvatarAvatarOptions)
```

| Option                | Type                          | Required | Description                                   |
| --------------------- | ----------------------------- | -------- | --------------------------------------------- |
| `apiKey`              | `string`                      | Yes      | LiveAvatar API key                            |
| `quality`             | `'low' \| 'medium' \| 'high'` | Yes      | Video quality                                 |
| `agoraUid`            | `string`                      | Yes      | RTC UID for the avatar stream                 |
| `agoraToken`          | `string`                      | No       | Avatar token override                         |
| `avatarId`            | `string`                      | No       | Avatar ID                                     |
| `disableIdleTimeout`  | `boolean`                     | No       | Disable idle timeout                          |
| `activityIdleTimeout` | `number`                      | No       | Idle timeout in seconds                       |
| `enable`              | `boolean`                     | No       | Enable or disable the avatar. Default: `true` |

#### AnamAvatar [#anamavatar]

```typescript
new AnamAvatar(options: AnamAvatarOptions)
```

| Option      | Type      | Required | Description                                   |
| ----------- | --------- | -------- | --------------------------------------------- |
| `apiKey`    | `string`  | Yes      | Anam API key                                  |
| `personaId` | `string`  | No       | Anam persona ID                               |
| `enable`    | `boolean` | No       | Enable or disable the avatar. Default: `true` |

#### GenericAvatar [#genericavatar]

Generic avatars can omit `agoraAppId`, `agoraChannel`, and `agoraToken`. AgentKit fills them from the session at `start()`.

```typescript
new GenericAvatar(options: GenericAvatarOptions)
```

| Option         | Type      | Required | Description                                   |
| -------------- | --------- | -------- | --------------------------------------------- |
| `apiKey`       | `string`  | Yes      | Custom avatar provider API key                |
| `apiBaseUrl`   | `string`  | Yes      | Avatar provider API base URL                  |
| `avatarId`     | `string`  | Yes      | Avatar ID                                     |
| `agoraUid`     | `string`  | Yes      | RTC UID for the avatar stream                 |
| `agoraAppId`   | `string`  | No       | Agora App ID override                         |
| `agoraChannel` | `string`  | No       | Agora channel override                        |
| `agoraToken`   | `string`  | No       | Avatar token override                         |
| `enable`       | `boolean` | No       | Enable or disable the avatar. Default: `true` |

## Token utilities [#token-utilities]

Helper functions and classes for generating and managing tokens. Use these when you need control over token lifetime, or when generating tokens outside of a session.

```typescript
import { generateConvoAIToken, ExpiresIn } from 'agora-agent-sdk';
```

### `generateConvoAIToken(options)` [#generateconvoaitokenoptions]

Generates a Conversational AI token combining RTC and RTM privileges. This is the same token the SDK generates automatically in app-credentials mode. Use this when you need a token outside of a session, or when passing a pre-built token to [`SessionOptions.token`](#createsessionclient-options).

```typescript
generateConvoAIToken(options: GenerateConvoAITokenOptions): string
```

| Option           | Type     | Required | Description                                                       |
| ---------------- | -------- | -------- | ----------------------------------------------------------------- |
| `appId`          | `string` | Yes      | Agora App ID                                                      |
| `appCertificate` | `string` | Yes      | Agora App Certificate                                             |
| `channelName`    | `string` | Yes      | The channel the token grants access to                            |
| `account`        | `string` | Yes      | The UID this token is issued for, as a string                     |
| `tokenExpire`    | `number` | No       | Token lifetime in seconds. Default: `86400`. Valid range: 1–86400 |

**Returns:** `string` — the generated token.

```typescript
const token = generateConvoAIToken({
  appId: 'your-app-id',
  appCertificate: 'your-app-certificate',
  channelName: 'support-room-123',
  account: '1',
  tokenExpire: ExpiresIn.hours(12),
});
```

### `ExpiresIn` [#expiresin]

Helper for specifying token lifetimes. Use with [`SessionOptions.expiresIn`](#createsessionclient-options) or [`generateConvoAIToken`](#generateconvoaitokenoptions). Values are validated and capped at the Agora maximum of 86400 seconds (24 hours).

| Value or method        | Returns  | Description                                                            |
| ---------------------- | -------- | ---------------------------------------------------------------------- |
| `ExpiresIn.DAY`        | `86400`  | 24 hours — the Agora maximum and default                               |
| `ExpiresIn.hours(n)`   | `number` | `n` hours in seconds. Throws if `n` ≤ 0, caps at 24 h with a warning   |
| `ExpiresIn.minutes(n)` | `number` | `n` minutes in seconds. Throws if `n` ≤ 0, caps at 24 h with a warning |

## Types and enums [#types-and-enums]

Shared types and enums used across `AgoraClient`, `Agent`, `AgentSession`, and vendor classes.

### `Area` [#area]

Region used for API routing. Pass to `AgoraClient` via the `area` option.

```typescript
import { Area } from 'agora-agent-sdk';
```

| Value     | Region         |
| --------- | -------------- |
| `Area.US` | United States  |
| `Area.EU` | Europe         |
| `Area.AP` | Asia-Pacific   |
| `Area.CN` | China mainland |

### `AgoraAuthMode` [#agoraauthmode]

The resolved authentication mode on an `AgoraClient` instance. Read via `client.authMode`.

```typescript
type AgoraAuthMode = "app-credentials" | "token" | "basic";
```

| Value               | Description                                                    |
| ------------------- | -------------------------------------------------------------- |
| `"app-credentials"` | App ID and App Certificate provided. SDK auto-generates tokens |
| `"token"`           | Pre-built `authToken` provided                                 |
| `"basic"`           | `customerId` and `customerSecret` provided                     |

### `AgentSessionEvent` [#agentsessionevent]

Union type of all valid event names for `session.on()` and `session.off()`.

```typescript
type AgentSessionEvent = "started" | "stopped" | "error";
```

### `AgentSessionEventHandler` [#agentsessioneventhandler]

Generic handler type for session event callbacks.

```typescript
type AgentSessionEventHandler<T> = (data: T) => void;
```

| Event       | `T`                   |
| ----------- | --------------------- |
| `"started"` | `{ agentId: string }` |
| `"stopped"` | `{ agentId: string }` |
| `"error"`   | `Error`               |

### `SpeakPriority` [#speakpriority]

Controls how the agent handles a [`say()`](#saytext-options) call relative to its current activity.

```typescript
type SpeakPriority = "INTERRUPT" | "APPEND" | "IGNORE";
```

| Value         | Description                                                     |
| ------------- | --------------------------------------------------------------- |
| `"INTERRUPT"` | Agent immediately stops current speech and delivers the message |
| `"APPEND"`    | Message is queued and delivered after current speech ends       |
| `"IGNORE"`    | Message is discarded if the agent is currently speaking         |

### `AgoraError` [#agoraerror]

Thrown when the API returns a 4xx or 5xx response. Catch this to inspect the status code and response body.

```typescript
import { AgoraError } from 'agora-agent-sdk';

try {
  const agentId = await session.start();
} catch (err) {
  if (err instanceof AgoraError) {
    console.error('Status:', err.statusCode);
    console.error('Message:', err.message);
    console.error('Body:', err.body);
  }
}
```

| Property      | Type       | Description                          |
| ------------- | ---------- | ------------------------------------ |
| `statusCode`  | `number`   | HTTP status code returned by the API |
| `message`     | `string`   | Human-readable error message         |
| `body`        | `unknown`  | Raw response body from the API       |
| `rawResponse` | `Response` | The full HTTP response object        |