adk-debug

ADK エージェントのデバッグ

エントリーポイントは 2 つあります。基本的には adk run を使ってください。単一のプロセスで実行でき、サーバーは不要で、grep や python3 にそのままパイプできる --jsonl 出力を利用できます。ブラウザー UI、クリックして操作できる永続セッション、または LLM リクエストの内容を正確に確認できるトレースエンドポイントが必要な場合は、adk web に切り替えてください。

最初に行うこと

1. ヘッドレスで再現します：adk run --jsonl {agent_dir} "{query}"。--jsonl を指定しない場合、adk run が出力するのはテキスト部分のみで、ツール呼び出しやツールのエラーは表示されません。
2. ログファイルを読みます。adk run は /tmp/agents_log/agent.latest.log に書き込み、ターミナルには何も出力しません。adk web はその逆です。logs-and-traces.md を参照してください。
3. ソースを読む前に、failure-modes.md で症状と照合してください。報告の大半は、よく知られた少数のパターンに当てはまります。
4. テキストは正しいのにルーティングに問題がある場合は、イベントをダンプし、author、branch、nodeInfo.path、actions を確認してください。event-flow.md を参照してください。
5. モデル自体の動作に問題があった場合は、エージェント定義から推測するのではなく、call_llm スパンからモデルが実際に受け取った内容を確認してください。logs-and-traces.md を参照してください。

リファレンス

• cli-run.md — adk run のフラグ、JSONL イベントの形式、複数ターンの実行とヒューマン・イン・ザ・ループによる再開、終了コード、Python から Runner を実行する方法。
• web-api.md — adk web の起動、HTTP 経由でのセッション一覧表示と読み込み、/run_sse へのテストメッセージの送信。
• logs-and-traces.md — ログレベルと各コマンドのログ出力先、トレースエンドポイント、スパンの属性、プロンプトをスパンに表示するかどうかを制御する環境変数。
• failure-modes.md — ADK 固有の症状と、それぞれの原因および具体的な確認方法。
• event-flow.md — 呼び出しがイベントになる仕組み、コールバックの順序、重要なイベントフィールド、各ステージのソースコード上の場所。

基本ルール

• 作業が終わってもセッションはそのまま残してください。ユーザーが Web UI で開きたい場合があります。また、adk web には削除の取り消し機能がありません。
• 再現用に作成した使い捨てのエージェントは、ユーザーから残すように指示されていない限り削除してください。
• バグが単一のコンポーネント内にある場合は tests/unittests/ のユニットテストを利用し、runner、agent、workflow を連携させた場合にのみ再現する場合は contributing/samples/ のサンプルを利用してください（adk-sample-creator を参照）。