agents

# ElevenLabs Agents Platform Build voice AI agents with natural conversations, multiple LLM providers, custom tools, and easy web embedding. > **Setup, before writing any code:** if `ELEVENLABS_API_KEY` isn't set for this project, run `npx -y @elevenlabs/cli@latest onboard init` from the app's folder first and follow what it prints: it signs the user in and stores a key for the project, so nobody copies one by hand. Otherwise see the [Installation Guide](references/installation.md) for CLI and SDK setup. ## Quick Start with CLI The ElevenLabs CLI is the recommended way to create and manage agents: ```bash # Install CLI and authenticate npm install -g @elevenlabs/cli elevenlabs auth login # Initialize project and create an agent elevenlabs agents init elevenlabs agents add "My Assistant" --template complete # Push to ElevenLabs platform elevenlabs agents push ``` **Available templates:** `complete`, `minimal`, `voice-only`, `text-only`, `customer-service`, `assistant` ### Python ```python from elevenlabs import ElevenLabs client = ElevenLabs() agent = client.conversational_ai.agents.create( name="My Assistant", conversation_config={ "agent": { "first_message": "Hello! How can I help?", "language": "en", "prompt": { "prompt": "You are a helpful assistant. Be concise and friendly.", "llm": "gemini-2.0-flash", "temperature": 0.7 } }, "tts": {"voice_id": "JBFqnCBsd6RMkjVDRZzb"} } ) ``` ### JavaScript ```javascript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const client = new ElevenLabsClient(); const agent = await client.conversationalAi.agents.create({ name: "My Assistant", conversationConfig: { agent: { firstMessage: "Hello! How can I help?", language: "en", prompt: { prompt: "You are a helpful assistant.", llm: "gemini-2.0-flash", temperature: 0.7 } }, tts: { voiceId: "JBFqnCBsd6RMkjVDRZzb" } } }); ``` ### CLI The CLI reads `ELEVENLABS_API_KEY` from the environment automatically: ```bash elevenlabs agents create \ --json '{"name": "My Assistant", "conversation_config": {"agent": {"first_message": "Hello!", "language": "en", "prompt": {"prompt": "You are helpful.", "llm": "gemini-2.0-flash"}}, "tts": {"voice_id": "JBFqnCBsd6RMkjVDRZzb"}}}' ``` ## Starting Conversations **Authenticated WebRTC:** Request a session token from your backend. The response includes both the token and the conversation ID: ```python session = client.conversational_ai.conversations.get_webrtc_token( agent_id="your-agent-id", ) print(session.token, session.conversation_id) ``` **Server-side (Python):** Get signed URL for client connection: ```python signed_url = client.conversational_ai.conversations.get_signed_url( agent_id="your-agent-id", environment="staging", ) ``` **Client-side (JavaScript):** ```javascript import { Conversation } from "@elevenlabs/client"; const conversation = await Conversation.startSession({ agentId: "your-agent-id", environment: "staging", overrides: { asr: { keywords: ["ElevenLabs", "TechCorp"] } }, onMessage: (msg) => console.log("Agent:", msg.message), onUserTranscript: (t) => console.log("User:", t.message), onPing: (event) => console.log("Estimated latency:", event.ping_ms), onContextUsage: ({ model, context_tokens, context_limit_tokens }) => console.log(`${model}: ${context_tokens}/${context_limit_tokens} context tokens`), onError: (e) => console.error(e) }); ``` **React Hook:** Wrap hook consumers in `ConversationProvider`. Prefer granular hooks such as `useConversationControls` and `useConversationStatus` for session controls and UI state; `useConversation` remains available as the convenience all-in-one hook. Pass provider-level callbacks such as `onError` when you want React to handle conversation errors in one place. ```typescript import { ConversationProvider, useConversationControls, useConversationStatus, } from "@elevenlabs/react"; function Agent({ signedUrl }: { signedUrl: string }) { const { startSession, endSession } = useConversationControls(); const { status } = useConversationStatus(); if (status === "connected") { return <button onClick={endSession}>End conversation</button>; } return ( <button onClick={() => startSession({ signedUrl })}> Start conversation </button> ); } function App({ signedUrl }: { signedUrl: string }) { return ( <ConversationProvider onError={(error) => console.error("Conversation error:", error)} onPing={(event) => console.log("Estimated latency:", event.ping_ms)} onContextUsage={({ model, context_tokens, context_limit_tokens }) => console.log(`${model}: ${context_tokens}/${context_limit_tokens} context tokens`) } > <Agent signedUrl={signedUrl} /> </ConversationProvider> ); } ``` ## Configuration | Provider | Models | |----------|--------| | OpenAI | `gpt-6.1-sol`, `gpt-6-sol`, `gpt-6-luna`, `gpt-6-astra`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.5`, `gpt-5.5-2026-04-23`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.4-2026-03-05`, `gpt-5.4-mini-2026-03-17`, `gpt-5.4-nano-2026-03-17`, `gpt-5`, `gpt-5-mini`, `gpt-5-nano`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo` | | Anthropic | `claude-opus-5-5`, `claude-opus-5`, `claude-sonnet-5-5`, `claude-opus-4-7`, `claude-sonnet-4-6`, `claude-sonnet-4-5`, `claude-sonnet-4`, `claude-haiku-4-5`, `claude-3-7-sonnet`, `claude-3-5-sonnet`, `claude-3-haiku` | | Google | `gemini-3.8-flash`, `gemini-3.7-flash`, `gemini-3.6-flash`, `gemini-3.1-flash-lite-preview`, `gemini-3.1-pro-preview`, `gemini-3-pro-preview`, `gemini-3-flash-preview`, `gemini-2.5-flash`, `gemini-2.5-flash-lite`, `gemini-2.0-flash`, `gemini-2.0-flash-lite` | | ElevenLabs | `glm-52`, `deepseek-v41-flash`, `glm-45-air-fp8`, `qwen3-30b-a3b`, `qwen36-35b-a3b`, `qwen35-35b-a3b`, `qwen35-397b-a17b`, `gpt-oss-120b` | | Custom | `custom-llm` (bring your own endpoint) | Use `GET /v1/convai/llm/list` to inspect the current model catalog, including deprecation state, token/context limits, capability flags such as image-input support, and model-specific reasoning effort support. To run an agent on an ElevenLabs Realtime model instead of a separate LLM and TTS model (`conversation_config.realtime_model`), use the `realtime` skill. **Popular voices:** `JBFqnCBsd6RMkjVDRZzb` (George), `EXAVITQu4vr4xnSDxMaL` (Sarah), `onwK4e9ZLuTAKqWW03F9` (Daniel), `XB0fDUnXU5powFXDhCwa` (Charlotte) **Turn eagerness:** `patient` (waits longer for user to finish), `normal`, or `eager` (responds quickly) See [Agent Configuration](references/agent-configuration.md) for all options. ## System Prompt Structure Section the prompt with markdown headings — the model prioritizes and interprets instructions more reliably ([prompting guide](https://elevenlabs.io/docs/eleven-agents/best-practices/prompting-guide)): ``` # Personality – named character, 2-3 traits # Environment – where they work, who they talk to # Tone – vocal style as 4-5 bullets # Goal – what success looks like (numbered for multi-step flows) ``` Keep instructions short and action-based. Mark critical steps with "This step is important." For critical refusal/safety rules, include concise instructions in the prompt and also configure independent custom Guardrails via `platform_settings.guardrails` (see [Guardrails](#guardrails)). ## Tools Extend agents with webhook, client, or built-in system tools. Tools are defined inside `conversation_config.agent.prompt`: Workspace environment variables can resolve per-environment server tool URLs, headers, and auth connections, and runtime system variables such as `{{system__conversation_history}}` can pass full conversation context into tool calls when needed. ```python "prompt": { "prompt": "You are a helpful assistant that can check the weather.", "llm": "gemini-2.0-flash", "tools": [ # Webhook: server-side API call {"type": "webhook", "name": "get_weather", "description": "Get weather", "api_schema": {"url": "https://api.example.com/weather", "method": "POST", "request_body_schema": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}}}, # Client: runs in the browser {"type": "client", "name": "show_product", "description": "Display a product", "parameters": {"type": "object", "properties": {"productId": {"type": "string"}}, "required": ["productId"]}} ], "built_in_tools": { "end_call": {}, "transfer_to_number": {"transfers": [{"transfer_destination": {"type": "phone", "phone_number": "+1234567890"}, "condition": "User asks for human support"}]} } } ``` **Client tools** run in browser: ```javascript clientTools: { show_product: async ({ productId }) => { document.getElementById("product").src = `/products/${productId}`; return { success: true }; } } ``` See [Client Tools Reference](references/client-tools.md) for complete documentation. ### Built-in System Tools Set under `conversation_config.agent.prompt.built_in_tools`. `{}` enables defaults; provide `description` to customize; omit to disable. | Tool | Enable for | |------|------------| | `end_call` | All agents | | `language_detection` | Multilingual agents | | `transfer_to_number` | Phone-based human escalation | | `transfer_to_agent` | Multi-agent workflows | | `skip_turn` | Tutoring / coaching (silent listening) | | `voicemail_detection` | Outbound calling | | `play_keypad_touch_tone` | IVR navigation | `start_procedure` and `end_procedure` are not configured here. The platform adds them automatically whenever the agent has at least one procedure (see [Procedures](#procedures)). `run_subagent` is a system tool for delegating a task to another configured agent. Add it to `conversation_config.agent.prompt.tools` with `params.system_tool_type: "run_subagent"` and an `agents` array. Each entry requires `agent_id` and `description`; `branch_id` and a JSON-schema `parameters` object are optional. `knowledge_base` is a system tool for letting the model choose how to inspect attached knowledge. Add it to `conversation_config.agent.prompt.tools` with `type: "system"`, a `name`, and `params.system_tool_type: "knowledge_base"`. Use `enabled_strategies` to expose any combination of `cat`, `keyword`, `semantic`, and `ls`: ```json { "type": "system", "name": "knowledge_base", "description": "Search the attached knowledge base.", "params": { "system_tool_type": "knowledge_base",