Microsoft Foundry Toolkit でエージェント インスペクターを使用してエージェントをデバッグする

Microsoft Foundry Toolkit for Visual Studio Code の Agent Inspector を使用すると、ローカル エージェントに要求を送信し、モデルとツールのアクティビティを検査し、コードをデバッグできます。 これを使用して、変更をデプロイする前に予期しない応答を調査します。

このワークフローは、Foundry Agent Service でカスタム コードを実行する ホストされたエージェント に役立ちます。 ローカル検査は、そのコードをデバッグするのに役立ちます。 運用環境で使用する前に、デプロイされたエージェントをランタイム ID、構成、ネットワーク アクセスを使用してテストしてください。

この記事では、ローカル エージェントに接続し、要求を調査し、診断イベントを保存します。 メイン パスは Responses プロトコルを使用します。 使用可能なビューは、エージェント サーバーが提供するプロトコルと診断によって異なります。

Prerequisites

• 現在公開中の Foundry Toolkit 拡張機能を使用する Visual Studio Code 「Foundry Toolkit のインストール」を参照してください。
• 依存関係、モデル構成、および認証情報が設定されたローカル エージェント プロジェクト。 サンプルから開始するには、ローカル テストまで hosted-agent のクイック スタートに従います。
• プロジェクトに必要なデバッガー。 Pythonサンプルでは、Python拡張機能とdebugpyを使用します。 その他の言語とサンプルには、異なる要件があります。

既存のプロジェクトの場合、Foundry Toolkit Copilot ツールは、構成の準備に役立ちます。 生成されたファイルを確認し、プロジェクトの README.md に従ってください。 起動ファイルを汎用構成に置き換えないでください。

接続してデバッグする

Inspector に接続する前に、エージェント サーバーを起動してください。 プロジェクトの生成された起動構成を使用して、サーバー、作業ディレクトリ、インタープリター、デバッガーを調整します。

1. 記載されたデバッグ構成でエージェントを起動します。 hosted-agent Python サンプルの場合は、[ローカル エージェント HTTP サーバーのデバッグ] を選択し、F5 キーを押します。
2. Inspector が開いていない場合は、アクティビティ バーでまず Foundry Toolkit を選択してから [開発者ツール]>[ビルド]>[Agent Inspector] を選択します。
3. Inspector ヘッダーでエンドポイントを確認します。 現在の Python スキャフォールディングでは、http://localhost:8088 を使用します。 別のサーバー ポートの場合は、エンドポイントの横にある鉛筆ボタンを選択し、ポートを入力して、[ 接続] を選択します。
4. ヘッダーに [接続済み] と表示されていることを確認します。 Inspector は、エンドポイントに到達可能な場合、応答または呼び出しプロトコルを自動的に検出します。
5. エージェント コードにブレークポイントを設定し、プレイグラウンドでメッセージを送信します。 実行が一時停止したときに変数を検査し、続行して応答を確認します。

インスペクターを開くだけでは、サーバーが起動されたり、デバッガーがアタッチされたりすることはありません。 生成されたPython構成では、デバッガーの場合はポート 5679、エージェントの HTTP 要求にはポート 8088 が使用されます。 これらのポートは、 OTLP トレース ポートとは別です。

汎用応答エンドポイントに接続する

Inspector は、開発診断インターフェイス全体を使用せずに、ローカルの汎用応答エンドポイントに接続できます。 サーバーが送信する応答イベントを検査できますが、ワークフロー グラフとその入力および出力ビューは利用できません。

接続が成功しても、サーバーがソース位置、トークンの使用、または推論を提供するわけではありません。

HTTP 呼び出しを送信する

エージェントが会話型メッセージではなくカスタム要求本文を受け入れる場合は、HTTP 呼び出しを使用します。 サーバーの要求形式と応答プロトコルによって、Inspector が要求を送信し、結果を表示する方法が決まります。

1. 実行中の HTTP 呼び出しのサーバーに接続します。 Inspector はプロトコルを自動的に検出します。
2. エージェントが必要とする要求本文を入力します。 サーバーが互換性のある OpenAPI 仕様を公開している場合、Inspector は例を入力できます。 送信する前に確認するか、例がない場合はサンプルの要求形式に従ってください。
3. 入力の横にある [要求設定] の歯車を選択して、サーバーで必要とされる　Content-Type と Accept を設定します。 たとえば、JSON 本文に application/json を使用し、サーバーがストリーミング応答をサポートする場合には text/event-stream を使用します。
4. 送信 を選択し、応答の状態と本文を調べます。
5. 書式設定された出力の Preview と、基になる応答の Raw を切り替えます。 詳細ウィンドウには、I/O と LLM Calls も含まれます。 モデル、ツール、およびトークンの詳細は、認識されたサーバー イベントに依存するため、すべての応答がすべてのタブに入力されるわけではありません。

インスペクターは、通常の HTTP 応答、Server-Sent Events のストリーム、または非同期応答を処理します。 非同期 202 Accepted 応答の場合は、完了または失敗するまで呼び出しをポーリングします。 応答形式を選択しても、ストリーミングや非同期のサポートはサーバーに追加されません。

ストリーミング応答の場合、 Stop はクライアント ストリームを切断します。 ポーリング呼び出しの場合、Cancel はキャンセル要求をサーバーに送信します。 どちらのアクションも、エージェント プロセスまたは外部ツール操作が停止したことを保証しません。

このビューは WebSocket クライアントではありません。 アクティビティ プロトコルのサンプルでは、別のプレイグラウンドを使用します。 適切なローカル テスト パスについては、「 別のプロトコルまたはサンプルを選択 する」を参照してください。

Inspector を使う

理解する必要のある動作を実行する要求から始めます。 たとえば、気象ツールの場合は、モデルが生成できる一般的な回答ではなく、そのツールを必要とする情報を求めます。

1. プレイグラウンドで要求を送信し、ストリーミング応答を確認します。
2. 詳細タブを使用して、低速または失敗した操作を見つけます。
3. 関連するイベントまたはツールの呼び出しを検査し、コードまたは構成を変更して、要求を繰り返します。

Enter キーを押して送信するか、Shift+Enter キーを押して改行します。 以前の要求を呼び戻すには、入力の先頭にキャレットを配置し、上方向キーを押します。 末尾にある下方向キーを押して新しい要求に移動し、未送信の下書きに戻ります。

呼び戻された要求は送信前に編集できます。 入力履歴はインスペクター内で便利であり、保存されたプロンプトの永続的なストアではありません。

応答フッターには、指定された場合のモデル、所要時間、トークンの使用状況、タイムスタンプ情報が表示されます。 推論テキストと推論の概要は、エージェントがそれらを出力する場合、別々の折りたたみ可能なセクションに表示されます。 インスペクターは、不足している推論を生成したり、モデル プロバイダーが返さない情報を公開したりしません。

ツールとアクセス許可を検査する

Tools を使用して、エージェントが予期される引数を使用して予期されるツールを呼び出し、結果を受け取ったかどうかを確認します。 モデルの応答が成功しても、ツールが実行されたことを証明することはできません。 コードでモックを使用する場合、表示される結果はモック結果のままです。

モデル コンテキスト プロトコル (MCP) の承認または OAuth の同意に対して応答が一時停止すると、保留中の要求がメッセージ入力の上に表示されます。 許可するアクセス権のみを付与します。

MCP ツール呼び出しの場合は、[引数の表示] を選択し、入力を確認して、[承認] または [拒否] を選択します。 [すべて承認] と [すべて拒否] は、永続的なツール承認ポリシーではなく、保留中の要求に適用されます。

OAuth 同意の場合は、ブラウザーの認可および Inspector の確認の両方を完了します。

1. 保留中の要求に対して [同意を開く] を選択します。
2. ブラウザーで認可を完了し、Inspector に戻り、[同意完了] を選択します。 認可を拒否するには、代わりに [キャンセル] を選択します。
3. 残りの同意要求を解決します。 使用可能な場合は、開いているすべての要求の承認が完了した後でのみ、All doneを使用します。

同意ページだけを開いても、要求は再開されません。 インスペクターは、保留中の各同意に関する決定を待ってから、サーバーをもう一度確認します。 サーバーで承認が必要な場合は、要求が再び表示される可能性があります。

承認だけでなく、後続のツールの結果を確認して、完了を確認してください。 接続と認証のセットアップについては、「 ツール カタログ」を参照してください。 診断エラーが消えるためだけに、ツールの資格情報やアクセス許可を変更しないでください。

ワークフローとソースコードを確認する

サポートされている Microsoft Agent Framework ワークフローの場合、開発サーバーはワークフロー診断とソースの位置を提供できます。 インスペクターはこの情報を使用して実行グラフを表示し、コードに移動するのに役立ちます。

1. ワークフロー ノードを選択して、使用可能な入力と出力を検査します。
2. ノードをダブルクリックして、ソースの場所を開きます。
3. ブレークポイントを設定し、リクエストを再実行してデバッガーで操作を検査します。

プレイグラウンドで LangGraph ワークフローをテストできますが、ワークフローの視覚化はサポートされていません。 ワークフロー メタデータのないサーバーは、引き続き有用な応答イベントを返すことができます。

Copilot のエラーを調査する

[イベント] のエラー アクションを使用して、会話全体をコピーするのではなく、GitHub Copilot に対する焦点を絞った要求を準備します。

1. 失敗したイベントを見つけ、その詳細を共有する前に機密コンテンツが含まれていないか確認してください。
2. 失敗したイベントの横にある [修正] を選択して、そのエラーに対するプロンプトを準備します。 複数のエラーについては、検索フィルターとカテゴリ フィルターでリストを絞り込み、[Copilot で解決] を選択します。 このアクションには、目に見えるエラーが含まれます。
3. 送信する前に、GitHub Copilot Chat で準備されたプロンプトを確認してください。 提案された変更を確認し、元のエージェント要求を再実行して結果を確認してください。

これらのアクションでは、OTLP コレクターは必要ありません。 診断プロンプトを準備しても、エージェントが修正されたり、失敗した操作が再実行されたりすることはありません。

診断イベントを保存する

イベント スナップショットを保存して、エラーと後の実行を比較するか、焦点を絞った再現を共有します。

1. イベントで、検索フィールドとカテゴリ フィルターを使用してリストを絞り込みます。
2. [ 表示されるイベントをコピー ] を選択して、フィルター処理されたイベントを JSONL としてコピーします。 または、[表示中のイベントをダウンロード] を選択して VS Code でエクスポートを開きます。
3. 開いたエクスポートに対し、[ファイル]>[名前を付けて保存] を使用して、文書を閉じる前に、自分で管理できる場所にコピーを保存します。 開いたエクスポートファイルは一時ファイルであり、永続的なダウンロードではありません。

スナップショットには、実行中のエージェントからの今後のイベントではなく、アクションを選択したときに表示されるイベントが含まれます。 エージェントのバージョンの保存、コードのデプロイ、クラウド トレース履歴の作成は行われません。

新しい会話を開始する

[ チャットのクリア ] を選択して新しい会話を開始し、チャット、イベント、詳細の状態をクリアします。 まず、必要な診断イベントをエクスポートしてください。 同じ接続済みエージェントを更新すると、そのインスペクション状態が保持され、エージェントを変更すると古い状態がクリアされます。

応答の場合、応答がアクティブにストリーム配信されている間、 クリア チャット は無効になります。 ターンが承認または同意のために一時停止した場合でも利用可能なままです。 エージェントを停止する一般的なコマンドではありません。

永続的な会話アーカイブとしてローカルインスペクターの状態に依存しないでください。 サーバーは会話の永続化を所有します。これは、ローカル開発とデプロイされたホステッド エージェントとの間で異なる場合があります。 Inspector をクリアしても、既にローカルで収集されたトレースや Application Insights に格納されているトレースは削除されません。

Inspector とトレーシングの違い

Inspector は、HTTP 経由でお使いのローカル サーバーと通信し、応答イベントをストリームします。 互換性のある開発サーバーには、ワークフローの詳細とソース ナビゲーション用の個別の診断ストリームも用意されています。 デバッガーは、実行中のプロセスに独立してアタッチします。

これらのライブ診断では、ローカル OTLP コレクターは必要ありません。 Inspector の [トレース] タブで、個別のトレース ビューアーが開きます。 プロトコル イベントが、格納された OpenTelemetry スパンに変換されることはありません。

後で分析するためにスパンを収集するには、 ローカル トレースを構成します。 デプロイ済みエージェントでは、hosted-agent トレースを使用してください。

ローカル テストの後、ホステッド エージェントをデプロイします。 その ID、環境、ネットワーク アクセスはローカル プロセスと異なるため、個別にテストします。

Troubleshooting

関連するコンテンツ

• Foundry Toolkit でトレースを収集して検査します。
• VS Code でホステッド エージェント ワークフローを作成します。
• Azure Developer CLI を使用して、ブラウザー ベースのエージェントインスペクターを起動します。