ElevenLabsAgentConfig

Configuration for ElevenLabsAgent.

Defined in: src/providers/agent/elevenlabs/types.ts:62

Remarks

Extends BaseProviderConfig, so apiKey, proxyUrl, timeout, and debug are also available. Connection/authentication options, in priority order:

signedUrl — a signed WebSocket URL (or async factory returning one) minted server-side via GET /v1/convai/conversation/get-signed-url?agent_id=.... The recommended flow for private agents in the browser.
proxyUrl — route through the CompositeVoice proxy, which injects the xi-api-key header server-side.
apiKey + agentId — direct connection with the key as a query parameter. Avoid in browsers with long-lived keys.
agentId alone — public agents require no authentication.

Example

const agent = new ElevenLabsAgent({
  agentId: 'agent_abc123',
  proxyUrl: '/api/proxy/elevenlabs',
});

Extends

BaseProviderConfig

Properties

Property	Type	Default value	Description	Inherited from	Defined in
`agentId?`	`string`	`undefined`	The Conversational AI agent ID (from the ElevenLabs dashboard). Remarks Required unless ElevenLabsAgentConfig.signedUrl is provided.	-	src/providers/agent/elevenlabs/types.ts:69
`apiKey?`	`string` \| () => `Promise`<`string`>	`undefined`	API key or authentication token for the provider. Remarks Can be a static string or an async factory function that returns a fresh token on each call. Use a factory for short-lived tokens (e.g. Deepgram JWTs) so each WebSocket connection gets a valid credential. For client-side usage, consider using a proxy server to keep API keys secure. The SDK provides Express, Next.js, and Node adapters for this purpose.	`BaseProviderConfig`.`apiKey`	src/core/types/providers.ts:71
`audioDoneSilenceMs?`	`number`	`1000`	Milliseconds of audio-event silence after which the agent’s turn is considered complete. Remarks The ElevenLabs protocol has no explicit “audio done” message, so the provider treats a gap in audio chunk arrival as the end of the agent’s turn (resolving the pipeline’s `finalize()` wait).	-	src/providers/agent/elevenlabs/types.ts:137
`authType?`	`"token"` \| `"bearer"`	`Provider-specific (typically 'token' for Deepgram, ignored for REST providers)`	Authentication type for providers that support multiple auth mechanisms. Remarks Controls how the `apiKey` is sent to the provider: - `'token'` — WebSocket subprotocol `['token', apiKey]` or header `Authorization: Token <key>`. This is the default for Deepgram providers. - `'bearer'` — WebSocket subprotocol `['bearer', token]` or header `Authorization: Bearer <token>`. Use this for OAuth tokens or providers that expect Bearer auth. REST/SDK providers (Anthropic, OpenAI) handle auth through their SDK constructors and ignore this field.	`BaseProviderConfig`.`authType`	src/core/types/providers.ts:115
`debug?`	`boolean`	`false`	Whether to enable debug logging for this provider. Remarks When `true`, the provider emits detailed internal logs. This is separate from the SDK-level LoggingConfig.	`BaseProviderConfig`.`debug`	src/core/types/providers.ts:126
`dynamicVariables?`	`Record`<`string`, `string` \| `number` \| `boolean`>	`undefined`	Dynamic variables substituted into the agent’s prompt templates. Remarks Sent as `dynamic_variables` in `conversation_initiation_client_data`.	-	src/providers/agent/elevenlabs/types.ts:105
`endpoint?`	`string`	`undefined`	Custom endpoint URL to override the provider’s default API endpoint. Remarks Useful for self-hosted instances, proxy servers, or development environments.	`BaseProviderConfig`.`endpoint`	src/core/types/providers.ts:79
`firstMessage?`	`string`	`undefined`	Override the agent’s first message (spoken greeting).	-	src/providers/agent/elevenlabs/types.ts:91
`initiationOverrides?`	`Record`<`string`, `unknown`>	`undefined`	Extra fields merged into the `conversation_initiation_client_data` payload, after the fields derived from this config. Remarks Escape hatch for initiation options this config does not model (e.g. `custom_llm_extra_body`, extended override blocks).	-	src/providers/agent/elevenlabs/types.ts:115
`language?`	`string`	`undefined`	Override the agent’s language (e.g. `'en'`, `'es'`).	-	src/providers/agent/elevenlabs/types.ts:94
`onClientToolCall?`	(`call`) => `Promise`<{ `result`: `unknown`; }>	`undefined`	Handler invoked when the agent calls a client tool. Remarks The returned result is sent back as a `client_tool_result` message. Throwing marks the result as an error.	-	src/providers/agent/elevenlabs/types.ts:124
`proxyUrl?`	`string`	`undefined`	URL of a CompositeVoice proxy server endpoint for this provider. Remarks When set, requests are routed through the proxy which injects the real API key server-side. This keeps API keys out of the browser. For WebSocket providers the HTTP URL is automatically converted to `ws(s)://`. At least one of `apiKey` or `proxyUrl` must be set for providers that require authentication (all except NativeSTT, NativeTTS, and WebLLM). Example `proxyUrl: 'http://localhost:3000/api/proxy/deepgram'`	`BaseProviderConfig`.`proxyUrl`	src/core/types/providers.ts:97
`signedUrl?`	`string` \| () => `Promise`<`string`>	`undefined`	A pre-signed WebSocket URL, or an async factory that returns one. Remarks Signed URLs are short-lived; pass a factory so each `connect()` gets a fresh one. When set, `agentId`, `apiKey`, and `proxyUrl` are ignored for the connection itself.	-	src/providers/agent/elevenlabs/types.ts:79
`systemPrompt?`	`string`	`undefined`	Override the agent’s system prompt for this conversation. Remarks Sent in `conversation_initiation_client_data`. Overrides must be enabled in the agent’s security settings.	-	src/providers/agent/elevenlabs/types.ts:88
`timeout?`	`number`	`undefined`	Request timeout in milliseconds. Remarks Applies to HTTP requests (REST providers) and connection establishment (WebSocket providers). Set to `0` for no timeout.	`BaseProviderConfig`.`timeout`	src/core/types/providers.ts:135
`voiceId?`	`string`	`undefined`	Override the agent’s TTS voice ID.	-	src/providers/agent/elevenlabs/types.ts:97