Asterisk开源AI语音Agent框架

最强大、最灵活的 Asterisk/FreePBX 开源 AI 语音智能体。采用模块化管线架构，可自由组合 STT、LLM 和 TTS 提供商，并提供 6 套经过企业部署验证、可直接用于生产环境的黄金基线。

快速开始 • 功能 • 路线图 • 演示 • 文档 • 社区

🌟 为什么选择 Asterisk AI Voice Agent？

🛠️ AI 驱动的操作

🏗️ 项目架构

2 分钟内启动 Admin UI。

如需完整了解首次成功通话的操作流程（拨号计划 + 传输方式选择 + 验证），请参阅：

传输兼容性

1. 运行预检（必需）

# 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。务必先运行此步骤！

2. 启动 Admin UI

# Start the Admin UI container
docker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui

3. 访问仪表盘

在浏览器中打开：

本地：http://localhost:3003

远程服务器：http://<server-ip>:3003

首次登录：第一次启动时，容器日志中会输出一次性的管理员密码。使用以下命令获取：

docker compose -p asterisk-ai-voice-agent logs admin_ui | grep -i password

首次登录时必须修改此密码。在生产环境中，请通过防火墙、VPN 或反向代理限制对 3003 端口的访问。

按照设置向导配置提供商并拨打测试电话。

⚠️ 安全提示：Admin UI 可通过网络访问。在生产环境中，请通过防火墙、VPN 或反向代理限制对 3003 端口的访问。

4. 验证安装

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 设置。

出站活动更容易准备、更安全调度，也更容易从管理员 UI 排查故障

更简单的线索导入 —— 导入已验证的 CSV 或 Excel .xlsx 文件，或手动添加单个线索。示例和新活动采用规范的 AI_AGENT/agent 路由模型，同时保持对遗留 AI_CONTEXT/context 输入的兼容性。

更安全的活动调度 —— 已调度的呼叫始终接收线索的被呼号码，格式错误的时区或通话窗口设置会安全失败，活动并发性计数正确，陈旧的尝试通过单一经过验证的超时策略恢复。

更可靠的人工处理 —— 人工优先的 AMD 默认设置减少了虚假语音信箱分类，终端告别/挂断处理防止新的呼叫者输入复活已结束的呼叫。

更好的 HTTP 工具工作流 —— 通话前、通话中和通话后的 HTTP 工具强制执行方法/请求体兼容性；通话前的输出变量保持可用以支持丰富的问候语；有界的、清理过的工具响应和诊断在通话历史和调度中可见。

更安全的升级 —— 更新程序恢复现在更可靠地处理较旧的 Git 安装、权限降低后的 Docker Compose 访问和混合所有权检出，无需牺牲本地跟踪的更改。

详见《出站呼叫指南》和 v7.4.1 更新日志。

每个 Agent 现在只能接收其被授权使用的转移目的地、日历和语音信箱

按 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 是仅限本地 AI 的稳定化版本

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 是稳定化补丁版本

v7.3.2 从受监管的 AudioSocket 和 ExternalMedia 验证周期构建。

无新提供商 —— 范围仅限于可靠性、部署安全性、文档和面向贡献者的 CI。

Grok ExternalMedia 已修复 —— 清洁的抢插、已取消输出隔离、命名实例运行时继承、完整替换转向和通过 xAI force_message 的精确不活动公告。

AudioSocket 和模块化管道强化 —— 终端播放、管道生成器所有权、话音检测回显和不活动宽限期回归由重点测试和监督呼叫覆盖。

更新程序和提供商故障恢复强化 —— 更安全的所有权、回滚/隐藏处理、就绪验证和可选的 dialplan 重定向。

PR 质量大门扩展 —— 管理员后端/前端检查和 CLI 交叉编译现在在合并前运行。

发布证据和剩余大门在 v7.3.2 验证矩阵中跟踪。

AVA 现在保护无声呼叫，并在断开连接前完成每条终端消息

默认 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

配置一个提供商，创建多个共享它的 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。

管理员 UI 的实时系统状态 —— 推送而非轮询

实时状态中心 —— 单个 /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。

管理员 UI 的一次重点质量版本 —— 无呼叫路径更改

仪表板可靠性 — 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 次故障防抖（瞬时探测抖动不再使点变红），响应式提供商网格，多实例支持