AWS 官方示例：语音 AI 代理工作室

aws-samples/sample-voice-ai-agent-studio

在 AWS 上设计、构建并跑通语音 AI 代理的原型。一个引导式工作室，专门用来配置实时语音代理，从行业模板一路走到实际电话呼叫，底层由 Amazon Nova Sonic、Strands Agents BidiAgent 和 Amazon Bedrock AgentCore 提供支持。

样例 / 概念验证。

本项目是供学习和原型设计使用的参考实现。在用于生产工作负载之前，请先审查并加固（安全性、错误处理、扩展性、成本控制都得看）。

语音代理技术栈

实时语音代理不是单一模型，而是一个由一层层决策叠起来的技术栈。每一层都可以独立选择，但某一层的取舍会波及其他层：

- 模型（Model），决定谁来听、想、说，比如 Nova Sonic 这类语音到语音（speech-to-speech）模型，也可以是 STT + LLM + TTS 的组合
- 框架（Framework），负责协调整个会话，包括流式传输、轮次检测和工具调用，比如 Strands BidiAgent、LiveKit、Pipecat
- 集成（Integrations），决定代理到底能干些什么，比如知识库/RAG、API、MCP、其他代理
- 通道（Channel），决定呼叫者怎么连进来，关乎协议和传输方式，比如 WebSocket、WebRTC、PSTN、SIP
- 托管（Hosting），决定跑在哪里、怎么扩容，比如托管运行时、容器、本地部署关于这些层背后的概念，可以看《构建实时语音代理：选择模型、框架、协议与托管》这篇文章。

本工作室把这些层串成一个引导式工作流。选好模型和语音，接上工具和 RAG，挑一个通道（浏览器、PSTN 或 SIP），再部署到 AWS 上的托管运行时就行，不用自己手搓整个栈。当前版本用的是 Amazon Nova 2 Sonic（语音到语音），跑在 Strands BidiAgent 框架上，托管在 Amazon Bedrock AgentCore。

架构

整套方案有四个可部署的组件。核心应用由 CDK（deployment/deploy.sh）负责部署；两条电话路径则是独立部署的，因为它们要预配面向公网的网络基础设施，安全审查门槛要高一些。

| 组件 | 部署方式 |
| --- | --- |
| 前端应用（React UI + demos/tools/RAG API，Cognito） | CDK，deploy.sh |
| AgentCore 上的语音代理（Nova Sonic BidiAgent runtime） | CDK，deploy.sh |
| PSTN 中继（Twilio TAC bridge） | 独立部署，telephony/pstn/ |
| SIP 中继（drachtio + bridge） | 独立部署，telephony/sip/ |

功能

代理构建器

- 引导式向导，选模板、流水线、模型、语音、工具、提示词和工作流
- 行业模板覆盖保险、银行、联络中心培训、得来速（译注：drive-through，免下车服务窗口）、汽车、医疗
- 可视化工作流设计器，每个步骤都能挂工具
- 实时语音测试，附带实时转录

语音与推理

- 双向流式传输（语音到语音），Amazon Nova 2 Sonic（不需要密钥），另外支持 OpenAI Realtime 和 Google Gemini Live（这俩得自备 API 密钥）

集成

- 每个代理天生就能用内置保留工具（结束通话、转接人工）
- 在 UI 里自定义工具，附带 mock 响应
- Webhooks、Lambda 函数、AgentCore MCP gateway、AgentCore 子代理运行时
- 基于现有 Bedrock Knowledge Base 的 RAG，支持文档上传和数据源同步
- 电话方面支持 PSTN（Twilio）和直 SIP 中继（Genesys、Five9、NICE）

评估

- 评估套件（Eval suites），把可复用的测试用例（提示词、模型、模拟呼叫者场景）打成组，给某个代理用
- LLM 当裁判，按可配置的维度和评分标准打分，给出 PASS/FAIL 判定和理由
- 真实工具或 mock 工具二选一，可以让代理去调真实集成（HTTP/Lambda/MCP/子代理），也可以喂 mock 响应
- 性能指标 TTFT（time to first token，首次令牌时间）、TTFB（time to first audio byte，首次音频字节时间）、工具执行延迟，给到 min/max/avg/p50/p95

平台

- 语音代理部署在 AgentCore 上，跑的是双向运行时（Bidirectional Runtime）
- 仪表盘，指标、对话历史、成本跟踪都在里面
- Cognito 身份认证，搭配 SigV4 预签名 WebSocket URL
- 多租户，每个用户只能看到自己的代理、工具和评估（管理员看得到全部）
- 一条命令走 CDK 部署到 AWS

部署

核心应用（前端 + AgentCore 上的语音代理）通过 CDK 走 deployment/deploy.sh 部署。前置条件、支持区域、CDK 堆栈、IAM 权限、环境变量，还有分步操作说明，都放在部署指南里：

- docs/DEPLOYMENT.md，完整部署指南
- docs/LOCAL-DEVELOPMENT.md，不完整部署、本地怎么跑两条电话路径（PSTN 和 SIP）是可选的，独立部署，见 telephony/pstn/ 和 telephony/sip/。

电话

真实场景下的语音代理得能接电话。工作室提供两条电话路径，开发时可以直接拨实际电话来测代理，另外还留了一条直 SIP 集成路径，方便企业级部署。

> 与主 CDK 应用分开部署。

两条电话路径都要预配面向公网的网络基础设施（公共负载均衡器、开放的 UDP 端口），安全审查要求比方案其他部分更严。源码和自管部署说明都放在顶层 telephony/ 目录下的 telephony/pstn/ 和 telephony/sip/ 里，不归 deploy.sh 管。

PSTN（Twilio Conversation Relay）

呼叫者拨 Twilio 号码，就能跟浏览器里跑的那个语音代理对话。多个代理可以共用一个号码，靠 DTMF（双音多频）菜单切换。

- 基础设施，ECS Fargate + ALB + CloudFront（仅 HTTPS/WSS）
- 网络，仅公有子网的 VPC（没有私有子网，也没有 NAT Gateway），Fargate 任务直接拿公网 IP
- 媒体，Twilio 处理所有 RTP/codec，bridge 收到的是 base64 编码的 WebSocket 音频消息
- 安全边界，CloudFront TLS 终止，没有开放的 UDP 端口

SIP（直接中继）

面向企业联络中心（Genesys、Five9、NICE）或 Twilio SIP Trunking 的直接 SIP 集成。直连 RTP 处理媒体，延迟更低。

- 基础设施，EKS Managed Node Group + NLB（UDP）
- 网络，节点落在公有子网并启用 hostNetwork，因为 RTP 要求 IP 可直接寻址（NAT Gateway 没法转发入站 UDP）
- 媒体，自管 RTP，bridge 直接收原始 UDP 包，做 μ-law 8kHz ↔ PCM 16kHz 之间的转换
- 安全边界，安全组（生产环境里记得限定为提供商的 IP），建议开 SIP TLS + SRTP

为什么网络设计不一样

| | PSTN 中继 | SIP 中继 |
| --- | --- | --- |
| VPC | 仅公有子网，无 NAT | 公有 + 私有子网，EKS 控制平面 ENI 用 NAT |
| 入站协议 | HTTPS/WSS（Twilio 管理 RTP） | 原始 UDP 5060 + 20000-20100 |
| 计算 | Fargate（不需要主机访问） | EKS 用 hostNetwork（必须把 UDP 端口绑到主机 IP） |
| 负载均衡 | ALB（HTTP/WebSocket） | NLB（UDP） |
| 公网 IP 暴露 | 只走 CloudFront | 节点公网 IP 直接出现在 SDP 里（可直接寻址） |

文档

| 指南 | 描述 |
| --- | --- |
| telephony/README.md | 电话概览，PSTN vs SIP，独立部署 |
| telephony/pstn/README.md | PSTN 中继源码 + 自管部署说明 |
| telephony/sip/README.md | SIP 中继源码 + 自管部署说明 |
| GUIDE-pstn-relay-server.md | PSTN 中继的设计、网络架构与安全 |
| GUIDE-sip-server.md | SIP 服务器的设计、网络架构与生产安全 |
| SETUP-twilio-sip.md | Twilio SIP Trunk 配置（UI + CLI） |
| GUIDE-genesys-sip-integration.md | Genesys Cloud CX 集成 |
| GUIDE-connect-integration.md | Amazon Connect 集成 |

语音流水线

双向流式传输（语音到语音）

这是已实现的流水线。一个模型在一个流里同时处理语音输入、推理和语音输出。延迟最低，音频进、音频出，中间没有文本这一步。

代理运行时（source/agent/main.py）用选定的语音到语音模型构造一个 Strands BidiAgent，负责管双向 WebSocket 流、工具编排和轮次检测。

支持三种提供商，在向导里选：

| 提供商 | 模型 | API 密钥 | 音频采样率 |
| --- | --- | --- | --- |
| Amazon Nova 2 Sonic | amazon.nova-2-sonic-v1:0 | 不需要（走 AgentCore 角色） | 16 kHz |
| OpenAI Realtime | gpt-realtime | 需要（向导里填） | 24 kHz |
| Google Gemini Live | gemini-2.5-flash-native-audio-preview-09-2025 | 需要（向导里填） | 24 kHz |运行时通过 create_model()（位于 main.py / strands_agent.py）选模型，在会话就绪消息里把模型的音频采样率报给客户端，浏览器就能按正确的采样率播放和采集音频。提供商的模型 ID 可以通过 OPENAI_REALTIME_MODEL_ID / GEMINI_LIVE_MODEL_ID 环境变量覆盖。

注意，如果选了 OpenAI 或 Gemini 但没填对应提供商的 API 密钥，会话会直接挂掉并报清晰的错误，不会悄悄回退到 Nova Sonic。

电话桥接（PSTN/SIP）目前默认音频是 16 kHz，所以走电话用 OpenAI/Gemini 之前得先把桥接的采样率调对，现在浏览器测试三种都支持。

级联流水线（STT → LLM → TTS）还没实现。

向导里其实留了一份禁用的级联工作流 UI 脚手架（一个隐藏的 CascadedSpeech 页面，以及没启用的 pipeline: 'cascaded' / framework: 'pipecat' | 'livekit' type 选项），但后端没跟上。代理运行时只会建 Nova Sonic BidiAgent，源码里也找不到任何 STT/LLM/TTS 或 Pipecat/LiveKit 的代码和依赖。语音到语音是唯一能跑通的流水线。

代理工具

- 保留工具，endCallTool（优雅地结束通话）和 transferCall（转接到人工/部门），每个代理天生就有
- 其他工具（知识库、CRM、日历之类）都得通过 Tools UI 配置成自定义工具，方案里没有预置的
- 集成形式支持 Webhooks（HTTP）、Lambda 函数、MCP gateways（AgentCore）、子代理
- 自定义工具，在 UI 里填名称、描述、参数、mock 响应，会话开始时动态生成
- RAG，把文档上传到 Bedrock Knowledge Base，对话时直接当工具查

评估

语音代理上线前先过一遍测试。工作室会让代理跟模拟呼叫者聊一轮，再给出来的对话打分，方便对比不同提示词和模型，也能及早抓回归。

评估套件

评估套件把某个代理的可复用测试用例打成一组。每个测试用例记录一份基础提示词、一个目标模型、一组模拟呼叫者场景，代理迭代时可以反复跑同一套检查。套件按用户分（管理员可以看全部），每次跑的记录都存下来，方便事后对比。

真实工具 vs Mock 工具

每次跑都可以决定代理的工具到底走哪种：

- 真实模式（Live），代理调真实集成（HTTP webhook、Lambda、AgentCore MCP gateway 或子代理）。没有真实集成的工具会回退到 mock 响应。