LiveKit Agents 如何构建听懂 IVR 菜单并发送 DTMF 键音的导航 Agent【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents如果你想让语音 Agent 像真人拨打者一样操作一台电话 IVR 系统——听菜单提示Press 1 for accounts...、理解提示内容、再按 DTMF 键音逐级导航并取回信息——LiveKit Agents 仓库中的 bank-ivr 示例examples/telephony/bank-ivr给出了一条可直接运行的路径。示例由三部分组成见 READMENavigatorivr_navigator_agent.py主角色它打电话给银行监听 IVR、用 LLM 决定按哪个键并发送 DTMF 键音Mock Bankivr_system_agent.py一个模拟银行 IVR 系统播报提示并等待 DTMF 输入用MockBankService从data.json提供只读银行数据。真实场景中它就是某个实际电话号码航空公司、药房等示例提供 mock 是为了让你对着已知系统测试Dialerdial_bank_agent.py连接两者的脚本负责派发 Navigator 任务并通过 SIP 外呼 Mock Bank。准备条件按 README 的 Prerequisites本示例依赖外呼能力前置要求是一个已配置 SIP trunk 的 LiveKit让 Agent 能接听入站电话并发起外呼按 examples/README.md 的要求准备环境LiveKit Cloud 账号或本地 LiveKit server、Python 3.10、uv在examples目录下创建.env写入LIVEKIT_URL、LIVEKIT_API_KEY、LIVEKIT_API_SECRET示例使用 LiveKit Inference 时鉴权走 LiveKit API key/secret外呼脚本dial_bank_agent.py还需要环境变量SIP_OUTBOUND_TRUNK_ID。代码会校验该值未设置或不以ST_开头时脚本记录SIP_OUTBOUND_TRUNK_ID is not set or invalid并停止拨号在仓库根目录安装依赖uv sync --all-extras --dev注意一点README 中的命令写作uv run python examples/bank-ivr/...而本仓库中示例实际位于examples/telephony/bank-ivr/下面使用真实路径。启动三个进程整个流程需要三个终端README 把它们标记为 Target、Caller 和拨号触发。1. 启动 Mock Bank被叫方uv run python examples/telephony/bank-ivr/ivr_system_agent.py dev这个 Agent 作为 IVR 系统等待来电。它使用inference.LLM(openai/gpt-4.1)、inference.STT(deepgram/nova-3)、inference.TTS(cartesia/sonic-3)dispatch 名称取环境变量BANK_IVR_DISPATCH_NAME默认bank-ivr-agent。2. 启动 Navigator Agent主叫方新开终端uv run python examples/telephony/bank-ivr/ivr_navigator_agent.py dev这个进程会等待一个 dispatch 任务来告诉它该打给谁。模型配置为inference.LLM(openai/gpt-4.1)、inference.STT(deepgram/nova-3)、inference.TTS(rime/coda, voiceastra)dispatch 名称取PHONE_TREE_AGENT_DISPATCH_NAME默认my-telephony-agent。3. 触发外呼再开第三个终端uv run python examples/telephony/bank-ivr/dial_bank_agent.py --phone 1234567890 --request check balance for all accounts I have--phone要拨打的号码。README 明确提示要把它替换成经你 SIP 配置能路由到ivr_system_agent.py的号码脚本自身的默认值是12132896618--request给 Navigator 设定的目标作为 dispatch metadata 传递。脚本会自动把演示用的客户 ID 和 PIN 追加到请求末尾让 Agent 能完成认证默认--id 10000001、--pin 0000。导航是如何完成的Navigator 的核心在 ivr_navigator_agent.py。AgentSession有两个关键配置session: AgentSession AgentSession( llminference.LLM(openai/gpt-4.1), sttinference.STT(deepgram/nova-3), ttsinference.TTS(rime/coda, voiceastra), # This flag does two things: # 1. Helps agent avoid getting stuck listening to repeating IVR loops by actively responding when a loop is detected. # 2. Automatically gives the agent the send_dtmf_events tool to allow it to dial DTMF digits. ivr_detectionTrue, min_endpointing_delay5, )ivr_detectionTrue按源码注释做两件事防止 Agent 卡在重复播放的 IVR 循环里检测到循环时主动回应并自动给 Agent 提供send_dtmf_events工具用于发送 DTMF 数字。系统提示词DtmfAgent的instructions进一步约束行为需要输数字时必须用 DTMF 工具而不是口头说出数字不能单独发送#或*必须附在非空数字序列末尾推荐在数字序列后追加#来跳过 IVR 的等待期IVR 将其视为立即确认。Agent 完成任务后调用record_task_result_and_hang_up工具它记录结果并以context.session.shutdown(drainTrue)挂断。提示词明确要求只在任务完成且 IVR 已处理结果后调用该工具。对端的 Mock Bank 则用livekit.agents.beta.workflows.dtmf_inputs中的GetDtmfTask接收键音见 ivr_system_agent.py先收 8 位客户 ID、再收 4 位 PIN 完成认证然后进入主菜单循环1 存款账户、2 信用卡、3 贷款、4 奖励、5 切换客户无效选择会播报 I did not catch that selection. Lets try again. 并重问。data.json 提供两个演示客户10000001/0000Jordan Carter与20000002/1111Riley Martinez。验证运行结果README 描述的成功路径是交互持续进行直到 Navigator 取到信息或完成任务然后挂断并记录结果。可核对的观测点有Dialer 终端dial_bank_agent.py会依次记录Creating dispatch for agent ... in room dtmf-agent-example、Created dispatch: ...、Dialing **** (号码仅保留后 4 位掩码显示)、Created SIP participant: ...创建 SIP participant 失败时会记录Error creating SIP participant: ...这是最直接的失败信号Navigator 终端任务结果通过record_task_result_and_hang_up以 {content}格式输出到phone-tree-agentlogger随后会话结束说明 Agent 已按提示词要求完成任务并挂断Mock Bank 侧认证、菜单选择等操作会写入SessionState.audit_log如auth_success:10000001、deposit:balances会话结束时有Usage summary: ...日志。换一条菜单路径再测README 给出的三个可测试场景只需要改dial_bank_agent.py的--request查支票账户Summarize jordan carter checking account贷款情况What are riley martinez loan obligations对应data.json中 Riley Martinez 的 20000002/1111信用卡奖励Give me the platinum travel rewards card details for jordan carterNavigator 会把这些自然语言请求解释为菜单导航动作。改造成真实场景README 给出的改造路径是修改ivr_navigator_agent.py更新系统提示词以描述新的角色和目标send_dtmf_events工具是 Agent 与世界交互的主要方式。若 mock 银行数据不符合测试需要可以编辑data.jsonREADME 将其列为可定制项。限制方面需要明确本示例依赖 SIP trunk 完成外呼--phone必须能路由到你的 Mock BankMock Bank 只是测试替身真实部署中它是某个实际电话号码而 Navigator 的提示词银行场景的角色、#确认技巧等需要按目标 IVR 重新编写。更多示例的运行方式与 Inference 模型配置说明见 examples/README.md。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考