电话语音 Agent
本示例使用 Twilio 和 Grok API 的实时语音功能构建可通过电话呼叫的语音 Agent，适合作为客服、预订等需要与来电者实时交谈的电话系统的开发起点。
注意：这些实现供学习和开发使用。用于生产环境前，还需进一步加固。
概览
这些示例演示如何构建可接听电话的语音 Agent，适用于交互式语音应答（IVR）、呼叫中心和语音客服。
可用示例
XAI 原生实现
基于 Twilio Media Streams 的 XAI 原生实现。
功能：
通过 WebSocket 直接接入 XAI
实时语音处理
会话管理
技术栈：
Node.js + TypeScript
Twilio Media Streams
WebSockets
Express 服务器
快速开始
XAI 原生实现（推荐）
cd xai
npm install
# Configure environment
cp .env.example .env
# Edit .env with your keys
# Start server
npm run dev
# Expose to internet (for Twilio)
ngrok http 3000
# Configure Twilio webhook with ngrok URL
# Call your Twilio number!架构
呼叫流程
┌─────────┐ 1. SIP ┌─────────────┐ 2. WebSocket ┌──────────────┐
│ Phone │ ←──────────→ │ Twilio │ ←──────────────→ │ Your Server │
│ Call │ Audio │Media Streams│ μ-law (native) │ (Node.js) │
└─────────┘ └─────────────┘ └──────────────┘
↓
3. WebSocket
↓
┌──────────────┐
│ XAI API │
│ (Realtime) │
└──────────────┘数据流
电话 → Twilio：来电者拨打你的 Twilio 号码
Twilio → 服务器：Twilio 通过 WebSocket 流式传输 μ-law PCM 音频
服务器 → XAI：服务器将 μ-law 音频直接转发至 XAI Realtime API，无需转换
XAI → 服务器：AI 返回 μ-law 音频和文本
服务器 → Twilio：服务器将 μ-law 音频直接转发给 Twilio，无需转换
Twilio → 电话：来电者听到 AI 的回答
前提条件
所需账号
XAI 账号
获取 API 密钥：console.x.ai
Realtime API 访问权限
Twilio 账号
支持语音通话的电话号码
已启用 Media Streams
技术要求
Node.js：18 或更高版本
公开端点：使用 ngrok 或已部署的服务器
端口：3000（可配置）
设置指南
1. 获取 Twilio 凭据
# From Twilio Console
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_PHONE_NUMBER=+12345678902. 配置环境
cd xai
cp .env.example .env
# Edit .env with:
XAI_API_KEY=your_xai_api_key_here
HOSTNAME=your-ngrok-domain.ngrok.app3. 允许通过互联网访问
使用 ngrok：
# Install ngrok
brew install ngrok # macOS
# or download from ngrok.com
# Start your server first
npm run dev
# In another terminal, expose it
ngrok http 3000
# Copy the HTTPS URL (e.g., https://abc123.ngrok.io)4. 配置 Twilio webhook
前往 Phone Numbers → Manage → Active Numbers
点击你的电话号码
在 Voice & Fax 下设置：
A call comes in：Webhook
URL：
https://your-ngrok-url.ngrok.io/twimlMethod：POST
保存
5. 测试通话
# Call your Twilio number
# You should hear the AI agent!功能
XAI 原生实现的功能
实时语音处理
低延迟响应
会话管理
通话日志
错误处理
平稳断开连接
配置选项
环境变量
# Required
XAI_API_KEY=your_key_here
HOSTNAME=your-ngrok-domain.ngrok.app
# Optional (with defaults)
API_URL=wss://api.x.ai/v1/realtime
PORT=3000注意：请在 Twilio Console 中配置 Twilio 凭据，无需将它们设为环境变量。
语音配置
// In your code
const sessionConfig = {
type: "session.update",
session: {
voice: "Ara", // Choose from: Ara, Rex, Sal, Eve, Leo
instructions: "You are a helpful assistant.",
// Audio format settings (these are the defaults if not specified)
audio: {
input: { format: { type: "audio/pcm", rate: 24000 } },
output: { format: { type: "audio/pcm", rate: 24000 } }
}
}
};音频处理
音频格式（无需转换）
端到端格式：
格式：μ-law PCM（audio/pcmu）
采样率：8 kHz
编码：Base64
Twilio → 服务器 → XAI：
直接传输 μ-law 音频，无需转换
XAI API 原生支持 PCMU（μ-law）格式
XAI → 服务器 → Twilio：
直接传输 μ-law 音频，无需转换
直接转发可降低延迟并改善音质
音频处理流程
// Incoming audio from Twilio (μ-law @ 8kHz)
const twilioAudio = μ-law PCM @ 8kHz
// Send directly to XAI (configured for native μ-law input)
await xaiWebSocket.send(twilioAudio)
// Receive from XAI (μ-law @ 8kHz - native telephony format)
const xaiResponse = μ-law PCM @ 8kHz
// Send directly to Twilio
await twilioWebSocket.send(xaiResponse)主要改进：XAI API 原生支持 μ-law（PCMU）和 A-law（PCMA），无需转换为 PCM16，从而改善音质并降低延迟。
监控与调试
启用日志
# Set log level
LOG_LEVEL=debug npm run dev检查 WebSocket 连接
// Connection events
ws.on('open', () => console.log('Connected to XAI'));
ws.on('close', () => console.log('Disconnected from XAI'));
ws.on('error', (err) => console.error('WebSocket error:', err));测试
本地测试
# Start server
npm run dev
# Use ngrok for external access
ngrok http 3000
# Call your Twilio number通话测试脚本
# Make a test call via Twilio API
curl -X POST https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls.json \
--data-urlencode "Url=http://your-server.com/twiml" \
--data-urlencode "To=+1234567890" \
--data-urlencode "From=$TWILIO_PHONE_NUMBER" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN文档
XAI 实现 README：XAI 实现细节
Twilio 文档：Twilio Media Streams
XAI API 文档：XAI Realtime API
示例
使用场景
IVR 系统：
菜单导航
呼叫路由
信息收集
客户支持：
一线支持
处理常见问题
预约安排
调查：
语音调查
收集反馈
市场调研
通知：
预约提醒
付款提醒
状态更新