`ElevenLabsAgentAdapter`

Connects to an ElevenLabs Conversational AI ("Convai") agent over WebSocket. Use this when you've built an agent in the ElevenLabs dashboard and want to test it end-to-end.

Constructor

python

import os
import scenario
 
adapter = scenario.ElevenLabsAgentAdapter(
    agent_id=os.environ["ELEVENLABS_AGENT_ID"],
    api_key=os.environ["ELEVENLABS_API_KEY"],
    # Optional per-session overrides (sent via conversation_initiation_client_data):
    # system_prompt_override="Be terse for this test.",
    # first_message_override="Hi — this is the test harness.",
)

The two optional per-session override fields let you adjust the hosted agent's behaviour for a specific test run without modifying the shared ElevenLabs dashboard configuration. They are transmitted in the WebSocket conversation_initiation_client_data handshake at connect time:

Python	TypeScript	Description
`system_prompt_override`	`systemPromptOverride`	Replaces the agent's system prompt for this session only. Useful for pinning a test persona without touching the shared dashboard agent.
`first_message_override`	`firstMessageOverride`	Overrides the agent's opening message for this session.

Capabilities

streaming_transcripts	native_vad	dtmf	interruption	input_formats	output_formats
✅	✅	❌	❌	`pcm16/24000`	`pcm16/24000`

Worked examples

Python: elevenlabs_hosted.py — hosted Convai scenario with a judge step; elevenlabs_branded.py — branded voice variant; elevenlabs_interruption.py — barge-in handling.
TypeScript: elevenlabs-hosted.test.ts — hosted ConvAI path and the branded ElevenLabsVoiceAgent composable variant.

Common failures

HTTP 401 quota_exceeded — your character quota is exhausted. See Troubleshooting → ElevenLabs HTTP 401 quota_exceeded.

Composable variant — `ElevenLabsVoiceAgent`

If you'd rather pair ElevenLabs STT/TTS with a different LLM, use ElevenLabsVoiceAgent: