AIエージェントにコードを書かせたのに、なぜその結果になったのか分からない。VS Code 1.116で追加された「Agent Debug Logs」を使えば、プロンプトの裏で何が起きているかを時系列で追跡できます。
この記事でわかること
- Agent Debug Logsの概要と開き方
- 3つのビュー（ログ・フローチャート・サマリー）の使い分け
- 過去セッションの振り返りとエクスポート機能
- /troubleshootコマンドによるセルフ診断
Agent Debug Logsとは
Agent Debug Logsは、VS Codeのチャットセッション中に発生したイベントを時系列で記録・表示するパネルです。現在プレビュー機能として提供されています。
GitHub Copilotのエージェントモードでは、ユーザーのプロンプトに応じてファイル読み込み、ツール呼び出し、LLMへのリクエストなど複数の処理が自動で走ります。従来はこれらの内部処理がブラックボックスでした。Agent Debug Logsを開くと、各処理がいつ・どの順序で実行されたかをひと目で確認できます。
パネルを開くには、チャットビューの「…」メニューから「Show Agent Debug Logs」を選択します。コマンドパレットから「Developer: Open Agent Debug Logs」を実行しても同じです。利用にはあらかじめ設定で github.copilot.chat.agentDebugLog.fileLogging.enabled を有効にしておく必要があります。
3つのビューで異なる粒度の情報を得る
Agent Debug Logsパネルには3つのビューがあり、目的に応じて切り替えられます。
Logs（ログビュー） は、セッション中に発生したイベントの時系列リストです。タイムスタンプ、イベントタイプ、概要が表示され、各イベントを展開するとLLMリクエストのシステムプロンプト全文やツール呼び出しの入出力を確認できます。フィルター機能で特定のイベントタイプだけに絞り込むことも可能です。フラットリスト表示とサブエージェント単位のツリー表示を切り替えられるため、複雑なエージェント構成でも追いやすくなっています。
Agent Flow Chart（フローチャートビュー） は、エージェントとサブエージェント間のやり取りをフローチャートで可視化します。カスタムエージェントやMCPサーバーを組み合わせたワークフローで、どのエージェントがどの順序で呼ばれたかを視覚的に把握するのに向いています。ノードを選択すると、そのイベントの詳細を確認できます。
Summary（サマリービュー） は、セッション全体の集計情報を表示します。ツール呼び出しの合計回数、トークン使用量、エラー数、所要時間などが一覧できます。トークンの消費状況を把握したいときに最初に確認するビューです。
過去セッションの振り返りとエクスポート
VS Code 1.116で追加された重要な改善が、セッションログの永続化です。以前はリアルタイムのセッションしか確認できませんでしたが、現在はログがローカルディスクに保存され、過去のセッションも振り返れるようになりました。
「昨日のエージェント実行で、なぜあのファイルが変更されたのか」といった疑問に、後からでも答えを探せます。
エクスポート機能も備わっています。Agent Debug Logsパネル右上のエクスポートアイコンを押すと、セッションデータをOpen Telemetry JSON（OTLP形式）で書き出せます。チームメンバーとの共有やオフライン分析に使えます。逆にインポートも可能で、他の人が書き出したセッションファイルをパネル上で閲覧できます。50MBを超えるファイルは警告が出るため、長時間セッションは適宜分割してください。
/troubleshootコマンドで素早くセルフ診断
Agent Debug Logsパネルを開かなくても、チャットから直接セッションの診断ができます。チャット入力欄で /troubleshoot と入力し、続けて質問を書くだけです。
例えば /troubleshoot how many tokens did you use in #session と入力すると、現在のセッションのトークン使用量をAIが回答します。/troubleshoot list all paths you tried to load customizations のように、カスタマイズファイルの読み込み状況を確認する使い方もあります。
もう一つの方法として、Agent Logsビュー右上のスパークルアイコンを押すと、デバッグイベントのスナップショットがチャットにコンテキストとして添付されます。そのまま「このセッションでエラーは発生した？」のように質問すれば、AIがログを分析して答えてくれます。
Chat Debug Viewとの違い
VS Codeにはもう一つ「Chat Debug View」というデバッグ機能があります。Agent Debug Logsがセッション全体のイベントフローを追うのに対し、Chat Debug Viewは個々のLLMリクエストとレスポンスの生データを表示するツールです。
Chat Debug Viewでは、システムプロンプト、ユーザープロンプト、コンテキスト、ツールレスポンスの各セクションを展開して中身を確認できます。「送ったはずのファイルがコンテキストに含まれていない」「MCPツールの入出力が想定と違う」といった細かい問題の切り分けに適しています。
使い分けの目安は明確です。セッション全体の流れを把握したいならAgent Debug Logs、特定のリクエストの中身を詳しく見たいならChat Debug Viewです。
よくあるトラブルと確認手順
Agent Debug Logsが役立つ場面をいくつか紹介します。
ワークスペースのファイルをAIが参照してくれない場合は、Agent LogsでDiscoveryイベントを確認します。ワークスペースのインデックスが完了しているか、対象ファイルがコンテキストに含まれているかを追えます。含まれていなければ、チャットで #file や #codebase を明示的に指定してみてください。
MCPツールが呼ばれない場合は、Agent LogsのTool callsフィルターでツールの呼び出し状況を確認します。Chat Debug Viewのシステムプロンプトセクションで、利用可能なツール一覧にそのツールが含まれているかも確認ポイントです。
AIの応答が途中で切れる場合は、LLM requestsイベントでトークン使用量を確認します。コンテキストウィンドウが一杯になっている可能性があるため、新しいチャットセッションを開始すると解消することがあります。
エージェント開発のデバッグ基盤として
VS Codeはバージョン1.115でエージェント専用アプリ「VS Code Agents」のプレビューを追加し、1.116ではGitHub Copilotを拡張機能なしで利用可能にしました。エージェントの活用範囲が広がるほど、「なぜこうなったか」を追える仕組みの価値は高まります。
Agent Debug Logsは、カスタムエージェントやMCPサーバーを開発する人だけでなく、Copilotの挙動を理解したいすべてのVS Codeユーザーに有用な機能です。プロンプトを投げて結果だけ見る使い方から、内部の動きを把握して精度を上げる使い方へ。まずはチャットビューの「…」メニューからパネルを開いてみてください。