debug-bolna-calls

调试 Bolna 通话

Bolna 语音 Agent 的症状排查手册。大多数问题都符合几种常见模式；下表将症状对应到需要更改的具体字段，以及用于验证修复效果的 API 调用。

30 秒内完成初步排查

向用户询问（或从日志中获取）：

项目	原因
execution_id	最有用的信息——其他所有诊断都由此展开。
agent_id	用于并排检查 Agent 配置。
batch_id（如适用）	批次上下文会影响重试和并发。
接收方 / 发送方电话号码	检查 E.164 格式问题和运营商覆盖范围。
大致通话时间	与速率限制 / 服务中断时段交叉核对。
观察到的症状	用一句话说明。“Agent 响应前会沉默 4 秒。”

然后获取两个执行视图：

# Full execution: status, costs, transcript, latency_data, telephony_data, extracted_data
curl "https://api.bolna.ai/executions/$EXECUTION_ID" \
  -H "Authorization: Bearer $BOLNA_API_KEY"

# Raw logs: every prompt/request/response, including LLM reasoning_content when available
curl "https://api.bolna.ai/executions/$EXECUTION_ID/log" \
  -H "Authorization: Bearer $BOLNA_API_KEY"

执行负载包含 latency_data，这是诊断“通话为什么这么慢”的事实来源。参见 references/latency-metrics.md。

症状 → 修复方法

“Agent 响应前沉默很久”

查看 GET /executions/{id} 中的 latency_data：

延迟组件	修复方法
每个序列的 transcriber.turns[].turn_latency[].audio_to_text_latency > 100ms	更换转写服务提供商；检查音频质量；排查到 Deepgram / Sarvam 的网络问题。
llm.turns[].time_to_first_token > 1000ms	更换大模型（低延迟场景可用 Azure GPT-4.1-mini）；缩短提示词；检查服务提供商的运行状况。
synthesizer.turns[].time_to_first_token > 500ms	更换 TTS（ElevenLabs turbo_v2_5、Cartesia）；选择更轻量的语音；检查服务提供商负载。
transcriber.time_to_connect、llm.time_to_connect、synthesizer.time_to_connect 较高	冷启动。每次通话的第一轮都较慢；如果多轮持续出现此问题，请升级给服务提供商处理。

还可以调整 Agent 端的设置：

• task_config.incremental_delay — Agent 开始说话前的缓冲时间。默认值为 400ms。调低可加快响应速度（但部分转录结果可能导致 Agent 打断自己）。音频噪声较大时可调高。
• transcriber.endpointing — STT 在静音多久后才将用户发言判定为“结束”。默认值为 250ms。快速对话时可调低；面对思考时间较长的用户或较长停顿时可调高。

“我还在说话，Agent 就打断我”

task_config.number_of_words_for_interruption 设置过低（默认值为 2）。

• 调至 4 或 5，实现“让用户说完一句话”的效果。
• 对会在句中停顿的用户，可结合设置 transcriber.endpointing: 500-700。

“Agent 从不打断我——一直压着我说”

与上述情况相反。调低 number_of_words_for_interruption（响应非常积极的 Agent 可尝试设为 1）。还要检查转写服务是否确实捕捉到了用户的发言——每次用户发言后，latency_data.transcriber.turns[] 都应增长。如果缺少转录文本，Agent 就根本听不到用户的打断。

“用户静音后，通话就挂断了”

task_config.hangup_after_silence（默认值为 10 秒）。对于开口前需要思考的来电者，可调高；对于 IVR 式流程，可调低。

对于图 Agent，建议在单个节点上使用 repeat_after_silence_seconds，并在 _silence_repeats 上添加表达式边——这样可以平稳升级处理，而不是直接挂断。

“Agent 说完后，通话很快就结束了”

可能由以下设置导致：

• task_config.hangup_after_LLMCall: true — Agent 首次响应后立即结束通话。仅用于单次播报。
• task_config.call_terminate — 通话时长上限，单位为秒。默认值为 300（5 分钟）。较长场景可调高。
• 系统提示词中由大模型提示挂断（“如果用户说再见，就挂断”）。如果触发过于频繁，请放宽触发条件。

“Agent 听起来像机器人／说话生硬／旁白太多”

• 在系统提示词中限制回复长度："Never speak more than two sentences per turn."
• 选择更高品质的语音：ElevenLabs turbo_v2_5 / multilingual_v2；印度语言可使用 Sarvam。
• 仅在适合的情况下启用附和（task_config.backchanneling: true）——在用户说话的间隙回应“嗯”。这非常适合客服通话，但在 IVR 式流程中会显得奇怪。
• 将 temperature 降至 0.2-0.3——长尾创造性不值得以不稳定为代价。
• 对于印度语言：使用母语文字（天城文）编写提示词，而不是用英语标注发音。请参阅 https://raw.githubusercontent.com/bolna-ai/skills/main/references/prompting-tips.md。

“通话一直停留在 queued 状态”

检查项	原因
Agent 并发限制（GET /user/me）	已达到上限；排队的通话要等当前通话结束。
calling_guardrails.call_start_hour / call_end_hour	通话时间不在允许时段内——Bolna 会重新安排。
scheduled_at 设置为未来时间	通话正在等待预定时间。
钱包余额	如果 status 变为 balance-low，说明额度已用完。
重试配置	失败的通话可能会按重试间隔排队——请检查 retry_intervals_minutes。

状态：balance-low

为账户钱包充值。在此之前，每个 POST /call 请求都会进入此状态。使用以下命令验证：

curl https://api.bolna.ai/user/me -H "Authorization: Bearer $BOLNA_API_KEY"

检查 wallet。

状态：failed / error

检查执行记录中的 error_message。常见原因：

error_message 提示	解决方法
from_phone_number not owned by account	使用实际归你所有的号码；通过 GET /phone-numbers/all 检查。
invalid phone number format	仅支持 E.164 格式。使用 +91...，不要使用 91... 或 091...。
agent restricted due to disallowed content	Bolna 的内容检查器标记了提示词。检查并重新保存 Agent。
concurrency limit reached	等待，或升级账户。
provider auth failed	重新添加提供商凭据（Twilio/Plivo 等）。

“无人接听／占线”

这些是正常结果，不代表 Agent 出错。使用 POST /call 上的 retry_config 自动重试：

{
  "retry_config": {
    "enabled": true,
    "max_retries": 2,
    "retry_on_statuses": ["no-answer", "busy"],
    "retry_intervals_minutes": [30, 60]
  }
}

除非已确认原因是暂时性的，否则不要将 failed / error 加入 retry_on_statuses。

“Webhook 始终不触发”／“Webhook 已触发，但我的服务器没有收到”

按顺序检查以下各项：

1. 是否已在 Agent 上设置 agent_config.webhook_url？（使用 GET /v2/agent/{id} 检查。）
2. URL 是否可通过 HTTPS 从公网访问？使用 curl -X POST https://your-server/webhook -d '{}' 测试。
3. 服务器是否向 Bolna 的 POST 请求返回 2xx？非 2xx 响应会触发 Bolna 重试，但最终会停止。
4. 防火墙是否将 Bolna 的源 IP 13.203.39.153 加入白名单？
5. 是否按 execution_id + status 去重？Bolna 会在每次状态转换时发送 POST——每次通话有多个事件是正常的。
6. 接收端是否会超时（约 10 秒）？如果会，请立即返回 2xx，并异步处理。

有关数据结构，请参阅 https://raw.githubusercontent.com/bolna-ai/skills/main/references/execution-payload.md。

“来电者上下文（{customer_name} 等）有误”

来源	检查项
外呼 POST /call	user_data 的键与提示词变量完全匹配（区分大小写）。
批量 CSV	列名 = 变量名。使用 customer_name，而不是 Customer Name 或 customer-name。
入呼 ingest_source_config（API）	端点返回匹配的 JSON 键。使用 Bolna 发送的确切 contact_number 进行测试。
入呼 CSV / Google Sheet	存在 contact_number 列，且其值为 E.164 格式。

“转录内容有误／Agent 的句子只有半截”

在 Agent 的 Analytics Tab（测试版）中启用精准转录生成。用户打断 Agent 时，Bolna 会从转录中删去 Agent 尚未说出的内容，使转录反映实际听到的内容。

未启用时，转录显示 LLM 打算说什么；启用后，则显示来电者实际听到的内容。

SIP 中继：“通话已接通，但没有音频”

典型的 SRTP 不匹配。请参阅 setup-sip-trunk/SKILL.md § 故障排除。快速修复方法：

• 测试时设置 media_encryption: "no"。
• 设置 media_encryption_optimistic: true，以便在必要时自动回退到明文 RTP。
• 如果打算继续使用 sdes，请确认运营商已启用 SRTP。

SIP 中继：“出站 INVITE 静默失败”

可能是大型 SIP 标头导致 UDP 分片。请切换到 transport: "transport-tcp"。

批次：“大量通话失败／未发起”

问题	查看位置
CSV 列名错误	收件人列必须是 contact_number。其他列会成为变量。
valid_contacts < total_contacts	部分行的电话号码无效 — 请检查 GET /batches/{id} 摘要。
单通电话重试配置导致并发问题	每次重试都会占用一个并发名额。如果批次与重试时间重叠，可能导致任务停滞。
服务提供商级拒绝	GET /batches/{id}/executions → 查看每通电话的 status 和 error_message。

印度号码：140／160 系列号码遭拒

合规问题：DLT 注册、标头注册或模板注册尚未完成。请参阅 https://raw.githubusercontent.com/bolna-ai/skills/main/references/india-compliance.md。这不是 Bolna API 故障 — 运营商会在 Bolna 发起呼叫之前拒绝请求。

检查原始日志

GET /executions/{id}/log 会按顺序返回每条提示词、请求和响应。每条记录都包含：

字段	含义
component	transcriber、llm、synthesizer、tool、system
type	request、response、event
data	实际负载（对于 LLM 响应，这是助手文本）
reasoning_content	如果模型会公开推理内容，则为 LLM 推理摘要（GPT-5 系列、启用扩展思考的 Claude）
timestamp	触发时间

实用方法：

• 查找错误的 Agent 回复 → 在时间戳附近搜索 component: "llm" 和 type: "response"。
• 工具未调用 → 在 component: "llm" 条目中搜索工具名称；如果不存在，说明 LLM 未选择该工具。
• 工具调用时参数错误 → component: "tool" 和 type: "request" 会显示实际替换后的负载。

原始日志是 Bolna 提供的最强大调试工具。假定是平台错误之前，请先查看原始日志。

深入了解

文件	内容
references/latency-metrics.md	说明 latency_data 字段及其阈值。
references/symptoms.md	扩展的症状 → 原因 → 修复方法对照表（涵盖约 30 种模式）。
references/raw-logs.md	如何读取 /executions/{id}/log：各组件记录的内容及 reasoning_content。
scripts/diagnose_execution.py	获取 GET /executions/{id} 和原始日志，并输出单页诊断结果。

另请参阅

• get-executions — /executions/{id} 和 /executions/{id}/log 的完整参考。
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/call-statuses.md — 各状态的含义。
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/hangup-codes.md — 解读 hangup_by、hangup_code 和 hangup_reason。
• setup-tools/references/tool-schemas.md — 调试工具触发问题。
• bolna-graph-agents/references/debugging.md — 专门针对图 Agent 的路由日志调试。