Twilio 上的语音智能体
Twilio 提供了 Media Streams API,可将电话通话的原始音频发送到 WebSocket 服务器。您可以通过这种方式将语音智能体概述中介绍的语音智能体连接到 Twilio。您可以在 websocket 模式下使用默认的 Realtime 会话传输机制,将来自 Twilio 的事件接入 Realtime 会话。不过,由于电话通话的延迟通常高于基于 Web 的对话,您需要设置正确的音频格式,并自行调整打断时机。
为了简化配置过程,我们创建了一个专用传输层,负责处理与 Twilio 的连接,包括打断处理和音频转发。
-
确保您拥有 Twilio 账户和 Twilio 电话号码。
-
设置一台服务器来验证来自 Twilio 的请求。
如果您在本地开发,需要配置本地隧道,例如
ngrok或 Cloudflare Tunnel,以便 Twilio 能够访问您的本地服务器。服务器必须在创建传输层或连接 OpenAI 之前,验证传入呼叫 webhook 请求和 WebSocket 升级请求中的X-Twilio-Signature。请使用 Twilio 官方请求验证器、账户的主 Auth Token 和预先配置的公共 URL。不要根据请求的 Host 或转发头推导该 URL。TwilioRealtimeTransportLayer接收的是已经过身份验证的 WebSocket;此适配器不会对 HTTP 请求进行身份验证。 -
通过安装扩展包来安装 Twilio 适配器:
终端窗口 npm install @openai/agents-extensions -
导入适配器和模型,以连接到您的
RealtimeSession:import { TwilioRealtimeTransportLayer } from '@openai/agents-extensions';import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';const agent = new RealtimeAgent({name: 'My Agent',});// Authenticate the HTTP webhook and WebSocket upgrade in your server first.// Create a new transport mechanism that will bridge the connection between Twilio and// the OpenAI Realtime API.const twilioTransport = new TwilioRealtimeTransportLayer({twilioWebSocket: websocketConnection,});const session = new RealtimeSession(agent, {// set your own transporttransport: twilioTransport,}); -
将您的
RealtimeSession连接到 Twilio:import type { RealtimeSession } from '@openai/agents/realtime';// Connect only after the server has authenticated the Twilio WebSocket upgrade.async function connectAuthenticatedSession(session: RealtimeSession,apiKey: string,) {await session.connect({ apiKey });}
RealtimeSession 的所有预期事件和行为都会正常工作,包括工具调用、护栏等。有关如何将 RealtimeSession 与语音智能体结合使用的更多信息,请阅读语音智能体概述。
提示与注意事项
Section titled “提示与注意事项”-
速度是关键。
为了接收来自 Twilio 的所有必要事件和音频,您应该在经过身份验证的 WebSocket 连接可用后,尽快创建
TwilioRealtimeTransportLayer实例,并立即调用session.connect()。 -
访问原始 Twilio 事件。
如果您想访问 Twilio 发送的原始事件,可以监听
RealtimeSession实例上的transport_event事件。来自 Twilio 的每个事件的类型都是twilio_message,并且都有一个包含原始事件数据的message属性。 -
查看调试日志。
有时您可能会遇到问题,需要了解更多运行情况。设置环境变量
DEBUG=openai-agents*可显示 Agents SDK 的所有调试日志。您也可以使用DEBUG=openai-agents:extensions:twilio*,仅启用 Twilio 适配器的调试日志。
完整示例服务器
Section titled “完整示例服务器”可运行的 Twilio 代码示例包含带身份验证的 Fastify 路由和 Realtime 会话设置。其 README 说明了服务器端必需的 OPENAI_API_KEY、TWILIO_AUTH_TOKEN 和 TWILIO_PUBLIC_BASE_URL 设置。公共基础 URL 必须是 HTTPS 源,不含路径前缀、查询字符串或片段。当隧道的公共源发生变化时,请更新此设置。
服务器会在建立 Realtime 连接之前,拒绝签名无效的呼叫请求和升级请求。Twilio Media Stream URL 使用 wss://,不支持查询参数。有关自定义参数的信息,请参阅 Twilio Stream 文档。