エージェントの作業をデバッグする

エージェントが予期しない動作をした場合、誤ったツールを呼び出した場合、奇妙な応答をした場合、あるいはカスタマイズファイルを無視した場合、その理由を理解する必要があります。VS CodeとGitHub Copilot Chatはオープンソースであり、その透明性はランタイムで何が起きているかまで及びます。本ガイドでは、エージェントデバッグログパネルとチャットデバッグビュー、およびこれらを使用してエージェントの動作を診断する方法について説明します。

エージェントデバッグログパネル

エージェントデバッグログパネルは、主要な診断ツールです。チャットビュー上部のオーバーフローメニューから「Show Agent Debug Logs（エージェントデバッグログを表示）」を選択するか、コマンドパレットから「Developer: Open Agent Debug Panel」を実行して開きます。

パネルはエディタータブとして開きます。上部のブレッドクラム（パンくずリスト）には、現在調査中のセッションが表示されます。

ログビュー

ログビューには、セッション中に発生したすべてのイベントが時系列で表示されます。各行には以下が含まれます。

• タイムスタンプ。
• イベント名。
• 詳細カラムの要約。

各リクエストの開始時に、一連のカスタマイズイベントが表示されます。

• Load Instructions（指示の読み込み） - どの指示ファイルが見つかり、適用されたか
• Load Agents（エージェントの読み込み） - どのエージェント設定が読み込まれたか
• Load Hooks（フックの読み込み） - どのフック定義が見つかったか
• Load Skills（スキルの読み込み） - どのスキルが見つかり、読み込まれたか

これらは、エージェントが動作を開始する前に何を読み込んだかを正確に示します。その後のセッションの進行に合わせて、ツール呼び出しとLLMリクエストが表示されます。

上部のトグルを使用して、リストビュー（フラット、時系列）とツリービュー（サブエージェントごとにグループ化）を切り替えます。フィルターバーを使用して、特定のイベントタイプ（例：ツール呼び出しのみを表示したい場合など）に絞り込むことができます。

イベント詳細の展開

ログビューで行を選択すると、右側に詳細パネルが開きます。

イベントタイプに応じて、パネルには以下が表示されます。

• Load Skills - 検索された全パスのリスト（順序通り）と、見つかって読み込まれたスキル
• Tool call - 正確な入力ペイロードと返された出力
• LLM Request - モデルに送信された完全なシステムプロンプト

ここが診断価値の大部分を占めます。カスタマイズが反映されない場合、読み込みの詳細を確認することで、正確にどのパスが検索され、ファイルが見つかったかどうかを確認できます。

サマリービュー

ブレッドクラムのセッション名を選択して、サマリービューに移動します。ここにはセッションの集計統計が表示されます。

• モデルのターン数。
• ツール呼び出し数。
• 合計トークン数。
• エラー数。
• イベント合計数。

サマリービューからは、エージェントフローチャートも開くことができます。

エージェントフローチャート

フローチャートは、イベントの順序をナビゲート可能な図として可視化します。サブエージェントがどのように呼び出され、作業がどのように構成されたかを理解するのに役立ちます。

チャットデバッグビュー

エージェントデバッグログパネルがイベントのシーケンスを表示するのに対し、チャットデバッグビューは各LLMリクエストとレスポンスの生のコンテンツを表示します。

チャットビューのオーバーフローメニューから「Show Chat Debug View（チャットデバッグビューを表示）」を選択して開きます。

サイドバーには、セッション中に行われたすべてのAIリクエストがエージェントごとにグループ化されて表示されます。リクエストを選択して以下を調査できます。

• 完全なシステムプロンプト。
• ユーザープロンプト。
• 添付されたすべてのコンテキスト。
• 完全なツール呼び出しペイロード。

これは、モデルに送信されたデータとモデルから返されたデータの正確な記録です。「エージェントはその関数を書くときに正しいファイル内容を持っていたか？」「システムプロンプトは期待通りに整形されていたか？」といった疑問に答えるのに役立ちます。

#debugEventsSnapshot と /troubleshoot

セッションのデバッグパネルを表示しているとき、それらのイベントのスナップショットをチャットメッセージに直接添付することができます。

#debugEventsSnapshot

チャット入力で #debugEventsSnapshot と入力すると、現在のデバッグイベントのスナップショットをコンテキストとして添付できます。

例

#debugEventsSnapshot how many tokens did this session use?

#debugEventsSnapshot which customization files were loaded?

#debugEventsSnapshot why did it call that tool twice?

エージェントはスナップショットを読み取り、一般的な知識ではなく、セッションの実際のイベントデータに基づいて回答します。

エージェントデバッグパネルの右上にあるキラキラアイコンをクリックして、スナップショットをチャットコンポーザーに自動的に添付することもできます。

/troubleshoot

/troubleshoot は、詳細なログ分析のための専用スラッシュコマンドです。

例

/troubleshoot list all paths you tried to load customizations from

/troubleshoot the agent made an unexpected file edit in the last response, why?

確認すべきこと

トークン使用量

回答が曖昧になったり繰り返されたりする場合は、まずサマリービューを確認してください。コンテキストウィンドウの不足は、出力が低下する一般的な原因です。

ツール呼び出しの順序

ログビューを確認し、エージェントが「ファイルを編集する前に読み込む」「変更を加えた後にテストを実行する」といった妥当な手順を踏んでいるか確認してください。

カスタマイズファイルの検出

カスタム指示、スキル、プロンプトファイルが反映されていないように見える場合は、読み込みイベントを調査し、検索されたすべてのパスを確認してください。

エラー

失敗したツール呼び出し、モデルのタイムアウト、欠落している依存関係は、ログビュー内にインラインで表示されます。

ログの永続性に関する重要な注意点

ログデータはVS Codeのセッションをまたいで保持されません。エージェントデバッグログパネルとチャットデバッグビューは現在のVS Codeセッションのデータのみを表示し、チャットデバッグビューはアクティブなウィンドウ中に行われたLLMリクエストのみをキャプチャします。これらのツールは作業中に使用してください。VS Codeを再起動すると利用できなくなります。

次のステップ

エージェントデバッグログパネルとチャットデバッグビューは、エージェントが何をしているかを完全に可視化します。時系列にはログビュー、数値にはサマリー、構造にはフローチャート、生のペイロードにはチャットデバッグビューを使用してください。セッションについて平易な言葉で質問する必要がある場合は、#debugEventsSnapshot と /troubleshoot を活用してください。

これで基礎はすべて網羅されました：ハーネス、モデル、コンテキスト、ツール、プロンプト、セッション、そしてデバッグレイヤーです。最後のガイドでは、これらすべてを組み合わせて、ゼロから実際のアプリケーションを構築します。

詳細情報

• チャットのやり取りをデバッグする