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に従ってください。起動ファイルを汎用構成に置き換えないでください。

Important

ローカルエージェントは、クラウドモデルとライブツールを呼び出すことができます。機密情報を含まないテスト入力を使用し、ツールのアクセス許可を確認し、構成されたサービスからの料金を考慮します。インスペクターはツールをモックに置き換えません。

接続してデバッグ

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

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

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

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

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

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

HTTP 呼び出しを送信する

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

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

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

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

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

インスペクターを使う

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

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

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

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

View	これを使用して、
Overview	待機時間のウォーターフォールと順序付けされた実行タイムラインに従います。すべての実行または 1 回の実行を選択して、モデルとツールのアクティビティを実行間の時間から区別します。
トークン	報告された入力トークンと出力トークンの使用状況を確認します。使用状況データが見つからない場合は、トークンが 0 の結果ではありません。
イベント	解析された応答イベント (エラー、関数呼び出し、結果など) を検査します。イベントの種類または JSON コンテンツで検索し、カテゴリでフィルター処理します。
ツール	状態、呼び出し ID、引数、結果など、応答実行ごとにグループ化されたツール呼び出しを検査します。

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

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

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

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

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

OAuth に同意するには、ブラウザーの承認とインスペクターの確認の両方を完了します。

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

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

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

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

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

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

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

Copilot の失敗を調査する

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

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

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

診断イベントを保存する

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

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

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

注意事項

イベントには、プロンプト、応答、ツール引数、結果、エラーの詳細を含めることができます。エクスポートを保存または共有する前に、機密コンテンツを確認して墨消しします。

新しい会話を開始する

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

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

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

Inspector とトレーシングの違い

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

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

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

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

Troubleshooting

Issue	確認すべきこと
インスペクターに接続できません。	エージェントターミナルで起動エラーを確認します。インタープリター、依存関係、および HTTP ポートを確認し、サーバーが報告するポートに再接続してください。インスペクターを開くことでは、プロセスが開始されません。
リクエストは成功しますが、ブレークポイントで停止しません。	デバッガーが要求を処理するプロセスにアタッチされ、正しいソースディレクトリを使用することを確認します。 Pythonについては、デバッグのトラブルシューティング情報を参照してください。
グラフまたはソースナビゲーションがありません。	サーバーとワークフローが開発診断とソースロケーションを提供していることを確認します。 Generic Responses 検査では、これらの機能は提供されません。 LangGraph ワークフローは、ワークフローの視覚化なしでプレイグラウンドで動作します。
ツールの結果がありません。	イベントで失敗と保留中の承認を確認します。要求にツールが必要であり、ツールが構成され、アクセス可能であることを確認します。
トークンまたは推論の詳細がありません。	モデルとサーバーが出力する内容を確認します。インスペクターは、提供された情報しか表示できません。
リモート画像はブロックされています。	インスペクターでリモートホストからリモートイメージをフェッチする場合にのみ、[リモートイメージの読み込み] を選択します。この表示許可は、ツールの承認ではありません。サポートされていないURLやコンテンツでも、読み込みに失敗することがあります。画像が表示されないからといって、必ずしもエージェントのリクエストが失敗したことを意味するとは限りません。
応答ストリームが中断されています。	部分応答と失敗の詳細情報を確認します。必要に応じて再接続し、再試行する前に保留中の承認を確認します。再試行では、ライブツールアクションを繰り返すことができます。
インスペクターにはイベントがありますが、トレースビューアーは空です。	プロトコルイベントと OTLP スパンは異なります。インストルメンテーションを構成し、コレクターを起動します。

フィードバック

このページはお役に立ちましたか?

最終更新: 2026-10-08