Foundry ToolkitのAgent Inspectorでエージェントを開発する

本記事では、Agent Inspectorを使用して、VS Code上で直接AIエージェントのデバッグ、視覚化、改善を行う方法を説明します。F5キーを押すだけで、完全なデバッガーサポートを備えたエージェントを起動し、ストリーミング応答をリアルタイムで確認したり、複数のエージェントがどのように連携するかを視覚的に把握したりできます。

利点

Agent Inspectorは、エージェント開発ワークフローに対して以下の機能を提供します。

前提条件

• Python 3.10以上 および VS Code Foundry Toolkit 拡張機能
• デバッグサポート用の Python 拡張機能 (VS Code用)（Pythonを使用する場合）

クイックスタート

Agent Inspectorをエージェントプロジェクトですぐに使い始めるには、以下のいずれかのオプションを選択してください。

オプション1: サンプルを構築する（推奨）

1. アクティビティバーで Foundry Toolkit > Developer Tools > Build > Agent Inspector の順に選択します。
2. Try a Sample を選択して、事前構成済みのプロジェクトを生成します。
3. READMEに従って、サンプルエージェントを実行およびデバッグします。

オプション2: Copilotを使用して新しいエージェントを作成する

1. アクティビティバーで Foundry Toolkit > Developer Tools > Build > Agent Inspector の順に選択します。
2. create with Copilot を選択し、エージェントの要件を入力します。
3. GitHub Copilotがエージェントコードを生成し、デバッグ設定を自動的に構成します。
4. Copilotが出力した手順に従って、エージェントを実行およびデバッグします。

オプション3: 既存のエージェントで開始する

Microsoft Agent Framework SDKで構築済みのエージェントがある場合は、GitHub CopilotにAgent Inspector用のデバッグ設定を依頼してください。

1. エージェントのドロップダウンから AIAgentExpert を選択します。

2. プロンプトを入力します

   Help me set up the debug environment for the workflow agent to use Foundry Toolkit Agent Inspector
   

3. GitHub Copilotが、Agent Inspectorを使用してエージェントを実行・デバッグするために必要な構成ファイルと手順を生成します。

デバッグを手動で構成する

これらのファイルを .vscode フォルダーに追加してエージェントのデバッグをセットアップし、${file} をエージェントの entrypoint Pythonファイルパスに置き換えてください。

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Validate prerequisites",
      "type": "aitk",
      "command": "debug-check-prerequisites",
      "args": { "portOccupancy": [5679, 8087] }
    },
    {
      "label": "Run Agent Server",
      "type": "shell",
      "command": "${command:python.interpreterPath} -m debugpy --listen 127.0.0.1:5679 -m agentdev run ${file} --port 8087",
      "isBackground": true,
      "dependsOn": ["Validate prerequisites"],
      "problemMatcher": {
        "pattern": [{ "regexp": "^.*$", "file": 0, "location": 1, "message": 2 }],
        "background": {
          "activeOnStart": true,
          "beginsPattern": ".*",
          "endsPattern": "Application startup complete|running on"
        }
      }
    },
    {
      "label": "Open Inspector",
      "type": "shell",
      "command": "echo '${input:openTestTool}'",
      "presentation": { "reveal": "never" },
      "dependsOn": ["Run Agent Server"]
    },
    {
      "label": "Terminate All",
      "command": "echo ${input:terminate}",
      "type": "shell",
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "openTestTool",
      "type": "command",
      "command": "ai-mlstudio.openTestTool",
      "args": { "port": 8087 }
    },
    {
      "id": "terminate",
      "type": "command",
      "command": "workbench.action.tasks.terminate",
      "args": "terminateAll"
    }
  ]
}

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Agent",
      "type": "debugpy",
      "request": "attach",
      "connect": { "host": "localhost", "port": 5679 },
      "preLaunchTask": "Open Inspector",
      "postDebugTask": "Terminate All"
    }
  ]
}

Inspectorを使用する

チャットプレイグラウンド

メッセージを送信してワークフローをトリガーし、実行結果をリアルタイムで確認します。

ワークフローの視覚化

WorkflowAgent の場合、エージェント間のメッセージフローを含む実行グラフを表示できます。また、以下の操作が可能です。

1. 各ノードを選択して、エージェントの入出力を確認する。
2. ノードをダブルクリックして、該当コードに移動する。
3. コードにブレークポイントを設定して実行を一時停止し、変数を検査する。

トラブルシューティング

仕組み

F5キーを押すと、Inspectorは以下の動作を行います。

1. エージェントサーバーの起動: agentdev CLIがエージェントをポート8087のHTTPサーバーとしてラップし、ポート5679でdebugpyをアタッチします。
2. エージェントの検出: UIが /agentdev/entities から利用可能なエージェント/ワークフローを取得します。
3. 実行のストリーミング: チャット入力が /v1/responses に送信され、リアルタイム視覚化のためにSSE経由でイベントがストリーミングされます。
4. コードナビゲーションの有効化: ワークフローノードをダブルクリックすると、エディターで対応するソースファイルが開きます。

アーキテクチャの概要

agentdev CLIはローカルのTestToolServerを起動し、エージェントをポート8087でHTTPサーバーとしてラップします。Inspector UI（VS Code Webview）は、このサーバーとHTTPおよびWebSocketで通信し、エージェントの一覧取得、SSE応答のストリーミング、エディターでのコードナビゲーションを実行します。EventMapperはAgent FrameworkのイベントをOpenAI互換のSSE形式に変換し、Pythonデバッガー（debugpy）がポート5679にアタッチされてステップ実行デバッグを可能にします。エージェントまたはワークフローは、Agent Framework SDKを通じて run_stream() により実行されます。