agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ElevenLabs Agents Platform

ElevenLabs Agent平台

Build voice AI agents with natural conversations, multiple LLM providers, custom tools, and easy web embedding.

Setup: See Installation Guide for CLI and SDK setup.

构建具备自然对话能力、支持多LLM提供商、可自定义工具且易于嵌入网页的语音AI Agent。

设置： 请查看安装指南了解CLI和SDK的设置方法。

Quick Start with CLI

CLI快速开始

The ElevenLabs CLI is the recommended way to create and manage agents:

bash

undefined

ElevenLabs CLI是创建和管理Agent的推荐方式：

bash

undefined

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 default

Push to ElevenLabs platform

elevenlabs agents push


**Available templates:** `default`, `minimal`, `voice-only`, `text-only`, `customer-service`, `assistant`

elevenlabs agents push


**可用模板：** `default`, `minimal`, `voice-only`, `text-only`, `customer-service`, `assistant`

Python

python

from elevenlabs.client 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"},
        "tts": {"voice_id": "JBFqnCBsd6RMkjVDRZzb"}
    },
    prompt={
        "prompt": "You are a helpful assistant. Be concise and friendly.",
        "llm": "gpt-4o-mini",
        "temperature": 0.7
    }
)

python

from elevenlabs.client 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"},
        "tts": {"voice_id": "JBFqnCBsd6RMkjVDRZzb"}
    },
    prompt={
        "prompt": "You are a helpful assistant. Be concise and friendly.",
        "llm": "gpt-4o-mini",
        "temperature": 0.7
    }
)

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" },
    tts: { voiceId: "JBFqnCBsd6RMkjVDRZzb" }
  },
  prompt: { prompt: "You are a helpful assistant.", llm: "gpt-4o-mini", temperature: 0.7 }
});

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" },
    tts: { voiceId: "JBFqnCBsd6RMkjVDRZzb" }
  },
  prompt: { prompt: "You are a helpful assistant.", llm: "gpt-4o-mini", temperature: 0.7 }
});

cURL

bash

curl -X POST "https://api.elevenlabs.io/v1/convai/agents/create" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "My Assistant", "conversation_config": {"agent": {"first_message": "Hello!", "language": "en"}, "tts": {"voice_id": "JBFqnCBsd6RMkjVDRZzb"}}, "prompt": {"prompt": "You are helpful.", "llm": "gpt-4o-mini"}}'

bash

curl -X POST "https://api.elevenlabs.io/v1/convai/agents/create" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "My Assistant", "conversation_config": {"agent": {"first_message": "Hello!", "language": "en"}, "tts": {"voice_id": "JBFqnCBsd6RMkjVDRZzb"}}, "prompt": {"prompt": "You are helpful.", "llm": "gpt-4o-mini"}}'

Starting Conversations

启动对话

Server-side (Python): Get signed URL for client connection:

python

signed_url = client.conversational_ai.conversations.get_signed_url(agent_id="your-agent-id")

Client-side (JavaScript):

javascript

import { Conversation } from "@elevenlabs/client";

const conversation = await Conversation.startSession({
  agentId: "your-agent-id",
  onMessage: (msg) => console.log("Agent:", msg.message),
  onUserTranscript: (t) => console.log("User:", t.message),
  onError: (e) => console.error(e)
});

React Hook:

typescript

import { useConversation } from "@elevenlabs/react";

const conversation = useConversation({ onMessage: (msg) => console.log(msg) });
// Get signed URL from backend, then:
await conversation.startSession({ signedUrl: token });

服务端（Python）： 获取用于客户端连接的签名URL：

python

signed_url = client.conversational_ai.conversations.get_signed_url(agent_id="your-agent-id")

客户端（JavaScript）：

javascript

import { Conversation } from "@elevenlabs/client";

const conversation = await Conversation.startSession({
  agentId: "your-agent-id",
  onMessage: (msg) => console.log("Agent:", msg.message),
  onUserTranscript: (t) => console.log("User:", t.message),
  onError: (e) => console.error(e)
});

React Hook：

typescript

import { useConversation } from "@elevenlabs/react";

const conversation = useConversation({ onMessage: (msg) => console.log(msg) });
// 从后端获取签名URL，然后：
await conversation.startSession({ signedUrl: token });

Configuration

配置

Provider	Models
OpenAI	`gpt-4o` , `gpt-4o-mini` , `gpt-4-turbo`
Anthropic	`claude-3-5-sonnet` , `claude-3-5-haiku`
Google	`gemini-1.5-pro` , `gemini-1.5-flash`
Custom	`custom-llm` (bring your own endpoint)

Popular voices:

JBFqnCBsd6RMkjVDRZzb

(George),

EXAVITQu4vr4xnSDxMaL

(Sarah),

onwK4e9ZLuTAKqWW03F9

(Daniel),

XB0fDUnXU5powFXDhCwa

(Charlotte)

Turn-taking modes:

server_vad

(auto-detect speech end) or

turn_based

(explicit signals)

See Agent Configuration for all options.

提供商	模型
OpenAI	`gpt-4o` , `gpt-4o-mini` , `gpt-4-turbo`
Anthropic	`claude-3-5-sonnet` , `claude-3-5-haiku`
Google	`gemini-1.5-pro` , `gemini-1.5-flash`
自定义	`custom-llm` （接入自有端点）

热门语音：

JBFqnCBsd6RMkjVDRZzb

（George）,

EXAVITQu4vr4xnSDxMaL

（Sarah）,

onwK4e9ZLuTAKqWW03F9

（Daniel）,

XB0fDUnXU5powFXDhCwa

（Charlotte）

话轮切换模式：

server_vad

（自动检测语音结束）或

turn_based

（显式信号）

查看Agent配置了解所有选项。

Tools

工具

Extend agents with webhook, client, or system tools:

python

tools=[
    # Webhook: server-side API call
    {"type": "webhook", "name": "get_weather", "description": "Get weather",
     "webhook": {"url": "https://api.example.com/weather", "method": "POST"},
     "parameters": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}},
    # System: built-in capabilities
    {"type": "system", "name": "end_call"},
    {"type": "system", "name": "transfer_to_number", "phone_number": "+1234567890"}
]

Client tools run in browser:

javascript

clientTools: {
  show_product: async ({ productId }) => {
    document.getElementById("product").src = `/products/${productId}`;
    return { success: true };
  }
}

See Client Tools Reference for complete documentation.

通过Webhook、客户端或系统工具扩展Agent功能：

python

tools=[
    # Webhook：服务端API调用
    {"type": "webhook", "name": "get_weather", "description": "Get weather",
     "webhook": {"url": "https://api.example.com/weather", "method": "POST"},
     "parameters": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}},
    # 系统：内置功能
    {"type": "system", "name": "end_call"},
    {"type": "system", "name": "transfer_to_number", "phone_number": "+1234567890"}
]

客户端工具在浏览器中运行：

javascript

clientTools: {
  show_product: async ({ productId }) => {
    document.getElementById("product").src = `/products/${productId}`;
    return { success: true };
  }
}

查看客户端工具参考获取完整文档。

Widget Embedding

小部件嵌入

html

<elevenlabs-convai agent-id="your-agent-id"></elevenlabs-convai>
<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>

Customize with attributes:

avatar-image-url

action-text

start-call-text

end-call-text

See Widget Embedding Reference for all options.

html

<elevenlabs-convai agent-id="your-agent-id"></elevenlabs-convai>
<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>

可通过属性自定义：

avatar-image-url

、

action-text

、

start-call-text

、

end-call-text

。

查看小部件嵌入参考了解所有选项。

Outbound Calls

外呼电话

Make outbound phone calls using your agent via Twilio integration:

通过Twilio集成使用你的Agent发起外呼电话：

Python

python

response = client.conversational_ai.twilio.outbound_call(
    agent_id="your-agent-id",
    agent_phone_number_id="your-phone-number-id",
    to_number="+1234567890"
)
print(f"Call initiated: {response.conversation_id}")

python

response = client.conversational_ai.twilio.outbound_call(
    agent_id="your-agent-id",
    agent_phone_number_id="your-phone-number-id",
    to_number="+1234567890"
)
print(f"Call initiated: {response.conversation_id}")

JavaScript

javascript

const response = await client.conversationalAi.twilio.outboundCall({
  agentId: "your-agent-id",
  agentPhoneNumberId: "your-phone-number-id",
  toNumber: "+1234567890",
});

javascript

const response = await client.conversationalAi.twilio.outboundCall({
  agentId: "your-agent-id",
  agentPhoneNumberId: "your-phone-number-id",
  toNumber: "+1234567890",
});

cURL

bash

curl -X POST "https://api.elevenlabs.io/v1/convai/twilio/outbound-call" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"agent_id": "your-agent-id", "agent_phone_number_id": "your-phone-number-id", "to_number": "+1234567890"}'

See Outbound Calls Reference for configuration overrides and dynamic variables.

bash

curl -X POST "https://api.elevenlabs.io/v1/convai/twilio/outbound-call" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"agent_id": "your-agent-id", "agent_phone_number_id": "your-phone-number-id", "to_number": "+1234567890"}'

查看外呼电话参考了解配置覆盖和动态变量。

Managing Agents

管理Agent

Using CLI (Recommended)

使用CLI（推荐）

bash

undefined

bash

undefined

List agents and check status

列出Agent并查看状态

elevenlabs agents list elevenlabs agents status

Import agents from platform to local config

从平台导入Agent到本地配置

elevenlabs agents pull # Import all agents elevenlabs agents pull --agent <agent-id> # Import specific agent

elevenlabs agents pull # 导入所有Agent elevenlabs agents pull --agent <agent-id> # 导入指定Agent

Push local changes to platform

将本地变更推送到平台

elevenlabs agents push # Upload configurations elevenlabs agents push --dry-run # Preview changes first

elevenlabs agents push # 上传配置 elevenlabs agents push --dry-run # 先预览变更

Add tools to agents

为Agent添加工具

elevenlabs agents tools add "Weather API" --type webhook --config-path ./weather.json

undefined

elevenlabs agents tools add "Weather API" --type webhook --config-path ./weather.json

undefined

Project Structure

项目结构

The CLI creates a project structure for managing agents:

your_project/
├── agents.json       # Agent definitions
├── tools.json        # Tool configurations
├── agent_configs/    # Individual agent configs
└── tool_configs/     # Individual tool configs

CLI会创建用于管理Agent的项目结构：

your_project/
├── agents.json       # Agent定义
├── tools.json        # 工具配置
├── agent_configs/    # 单个Agent配置
└── tool_configs/     # 单个工具配置

SDK Examples

SDK示例

python

undefined

python

undefined

List

列出

agents = client.conversational_ai.agents.list()

Get

获取

agent = client.conversational_ai.agents.get(agent_id="your-agent-id")

Update (partial - only include fields to change)

更新（部分更新 - 仅包含需要修改的字段）

client.conversational_ai.agents.update(agent_id="your-agent-id", name="New Name") client.conversational_ai.agents.update(agent_id="your-agent-id", prompt={"prompt": "New instructions", "llm": "claude-3-5-sonnet"})

Delete

删除

client.conversational_ai.agents.delete(agent_id="your-agent-id")


See [Agent Configuration](references/agent-configuration.md) for all configuration options and SDK examples.

client.conversational_ai.agents.delete(agent_id="your-agent-id")


查看[Agent配置](references/agent-configuration.md)了解所有配置选项和SDK示例。

Error Handling

错误处理

python

try:
    agent = client.conversational_ai.agents.create(...)
except Exception as e:
    print(f"API error: {e}")

Common errors: 401 (invalid key), 404 (not found), 422 (invalid config), 429 (rate limit)

python

try:
    agent = client.conversational_ai.agents.create(...)
except Exception as e:
    print(f"API error: {e}")

常见错误：401（无效密钥）、404（未找到）、422（无效配置）、429（请求超限）

References

参考

Installation Guide - SDK setup and migration
Agent Configuration - All config options and CRUD examples
Client Tools - Webhook, client, and system tools
Widget Embedding - Website integration
Outbound Calls - Twilio phone call integration

安装指南 - SDK设置和迁移
Agent配置 - 所有配置选项和增删改查示例
客户端工具 - Webhook、客户端和系统工具
小部件嵌入 - 网站集成
外呼电话 - Twilio电话集成