When to use this
Use an ElevenLabs agent when:- You already built and tuned an agent in ElevenLabs and want to add a video avatar to it
- You want to keep managing the prompt, voice, knowledge base, and tools in ElevenLabs
Prerequisites
- An ElevenLabs account API key
- The ID of an agent in that ElevenLabs account
- A Beyond Presence API key, if you set up the agent through the API
Requirements for the ElevenLabs agent
Configure your agent in ElevenLabs as follows:agent_response_completeclient event: Enable this client event so Beyond Presence knows when the agent has finished a reply.- Server-side tools only: Client tools are not supported. When the ElevenLabs agent calls a client tool, Beyond Presence returns an error result saying the tool is not available. Run tools on the ElevenLabs side, for example as server tools or webhooks.
Configuration
You can set up an ElevenLabs agent in Studio or through the API.In Studio
1
Choose ElevenLabs as the engine
Create a new agent in Studio, or open an existing one.
Under Powered by, select ElevenLabs Agent.
2
Connect your ElevenLabs account
Under ElevenLabs Account, click Connect ElevenLabs (or Connect Account).
Enter an account name and paste your ElevenLabs API key.
Beyond Presence checks the key with ElevenLabs before storing it.
To connect more accounts or remove one, select Manage accounts… in the account list.
3
Enter the ElevenLabs agent ID
Under ElevenLabs Agent ID, paste the agent ID from ElevenLabs, for example
agent_01jz8x3k2m....
You can also paste the agent’s link from the ElevenLabs dashboard, and Studio extracts the ID.4
Save the agent
Pick an avatar and save the agent.
The Managed in ElevenLabs card lists what the ElevenLabs agent handles and links to the agent with Open in ElevenLabs.
Removing a connected ElevenLabs account stops every agent that uses it until you pick another account for those agents.
With the API
1
Register your ElevenLabs account
Create an External API configuration of type
elevenlabs with your ElevenLabs API key using the Create External API Configuration endpoint.
Beyond Presence tests the key with ElevenLabs before storing it.
If ElevenLabs rejects the key, the request fails and nothing is stored.
The response contains the configuration id.2
Create the agent
Create an agent with the Create Agent endpoint and set
llm to type elevenlabs_agent:api_id: ID of theelevenlabsExternal API configuration from the previous stepagent_id: ID of the agent in ElevenLabs
Python
The Create Agent endpoint requires
system_prompt, but the ElevenLabs agent uses its own prompt.ElevenLabs Agent Example
Register your ElevenLabs key and create the agent from the command line
Troubleshooting
Beyond Presence checks your ElevenLabs key and agent ID with ElevenLabs when you save them, so mistakes surface right away instead of during a conversation.Error 400 when storing the ElevenLabs API key
Make sure the key is valid, for example with this request:
401, the key is invalid. Create a new one in your ElevenLabs API key settings.
Error 400 when connecting an ElevenLabs agent
Make sure the ElevenLabs API key you stored has access to that agent:
404, the key may have the wrong scope or belong to a different ElevenLabs account than the agent.
Error 400 about an ElevenLabs API key you stored successfully before
The key may have been revoked. Run the first request above to check whether it is still active. If it is not, create a new key and store it in a new elevenlabs External API configuration.
Unsupported settings
ElevenLabs owns speech recognition, the voice, the greeting, and every reply. The API rejects creating or updating anelevenlabs_agent agent that sets any of the following:
- Speech-to-text (STT) configuration
ttsgreeting- User-away ping
- The
webcam_visioncapability - The
wakeup_modecapability - Dynamic avatar emotions
knowledge_file_ids.
Add your content to the ElevenLabs agent’s knowledge base instead.
How the call ends
The call ends when the ElevenLabs conversation ends.- The agent hangs up: Beyond Presence lets the farewell finish playing, for up to 30 seconds, before ending the call. The call UI shows that the agent ended the call.
- The conversation drops: Beyond Presence ends the call right away. The call UI shows it as an error.