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

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

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

手順 1: 可観測性コードを更新する

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

Agent Inspector は agent-dev-cli を介してエージェントサーバーと通信するため、OTEL トレースは不要です。ワークフローの可視化のみが必要な場合は、以下のコードを削除してください。AI 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 モードから AIAgentExpert を選択します。
3. 以下のプロンプトを入力します

   Help me set up the debug environment for the workflow agent to use AI 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 を開く

トラブルシューティング

その他の質問や問題については、AI Toolkit GitHub リポジトリ を参照してください。

学んだこと

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

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