agents

Name: agents
Author: elevenlabs

ElevenLabs 代理平台

构建具有自然对话、多种 LLM 提供商、自定义工具和简单网页嵌入的语音 AI 代理。

设置： 请参阅安装指南了解 CLI 和 SDK 设置。

使用 CLI 快速开始

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

# 安装 CLI 并进行身份验证
npm install -g @elevenlabs/cli
elevenlabs auth login

# 初始化项目并创建代理
elevenlabs agents init
elevenlabs agents add "我的助手" --template complete

# 推送到 ElevenLabs 平台
elevenlabs agents push

可用模板： complete, minimal, voice-only, text-only, customer-service, assistant

Python

from elevenlabs import ElevenLabs

client = ElevenLabs()

agent = client.conversational_ai.agents.create(
    name="我的助手",
    conversation_config={
        "agent": {
            "first_message": "你好！有什么可以帮你的？",
            "language": "zh",
            "prompt": {
                "prompt": "你是一个乐于助人的助手。请简洁友好。",
                "llm": "gemini-2.0-flash",
                "temperature": 0.7
            }
        },
        "tts": {"voice_id": "JBFqnCBsd6RMkjVDRZzb"}
    }
)

JavaScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const client = new ElevenLabsClient();

const agent = await client.conversationalAi.agents.create({
  name: "我的助手",
  conversationConfig: {
    agent: {
      firstMessage: "你好！有什么可以帮你的？",
      language: "zh",
      prompt: {
        prompt: "你是一个乐于助人的助手。",
        llm: "gemini-2.0-flash",
        temperature: 0.7
      }
    },
    tts: { voiceId: "JBFqnCBsd6RMkjVDRZzb" }
  }
});

cURL

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": "我的助手", "conversation_config": {"agent": {"first_message": "你好！", "language": "zh", "prompt": {"prompt": "你是一个乐于助人的助手。", "llm": "gemini-2.0-flash"}}, "tts": {"voice_id": "JBFqnCBsd6RMkjVDRZzb"}}}'

开始对话

临时 LiveKit WebSocket 固定版本

在 ElevenLabs LiveKit 服务器支持 /rtc/v1 之前，使用 WebRTC 的浏览器客户端在底层 LiveKit WebSocket 握手过程中可能会失败或卡住，尤其是使用 livekit-client 版本高于 2.16.1 时。对于使用 connectionType: "webrtc" 或访问 wss://livekit.rtc.elevenlabs.io/rtc/v1 的 React、Next.js、Electron 或其他 @elevenlabs/client / @elevenlabs/react 集成，请在 package.json 中添加此临时固定版本：

{
  "overrides": {
    "livekit-client": "2.16.1"
  }
}

当应用在会话启动时记录 /rtc/v1 404、v1 RTC path not found 或 could not establish pc connection 时，请使用此固定版本。这是针对 WebRTC 会话的 LiveKit 服务器兼容性解决方法，而非 ElevenLabs 的 connectionType: "websocket" 传输方式。上游 LiveKit 服务器或 SDK 问题修复后请移除。

服务器端 (Python)： 获取用于客户端连接的签名 URL：

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

客户端 (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("代理:", msg.message),
  onUserTranscript: (t) => console.log("用户:", t.message),
  onPing: (event) => console.log("估计延迟:", event.ping_ms),
  onError: (e) => console.error(e)
});

React Hook： 将 Hook 消费者包裹在 ConversationProvider 中。建议使用细粒度 Hook，如 useConversationControls 和 useConversationStatus 来控制会话和 UI 状态；useConversation 仍可作为便捷的全能 Hook 使用。当希望 React 在统一位置处理对话错误时，可传递提供者级别的回调，如 onError。

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}>结束对话</button>;
  }

  return (
    <button onClick={() => startSession({ signedUrl })}>
      开始对话
    </button>
  );
}

function App({ signedUrl }: { signedUrl: string }) {
  return (
    <ConversationProvider
      onError={(error) => console.error("对话错误:", error)}
      onPing={(event) => console.log("估计延迟:", event.ping_ms)}
    >
      <Agent signedUrl={signedUrl} />
    </ConversationProvider>
  );
}

配置

提供商	模型
OpenAI	`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-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.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-45-air-fp8`, `qwen3-30b-a3b`, `qwen36-35b-a3b`, `qwen35-35b-a3b`, `qwen35-397b-a17b`, `gpt-oss-120b`
自定义	`custom-llm` (自带端点)

使用 GET /v1/convai/llm/list 查看当前模型目录，包括弃用状态、令牌/上下文限制、能力标志（如图像输入支持）以及模型特定的推理努力支持。

热门语音： JBFqnCBsd6RMkjVDRZzb (George), EXAVITQu4vr4xnSDxMaL (Sarah), onwK4e9ZLuTAKqWW03F9 (Daniel), XB0fDUnXU5powFXDhCwa (Charlotte)

轮次急切度： patient (等待用户完成更长时间), normal, 或 eager (快速响应)

所有选项请参阅代理配置。

系统提示结构

使用 Markdown 标题对提示进行分段——模型会更可靠地优先处理和解释指令（提示指南）：

# 个性   – 命名角色，2-3 个特质
# 环境   – 工作地点，与谁交谈
# 语气   – 语音风格，4-5 个要点
# 目标   – 成功的标准（多步骤流程使用编号）

保持指令简短且基于行动。用“此步骤很重要”标记关键步骤。对于关键的拒绝/安全规则，在提示中包含简洁的指令，并通过 platform_settings.guardrails 配置独立的自定义护栏（请参阅护栏）。

工具

通过 Webhook、客户端或内置系统工具扩展代理。工具定义在 conversation_config.agent.prompt 内：

工作区环境变量可以解析每个环境的服务器工具 URL、标头和身份验证连接，运行时系统变量（如 {{system__conversation_history}}）可以在需要时将完整的对话上下文传递给工具调用。

"prompt": {
    "prompt": "你是一个乐于助人的助手，可以查询天气。",
    "llm": "gemini-2.0-flash",
    "tools": [
        # Webhook：服务器端 API 调用
        {"type": "webhook", "name": "get_weather", "description": "获取天气",
         "api_schema": {"url": "https://api.example.com/weather", "method": "POST",
             "request_body_schema": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}}},
        # 客户端：在浏览器中运行
        {"type": "client", "name": "show_product", "description": "显示产品",
         "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": "用户要求人工支持"}]},
        "start_procedure": {}
    }
}

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

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

完整文档请参阅客户端工具参考。

内置系统工具

在 conversation_config.agent.prompt.built_in_tools 下设置。{} 启用默认设置；提供 description 进行自定义；省略则禁用。

工具	启用场景
`end_call`	所有代理
`language_detection`	多语言代理
`transfer_to_number`	基于电话的人工升级
`transfer_to_agent`	多代理工作流
`start_procedure`	流程引导的对话
`end_procedure`	完成活动流程
`skip_turn`	辅导/指导（静默监听）
`voicemail_detection`	外呼
`play_keypad_touch_tone`	IVR 导航

run_subagent 是一个系统工具，用于将任务委托给另一个已配置的代理。将其添加到 conversation_config.agent.prompt.tools，并设置 params.system_tool_type: "run_subagent" 和一个 agents 数组。每个条目需要 agent_id 和 description；branch_id 和 JSON 模式的 parameters 对象是可选的。

集成工具

由平台管理的预构建连接器。使用凭据创建连接，然后通过 tool_ids 附加：

集成	用例
`calcom`	预约安排
`salesforce`	CRM 查询、创建案例
`hubspot`	CRM、营销、联系人
`zendesk`	支持工单

三步流程：POST /v1/convai/api-integrations/{id}/connections → GET /v1/convai/api-integrations/{id}/tools → POST /v1/convai/tools，包含 api_integration_id 和 api_integration_connection_id。通过 "prompt": {"tool_ids": ["tool_xxxx"]} 附加到代理。内联 tools 和 tool_ids 可以共存——优先使用集成而不是重复的自定义 Webhook。

公共 API Webhook 示例

适用于原型的无需身份验证的 API（URL 必须为 HTTPS）：

工具	URL	用途
`get_weather`	`https://wttr.in/{location}?format=j1`	当前天气
`search_wikipedia`	`https://en.wikipedia.org/api/rest_v1/page/summary/{topic}`	主题摘要
`get_exchange_rate`	`https://open.er-api.com/v6/latest/{base_currency}`	汇率

工作流

通过具有分支逻辑的离散步骤路由对话。在代理顶层的 workflow 字段下定义。参考：代理工作流。

节点类型： start (ID 必须为 "start_node"), end, override_agent (子代理步骤，包含 label + additional_prompt), dispatch_tool (执行工具，带有成功/失败路由), agent_transfer, transfer_to_number。

边类型： unconditional, llm (自然语言条件), expression (确定性数据检查)。工具节点有单独的成功/失败边。

按步骤限定工具范围 使用节点上的 additional_tool_ids——防止错误的工具在错误的步骤触发。在对话路由节点（如问候和 classify_intent）上设置 additional_tool_ids: []，使其仅进行对话：

{
  "type": "override_agent",
  "label": "预约",
  "additional_prompt": "讨论首选日期和医生。一旦达成一致，显示预约表单。",
  "entry_behavior": "wait_for_user",
  "additional_tool_ids": ["show_booking_form", "display_appointment_card"],
  "position": {"x": 0, "y": 400}
}

在每个节点上包含 position ({x, y})，以便编辑器清晰渲染。从 y=0 开始，将 end 放在底部，水平分支间距为 x=-150 和 x=150；建议垂直间距为 200px，水平间距为 300px。保持工作流在 4-7 个节点内，并始终有一条通往 end 的路径。

在 override_agent 节点上使用 entry_behavior 来选择子代理是立即发言 (generate_immediately)、等待用户输入 (wait_for_user) 还是让平台决定 (auto)。

对于嵌套代理转移，在 standalone_agent 节点上设置 enable_nesting，并在应返回控制权给父工作流的 end 节点上设置 return_when_nested。

护栏

独立于 LLM 运行的分层安全执行——在 platform_settings.guardrails 下配置，而不是在系统提示中。参考：护栏。

"platform_settings": {
  "guardrails": {
    "version": "1",
    "focus": {"is_enabled": true},
    "prompt_injection": {"is_enabled": true},
    "content": {"config": {"harassment": {"is_enabled": true, "threshold": 0.5}}},
    "custom": {
      "config": {
        "configs": [{
          "is_enabled": true,
          "name": "禁止医疗诊断",
          "prompt": "阻止代理提供医疗诊断或治疗建议。",
          "execution_mode": "blocking",
          "model": "gemini-2.5-flash-lite",
          "history_message_count": 1,
          "trigger_action": {"type": "retry", "feedback": "原因: {{trigger_reason}}"}
        }]
      }
    }
  }
}

类型： focus (话题相关), prompt_injection (操纵防御), content (类别过滤器), custom (LLM 评估的领域规则)。内容类别包括 harassment, profanity, sexual, violence, self_harm 和 medical_and_legal_information——阈值范围 0.0–1.0 (默认 0.3)。自定义规则使用 execution_mode: "blocking"，并包含 model、history_message_count 和 trigger_action (例如，带反馈的 retry)。自定义护栏并行评估，失败时开放。

按垂直领域： 医疗/金融/法律 → 启用 medical_and_legal_information；教育/青少年 → sexual/violence/self_harm/profanity；支持/销售 → harassment/profanity。所有代理都受益于 focus + prompt_injection + 2-4 条自定义规则。

测试代理

通过 POST /v1/convai/agent-testing/create 创建三种测试类型，然后通过 PATCH 附加到代理。参考：代理测试。

类型	用途
`llm`	场景测试——代理是否对消息做出适当响应？
`tool`	工具调用测试——正确的工具，正确的参数？
`simulation`	使用模拟用户角色的多轮流程

// 工具调用测试 (全程使用 snake_case；chat_history 角色为 "user" 或 "agent")
{
  "name": "使用正确的医生和日期预约",
  "type": "tool",
  "chat_history": [
    {"role": "user", "message": "3月5日下午2点找史密斯医生", "time_in_call_secs": 10}
  ],
  "tool_call_parameters": {
    "referenced_tool": {"id": "show_booking_form", "type": "client"},
    "parameters": [
      {"path": "doctor_name", "eval": {"type": "llm", "description": "应提及史密斯医生"}},
      {"path": "date", "eval": {"type": "regex", "pattern": "2025-03-05|3月5日"}}
    ]
  }
}

评估策略：exact, regex, llm。提示评估标准可以使用二元评分或数值评分，使用 scoring_mode: "numeric_uniform"、max_score 和 score_instructions；数值评分会归一化到聚合的对话成功百分比。通过 PATCH 附加：

curl -s -X PATCH "https://api.elevenlabs.io/v1/convai/agents/{agent_id}" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"platform_settings": {"testing": {"attached_tests": [{"test_id": "test_xxxx"}]}}}'

使用 POST /v1/convai/agents/{agent_id}/run-tests 运行选定的测试。请求体需要 tests，并接受 repeat_count，范围从 1 到 50，用于重复运行。模拟测试可以定义最多 30 个 success_conditions 提示；所有标准都会被评估并合并到最终结果中。
对于已完成的对话，使用 POST /v1/convai/conversations/{conversation_id}/analysis/evaluations/run 和包含 evaluation_id 的请求体重新运行一个评估标准。

小部件嵌入

<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。

所有选项请参阅小部件嵌入参考。

外呼

通过 Twilio 或 Exotel 集成使用您的代理进行外呼：

以下示例使用 Twilio。Exotel REST 用法请参阅参考。

Python

response = client.conversational_ai.twilio.outbound_call(
    agent_id="your-agent-id",
    agent_phone_number_id="your-phone-number-id",
    to_number="+1234567890",
    call_recording_enabled=True
)
print(f"呼叫已发起: {response.conversation_id}")

JavaScript

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

cURL

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", "call_recording_enabled": true}'

请参阅外呼参考了解提供商特定的端点、配置覆盖和动态变量。

管理代理

使用 CLI (推荐)

# 列出代理并检查状态
elevenlabs agents list
elevenlabs agents status

# 从平台导入代理到本地配置
elevenlabs agents pull                      # 导入所有代理
elevenlabs agents pull --agent <agent-id>   # 导入特定代理

# 将本地更改推送到平台
elevenlabs agents push              # 上传配置
elevenlabs agents push --dry-run    # 先预览更改

# 添加工具
elevenlabs tools add-webhook "天气 API"
elevenlabs tools add-client "UI 工具"

项目结构

CLI 创建一个用于管理代理的项目结构：

your_project/
├── agents.json       # 代理定义
├── tools.json        # 工具配置
├── tests.json        # 测试配置
├── agent_configs/    # 单个代理配置
├── tool_configs/     # 单个工具配置
└── test_configs/     # 单个测试配置

SDK 示例

# 列出
agents = client.conversational_ai.agents.list()

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

# 更新 (部分更新 - 仅包含要更改的字段)
client.conversational_ai.agents.update(agent_id="your-agent-id", name="新名称")
client.conversational_ai.agents.update(agent_id="your-agent-id",
    conversation_config={
        "agent": {"prompt": {"prompt": "新指令", "llm": "claude-sonnet-4"}}
    })

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

所有配置选项和 SDK 示例请参阅代理配置。

错误处理

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

常见错误：401 (无效密钥), 404 (未找到), 422 (无效配置), 429 (速率限制)

参考

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

你可能还喜欢

flox-environments

237Kbackend-api

使用 Flox 打造可复现、跨平台（macOS/Linux）的开发环境。Flox 是一款基于 Nix 的声明式环境管理工具。适用于为任意语言搭建项目工具链、安装系统级依赖（编译器、数据库、openssl/BLAS 等底层原生库）、锁定团队统一的软件包版本、运行本地服务（PostgreSQL、Redis、Kafka）、一键完成新成员入职环境配置，或解决“在我电脑上明明能跑”的经典坑——也包括不需要 sudo 权限就能在项目作用域下安装所需工具的 AI Agent / vibe coding 场景。当用户提及 .flox/、manifest.toml、flox activate 或 FloxHub 时同样适用。

affaan-m

获取

cloud

107Kbackend-api

Browser Use Cloud 参考文档指南。Browser Use Cloud 是用于浏览器自动化的托管式 API 与 SDK。当用户需要处理以下需求时请触发此 Skill：Cloud REST API（v2 或 v3）、browser-use-sdk（Python 或 TypeScript）、X-Browser-Use-API-Key 身份验证、云端 Session（会话）、浏览器 Profile 配置与同步、CDP WebSocket 直连、防检测隐身浏览器、住宅代理、验证码（CAPTCHA）处理、Webhook、工作区（Workspace）、Skill 技能市场、liveUrl 实时流传输、价格方案，或各类集成模式（如 Chat UI 界面、Subagent 子 Agent 模式、为现有 Agent 扩展浏览器工具等）。当遇到 n8n / Make / Zapier 集成、在云端基础设施上运行 Playwright / Puppeteer / Selenium，或 1Password 凭据库集成相关问题时也可触发。请注意：若用户询问的是开源版 Python 库（Agent、Browser、Tools 配置），请勿使用本 Skill，请改用开源版 Skill。