elevenlabs-agents

ElevenLabs Agents Platform

概述

ElevenLabs Agents Platform 是一个全面的解决方案，用于构建可投入生产的对话式语音 AI Agent。该平台协调四个核心组件：

1. ASR（自动语音识别） - 将语音转换为文本（支持 32+ 种语言，延迟低于一秒）
2. LLM（大语言模型） - 推理和生成回复（GPT、Claude、Gemini、自定义模型）
3. TTS（文本转语音） - 将文本转换为语音（5000+ 种声音，31 种语言，低延迟）
4. 轮流发言模型 - 专有模型，用于处理对话时机和打断

🚨 软件包迁移（2025 年 8 月）

已弃用（请勿使用）： @11labs/react 和 @11labs/client

当前软件包：

bun add @elevenlabs/[email protected]        # React SDK
bun add @elevenlabs/[email protected]       # JavaScript SDK
bun add @elevenlabs/[email protected]  # React Native SDK
bun add @elevenlabs/[email protected] # Base SDK
bun add -g @elevenlabs/[email protected]  # CLI

如果要迁移，请先卸载旧软件包：npm uninstall @11labs/react @11labs/client

---

快速入门

路径 A：React SDK（嵌入式语音聊天）

用于在 React 应用中构建语音聊天界面。

安装：

bun add @elevenlabs/react zod

基本示例：

import { useConversation } from '@elevenlabs/react';
import { z } from 'zod';

export default function VoiceChat() {
  const { startConversation, stopConversation, status } = useConversation({
    // Authentication (choose one)
    agentId: 'your-agent-id',  // Public agent (no key needed)
    // apiKey: process.env.NEXT_PUBLIC_ELEVENLABS_API_KEY,  // Private (dev only)
    // signedUrl: '/api/elevenlabs/auth',  // Signed URL (production)

    // Client-side tools
    clientTools: {
      updateCart: {
        description: "Update the shopping cart",
        parameters: z.object({
          item: z.string(),
          quantity: z.number()
        }),
        handler: async ({ item, quantity }) => {
          console.log('Updating cart:', item, quantity);
          return { success: true };
        }
      }
    },

    // Event handlers
    onEvent: (event) => {
      if (event.type === 'transcript') console.log('User:', event.data.text);
      if (event.type === 'agent_response') console.log('Agent:', event.data.text);
    },

    // Regional compliance
    serverLocation: 'us' // 'us' | 'global' | 'eu-residency' | 'in-residency'
  });

  return (
    <div>
      <button onClick={startConversation}>Start Conversation</button>
      <button onClick={stopConversation}>Stop</button>
      <p>Status: {status}</p>
    </div>
  );
}

完整模板： 请参阅 templates/basic-react-agent.tsx

路径 B：CLI（“Agents as Code”）

通过代码管理 Agent，并使用版本控制和 CI/CD。使用 CLI 工作流时，请加载 references/cli-commands.md。

快速工作流：

bun add -g @elevenlabs/agents-cli
elevenlabs auth login
elevenlabs agents init
elevenlabs agents add "Support Agent" --template customer-service
# Edit agent_configs/support-agent.json
elevenlabs agents push --env dev
elevenlabs agents test "Support Agent"

请参阅： references/cli-commands.md，了解完整的 CLI 参考和工作流。

路径 C：API（以编程方式管理 Agent）

用于动态创建 Agent（多租户、SaaS 平台）。直接使用 API 时，请加载 references/api-reference.md。

快速示例：

import { ElevenLabsClient } from 'elevenlabs';

const client = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY
});

const agent = await client.agents.create({
  name: 'Support Bot',
  conversation_config: {
    agent: {
      prompt: { prompt: "You are a helpful support agent.", llm: "gpt-4o" },
      first_message: "Hello! How can I help you today?"
    },
    tts: { model_id: "eleven_turbo_v2_5", voice_id: "your-voice-id" }
  }
});

请参阅： references/api-reference.md，了解完整的 API 参考。

---

Agent 配置

系统提示词框架

ElevenLabs 推荐采用包含 6 个组成部分的提示词结构：个性（身份／角色）、环境（交流情境）、语气（正式程度／说话方式）、目标（目标／成功标准）、护栏（边界／道德规范）和工具（可用功能）。

结构示例：

Personality: You are Alex, a friendly customer support specialist at TechCorp.
Environment: Phone communication, voice-only, potential background noise.
Tone: Professional yet warm. Use contractions. Keep responses to 2-3 sentences.
Goal: Resolve issues on first call. Success = customer confirms resolution.
Guardrails: Never give medical/legal advice. Escalate if customer becomes abusive.
Tools: lookup_order(id), transfer_to_supervisor(), send_password_reset(email)

完整指南： 配置 Agent 提示词或提升对话质量时，请加载 references/system-prompt-guide.md。

轮流发言模式

模式	行为	适用场景
积极	快速回应，较早插话	快节奏支持、快速下单
普通	均衡，在自然停顿时等待	通用客户服务（默认）
耐心	等待更长时间，以便获得详细回复	信息收集、辅导

在 conversation_config 中配置："turn": { "mode": "patient" }

---

核心功能摘要

语音与语言

• 多语音： 动态切换语音（每次切换增加约 200 ms 延迟）
• 发音词典： 使用 IPA、CMU 或单词替换来定制发音
• 语速控制： 0.7x - 1.2x（1.0x = 正常语速）
• 语言： 支持 32+ 种语言，具备自动检测和多语言预设

知识库（RAG）

上传文档（PDF/TXT/DOCX），以便在对话期间进行语义搜索。Agent 会自动检索相关片段。每次查询会增加约 500 ms 延迟。文档必须先建立索引才能使用。

请参阅： references/api-reference.md，了解知识库 API 和配置。

工具（4 种类型）

1. 客户端工具 - 在浏览器中执行（UI 更新、导航、本地存储）
2. 服务端工具（Webhook） - 在后端执行（数据库、支付、CRM）
3. MCP 工具 - 连接到 Model Context Protocol 服务（企业 API）
4. 系统工具 - 平台内置工具（end_conversation、transfer_call、mute_microphone、press_digit）

请参阅： 实现工具时请加载 references/tool-examples.md。创建 webhook 工具 API 时请加载 references/api-reference.md。

---

最常见的 3 个严重错误

错误 1：软件包已弃用（@11labs/*）

症状： 导入错误、“找不到模块”

解决方案：

npm uninstall @11labs/react @11labs/client
bun add @elevenlabs/[email protected] @elevenlabs/[email protected]

# Update imports:
import { useConversation } from '@elevenlabs/react';  // Not @11labs/react

错误 2：Android 音频截断（第一条消息）

症状： 只有 Android 上 Agent 的第一条消息会被截断（iOS／Web 上正常）

解决方案：

const { startConversation } = useConversation({
  agentId: 'your-agent-id',
  connectionDelay: {
    android: 3_000,  // 3 seconds for Android audio mode switch
    ios: 0,
    default: 0
  }
});

错误 3：CSP（内容安全策略）违规

症状：“拒绝加载脚本……”错误，CSP 阻止 blob URL

解决方案 - 自托管 worklet 文件：

cp node_modules/@elevenlabs/client/dist/worklets/*.js public/elevenlabs/

const { startConversation } = useConversation({
  agentId: 'your-agent-id',
  workletPaths: {
    'rawAudioProcessor': '/elevenlabs/rawAudioProcessor.worklet.js',
    'audioConcatProcessor': '/elevenlabs/audioConcatProcessor.worklet.js',
  }
});

**查看全部 17 个错误：**在排查错误、调试 webhook 故障、处理 RAG 问题或解决特定平台问题时，加载 references/error-catalog.md。

---

何时加载参考资料

根据当前任务加载特定参考文件：

references/api-reference.md

在以下情况下加载：通过 API 创建 Agent、以编程方式管理 Agent、构建多租户系统、实现知识库、创建 webhook 工具、处理 API 错误或了解 API 速率限制。

references/cli-commands.md

在以下情况下加载：使用 CLI 管理 Agent、设置 CI/CD 管道、管理多环境部署（开发／预发布／生产）、对 Agent 配置进行版本控制或排查 CLI 问题。

references/compliance-guide.md

在以下情况下加载：实现 GDPR 合规、满足 HIPAA 要求（医疗保健）、配置 SOC 2 控制措施、设置数据保留策略、实现区域数据驻留（EU／IN）或处理 PCI DSS（支付）。

references/cost-optimization.md

在以下情况下加载：优化大模型成本、实现缓存策略、在模型（GPT／Claude／Gemini）之间进行选择、处理流量激增（突发定价）、减少 token 用量或设置预算上限。

references/error-catalog.md

在以下情况下加载：排查错误、调试 webhook 故障、修复语音一致性问题、解决身份验证问题、处理 RAG 索引问题或诊断特定平台的错误。

references/system-prompt-guide.md

在以下情况下加载：编写 Agent 系统提示词、改善对话质量、实现 6 组件框架、迭代提示词、测试提示词效果，或定义 Agent 的个性／目标／防护规则。

references/testing-guide.md

在以下情况下加载：设置自动化测试、实现场景测试、对 Agent 进行负载测试、将真实对话转换为测试、集成 CI/CD 或调试失败的测试。

references/tool-examples.md

在以下情况下加载：实现客户端工具（浏览器功能）、创建服务端工具（webhook）、连接 MCP 服务、使用系统工具或调试工具执行问题。

references/workflow-examples.md

在以下情况下加载：构建多 Agent 工作流、实现呼叫路由、创建升级流程、设计多语言支持或调试工作流转换。

---

SDK 集成

React SDK（@elevenlabs/react）

主要钩子：useConversation()。功能：客户端工具、事件流、连接管理、区域合规。参见上文的快速入门路径 A。

其他 SDK

• JavaScript SDK（@elevenlabs/client）- Vanilla JS／Node.js
• React Native SDK（@elevenlabs/react-native）- 移动应用（Expo）
• Swift SDK - iOS／macOS 原生应用
• Widget - 可嵌入的 Web 组件（无需代码）

**模板：**参见 templates/basic-react-agent.tsx，查看完整的 React 实现。

---

其他平台功能

**测试与评估：**场景测试（基于大模型）、工具调用测试、负载测试、模拟 API。参见 references/testing-guide.md。

**分析：**对话分析、成功率评估、数据收集、分析仪表板。

**隐私与合规：**数据保留、加密、零保留模式、GDPR／HIPAA／SOC 2。参见 references/compliance-guide.md。

**成本优化：**大模型缓存（节省 90%）、模型切换、突发定价。参见 references/cost-optimization.md。

**高级功能：**自定义模型（自带大模型）、通话后 webhook、聊天模式（仅文本）、电话通信（Twilio／SIP）、工作流（多 Agent 路由）。

---

与其他技能集成

组合使用：

• cloudflare-worker-base → 在边缘网络上部署 Agent
• cloudflare-workers-ai → 将 Cloudflare LLM 用作自定义模型
• cloudflare-durable-objects → 持久化对话状态
• nextjs → 在 Next.js 中集成 React SDK
• ai-sdk-core → Vercel AI SDK 提供程序
• clerk-auth → 经过身份验证的语音会话
• hono-routing → Webhook 的 API 路由

---

安全安装

安装 AI Agent SDK 软件包时，请遵循供应链安全最佳实践：

• 阻止安装后脚本 — npm config set ignore-scripts true（或使用 Bun：默认禁用）
• 冷却期 — 等待 7 天，让社区审核新版本的软件包
• 安装前审计 — 运行 socket package score npm <pkg> 或使用 socket npm install <pkg> 检查软件包

加载 dependency-upgrade 技能，以获取完整的安全配置，包括 Socket CLI 集成、冷却期设置、锁文件验证和 CI 强制执行。

资源

模板（templates/）：

• basic-react-agent.tsx - 包含客户端工具和事件的 React SDK
• basic-cli-agent.json - 包含 6 个组件提示词的 CLI Agent

参考资料（references/）：

• api-reference.md - 完整的 API 参考
• cli-commands.md - CLI 命令和工作流
• compliance-guide.md - GDPR/HIPAA/SOC 2 合规性
• cost-optimization.md - LLM 缓存和成本降低
• error-catalog.md - 全部 17 种错误及其解决方案
• system-prompt-guide.md - 6 个组件的框架指南
• testing-guide.md - 测试和评估
• tool-examples.md - 客户端/服务端/MCP 工具示例
• workflow-examples.md - 多 Agent 工作流模式

官方文档：

• 平台：https://elevenlabs.io/docs/agents-platform/overview
• API：https://elevenlabs.io/docs/api-reference
• 示例：https://github.com/elevenlabs/elevenlabs-examples
• Discord：https://discord.com/invite/elevenlabs

---

经过生产环境测试： WordPress Auditor、Customer Support Agents 最后更新： 2025-11-21 软件包版本： 已验证为当前版本（见元数据）