Realtime Agent を Twilio に接続
Twilio は Media Streams API を提供しており、電話の通話音声の元オーディオを WebSocket サーバーへ送信できます。このセットアップを使って、音声エージェントの概要 を Twilio に接続できます。Twilio から届くイベントを Realtime Session に接続するには、websocket
モードのデフォルト Realtime Session トランスポートを使用できます。ただし、電話は Web ベースの会話よりも遅延が大きくなるため、適切なオーディオ形式の設定や、独自の割り込みタイミングの調整が必要になります。
セットアップ体験を向上させるため、Twilio への接続、割り込み処理、音声の転送などを代わりに処理する専用のトランスポートレイヤーを用意しました。
セットアップ
Section titled “セットアップ”-
Twilio アカウントと Twilio の電話番号を用意します。
-
Twilio からのイベントを受け取れる WebSocket サーバーを用意します。
ローカル開発の場合、Twilio からローカルサーバーへアクセスできるよう、 this will require you to configure a local tunnel like
ngrok
or Cloudflare Tunnel を設定する必要があります。TwilioRealtimeTransportLayer
を使って Twilio に接続できます。 -
拡張パッケージをインストールして Twilio アダプターを導入します:
Terminal window 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',});// 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 に接続します:session.connect({ apiKey: 'your-openai-api-key' });
RealtimeSession
に期待されるイベントや挙動は、ツール呼び出し、ガードレールなどを含め、想定どおりに動作します。RealtimeSession
を音声エージェントで使う方法については、音声エージェントの概要 を参照してください。
ヒントと考慮事項
Section titled “ヒントと考慮事項”-
スピードがすべてです。
Twilio から必要なイベントとオーディオをすべて受け取るため、WebSocket 接続を参照できたらすぐに
TwilioRealtimeTransportLayer
インスタンスを作成し、直ちにsession.connect()
を呼び出してください。 -
Twilio の元イベントにアクセスします。
Twilio から送られてくる元イベントにアクセスしたい場合は、
RealtimeSession
インスタンスのtransport_event
イベントを監視します。Twilio のすべてのイベントはtwilio_message
の type を持ち、元イベントデータを含むmessage
プロパティがあります。 -
デバッグログを確認します。
状況を詳しく知りたい場合があります。
DEBUG=openai-agents*
環境変数を使うと Agents SDK からのすべてのデバッグログが表示されます。あるいは、DEBUG=openai-agents:extensions:twilio*
を使用して Twilio アダプターのデバッグログだけを有効にできます。
完全なサーバーの例
Section titled “完全なサーバーの例”以下は、Twilio からのリクエストを受け取り、それを RealtimeSession
に転送する WebSocket サーバーのエンドツーエンドの例です。
import Fastify from 'fastify';import dotenv from 'dotenv';import fastifyFormBody from '@fastify/formbody';import fastifyWs from '@fastify/websocket';import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';import { TwilioRealtimeTransportLayer } from '@openai/agents-extensions';
// Load environment variables from .env filedotenv.config();
// Retrieve the OpenAI API key from environment variables. You must have OpenAI Realtime API access.const { OPENAI_API_KEY } = process.env;if (!OPENAI_API_KEY) { console.error('Missing OpenAI API key. Please set it in the .env file.'); process.exit(1);}const PORT = +(process.env.PORT || 5050);
// Initialize Fastifyconst fastify = Fastify();fastify.register(fastifyFormBody);fastify.register(fastifyWs);
const agent = new RealtimeAgent({ name: 'Triage Agent', instructions: 'You are a helpful assistant that starts every conversation with a creative greeting.',});
// Root Routefastify.get('/', async (request, reply) => { reply.send({ message: 'Twilio Media Stream Server is running!' });});
// Route for Twilio to handle incoming and outgoing calls// <Say> punctuation to improve text-to-speech translationfastify.all('/incoming-call', async (request, reply) => { const twimlResponse = `<?xml version="1.0" encoding="UTF-8"?><Response> <Say>O.K. you can start talking!</Say> <Connect> <Stream url="wss://${request.headers.host}/media-stream" /> </Connect></Response>`.trim(); reply.type('text/xml').send(twimlResponse);});
// WebSocket route for media-streamfastify.register(async (fastify) => { fastify.get('/media-stream', { websocket: true }, async (connection) => { const twilioTransportLayer = new TwilioRealtimeTransportLayer({ twilioWebSocket: connection, });
const session = new RealtimeSession(agent, { transport: twilioTransportLayer, });
await session.connect({ apiKey: OPENAI_API_KEY, }); console.log('Connected to the OpenAI Realtime API'); });});
fastify.listen({ port: PORT }, (err) => { if (err) { console.error(err); process.exit(1); } console.log(`Server is listening on port ${PORT}`);});
process.on('SIGINT', () => { fastify.close(); process.exit(0);});