Local Agent Playground および Local Visualizer から Agent Inspector への移行

この記事では、既存の AI エージェントプロジェクトを Foundry Toolkit の Local Agent Playground および Local Visualizer から Agent Inspector へ移行する方法を学習します。Agent Inspector は、チャット、ワークフローの可視化、デバッグサポートを単一の環境に統合します。

Foundry Toolkit は、Local Agent Playground と Local Visualizer を統合し、Agent Inspector と呼ばれる単一の環境を提供します。この移行により、AI エージェントの開発ワークフローが向上します。

Agent Inspector の開発者向けメリット

Agent Inspector は、従来のツールに比べていくつかの改善点を提供します。

主な改善点

Agent Inspector は、Local Agent Playground および Local Visualizer に対して以下の改善を提供します。

1. 統合された環境: Agent Inspector はチャットとトレースを単一のインターフェイスに統合しているため、個別のツールを切り替える必要がありません。

2. デバッグサポート: エージェントコードにブレークポイントを設定し、実行を一時停止し、変数を検査し、ワークフローロジックをステップ実行できます。従来のツールではこれらの機能は提供されていませんでした。

3. Copilot による設定支援: GitHub Copilot がデバッグ設定、エンドポイント、環境設定を自動生成し、手動設定によるエラーを軽減します。

4. コードナビゲーション: ワークフローの実行グラフを表示する際、ノードをダブルクリックすると、対応するソースファイルがエディターで即座に開きます。

5. 本番環境との一貫性: Agent Inspector で使用される agentdev CLI と Agent Framework SDK は、Microsoft Foundry へのデプロイに使用するものと同じ基盤であり、ローカル開発と本番環境の動作が一致することを保証します。

ワークフローの変更点

移行ガイド：既存のプロジェクト

プロジェクトで Local Visualizer（Microsoft Foundry 拡張機能経由）または Local Agent Playground を使用している場合は、以下の手順に従って Agent Inspector に移行してください。

前提条件

始める前に、以下が準備されていることを確認してください：

• Python 3.10+ がインストールされていること
• VS Code Foundry Toolkit 拡張機能 がインストールされていること（Agent Inspector はこの拡張機能の一部です）。詳細については、「Foundry Toolkit のインストール」を参照してください。
• Agent Framework SDK (agent-framework パッケージ) を使用して構築されたエージェント。

ステップ 1: 監視用コードの更新

以前の Visualizer 設定コードを削除

Agent Inspector は agent-dev-cli を介してエージェントサーバーと通信するため、OTEL トレースは不要です。ワークフローの可視化のみが必要な場合は、以下のコードを削除してください。Foundry Toolkit のトレース機能を引き続き使用したい場合は、ポートを 4317 に変更してください。

from agent_framework.observability import setup_observability
setup_observability(vs_code_extension_port=4319)

ステップ 2: VS Code デバッグ設定の追加

GitHub Copilot を使用してデバッグファイルを生成するか、手動で追加します

オプション A: GitHub Copilot に設定させる（推奨）

1. VS Code で GitHub Copilot を開きます。
2. Agent Mode から AIAgentExpert を選択します。
3. 以下のプロンプトを入力します

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

4. GitHub Copilot が .vscode/tasks.json および .vscode/launch.json ファイルを生成します。

オプション B: 手動設定

以下のファイルを使用して .vscode フォルダーを作成または更新します

.vscode/tasks.json

{
  "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"
    }
  ]
}

.vscode/launch.json

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

ステップ 3: 必要な依存関係のインストール

debugpy および agent-dev-cli をインストールします

pip install debugpy agent-dev-cli

ステップ 4: Agent Inspector でエージェントを実行

1. F5 キーを押してデバッグを開始します。
2. Agent Inspector は自動的に以下を行います
   • ポート 8087 でエージェントサーバーを開始
   • ポート 5679 で Python デバッガーをアタッチ
   • チャットプレイグラウンドとワークフロー可視化を備えた Inspector UI を開く

トラブルシューティング

ご質問や問題がある場合は、Foundry Toolkit GitHub リポジトリをご覧ください。

学んだこと

この記事では、以下の方法を学びました。

• Local Agent Playground および Local Visualizer から Agent Inspector に移行します。
• 新しいデバッグ環境のためにエージェントコードと VS Code 設定を更新します。
• Agent Inspector の新機能を使用して、エージェント開発ワークフローを向上させます。
• 移行および設定中の一般的な問題をトラブルシューティングします。