6.0
关注
AI SCORE
开源项目2025-12-25 07:25
Asterisk开源AI语音Agent框架
Hacker News · github.com#开源#语音AI#Agent
Editor brief · 编辑速览
开源项目实现语音对话能力的AI Agent，支持语音交互和自动化。
最强大、最灵活的 Asterisk/FreePBX 开源 AI 语音智能体。采用模块化管线架构，可自由组合 STT、LLM 和 TTS 提供商，并提供 6 套经过企业部署验证、可直接用于生产环境的黄金基线。
快速开始 • 功能 • 路线图 • 演示 • 文档 • 社区
🌟 为什么选择 Asterisk AI Voice Agent？
🛠️ AI 驱动的操作
🏗️ 项目架构
2 分钟内启动 Admin UI。
如需完整了解首次成功通话的操作流程（拨号计划 + 传输方式选择 + 验证），请参阅：
传输兼容性
# Clone repository
git clone https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk.git
cd AVA-AI-Voice-Agent-for-Asterisk
# Run preflight with auto-fix (creates .env, generates JWT_SECRET)
sudo ./preflight.sh --apply-fixes
重要：预检会创建 .env 文件并生成安全的 JWT_SECRET。务必先运行此步骤！
# Start the Admin UI container
docker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui
在浏览器中打开：
远程服务器：http://<server-ip>:3003
首次登录：第一次启动时，容器日志中会输出一次性的管理员密码。使用以下命令获取：
docker compose -p asterisk-ai-voice-agent logs admin_ui | grep -i password
首次登录时必须修改此密码。在生产环境中，请通过防火墙、VPN 或反向代理限制对 3003 端口的访问。
按照设置向导配置提供商并拨打测试电话。
⚠️ 安全提示：Admin UI 可通过网络访问。在生产环境中，请通过防火墙、VPN 或反向代理限制对 3003 端口的访问。
GPU 用户：如果你使用 NVIDIA GPU 进行本地 AI 推理，请在构建前参阅 docs/LOCAL_ONLY_SETUP.md，了解 GPU Compose 覆盖配置（docker-compose.gpu.yml）。
# Start ai_engine (required for health checks)
docker compose -p asterisk-ai-voice-agent up -d --build ai_engine
# Check ai_engine health
curl http://localhost:15000/health
# Expected: {"status":"healthy"} ("degraded" is also possible if a subsystem is unhealthy)
# View logs for any errors
docker compose -p asterisk-ai-voice-agent logs ai_engine | tail -20
向导将为你的 Asterisk 服务器生成所需的拨号计划配置。
传输方式的选择取决于配置，并非严格区分为“管线或完整智能体”。请使用以下文档中经过验证的矩阵：
docs/Transport-Mode-Compatibility.md
🔧 高级设置（CLI）
适用于偏好命令行或需要无界面设置的用户。
选项 A：交互式 CLI
./install.sh
agent setup
注意：旧版命令 agent init、agent quickstart、agent doctor、agent troubleshoot 和 agent demo 仍作为隐藏的兼容性别名保留。新工作流应使用 docs/CLI_TOOLS_GUIDE.md 中记录的可见命令。
选项 B：手动设置
# Configure environment
cp .env.example .env
# Edit .env with your API keys
# Start services
docker compose -p asterisk-ai-voice-agent up -d
配置 Asterisk 拨号计划
将以下内容添加到 FreePBX（extensions_custom.conf）：
[from-ai-agent]
exten => s,1,NoOp(Asterisk AI Voice Agent)
; AI_AGENT selects an operator-managed agent by slug.
same => n,Set(AI_AGENT=sales-agent)
; Optional: override that agent's configured provider/pipeline for this call.
; same => n,Set(AI_PROVIDER=google_live)
same => n,Stasis(asterisk-ai-voice-agent)
same => n,Hangup()
使用 AI_AGENT 选择由运维人员管理的智能体。除非有意将 AI_PROVIDER 设置为单次通话级别的覆盖项，否则该智能体配置的目标具有最终决定权。
使用 agent dialplan --agent <slug> 生成当前配置片段。
有关通道变量优先级和示例，请参阅 docs/FreePBX-Integration-Guide.md。
agent check
docker compose -p asterisk-ai-voice-agent logs -f ai_engine
v7.5.3 专注于将安装恢复到已知的正常配置，同时不撤销运维人员所做的其他无关更改。
在对应上下文中恢复音频默认值——Admin UI 中的提供商、音频配置文件和模块化管线均提供各自的恢复操作。恢复提供商时会保留凭据、模型、语音、提示词、启用状态和提供商标识；恢复配置文件时会保留智能体分配；恢复管线时会保留 STT/LLM/TTS 提供商选择和非音频选项。
由后端维护的基线——恢复值来自与验证过程相同的规范注册表，其中包括受支持的 OpenAI Realtime GA linear16/24 kHz 契约。由环境维护的覆盖项仍然可见，且绝不会被静默改写。
明确的应用指导——每次恢复都会说明在新通话使用该基线之前，是无须执行任何操作、需要热重载，还是需要重启 AI Engine。
故障关闭式拨号计划转接——分机、队列和振铃组转接会验证确认缺失的目标，要求已确认的 ARI 移交，并在 Asterisk 响应无法确定时安全地保留所有权。FreePBX 队列默认使用标准的 ext-queues 上下文（#577）。
查询智能体实际执行的操作——已完成的通话中工具现在会在通话历史及其 API 中公开稳定的 tool_call_id、标准化的成功/失败状态、操作以及可用于对账的 target_id，同时不会将遥测数据混入对话文本（#587）。
这些恢复操作的范围经过刻意限定：它们不提供全局恢复出厂设置，也不会更改密钥或智能体路由。
有关实现和兼容性的详细信息，请参阅 v7.5.3 变更日志。
v7.5.2 新增了通话级宽带路径，同时不更改现有的智能体配置文件或既定的 8 kHz 兼容性默认值。
原生 16 kHz AudioSocket——为智能体分配 wideband_pcm_16k，即可在双向传输中使用 Asterisk slin16 和与采样率匹配的 AudioSocket 分帧。
提供商和管线对齐——Grok、Google Live、Deepgram、OpenAI、ElevenLabs、Local Hybrid 和 Full Local 均保留准确反映实际情况的单次通话媒体契约，包括重试、工具续接、中断和清理。
故障关闭式兼容性——宽带要求使用 Asterisk 20.17+、21.12+、22.7+ 或 23.1+，并具备真正的宽带终端或 SIP 中继路径，例如 G.722。ExternalMedia RTP 和 PSTN/G.711 通话仍使用 8 kHz 配置文件。
简单回滚——将智能体切换回 telephony_ulaw_8k 或 telephony_enhanced_8k 即可，无须更改全局传输方式或提供商默认设置。
请参阅 v7.5.2 变更日志、v7.5.2 迁移说明和 v7.5.2 验证矩阵。
v7.5.1 热修复专注于恢复能力和可观测性，不会更改音频配置文件、提供商传输方式或全新安装的默认设置。
可恢复的“应用更改”——Admin UI 会在操作运行中的服务之前准备好更新程序运行器；如果 Compose 替换失败或替换后的服务未能恢复健康状态，则还原之前的镜像和容器环境。
完整的实时转录文本——OpenAI 和 Grok 将助手转录状态与交错到达的呼叫者最终事件分开保存，防止通话历史和通话后处理方收到前缀被截断的内容。
应用更改，而非不必要的重启——仅涉及工具的编辑会提示并使用热重载，使更改对新通话生效。提供商、环境和进程级更改仍采用重启或重新创建流程。
无须执行数据库迁移或重新分配音频配置文件。现有的已存储转录文本不会被改写。
请参阅 v7.5.1 变更日志和 v7.5.1 迁移说明。
v7.5.0 在不改变既定 8 kHz Asterisk 线路契约的前提下改善了窄带通话音频，并新增面向生产环境的 VICIdial Remote Agent 集成。
可选启用的增强型电话音频——为智能体分配 telephony_enhanced_8k，即可使用有状态的带限降采样，获得更清晰的 G.711 播放效果。现有配置文件会保留其兼容性行为，切换回 telephony_ulaw_8k 即可立即回滚。
一致的提供商和管线策略——托管提供商和模块化 TTS 管线默认继承智能体的音频配置文件，同时提供范围受限的故障排查覆盖项，并在应用前验证不兼容的编码、采样率、重采样器、重叠和分段组合。
更安全的中断和终止处理——重采样器状态按通话隔离，并在响应、中断和清理期间重置；已被替换的流不会被过期的清理操作移除；通话终止流程取得所有权后，延迟到达的管线输出也会被阻止。
VICIdial Remote Agents——VICIdial 仍是营销活动、客户通道、报告、处置结果、DNC、回拨和转接的权威系统，而 AAVA 则提供已映射的 AI 智能体，并具备故障关闭式所有权检查以及经过清理的生命周期证据。
更易恢复的升级——主机恢复脚本能够处理混合 Git 所有权、过期的更新程序镜像、/root 遍历限制和已纳入跟踪的本地编辑，同时保留范围受限的备份并精确定位目标版本。
有关详细信息，请参阅 v7.5.0 变更日志、音频配置文件和 VICIdial Remote Agent 设置。
更简单的线索导入 —— 导入已验证的 CSV 或 Excel .xlsx 文件，或手动添加单个线索。示例和新活动采用规范的 AI_AGENT/agent 路由模型，同时保持对遗留 AI_CONTEXT/context 输入的兼容性。
更安全的活动调度 —— 已调度的呼叫始终接收线索的被呼号码，格式错误的时区或通话窗口设置会安全失败，活动并发性计数正确，陈旧的尝试通过单一经过验证的超时策略恢复。
更可靠的人工处理 —— 人工优先的 AMD 默认设置减少了虚假语音信箱分类，终端告别/挂断处理防止新的呼叫者输入复活已结束的呼叫。
更好的 HTTP 工具工作流 —— 通话前、通话中和通话后的 HTTP 工具强制执行方法/请求体兼容性；通话前的输出变量保持可用以支持丰富的问候语；有界的、清理过的工具响应和诊断在通话历史和调度中可见。
更安全的升级 —— 更新程序恢复现在更可靠地处理较旧的 Git 安装、权限降低后的 Docker Compose 访问和混合所有权检出，无需牺牲本地跟踪的更改。
详见《出站呼叫指南》和 v7.4.1 更新日志。
按 Agent 的资源访问 —— 在工具上配置全局库存，然后在 Agents → Edit Agent → Tools 下为转移系列、Google Calendar、Microsoft Calendar 和语音信箱选择继承、选定或无。
单个强制呼叫快照 —— 提供商架构、提示指导、执行、延迟转移和审计元数据均使用同一有效资源集。空的或过时的选择会安全失败，全局禁用的工具始终优先。
无需重启的工具更新 —— 工具 → 保存并应用验证并为新呼叫发布新的工具版本。活跃呼叫保留它们开始时的版本；失败的构建使前一个版本继续运行。
Contexts 已弃用 —— 运行时角色路由现在从 agents.db 读取 Agents。遗留的 YAML Contexts 在升级时被原子导入，AI_CONTEXT 仍是弃用的兼容性别名，而 dialplans 转移到 AI_AGENT。
更清洁的首次运行 —— 空安装以接待员、销售和支持开始，而不是一系列演示 Contexts。
通话历史兼容性 —— 工具名称保持为 google_calendar、microsoft_calendar 和 leave_voicemail，所以现有过滤器和报告继续工作。
升级前——尤其是从 v7.3.0–v7.3.3 升级时——请阅读当前升级过程和 Contexts → Agents 迁移指南。
按 Agent 的回铃音控制 —— 在 Agents UI 中启用连接时播放回铃音；tone:ring 作为默认重复的 Asterisk 音调提供。
每条呼叫路径一个实现 —— 完整 Agent 提供商和模块化管道共享同一仅限呼叫者的生命周期，无需向 AI 提供商发送设置音频。
清洁的音频交接 —— 回铃音在第一个提供商或管道问候语音频处停止，也在无问候语就绪、启动失败、断开连接或呼叫清理时被清除。
安全且可选 —— 现有 Agents 保持不变直到启用该设置。YAML/API 用户可配置 Asterisk 本地 tone:、sound: 或 recording: 媒体 URI。
详见《连接音频/回铃音》和 v7.3.5 更新日志。
v7.3.3 不添加任何提供商，保持云提供商呼叫路径不变。
呼叫按会话隔离 —— Agent 提示和对话状态不再改变共享的本地 AI 服务器配置或通过重用的 WebSocket 连接泄漏。AI Engine 和本地 AI 服务器应一起升级；遗留的无作用域开关保持暂时兼容。
抢插放弃中断的输出 —— 后期 LLM/TTS 工作被隔离，中断的交换从弱模型历史中删除，替换转向保持专注于呼叫者刚说的内容。
告别恰好完成一次 —— 本地 hangup_call 播放所选的 Kokoro/Piper 等告别语，无需第二次 LLM 重写，排空部分 AudioSocket 或 RTP 尾部，记录 agent_hangup，然后断开连接。
CPU/GPU 部署更安全 —— 依赖固定、CUDA/cuDNN 验证、可选的 llama.cpp 架构针对和幂等的预飞行检查减少首次构建和重新运行的失败。
社区 GPU 证据 —— Tesla V100S 测试通过了 Faster-Whisper CUDA float16、Llama 3.1 8B Q4_K_M、Kokoro、AudioSocket、ExternalMedia、抢插、终端挂断、并发会话隔离和重启恢复。
详见《本地 AI 社区测试矩阵》和《未发布更新日志》以了解完整范围。
v7.3.2 从受监管的 AudioSocket 和 ExternalMedia 验证周期构建。
无新提供商 —— 范围仅限于可靠性、部署安全性、文档和面向贡献者的 CI。
Grok ExternalMedia 已修复 —— 清洁的抢插、已取消输出隔离、命名实例运行时继承、完整替换转向和通过 xAI force_message 的精确不活动公告。
AudioSocket 和模块化管道强化 —— 终端播放、管道生成器所有权、话音检测回显和不活动宽限期回归由重点测试和监督呼叫覆盖。
更新程序和提供商故障恢复强化 —— 更安全的所有权、回滚/隐藏处理、就绪验证和可选的 dialplan 重定向。
PR 质量大门扩展 —— 管理员后端/前端检查和 CLI 交叉编译现在在合并前运行。
发布证据和剩余大门在 v7.3.2 验证矩阵中跟踪。
默认 30 秒入站不活动保护 —— AVA 询问"你还在吗？"，等待 15 秒以获得回复，然后播放一个可配置的最终警告并结束呼叫。出站 Agents 保持可选。
Agent 保持其配置的语音 —— 签到和最终警告由活跃的 Google Live、OpenAI Realtime、Grok、Deepgram、ElevenLabs、本地完整 Agent 或管道语音合成。
传输安全挂断 —— 监控程序和 hangup_call 告别在 ARI 断开呼叫者前排空 AudioSocket 或 ExternalMedia/RTP 流缓冲和 ARI 文件播放。固定睡眠不再截断长的最终句子。
Deepgram 和 ElevenLabs 生命周期修复 —— Deepgram 控制帧不再拆分问候语，ElevenLabs 响应完成加托管静音处理保持 AVA 的监控程序权威。
全局和按 Agent 的控制 —— 在高级设置 → 语音活动检测 → 呼叫者不活动下配置默认值，然后可选地按 Agent 覆盖。通话历史将监控程序结束标记为"无输入超时"。
详见《呼叫者不活动配置》、《ElevenLabs 设置》和完整的 v7.3.1 更新日志。
配置一个提供商，创建多个共享它的 Agents —— 每个都有自己的语音。
Agent 表单中的提供商感知语音选择器：OpenAI 的 10 个 GA 语音的下拉菜单、Grok 的建议 + 自定义克隆 ID、Google Live 的 30 个预构建语音、Deepgram 的 Aura 模型 —— 控制适应于 Agent 选择的 AI Engine。
默认安全 —— 提供商级语音成为默认语音；没有配置的 Agents 行为完全如前。无法识别的值（OpenAI/Google/Deepgram 目录被验证）记录警告并回退 —— 一个坏的语音值永不导致呼叫失败。
可观察 —— 每个呼叫记录已解析的语音及其来源，通话历史按呼叫显示"Voice: marin (from agent)"。
Agent 语音更改立即应用 —— 无需引擎重启。
感谢 @foytech 为此功能播种（#497）。完整指南：docs/VOICE_SELECTION.md。
实时状态中心 —— 单个 /api/live-status 快照端点加上 SSE 流（/api/live-status/stream）将 AI Engine 健康、本地 AI 连接性、活跃会话、音频目录、平台检查和 Asterisk ARI 聚合为一个规范化状态馈送。
推送优先 —— ai_engine 和 local_ai_server 将其自身就绪状态推送到管理员 UI（POST /api/live-status/publish，使用 LIVE_STATUS_PUSH_TOKEN 认证），所以仪表板在重启后亚秒级时间内收敛，而非等待交错轮询。遗留的 /api/system/* 探针保持为回退/富化。
可配置 —— LIVE_STATUS_POLL_INTERVAL_SECONDS（默认 30 秒，最小 2 秒）和 LIVE_STATUS_INITIAL_PROBE_TIMEOUT_SECONDS（默认 2 秒），从 .env 实时读取。
完整说明在 CHANGELOG.md。
仪表板可靠性 — Asterisk 状态指示器不再因瞬时 ARI 波动而闪烁：它读取引擎的权威性、经过重连监督的 ARI 状态，并应用滞后机制。仪表板每 5 秒轮询的系统端点不再阻塞管理员事件循环，最重的端点使用 TTL 缓存，轮询在错误时退避，失败的轮询在错误横幅中显示，单次轮询失败不再将卡片闪烁到"正在加载…"。
不再有"正在加载配置…"闪屏 — 约 11 个配置页面现在从配置文档的共享 stale-while-revalidate 缓存中获取初始数据，所以重新访问设置页面是即时的。
无障碍访问 (WCAG AA) — 表单标签以编程方式关联到输入框，焦点陷阱模态框，导航地标 + "跳转到内容"链接，纯图标按钮的无障碍名称，拓扑图上的非颜色状态提示，可见的深色模式切换开启状态，以及浅色模式的对比度修复。调试 console.logs（包括一个向浏览器控制台泄露身份验证令牌的）已被删除。
提示词编辑器 — 配置的工具名称按其通话中的状态（启用 / 全局 / 未启用）进行颜色编码，随着您输入而动态更新。
修复 (#436) — 规范的 google_live: { type: full } 提供商现在可以编辑并再次保存。
完整说明见 CHANGELOG.md。
迄今为止最大的发布：从管理员 UI 管理您的 AI 智能体，而不是配置文件。
🤖 智能体选项卡 — 在 UI 中创建、编辑和管理智能体。从模板开始（接待员、下班后、预约预约员等），设置提示词和提供商，并复制可直接粘贴的拨号方案代码片段。
📊 多智能体仪表板 — 实时 KPI（活跃智能体、活跃通话、路由通话、转接），按智能体统计和路由分解一目了然。
☎️ 新的 AI_AGENT 拨号方案变量 — 按名称将通话路由到智能体。您现有的 AI_CONTEXT 拨号方案继续工作不变。
🔄 自动迁移 — 您现有的上下文在首次启动时迁移到本地智能体数据库。在后续主版本升级前备份 agents.db；有关回滚界限，请参阅操作员迁移指南。
🔒 安全加固 — 不再有 admin/admin：生成一次性管理员密码，必须在首次登录时更改。配置导出默认情况下不再包含您的 .env。
⚠️ 主要版本 — 在从 6.x 升级前请阅读升级说明。
对 v6.5.3 热修复的后续。v6.5.3 仅翻转了 config/ai-agent.yaml；v6.5.4 使代码库的其余部分保持一致：
src/config.py 中的 Pydantic 默认值现在默认为 api_version: ga + model: gpt-realtime（因此全新向导安装是正确的）。
OpenAI Realtime 的管理员 UI"添加提供商"模板不再设置 sunset 预览模型。
模型下拉列表移除了 5 个 sunset 预览选项，并添加了 3 个新的 GA 模型 — gpt-realtime-1.5（最佳音频输入/输出质量）、gpt-realtime-2（推理语音模型，GPT-5 级）和 gpt-realtime-mini（成本优化）— 与现有的 gpt-realtime 并列。
操作员 YAML 中的旧版预览值现在在"自定义（旧版 — 将不连接）"选项组中呈现，表单上方有黄色警告横幅，因此无需静默交换操作员的配置即可看到损坏状态。
当在配置中检测到 api_version: beta 时，引擎会发出一次性警告（每个提供商生命周期恰好一次，而不是每次重连尝试）。
文档：完全重写 docs/Provider-OpenAI-Setup.md 模型部分 + 修复 docs/TROUBLESHOOTING_GUIDE.md。
OpenAI 在 2026-05-12 弃用了 Realtime Beta API，并在 2026-05-07 删除了 gpt-4o-realtime-preview-2024-12-17 模型。已发布的 config/ai-agent.yaml 仍然固定了 api_version: beta + 该预览模型，因此每个使用 OpenAI Realtime 的操作员都遇到了 error.code: beta_api_shape_disabled，WebSocket 立即关闭。两行配置翻转 — 无需代码更改。提供商的 GA 线路协议路径自 v6.0.0 起已发布；v6.5.3 只是使其成为每个人都会获得的默认值：
api_version: ga (was beta)
model: gpt-realtime (was gpt-4o-realtime-preview-2024-12-17)
如果您有明确固定 api_version: beta 的 ai-agent.local.yaml，请删除覆盖或将其更改为 ga。参考：OpenAI deprecations、gpt-realtime。
🆕 xAI Grok Voice Agent 实时提供商（新增，v6.5.2）
第五个全功能智能体实时提供商 — 在结构上平行于 OpenAI Realtime 和 Google Live，从第一天开始就建立在多实例基础之上
μ-law @ 8 kHz 来电输入，无输入重采样；观察到的 xAI 输出是 PCM16 @ 24 kHz，AAVA 将其转换为配置的 Asterisk 传输格式
五个命名声音（eve、ara、rex、sal、leo）加上自定义语音 ID 自由文本用于克隆声音
自定义函数工具与 OpenAI Realtime 相同；xAI 原生工具（web_search、x_search、file_search、mcp）通过 YAML extra_tools 转义舱口接受
28 分钟的保守长会话警告，以兼容较旧的 xAI 限制；xAI 的当前语音智能体模型页面列出 120 分钟的最大会话
设置指南：docs/Provider-Grok-Setup.md
🏢 多实例全功能智能体提供商（新增，v6.5.2）
运行相同全功能智能体提供商类型的多个实例，具有隔离的凭证（例如 acme_google_live + globex_google_live 都使用 type: google_live）
每实例凭证文件位于 /app/project/secrets/providers/<provider_key>/{api-key,agent-id,vertex-json} — 新的每提供商 Vertex 上传路径不会改变 .env
通过 AI_PROVIDER、智能体的提供商选择加 AI_AGENT，或使用 Asterisk Gosub 进行基于 DID 的调度来路由
设置指南：docs/Multi-Instance-Full-Agent-Providers.md
多实例设置的破坏性变更：短别名 AI_PROVIDER=openai、AI_PROVIDER=google、provider: deepgram_agent 现在无法通过验证 — 改用精确的提供商实例密钥。使用规范块名称的单实例设置不受影响。
🎛 管理员 UI 打磨（v6.5.2）
在所有全功能智能体提供商表单（Grok、OpenAI Realtime、Deepgram、Google Live、ElevenLabs Agent）中统一的每实例凭证粘贴式上传器
EnvPage 添加了新的"每实例提供商凭证"状态部分，以便操作员可以在不使用 SSH 的情况下审计凭证文件的存在
仪表板系统拓扑重建：三态按组件运行状况，2 次故障防抖（瞬时探测抖动不再使点变红），响应式提供商网格，多实例支持