Skip to main content
Bring your own ElevenLabs agent and give it a Beyond Presence avatar. ElevenLabs runs the conversation with the agent’s own prompt, voice, knowledge base, tools, and turn-taking. Beyond Presence renders the avatar and streams the video call.

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
To use your own Chat Completions endpoint instead, see External LLM.

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_complete client 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.
Switching an existing agent to ElevenLabs removes its starting script, vision mode, keyword activation, and knowledge files, because ElevenLabs owns those settings. The agent keeps its prompt and conversation flow, so you can switch back later. To keep the original agent unchanged, click Duplicate Instead in the confirmation dialog and switch the copy.
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 the elevenlabs External API configuration from the previous step
  • agent_id: ID of the agent in ElevenLabs
Python
The Create Agent endpoint requires system_prompt, but the ElevenLabs agent uses its own prompt.
See our ElevenLabs agent example for both steps as ready-to-run scripts:

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:
If ElevenLabs answers 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:
If ElevenLabs answers 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 an elevenlabs_agent agent that sets any of the following:
  • Speech-to-text (STT) configuration
  • tts
  • greeting
  • User-away ping
  • The webcam_vision capability
  • The wakeup_mode capability
  • Dynamic avatar emotions
A static avatar emotion still works. Configure the other settings in the ElevenLabs agent instead. You also can’t attach knowledge files with 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.