adk-debugger

ADK デバッガースキル

ADK のデバッグとは？

すべての ADK エージェントは、会話の各ターン、ツール呼び出し、LLM の推論ステップ、エラーなどの動作をトレースとログとして記録します。これらは、エージェントが何をしたのか、そしてその理由を理解するための信頼できる情報源です。

ADK CLI は、デバッグに必要なツールを提供します。ほとんどの診断コマンドは --format json をサポートしています。プログラムで出力を扱う場合に使用してください。例外は adk dev です。このコマンドには --format フラグがなく、構造化された NDJSON 出力には adk dev --non-interactive を使用します。

このスキルを使用する場面

開発者から次のような質問を受けたときに、このスキルを使用してください。

• ボットが動作しない — 応答しない、誤った応答をする、予期しない動作をする
• ツールの問題 — 誤ったツールが呼び出される、ツールエラー、パラメーターの幻覚
• ワークフローの問題 — ワークフローが停止する、ステップが実行されない、状態の問題
• トレース／ログの読み取り — デバッグ出力のクエリ方法、フィルタリング方法、解釈方法
• LLM の不適切な動作 — 幻覚、拒否、ループ、抽出の精度が低い
• ビルド／デプロイの失敗 — 検証エラー、スキーマの不一致
• 設定の問題 — agent.json と agent.local.json の違い、インテグレーションの設定
• 修正後の検証 — 修正が機能したことの確認、回帰評価の作成

質問の例：

• 「ボットが応答しません」
• 「誤ったツールが呼び出されました」
• 「ワークフローが停止しています」
• 「トレースを読むにはどうすればよいですか？」
• 「ログを確認するにはどうすればよいですか？」
• 「LLM が幻覚を起こしています」
• 「最後に変更してから何かが壊れました」
• 「デプロイに失敗しました」
• 「adk check でエラーが見つかりました」
• 「このトレースを要約してください」
• 「トレース X で何が起きましたか？」
• 「この会話ターンの概要を教えてください」
• 「このトレースでボットが X をしたのはなぜですか？」
• 「何が起きたのか順を追って説明してください」
• 「これをデバッグするにはどうすればよいですか？」
• 「この会話を要約してください」
• 「会話 X で何が起きたのか説明してください」
• 「ボットがそのように応答したのはなぜですか？」
• 「この会話を順を追って説明してください」
• 「この会話で何が問題だったのですか？」

利用可能なドキュメント

ファイル	内容
references/traces-and-logs.md	CLI デバッグツール、ログのクエリ、トレースの構造、スパンの種類、onTrace フック、adk chat を使った再現
references/common-failures.md	実行時の失敗パターン — 検証、ボットが応答しない、ツールエラー、ワークフローの停止、インテグレーションの失敗、ビルドエラー、設定の混乱
references/llm-debugging.md	LLM の動作に関する問題 — 誤ったツール、パラメーターの幻覚、拒否、トークン制限、ループ、モデルの推論の読み取り
references/debug-workflow.md	体系的な 8 ステップのデバッグループ：検証 → 再現 → ログ → トレース → 分類 → 修正 → 検証 → 防止
references/trace-summarization.md	自由形式の自然言語による説明としてトレースを取得、追跡、要約する方法 — 状況に応じて詳細さを調整
references/conversation-analysis.md	会話全体を要約して説明する方法 — 会話の一覧表示、時系列分析、トレースとの関連付け、よくあるパターン

回答方法

1. 「トレース／ログを読むにはどうすればよいですか？」 → CLI コマンドとトレース構造については、traces-and-logs.md を読んでください
2. 既知のパターンで問題が発生している → 該当する失敗パターンについては、common-failures.md を読んでください
3. LLM の動作に問題がある → 該当する動作の問題については、llm-debugging.md を読んでください
4. 体系的な調査が必要 → debug-workflow.md を読み、8 ステップのループに従ってください
5. 「このトレースを要約して」／「何が起きましたか？」 → トレースの取得、確認、説明の方法については、trace-summarization.md を読んでください
6. 「この会話を要約して」／「何が起きたか説明して」 → 複数ターンの会話の要約と説明については、conversation-analysis.md を読んでください
7. 修正後に再発を防ぎたい → eval の作成方法について、adk-evals スキルを参照してください

---

クイックリファレンス

デバッグループ

symptom → validate (adk check) → reproduce (adk chat) → logs (adk logs) → traces (adk traces) → root cause → fix → verify

CLI コマンド（構造化出力を優先）

adk check --format json                         # offline validation
adk logs error --format json                     # recent errors
adk logs --follow --format json                  # stream live
adk traces --format json                         # recent traces
adk traces conversation=<id> --format json       # specific conversation
adk chat --single "msg" --format json            # test message
adk dev --non-interactive                        # structured NDJSON dev output (no TUI)
adk conversations --format json                  # list recent conversations
adk conversations show <id> --format json        # conversation timeline
adk conversations show <id> --include-llm --format json  # timeline with LLM reasoning

スパンの種類

種類	表示内容
think	LLM の推論 — アクションを選択した理由
tool_call	ツールの呼び出し — 名前、入力、出力、成功／エラー
code_execution_exception	実行時エラー — メッセージとスタックトレース
end	会話ターンの完了

---

前提条件の確認

デバッグの前に、以下を確認してください。

• プロジェクトは有効ですか？ adk check --format json を実行し、報告された問題があれば先に修正してください
• 開発サーバーは実行中ですか？ adk dev（または構造化された NDJSON 出力を得るには adk dev --non-interactive）
• ボットはリンクされていますか？ botId と workspaceId を含む agent.json が存在することを確認してください（adk link によって作成されます）
• 開発用ボットは作成されていますか？ agent.local.json に devId があることを確認してください（最初の adk dev の実行時に自動設定されます）
• インテグレーションは設定されていますか？ localhost:3001 の Dev Console で、未設定のインテグレーションを確認してください

---

重要なパターン

✅ 実行時の問題をデバッグする前に adk check を実行する

# CORRECT — catch config/schema problems offline first
adk check --format json
# Then debug runtime issues

❌ オフライン検証を省略する

# WRONG — jumping straight to runtime debugging wastes time on config issues
adk traces --format json  # might be chasing a config problem

---

✅ すべての CLI コマンドで --format json を使用する

# CORRECT — structured output for reliable parsing
adk logs error --format json
adk traces --format json
adk chat --single "test" --format json

❌ 人間が読みやすい形式の出力を解析する

# WRONG — human-readable format is for display, not parsing
adk logs error
adk traces

---

✅ エラーを絞り込むには adk logs error を使用する

# CORRECT — focused error scan
adk logs error --format json
adk logs warning since=1h --format json

❌ すべての出力をスクロールして確認する

# WRONG — too much noise, easy to miss the actual error
adk logs --format json  # 50 entries of everything

---

✅ プログラムで監視するには onTrace フックを使用する

// CORRECT — structured, automated trace analysis
hooks: {
  onTrace: ({ trace }) => {
    if (trace.type === 'tool_call' && !trace.success) {
      console.error(`[TOOL ERROR] ${trace.tool_name}`, trace.error)
    }
  }
}

❌ コンソール出力だけを確認する

// WRONG — console.log in handlers misses the structured trace data
handler: async (input) => {
  console.log('tool called') // not useful for debugging
}

---

✅ 修正後に回帰 eval を作成する

// CORRECT — prevents the bug from coming back
export default new Eval({
  name: 'fix-order-lookup',
  type: 'regression',
  conversation: [{ user: 'Look up order 123', assert: { tools: [{ called: 'lookupOrder' }] } }],
})

❌ 修正してそのまま先に進む

// WRONG — the same bug will return and you'll debug it again

---

質問の例

基本：

• 「ボットが応答しません。原因を調べるにはどうすればよいですか？」
• 「ADK プロジェクトのエラーを確認するにはどうすればよいですか？」
• 「agent.json と agent.local.json の違いは何ですか？」

中級：

• 「ボットが lookupTicket ではなく createTicket を呼び出しました。修正するにはどうすればよいですか？」
• 「ワークフローは開始しますが、2 つ目のステップが実行されません」
• 「LLM が判断したときに何を考えていたか確認するにはどうすればよいですか？」
• 「インテグレーションのアクションが認証エラーで失敗します」

上級：

• 「自動エラー検出のために onTrace フックを設定するにはどうすればよいですか？」
• 「モデルが同じツール呼び出しを繰り返します。ガードレールを追加するにはどうすればよいですか？」
• 「タイミングメトリクスを使ってツール呼び出しのパフォーマンスを監視するにはどうすればよいですか？」
• 「複数ステップのワークフローの失敗を体系的にデバッグするにはどうすればよいですか？」

---

回答形式

質問に合わせて詳しさを調整してください。

簡単な質問（「ログを確認するには？」「トレーススパンとは？」）

直接回答してください。1 文と CLI コマンドまたは概念で答えます。情報を求める質問に対して、デバッグループ全体を実行する必要はありません。

アクティブなデバッグ（「ボットが壊れた」「X が動かない」）

一連の手順を最後まで実施します。

1. 前提条件を確認する — 開発サーバー、設定ファイル、プロジェクトの検証を確認します
2. adk check --format json から始める — オフラインの問題を除外します
3. 再現する — adk chat --single "msg" --format json を使って、クリーンな再現ケースを作成します
4. 証拠を確認する — すばやく確認するには adk logs error --format json、詳細を確認するには adk traces --format json を使います
5. 根本原因を特定する — 該当するスパン、ログエントリ、または設定の問題を示します
6. 対象を絞った修正を提案する — 該当する障害パターンのドキュメントを参照します
7. 検証する — 再現手順を再実行し、出力に問題がないことを確認します
8. リグレッション評価を作成する — adk-evals スキルを読み込み、評価ファイルを自動生成します