OpenMontage 中基于 ElevenLabs Twilio 的语音 Agent 外呼实践agents 技能 outbound-calls 参考文档详解【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage本文围绕 OpenMontage 仓库中 outbound-calls.md 参考文档展开系统讲解如何通过 ElevenLabs 语音 Agent 平台结合 Twilio 集成发起外呼电话从前置条件、最小调用示例到请求参数、响应结构、逐通电话的配置覆盖Agent/TTS/电话配置/动态变量与批量外呼完整示例。读完本文你可以在 OpenMontage 的 agent 技能体系下独立编写并调试一条「AI 主动拨打电话」的完整链路并理解每个覆盖项在平台配置中的对应关系。文档定位agents 技能的外呼参考页outbound-calls.md是仓库 agents 技能ElevenLabs Agents Platform的参考文档之一与 installation.md、agent-configuration.md、client-tools.md 并列存放于references/目录。技能主文件SKILL.md的 frontmatter 声明了该技能的运行前提需要联网访问和ELEVENLABS_API_KEY环境变量见 SKILL.md 元数据。该文档的主题很明确让已在 ElevenLabs 平台配置的语音 Agent通过 Twilio 电话线路主动拨出电话并支持在每次外呼时临时覆盖 Agent 的问候语、语言、语音音色以及注入动态变量。仓库中.claude/skills/目录下存在同名镜像文档 outbound-calls.md内容保持一致方便不同 AI 编程助手Claude Code、Codex 等读取同一套技能知识。前置条件发起外呼前需要满足三个条件引自原文档 Prerequisites 一节一个已配置好的 ElevenLabs Agent——可通过 CLI 创建并推送npm install -g elevenlabs/cli elevenlabs auth login elevenlabs agents init elevenlabs agents add My Assistant --template complete elevenlabs agents push一个绑定到该 Agent 的 Twilio 电话号码——需要从 ElevenLabs 控制台获取agent_phone_number_idElevenLabs API Key——在 OpenMontage 中该密钥对应根目录 .env.example 中的ELEVENLABS_API_KEY变量位于 Voice 分组用于 TTS 旁白、音乐生成等语音能力SDK 与 cURL 请求均以此密钥认证。SDK 安装方式引自 installation.mdPythonpip install elevenlabsJavaScript/TypeScriptnpm install elevenlabs/elevenlabs-js。文档特别强调旧版elevenlabsnpm 包v1.x已弃用不应再使用cURL将密钥放入环境变量后通过xi-api-key请求头传递。最小调用Python、JavaScript 与 cURLoutbound-calls.md的 Basic Usage 一节将三语言的最小示例指向主技能文件的 Outbound Calls 章节原文档中的局部相对链接../SKILL.md#outbound-calls此处转换为仓库根路径 SKILL.md其代码如下Pythonresponse client.conversational_ai.twilio.outbound_call( agent_idyour-agent-id, agent_phone_number_idyour-phone-number-id, to_number1234567890, call_recording_enabledTrue ) print(fCall initiated: {response.conversation_id})JavaScriptconst response await client.conversationalAi.twilio.outboundCall({ agentId: your-agent-id, agentPhoneNumberId: your-phone-number-id, toNumber: 1234567890, callRecordingEnabled: true, });cURL直接调用 REST APIcurl -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}从三组示例可以推断SDK 的conversational_ai.twilio.outbound_call与conversationalAi.twilio.outboundCall均是对POST /v1/convai/twilio/outbound-call这一端点的封装Python 用 snake_case 参数名JavaScript 用 camelCase请求体字段则与下表中的参数名一致。请求参数外呼接口接受以下参数原文档 Request Parameters 表完整保留参数类型必填说明agent_idstring是ElevenLabs Agent 的 IDagent_phone_number_idstring是绑定到该 Agent 的 Twilio 电话号码 IDto_numberstring是被叫号码必须为 E.164 格式如1234567890conversation_initiation_client_dataobject否覆盖本次通话的会话设置详见下文call_recording_enabledboolean否是否允许 Twilio 录制通话telephony_call_configobject否电话呼叫设置如振铃超时时间两个必填参数构成了外呼的「主叫身份」agent_id决定谁哪个 Agent 人设来打电话agent_phone_number_id决定用哪条 Twilio 线路呼出to_number采用 E.164 国际号码格式国家码 号码不含空格与连字符。响应结构调用成功后返回如下 JSON原文档 Response 一节{ success: true, message: Call initiated successfully, conversation_id: conv_abc123, callSid: CA1234567890abcdef }字段类型说明successboolean呼叫是否成功发起messagestring状态信息conversation_idstringElevenLabs 侧的会话 ID用于后续追踪会话callSidstringTwilio 侧的 Call SID可用于在 Twilio 侧查询呼叫状态注意响应里同时保留了两个体系的标识conversation_id归属于 ElevenLabs Conversational AI 会话体系callSid归属于 Twilio 呼叫体系。这意味着外呼链路上存在两个可追踪的句柄——前者用于追踪 Agent 对话内容与工具调用后者用于查询传统电话侧的状态如未接、忙线。自定义单通电话conversation_initiation_client_data原文档 Customizing the Call 一节的要点是通过conversation_initiation_client_data可以为单次外呼临时覆盖 Agent 的默认设置而不会修改 Agent 本身。下面完整保留原文档的 Python 与 JavaScript 示例Pythonresponse client.conversational_ai.twilio.outbound_call( agent_idyour-agent-id, agent_phone_number_idyour-phone-number-id, to_number1234567890, call_recording_enabledTrue, conversation_initiation_client_data{ conversation_config_override: { agent: { first_message: Hello! This is a reminder about your appointment tomorrow., language: en }, tts: { voice_id: JBFqnCBsd6RMkjVDRZzb } }, dynamic_variables: { customer_name: John, appointment_time: 2:00 PM } } )JavaScriptconst response await client.conversationalAi.twilio.outboundCall({ agentId: your-agent-id, agentPhoneNumberId: your-phone-number-id, toNumber: 1234567890, callRecordingEnabled: true, conversationInitiationClientData: { conversationConfigOverride: { agent: { firstMessage: Hello! This is a reminder about your appointment tomorrow., language: en, }, tts: { voiceId: JBFqnCBsd6RMkjVDRZzb, }, }, dynamicVariables: { customer_name: John, appointment_time: 2:00 PM, }, }, });conversation_initiation_client_data的结构分两部分conversation_config_override覆盖conversation_config中的对应小节示例中覆盖了agent与ttsdynamic_variables则是本次通话注入的键值对。对照 agent-configuration.md 中conversation_config的完整结构agent、tts、asr、turn、conversation、vad等小节可以推断覆盖对象与 Agent 配置使用的是同一套字段命名——即你在 Agent 控制台配置过的字段都可以在单通电话级别做临时替换。配置覆盖项详解Agent 设置选项类型说明first_messagestring本次通话的自定义开场白languagestring语言代码如en、es、frpromptobject覆盖 Agent 的 prompt 与 LLM 设置其中prompt对应 Agent 配置中的 LLM 设置system prompt、模型、温度等结构详见 agent-configuration.md 的 prompt 章节覆盖后仅对当前通话生效。TTS 设置选项类型说明voice_idstring本次通话使用的语音 IDstabilitynumber语音稳定性0.0–1.0similarity_boostnumber音色相似度增强0.0–1.0speednumber语速倍率这几个字段与 Agent 级 TTS 配置同构。参考 agent-configuration.md 中给出的默认值作为调试基准stability默认0.5越低越富表现力、similarity_boost默认0.8越高越贴近原音色、speed默认1.0有效范围约 0.7–1.2。示例中的JBFqnCBsd6RMkjVDRZzb是 ElevenLabs 预置音色 George 的 ID与技能主文件 SKILL.md 列出的常用音色 一致。电话呼叫配置选项类型说明ringing_timeout_secsinteger对被叫振铃多久后放弃默认60秒该配置位于telephony_call_config参数请求参数表中的object类型项之下属于 Twilio 线路层行为被叫未接听时达到该秒数后呼叫被放弃。批量外呼场景下可按业务调整例如营销提醒类可缩短以节省线路资源重要通知类可保持默认。动态变量通过dynamic_variables向 Agent 的 prompt 注入自定义数据在 prompt 中用{{variable_name}}语法引用。例如把customer_name与appointment_time传入后Agent 的开场白模板即可渲染出「John您明天下午 2:00 有一个预约」。原文档还提到一个sanitize选项在动态变量赋值时若开启该选项赋值内容会在送入 LLM 和会话转录transcript之前从工具响应中剔除但变量赋值本身照常完成。字段类型默认说明sanitizebooleanfalse为true时赋值内容在发送到 LLM/转录前从工具响应中移除但仍参与变量赋值这一设计的用途很具体当工具响应里携带敏感值例如完整的账号或账单明细你可以只让变量拿到该值用于后续逻辑而不让原始响应文本进入 LLM 上下文与通话记录从而降低敏感信息在转录中的暴露面。完整示例批量个性化外呼原文档 Complete Example 一节给出了一段可直接运行的 Python 代码遍历客户列表为每位客户发起一通携带个性化开场白与动态变量的外呼并做基本的错误处理。完整保留如下from elevenlabs import ElevenLabs client ElevenLabs() # Make personalized outbound calls customers [ {name: Alice, phone: 1234567890, balance: $150.00}, {name: Bob, phone: 0987654321, balance: $75.50}, ] for customer in customers: try: response client.conversational_ai.twilio.outbound_call( agent_idpayment-reminder-agent, agent_phone_number_idyour-phone-number-id, to_numbercustomer[phone], call_recording_enabledTrue, conversation_initiation_client_data{ conversation_config_override: { agent: { first_message: fHello {customer[name]}, this is a friendly reminder about your account. } }, dynamic_variables: { customer_name: customer[name], balance: customer[balance] } } ) print(fCalled {customer[name]}: {response.conversation_id}) except Exception as e: print(fFailed to call {customer[name]}: {e})这段代码覆盖了外呼的三个关键实践点一人一话术用 f-string 把customer[name]写进first_message同时用dynamic_variables把balance等字段交给 Agent 的 prompt 模板两者互补——开场白立即个性化后续对话中 Agent 也能引用动态变量失败隔离逐通try/except单个号码失败不影响批量任务继续可追踪成功时打印conversation_id后续可用它回查该通电话的会话数据配合响应中的callSid还可以在 Twilio 侧核对线路状态。错误处理方面技能主文件 SKILL.md 归纳了平台常见错误码401密钥无效、404资源不存在如agent_id或agent_phone_number_id写错、422配置非法、429限流。批量外呼时建议把 429 单独识别并做退避重试。在 OpenMontage 仓库中如何找到这份文档技能入口.agents/skills/agents/SKILL.md 的 Outbound Calls 章节给出三语言最小示例并在末尾以「configuration overrides and dynamic variables」为由指向本文档参考文档目录references/下按主题拆分——安装installation、Agent 配置全量字段agent-configuration、客户端工具client-tools、外呼outbound-calls、网页组件嵌入widget-embedding便于按需检索多助手镜像.claude/skills/agents/references/下存有同套文档副本例如 outbound-calls.md内容一致密钥配置仓库根目录 .env.example 提供ELEVENLABS_API_KEY占位项实际使用时在本地.env中填入真实密钥即可SDK 会优先读取该环境变量。需要再次强调的前提外呼能力依赖 ElevenLabs 平台的 Twilio 集成与真实电话线路agent_phone_number_id必须在 ElevenLabs 控制台为 Agent 绑定后取得本文涉及的接口行为、参数与默认值均以当前仓库文档为准。【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考