debug-bolna-calls

Bolna の通話をデバッグする

Bolna 音声エージェントの症状から修正方法を特定するための手順書です。問題のほとんどはいくつかのよく知られたパターンに当てはまります。以下の表では、症状に応じて変更すべき正確なフィールドと、修正を確認する API 呼び出しを示します。

30 秒でトリアージする

ユーザーに次の情報を尋ねるか、ログから取得してください。

項目	理由
execution_id	最も役立つ情報です。ほかのすべての診断はこれを起点に行います。
agent_id	エージェントの設定を並べて確認するためです。
batch_id（該当する場合）	バッチの状況は再試行と並行処理に影響します。
発信先／発信元の電話番号	E.164 の問題や通信事業者のカバレッジを確認するためです。
おおよその通話時刻	レート制限や障害の発生時間帯と照合するためです。
観測された症状	1 文で記述します。「エージェントが応答するまで 4 秒間無音になる。」

次に、2 つの実行ビューを取得します。

# 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 を参照してください。

症状 → 修正方法

「エージェントが応答するまで長い間無音になる」

GET /executions/{id} の latency_data を確認します。

遅いコンポーネント	修正方法
transcriber.turns[].turn_latency[].audio_to_text_latency > 100ms（シーケンスあたり）	文字起こしプロバイダーを切り替えます。音声品質を確認し、Deepgram／Sarvam へのネットワークの問題を切り分けます。
llm.turns[].time_to_first_token > 1000ms	LLM を切り替えます（低レイテンシには 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 が高い	コールドスタートです。通話ごとの最初のターンは遅くなります。複数のターンで慢性的に発生する場合は、プロバイダーにエスカレーションしてください。

エージェント側の設定も調整します。

• task_config.incremental_delay — エージェントが発話を開始するまでのバッファー時間です。デフォルトは 400ms です。応答を速めるには値を小さくします（ただし、部分的な文字起こしに反応して自分の発話を遮ってしまう場合があります）。音声にノイズが多い場合は値を大きくします。
• transcriber.endpointing — STT がユーザーのターンを「確定」するまで、無音をどれだけ待つかを指定します。デフォルトは 250ms です。テンポの速い会話では値を小さくし、考えながら話すユーザーや長い間を置くユーザーには値を大きくします。

「まだ話しているのにエージェントに割り込まれる」

task_config.number_of_words_for_interruption の値が小さすぎます（デフォルトは 2 です）。

• 「ユーザーが文を言い終えるまで待つ」には、値を 4 または 5 に上げます。
• 文の途中で間を置くユーザーには、transcriber.endpointing: 500-700 と組み合わせます。

「エージェントがまったく割り込まず、こちらの発話にかぶせて話し続ける」

上記とは反対の状態です。number_of_words_for_interruption の値を下げます（応答性を非常に高くする場合は 1 を試します）。また、文字起こしプロバイダーが実際にユーザーの発話をキャプチャしているか確認します。ユーザーが発話するたびに latency_data.transcriber.turns[] が増えているはずです。文字起こしが欠落している場合、エージェントは文字どおり割り込みを聞き取れません。

「ユーザー側が無音になった後、通話が切断される」

task_config.hangup_after_silence の設定を確認します（デフォルトは 10 秒です）。話す前に考える発信者には値を大きくし、IVR 形式のフローでは値を小さくします。

グラフエージェントでは、個々のノードに repeat_after_silence_seconds を設定し、_silence_repeats に式エッジを設定する方法を推奨します。通話を切断する代わりに、適切にエスカレーションできます。

「エージェントが話した後、通話が早く終了する」

考えられる設定は 2 つあります。

• task_config.hangup_after_LLMCall: true — エージェントの最初の応答の直後に通話を終了します。1 回限りのアナウンスにのみ使用してください。
• task_config.call_terminate — 秒単位の通話時間上限です。デフォルトは 300（5 分）です。より長い用途では値を大きくします。
• システムプロンプトで LLM に切断を指示している（「ユーザーがさようならと言ったら、通話を切断する」）。切断が早すぎる場合は、条件を緩めます。

「エージェントの応答が機械的／ぎこちない／説明が長すぎる」

• システムプロンプトで応答の長さを制限します："Never speak more than two sentences per turn."
• より高品質な音声を選択します：ElevenLabs turbo_v2_5 / multilingual_v2、インドの言語にはSarvamを使用します。
• 適している場合にのみ、相づちを有効にします（task_config.backchanneling: true）。ユーザーの発話の合間に「mhm」と返します。サポートへの通話には最適ですが、IVR形式のフローでは不自然です。
• temperature を 0.2-0.3 に下げます。創造性を高める利点より、一貫性が損なわれる欠点のほうが大きいです。
• インドの言語では、プロンプトを発音を英字で表記したものではなく、現地の文字（デーヴァナーガリー文字）で記述します。https://raw.githubusercontent.com/bolna-ai/skills/main/references/prompting-tips.md を参照してください。

「通話がいつまでも queued のまま」

確認項目	理由
エージェントの同時実行数の上限（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... や 091... ではなく、+91... のように指定してください。
agent restricted due to disallowed content	Bolnaのコンテンツチェッカーがプロンプトを検出しました。エージェントを確認して保存し直してください。
concurrency limit reached	待つか、アカウントをアップグレードしてください。
provider auth failed	プロバイダーの認証情報を再登録してください（Twilio/Plivoなど）。

「応答なし／話し中」

これらは通常の結果であり、エージェントの失敗ではありません。POST /call の retry_config を使用すると、自動的に再試行できます。

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

原因が一時的なものだと確認できていない限り、retry_on_statuses に failed / error を追加しないでください。

「Webhookが一度も呼び出されない」／「Webhookは呼び出されるが、サーバーが受信しない」

次の順に確認してください。

1. エージェントに 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を送信するため、1回の通話で複数のイベントが発生するのは正常です。
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形式になっていることを確認してください。

「文字起こしが正しくない／エージェントの文が途中で終わっている」

エージェントのAnalytics Tab（ベータ版）で Precise Transcript Generation を有効にしてください。ユーザーがエージェントの発話に割り込むと、Bolnaはエージェントがまだ発話していない部分を文字起こしから削除し、実際に聞こえた内容を反映します。

この機能を無効にすると、文字起こしには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} の概要を確認してください。
1 通話あたりの再試行設定が同時実行数を圧迫している	再試行のたびに同時実行枠を 1 つ使用します。バッチと再試行が重なると、処理が停滞する場合があります。
プロバイダー側で拒否されている	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	発生時刻

便利な確認方法：

• エージェントの誤った応答を見つけるには、タイムスタンプ付近にある component: "llm" と type: "response" を検索します。
• ツールが呼び出されていない場合は、component: "llm" のエントリでツール名を grep します。見つからない場合、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} と生ログを取得し、1 ページの診断結果を出力します。

関連項目

• 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 — グラフエージェントに特化したルーティングログのデバッグ。