OpenMontage agents 技能实战：基于 ElevenLabs Agents 平台构建语音 AI 智能体的完整指南

在 OpenMontage 仓库中，.agents/skills/agents/SKILL.md 是一份面向 AI 编码助手的“agent 技能”文件，系统讲解如何用 ElevenLabs Agents 平台构建可自然对话、支持多 LLM 提供商、可挂载自定义工具并易于嵌入网页的语音 AI 智能体。本文以该技能文件为主体，覆盖从 CLI 初始化、智能体创建、会话启动、工具扩展、Widget 嵌入到 Twilio 外呼的完整技术链路，并深入其 references/ 目录下的五份参考文档，帮你掌握在任意项目中落地实时语音对话体验的具体配置与代码方案。

技能文件在 OpenMontage 中的定位

agents 技能位于 OpenMontage 的技能体系第三层（Layer 3），与 elevenlabs（TTS 语音合成）、setup-api-key（API 密钥引导配置）等技能共同归入 技能索引 中的 “TTS & Audio” 分类。该层技能提供“技术本身如何工作”的通用 API 知识，供 AI 助手按需加载——也就是说，当你在 OpenMontage 项目中让编码助手“创建一个语音客服机器人”时，助手加载这份技能即可获得完整的 ElevenLabs Agents 平台操作知识，而不是泛泛介绍整个视频生产项目。

技能文件以 YAML frontmatter 开头，声明了技能的身份与运行前提：

name: agents
description: Build voice AI agents with ElevenLabs. Use when creating voice assistants, customer service bots, interactive voice characters, or any real-time voice conversation experience.
license: MIT
compatibility: Requires internet access and an ElevenLabs API key (ELEVENLABS_API_KEY).
metadata: {"openclaw": {"requires": {"env": ["ELEVENLABS_API_KEY"]}, "primaryEnv": "ELEVENLABS_API_KEY"}}

其中 metadata 明确了该技能的环境变量依赖：必须提供 ELEVENLABS_API_KEY 才能工作。整个技能由一份主文档 SKILL.md 和 references/ 目录下五份参考文档组成：

参考文档	内容
installation.md	CLI 与 SDK 安装、认证、API Key 获取与环境变量
agent-configuration.md	完整的 conversation_config / platform_settings 配置项与 CRUD 示例
client-tools.md	Webhook、Client、System 三类工具的完整定义与服务端实现
widget-embedding.md	网页 Widget 嵌入的全部属性、CSS/JS 控制与框架集成
outbound-calls.md	Twilio 外呼的参数、配置覆盖与动态变量

以下各节严格按主文档脉络展开。

快速开始：CLI 创建与管理智能体

主文档明确推荐 ElevenLabs CLI 作为创建和管理智能体的首选方式（见 SKILL.md）：

# 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

主文档列出了六种可用模板：complete、minimal、voice-only、text-only、customer-service、assistant。参考文档 installation.md 补充了更多实操细节：

• CLI 支持 npm / pnpm / yarn 三种安装方式（npm install -g @elevenlabs/cli、pnpm add -g @elevenlabs/cli、yarn global add @elevenlabs/cli），要求 Node.js 16.0.0 或更高；
• 认证命令完整为 elevenlabs auth login（登录）、auth whoami（验证状态）、auth logout（清除凭据），API Key 安全存储于 ~/.agents/api_keys.json；
• 在 CI/CD 中可直接 export ELEVENLABS_API_KEY 后执行非交互式的 elevenlabs agents push 完成部署。

CLI 项目结构

elevenlabs agents init 会在本地生成如下项目结构，把智能体定义、工具配置、测试配置纳入版本管理：

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

这套“本地配置 + push/pull 同步”的工作流是后续所有 CLI 管理命令的基础。

用 SDK 与 REST API 创建智能体

除 CLI 外，主文档给出三种等价的智能体创建方式（见 SKILL.md）。

Python

from elevenlabs import ElevenLabs

client = ElevenLabs()

agent = client.conversational_ai.agents.create(
    name="My Assistant",
    enable_versioning=True,
    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"}
    }
)

注意创建时的顶层参数 enable_versioning=True 会为智能体开启版本管理；REST 对应写法是在 create 请求上附加 ?enable_versioning=true 查询参数。

JavaScript

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

const agent = await client.conversationalAi.agents.create({
  name: "My Assistant",
  enableVersioning: true,
  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" }
  }
});

installation.md 特别强调：JavaScript/TypeScript 端必须使用 @elevenlabs/elevenlabs-js，旧的 elevenlabs npm 包（v1.x）已弃用；浏览器端还需按需安装 @elevenlabs/client（浏览器客户端）与 @elevenlabs/react（React hooks），迁移时的正确导入方式为：

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { Conversation } from "@elevenlabs/client";
import { useConversation } from "@elevenlabs/react";

cURL / REST API

curl -X POST "https://api.elevenlabs.io/v1/convai/agents/create?enable_versioning=true" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"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"}}}'

认证统一通过 xi-api-key 请求头传递，Key 来源于环境变量 ELEVENLABS_API_KEY。API Key 的获取路径为：注册 ElevenLabs 账号后，进入 API Keys 设置页点击 Create API Key；OpenMontage 仓库内还有 setup-api-key 技能可配合完成引导式配置。

配置核心：LLM 提供商、语音与对话回合

主文档的 Configuration 一节（见 SKILL.md）给出三大配置要点。

支持的 LLM 提供商

Provider	Models
OpenAI	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-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-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、gpt-oss-120b（官方托管、超低延迟）
Custom	custom-llm（自带 endpoint，需配合 custom_llm 配置）

文档建议通过 GET /v1/convai/llm/list 查询当前模型目录，包括弃用状态、token/上下文限制以及是否支持图像输入等能力标志。

常用语音与回合策略

主文档列出的热门语音：JBFqnCBsd6RMkjVDRZzb（George）、EXAVITQu4vr4xnSDxMaL（Sarah）、onwK4e9ZLuTAKqWW03F9（Daniel）、XB0fDUnXU5powFXDhCwa（Charlotte）。

回合急切度（turn eagerness）三档：patient（更久地等待用户说完）、normal、eager（快速抢答）。

agent-configuration.md 进一步给出了完整 conversation_config 的骨架与各字段默认值，是配置时最重要的参考：

agent = client.conversational_ai.agents.create(
    name="My Agent",
    conversation_config={
        "agent": {
            "first_message": "Hello!",
            "language": "en",
            "prompt": {           # LLM、系统提示、工具与知识库
                "prompt": "You are helpful.",
                "llm": "gemini-2.0-flash",
                "tools": [...],
                "built_in_tools": {...}
            }
        },
        "tts": {...},             # 音色与 TTS 模型设置
        "asr": {...},             # 语音识别设置
        "turn": {...},            # 回合行为
        "conversation": {...},    # 时长、事件、监控
        "vad": {...},             # 语音活动检测
        "language_presets": {...}  # 语言级覆盖
    },
    platform_settings={...}       # 认证、通话限额
)

关键参数摘要（含默认值）：

• tts：voice_id（默认 cjVigY5qzO86Huf0OWal）、stability 0–1（越低越富表现力，默认 0.5）、similarity_boost 0–1（越高越接近原声，默认 0.8）、speed 0.7–1.2（默认 1.0）、optimize_streaming_latency 0–4（越高越快但质量下降）、expressive_mode（默认 true）。可用 TTS 模型中 eleven_flash_v2_5（32 语言、约 75ms 延迟）为文档推荐的低延迟选项，另有 eleven_flash_v2、eleven_turbo_v2_5（约 250–300ms）、eleven_multilingual_v2、eleven_v3_conversational（70+ 语言）。
• asr：quality（默认 "high"）、provider（elevenlabs 或 scribe_realtime）、keywords（提升特定词识别率）、user_input_audio_format（如 pcm_16000、ulaw_8000）。
• turn：turn_timeout（默认 7 秒后主动重新唤起用户）、turn_eagerness（默认 normal）、silence_end_call_timeout（-1 表示禁用静音挂断）、soft_timeout_config（含 timeout_seconds、message、use_llm_generated_message）。
• conversation：max_duration_seconds（默认 600）、text_only（纯文本模式，避免语音计费）、monitoring_enabled（实时 WebSocket 监控）。
• prompt（嵌套在 agent 内）：temperature（默认 0）、max_tokens（-1 不限）、reasoning_effort（none/minimal/low/medium/high）、backup_llm_config + cascade_timeout_seconds（默认 8 秒，取值 2–15）用于主模型超时后级联到备用 LLM。
• platform_settings：auth（enable_auth、allowlist）、call_limits（agent_concurrency_limit 默认不限、daily_limit 默认 100000、bursting_enabled 默认 true 允许 2 倍成本超限）、guardrails（focus、prompt_injection、content 内容审核，支持 streaming/blocking 执行模式与 trigger_action 重试策略）、privacy.conversation_history_redaction（对姓名、邮箱、电话等实体做脱敏）。

文档还给出两个典型完整配置：客服坐席智能体（gemini-2.0-flash + temperature 0.5 + end_call/transfer_to_number + 900 秒时长）和低延迟助手（max_tokens: 100、optimize_streaming_latency: 4、turn_eagerness: eager、turn_timeout: 3）。

启动会话：签名 URL 与客户端 SDK

实时对话采用“服务端签发、客户端连接”的架构（见 SKILL.md）。

服务端（Python） 为客户端获取签名 URL：

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

客户端（JavaScript） 用 @elevenlabs/client 建立会话：

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

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

React Hook 则更简洁：

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

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

三条路径的共同点：客户端回调 onMessage（智能体消息）、onUserTranscript（用户语音转写）、onError（错误）覆盖对话过程中的全部事件流。

工具扩展：Webhook、Client 与内置系统工具

工具是智能体“超越聊天”的关键能力。主文档指出：工具定义在 conversation_config.agent.prompt 内部，workspace 环境变量可解析各环境的 server 工具 URL、请求头与鉴权连接，运行时系统变量如 {{system__conversation_history}} 可在需要时把完整对话上下文传入工具调用（见 SKILL.md）。

主文档示例同时演示了 Webhook（服务端 API 调用）与 Client（浏览器内执行）两类工具，以及内置工具：

"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": "[phone]"}, "condition": "User asks for human support"}]}
    }
}

Client 工具在浏览器中执行：

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

client-tools.md 把工具体系展开为三类并给出请求/响应契约：

类型	执行位置	适用场景
Webhook	服务端 HTTP	数据库查询、API 调用、敏感操作
Client	浏览器端 JavaScript	UI 更新、本地存储、页面导航
System	ElevenLabs 内置	结束通话、转接、标准动作

Webhook 调用时平台向你的服务发送 {tool_call_id, tool_name, parameters, conversation_id}，服务端以 {"result": ...} 返回（result 可以是字符串或结构化 JSON）。参考文档补充的工程要点：

• Webhook 工具可选项：response_timeout_secs（5–120 秒，默认 20）、disable_interruptions、execution_mode（immediate / post_tool_speech / async）、tool_call_sound、tool_error_handling_mode（auto / summarized / passthrough / hide）。注意 api_schema.method 默认是 GET，发请求体时必须显式写 "method": "POST"；
• 工作区环境变量支持 {{system_env__label}} 用于 URL、{"env_var_label": "orders_api_key"} 填充请求头、{"env_var_label": "orders_oauth"} 解析 auth_connection，让同一份工具配置跨 staging/production 环境复用；
• 内置工具除 end_call、transfer_to_number、transfer_to_agent 外，还包含 language_detection、skip_turn、voicemail_detection、play_keypad_touch_tone，当前 API schema 还暴露 agent_prompt_change 与 memory_entry_*（创建/删除/搜索/更新记忆）系列。

Widget 网页嵌入

把语音智能体接入任意网页只需两行 HTML（见 SKILL.md）：

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

widget-embedding.md 给出完整属性矩阵与限制：

• 必填：agent-id（或替代性的 signed-url）。重要限制：Widget 目前要求智能体为公开且关闭鉴权，需要鉴权的流程应使用 SDK；
• 外观：avatar-image-url（默认 ElevenLabs logo）、avatar-orb-color-1（默认 #2792dc）、avatar-orb-color-2（默认 #9ce6e6）；
• 文案：action-text（"Talk to AI"）、start-call-text、end-call-text、expand-text、collapse-text、listening-text、speaking-text 均有默认值；
• 行为：variant（compact/expanded，默认 compact）、server-location（us/eu-residency/in-residency/global，默认 us）、dismissible（默认 false）、disable-banner（默认 false）；
• CSS 控制：Widget 使用 Shadow DOM 但暴露 CSS 变量，如 --elevenlabs-convai-widget-width: 400px；默认位于右下角，可用 position: fixed 覆写；
• JS 控制：widget.startConversation() / widget.endConversation()，监听 conversationStarted / conversationEnded 事件；也可隐藏默认 Widget 用自定义按钮触发；
• 鉴权场景：后端调用 get_signed_url 返回签名 URL，前端 widget.setAttribute("signed-url", signedUrl) 后启动会话，并确保域名在 platform_settings.auth.allowlist 中；
• 参考文档还提供 React（useEffect 动态注入脚本）、Vue（onMounted）、Next.js（next/script + strategy="lazyOnload"）三套框架集成写法，以及移动端响应式定位与多 Widget 并排（如 Support + Sales 两个智能体）的示例。

Twilio 外呼：智能体主动拨打电话

主文档的 Outbound Calls 一节（见 SKILL.md）通过 Twilio 集成让智能体发起外呼。前置条件：已配置的智能体、绑定到智能体的 Twilio 号码（从 ElevenLabs dashboard 获取 agent_phone_number_id）、API Key。

Python：

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

JavaScript：

const response = await client.conversationalAi.twilio.outboundCall({
  agentId: "your-agent-id",
  agentPhoneNumberId: "your-phone-number-id",
  toNumber: "[phone]",
  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": "[phone]", "call_recording_enabled": true}'

outbound-calls.md 补充了完整请求参数与响应结构：

Parameter	Type	Required	Description
agent_id	string	Yes	智能体 ID
agent_phone_number_id	string	Yes	绑定的 Twilio 号码 ID
to_number	string	Yes	目标号码（E.164 格式）
conversation_initiation_client_data	object	No	本次通话的配置覆盖
call_recording_enabled	boolean	No	是否允许 Twilio 录音
telephony_call_config	object	No	电话设置（如 ringing_timeout_secs，默认 60）

响应包含 success、message、conversation_id（ElevenLabs 会话 ID）与 callSid（Twilio Call SID）。核心进阶能力是 conversation_initiation_client_data：通过 conversation_config_override 为单次通话覆盖 first_message、language、prompt 与 voice_id/stability/speed 等 TTS 参数，并通过 dynamic_variables 把 customer_name、appointment_time 等数据注入提示词（在 prompt 中用 {{variable_name}} 引用）。参考文档的完整示例展示了批量个性化外呼循环：遍历客户列表，逐条发起带动态变量的提醒电话并捕获 response.conversation_id，失败时记录异常继续执行。

智能体管理：CLI 工作流与 SDK CRUD

主文档的 Managing Agents 一节（见 SKILL.md）给出推荐的 CLI 命令集：

# List agents and check status
elevenlabs agents list
elevenlabs agents status

# Import agents from platform to local config
elevenlabs agents pull                      # Import all agents
elevenlabs agents pull --agent <agent-id>   # Import specific agent

# Push local changes to platform
elevenlabs agents push              # Upload configurations
elevenlabs agents push --dry-run    # Preview changes first

# Add tools
elevenlabs tools add-webhook "Weather API"
elevenlabs tools add-client "UI Tool"

agent-configuration.md 在此之上补充了 agents pull --update（用平台配置覆盖本地）、agents templates list / templates show <name>（查看模板）、agents widget <agent-id>（生成 Widget 代码）等命令。

SDK 侧的 CRUD（Python 示例）：

# 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",
    conversation_config={
        "agent": {"prompt": {"prompt": "New instructions", "llm": "claude-sonnet-4"}}
    })

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

update 是部分更新语义——只传要改的字段。参考文档的“Updatable Fields”表明确了可更新范围：根级 name/tags；conversation_config.agent 的 first_message、language 等；agent.prompt 的 prompt、llm、temperature、tools、knowledge_base、custom_llm、timezone 等；tts、asr、turn、conversation 各自的字段；以及 platform_settings 下的 guardrails、privacy、widget、auth、call_limits 字段。对应的 REST 端点为 GET /v1/convai/agents（列表）、GET .../agents/{id}（查询）、PATCH .../agents/{id}（更新）、DELETE .../agents/{id}（删除）。

此外，参考文档介绍了 Knowledge Base / RAG 能力：在 prompt.knowledge_base 中挂接文档（如 {"type": "file", "id": "doc-id", "name": "Product Guide", "usage_mode": "auto"}），并可用 prompt.rag 配置 embedding_model（e5_mistral_7b_instruct、multilingual_e5_large_instruct、qwen3_embedding_4b 三选一）、max_documents_length（如 50000）与 max_retrieved_rag_chunks_count（如 20）。

错误处理

主文档给出最小错误处理模式（见 SKILL.md）：

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

常见错误码与含义：401（API Key 无效）、404（资源不存在）、422（配置非法）、429（触发限流）。

小结

agents 技能以一份 SKILL.md 加五份 references 文档的紧凑结构，完整覆盖了 ElevenLabs Agents 平台的工程实践：CLI 模板化创建与 push/pull 工作流、Python/JavaScript/cURL 三端等价的智能体 CRUD、多提供商 LLM 与 TTS 的延迟/质量权衡（eleven_flash_v2_5 约 75ms 为低延迟推荐）、三类工具的请求/响应契约、Widget 的鉴权限制与全量定制属性、以及 Twilio 外呼的配置覆盖与动态变量注入。对 OpenMontage 的使用者而言，这份技能与同仓库的 elevenlabs 技能（TTS 合成）和 setup-api-key 技能（密钥配置）形成互补，共同构成语音链路的完整知识层——当编码助手接到“做一个语音助手”这类任务时，这些技能文件就是它查阅的第一手操作手册。