> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bey.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# ElevenLabs Agent

> Run a Beyond Presence avatar on your own ElevenLabs Conversational AI agent, with ElevenLabs handling the prompt, voice, knowledge base, tools, and turn-taking.

Bring your own [ElevenLabs agent](https://elevenlabs.io/docs/conversational-ai/overview) 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](https://docs.bey.dev/concepts/agents/external-llm.md).

## Prerequisites

* An ElevenLabs account API key
* The ID of an agent in that ElevenLabs account
* A Beyond Presence [API key](https://docs.bey.dev/concepts/api.md), 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](https://elevenlabs.io/docs/eleven-agents/customization/events/client-events) 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](https://docs.bey.dev/concepts/studio.md) or through the API.

### In Studio

**1. Choose ElevenLabs as the engine**

Create a new agent in [Studio](https://bey.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**.

> [!WARNING]
>
> 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.

> [!NOTE]
>
> 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](https://docs.bey.dev/api-reference/agents-external-apis/create-external-api-configuration.md).
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](https://docs.bey.dev/api-reference/agents/create-agent.md) 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 Python theme={null}
import requests

API_URL = "https://api.bey.dev/v1"
HEADERS = {"x-api-key": "sk-your-api-key-here"}

# 1. Register the ElevenLabs account that owns the agent
response = requests.post(
    f"{API_URL}/external-apis",
    headers=HEADERS,
    json={
        "type": "elevenlabs",
        "name": "My ElevenLabs account",
        "api_key": "your-elevenlabs-api-key",
    },
)
response.raise_for_status()
elevenlabs_api_id = response.json()["id"]

# 2. Create a Beyond Presence agent that runs the ElevenLabs agent
response = requests.post(
    f"{API_URL}/agents",
    headers=HEADERS,
    json={
        "name": "My ElevenLabs avatar",
        "avatar_id": "your-avatar-id",
        "system_prompt": "Configured in ElevenLabs.",
        "llm": {
            "type": "elevenlabs_agent",
            "api_id": elevenlabs_api_id,
            "agent_id": "your-elevenlabs-agent-id",
        },
    },
)
response.raise_for_status()
agent = response.json()
```

> [!NOTE]
>
> 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:

> [card] [ElevenLabs Agent Example](https://github.com/bey-dev/bey-examples/tree/main/elevenlabs-agent#readme)
>
> 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:

```bash theme={null}
curl -H "xi-api-key: your-elevenlabs-api-key" "https://api.elevenlabs.io/v1/convai/agents?page_size=1"
```

If ElevenLabs answers `401`, the key is invalid. Create a new one in your [ElevenLabs API key settings](https://elevenlabs.io/app/settings/api-keys).

### Error `400` when connecting an ElevenLabs agent

Make sure the ElevenLabs API key you stored has access to that agent:

```bash theme={null}
curl -H "xi-api-key: your-elevenlabs-api-key" "https://api.elevenlabs.io/v1/convai/agents/your-elevenlabs-agent-id"
```

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.


## Related topics

- [Speech-to-Video Integration for Voice Agents](https://docs.bey.dev/integrations/voice-agents/index.md)
- [Changelog](https://docs.bey.dev/learn/changelog.md)
- [External LLM](https://docs.bey.dev/concepts/agents/external-llm.md)
- [Knowledge Base](https://docs.bey.dev/concepts/agents/knowledge-base.md)
- [Studio](https://docs.bey.dev/concepts/studio.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.