ElevenLabs语音智能体平台 elevenlabs-agents

---

name: elevenlabs-agents description: ElevenLabs 智能体平台，用于构建 AI 语音智能体（React/JS/Native/Swift）。适用于语音 AI、RAG、工具、或遇到包弃用、音频切断、CSP 违规、webhook 身份验证失败。

关键词：ElevenLabs 智能体，ElevenLabs 语音智能体，AI 语音智能体，对话式 AI，@elevenlabs/react，@elevenlabs/client，@elevenlabs/react-native，@elevenlabs/elevenlabs-js，@elevenlabs/agents-cli，elevenlabs SDK，语音 AI，TTS，文本转语音，ASR，语音识别，对话轮流模型，WebRTC 语音，WebSocket 语音，ElevenLabs 对话，智能体系统提示，智能体工具，智能体知识库，RAG 语音智能体，多语音智能体，发音词典，语音速度控制，elevenlabs scribe，@11labs 弃用，Android 音频切断，CSP 违规 elevenlabs，动态变量 elevenlabs，区分大小写工具名称，webhook 身份验证 license: MIT metadata: version: 1.1.0 last_updated: 2025-11-21 production_tested: true packages: - name: “@elevenlabs/elevenlabs-js” version: 2.25.0 - name: “@elevenlabs/agents-cli” version: 0.2.0 - name: “@elevenlabs/react” version: 0.11.0 - name: “@elevenlabs/client” version: 0.11.0 - name: “@elevenlabs/react-native” version: 0.5.2 documentation: - https://elevenlabs.io/docs/agents-platform/overview - https://elevenlabs.io/docs/api-reference - https://github.com/elevenlabs/elevenlabs-examples errors_prevented: 17+ token_savings: ~73%

ElevenLabs 智能体平台

概述

ElevenLabs 智能体平台是一个全面的解决方案，用于构建生产就绪的对话式 AI 语音智能体。该平台协调四个核心组件：

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

🚨 包迁移（2025 年 8 月）

弃用（不要使用）： @11labs/react 和 @11labs/client

当前包：

bun add @elevenlabs/react@0.11.0        # React SDK
bun add @elevenlabs/client@0.11.0       # JavaScript SDK
bun add @elevenlabs/react-native@0.5.2  # React Native SDK
bun add @elevenlabs/elevenlabs-js@2.25.0 # 基础 SDK
bun add -g @elevenlabs/agents-cli@0.2.0  # 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({
    // 身份验证（选择一个）
    agentId: '你的智能体 ID',  // 公共智能体（无需密钥）
    // apiKey: process.env.NEXT_PUBLIC_ELEVENLABS_API_KEY,  // 私有（仅开发）
    // signedUrl: '/api/elevenlabs/auth',  // 签名 URL（生产）

    // 客户端工具
    clientTools: {
      updateCart: {
        description: "更新购物车",
        parameters: z.object({
          item: z.string(),
          quantity: z.number()
        }),
        handler: async ({ item, quantity }) => {
          console.log('更新购物车：', item, quantity);
          return { success: true };
        }
      }
    },

    // 事件处理器
    onEvent: (event) => {
      if (event.type === 'transcript') console.log('用户：', event.data.text);
      if (event.type === 'agent_response') console.log('智能体：', event.data.text);
    },

    // 区域合规性
    serverLocation: 'us' // 'us' | 'global' | 'eu-residency' | 'in-residency'
  });

  return (
    <div>
      <button onClick={startConversation}>开始对话</button>
      <button onClick={stopConversation}>停止</button>
      <p>状态：{status}</p>
    </div>
  );
}

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

路径 B：CLI（“智能体即代码”）

用于通过代码管理智能体，支持版本控制和 CI/CD。使用 CLI 工作流时加载 references/cli-commands.md。

快速工作流：

bun add -g @elevenlabs/agents-cli
elevenlabs auth login
elevenlabs agents init
elevenlabs agents add "支持智能体" --template customer-service
# 编辑 agent_configs/support-agent.json
elevenlabs agents push --env dev
elevenlabs agents test "支持智能体"

参见： references/cli-commands.md 获取完整的 CLI 参考和工作流。

路径 C：API（程序化智能体管理）

用于动态创建智能体（多租户，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: '支持机器人',
  conversation_config: {
    agent: {
      prompt: { prompt: "你是一个有帮助的支持智能体。", llm: "gpt-4o" },
      first_message: "你好！今天我能帮你什么？"
    },
    tts: { model_id: "eleven_turbo_v2_5", voice_id: "你的声音 ID" }
  }
});

参见： references/api-reference.md 获取完整的 API 参考。

---

智能体配置

系统提示框架

ElevenLabs 推荐一个 6 组件提示结构：个性（身份/角色），环境（通信上下文），语气（正式性/语音模式），目标（目标/成功标准），护栏（边界/伦理），和工具（可用功能）。

示例结构：

个性：你是 Alex，TechCorp 的友好客户支持专员。
环境：电话通信，仅语音，可能有背景噪音。
语气：专业但温暖。使用缩约。保持回应 2-3 句话。
目标：首次通话解决问题。成功 = 客户确认解决。
护栏：从不提供医疗/法律建议。如果客户变得虐待，升级。
工具：lookup_order(id), transfer_to_supervisor(), send_password_reset(email)

完整指南： 配置智能体提示或提高对话质量时加载 references/system-prompt-guide.md。

对话轮流模式

模式	行为	最佳用途
急切	快速回应，早期打断	快速节奏的支持，快速订单
正常	平衡，等待自然停顿	通用客户服务（默认）
耐心	等待更久以获取详细回应	信息收集，辅导

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

---

核心功能摘要

语音和语言

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

知识库（RAG）

上传文档（PDF/TXT/DOCX）用于对话期间的语义搜索。智能体自动检索相关块。每次查询增加约 500ms 延迟。文档必须先索引。

参见： references/api-reference.md 获取知识库 API 和配置。

工具（4 种类型）

1. 客户端工具 - 在浏览器中执行（UI 更新、导航、本地存储）
2. 服务器工具（Webhooks） - 在您的后端执行（数据库、支付、CRM）
3. MCP 工具 - 连接到模型上下文协议服务器（企业 API）
4. 系统工具 - 内置平台工具（结束对话、转接电话、静音麦克风、按数字键）

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

---

前 3 个关键错误

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

症状： 导入错误，“模块未找到”

解决方案：

npm uninstall @11labs/react @11labs/client
bun add @elevenlabs/react@0.11.0 @elevenlabs/client@0.11.0

# 更新导入：
import { useConversation } from '@elevenlabs/react';  // 不是 @11labs/react

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

症状： 仅在 Android 上，第一条智能体消息切断（iOS/网页正常）

解决方案：

const { startConversation } = useConversation({
  agentId: '你的智能体 ID',
  connectionDelay: {
    android: 3_000,  // 3 秒用于 Android 音频模式切换
    ios: 0,
    default: 0
  }
});

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

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

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

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

const { startConversation } = useConversation({
  agentId: '你的智能体 ID',
  workletPaths: {
    'rawAudioProcessor': '/elevenlabs/rawAudioProcessor.worklet.js',
    'audioConcatProcessor': '/elevenlabs/audioConcatProcessor.worklet.js',
  }
});

查看所有 17 个错误： 故障排除时加载 references/error-catalog.md，调试 webhook 失败，RAG 问题，或平台特定问题。

---

何时加载参考

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

references/api-reference.md

加载当：通过 API 创建智能体，程序化管理智能体，构建多租户系统，实现知识库，创建 webhook 工具，处理 API 错误，或理解 API 速率限制。

references/cli-commands.md

加载当：使用 CLI 管理智能体，设置 CI/CD 管道，管理多环境部署（开发/暂存/生产），版本控制智能体配置，或故障排除 CLI 问题。

references/compliance-guide.md

加载当：实施 GDPR 合规性，处理 HIPAA 要求（医疗保健），配置 SOC 2 控制，设置数据保留策略，实现区域数据驻留（欧盟/印度），或处理 PCI DSS（支付）。

references/cost-optimization.md

加载当：优化 LLM 成本，实施缓存策略，选择模型（GPT/Claude/Gemini），处理流量高峰（突发定价），减少令牌使用，或设置预算限制。

references/error-catalog.md

加载当：故障排除错误，调试 webhook 失败，修复语音一致性问题，解决身份验证问题，处理 RAG 索引问题，或诊断平台特定错误。

references/system-prompt-guide.md

加载当：编写智能体系统提示，提高对话质量，实施 6 组件框架，迭代提示，测试提示效果，或定义智能体个性/目标/护栏。

references/testing-guide.md

加载当：设置自动测试，实施场景测试，负载测试智能体，将真实对话转换为测试，集成到 CI/CD，或调试失败测试。

references/tool-examples.md

加载当：实现客户端工具（浏览器功能），创建服务器工具（webhooks），连接 MCP 服务器，使用系统工具，或调试工具执行问题。

references/workflow-examples.md

加载当：构建多智能体工作流，实施呼叫路由，创建升级流程，设计多语言支持，或调试工作流转换。

---

SDK 集成

React SDK (@elevenlabs/react)

主要钩子：useConversation()。功能：客户端工具，事件流，连接管理，区域合规性。参见快速开始路径 A 如上。

其他 SDK

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

模板： 参见 templates/basic-react-agent.tsx 获取完整的 React 实现。

---

其他平台功能

测试和评估： 场景测试（基于 LLM），工具调用测试，负载测试，模拟 API。参见 references/testing-guide.md。

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

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

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

高级功能： 自定义模型（自带 LLM），通话后 webhooks，聊天模式（仅文本），电话（Twilio/SIP），工作流（多智能体路由）。

---

与其他技能集成

可与以下组合：

• cloudflare-worker-base → 在边缘网络部署智能体
• cloudflare-workers-ai → 使用 Cloudflare LLMs 作为自定义模型
• cloudflare-durable-objects → 持久化对话状态
• nextjs → Next.js 中的 React SDK 集成
• ai-sdk-core → Vercel AI SDK 提供商
• clerk-auth → 身份验证的语音会话
• hono-routing → webhooks 的 API 路由

---

资源

模板 (templates/):

• basic-react-agent.tsx - React SDK 与客户端工具和事件
• basic-cli-agent.json - CLI 智能体与 6 组件提示

参考 (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 - 多智能体工作流模式

官方文档：

• 平台：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，客户支持智能体 最后更新： 2025-11-21 包版本： 已验证当前（参见元数据）