從 Local Agent Playground 和 Local Visualizer 遷移至 Agent Inspector

在本文中，您將學習如何將現有的 AI 代理程式專案從 Local Agent Playground 和 Local Visualizer 遷移至 AI Toolkit 中的 Agent Inspector。Agent Inspector 將聊天、工作流程視覺化和偵錯支援整合到單一體驗中。

AI Toolkit 將 Local Agent Playground 和 Local Visualizer 整併為一個統一的體驗，稱為 Agent Inspector。此轉變可改善您的 AI 代理程式開發工作流程。

Agent Inspector 以開發人員為中心的優勢

相較於先前的工具，Agent Inspector 提供了多項改進。

主要改進

相較於 Local Agent Playground 和 Local Visualizer，Agent Inspector 提供了以下改進。

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：更新您的可觀測性程式碼

移除先前的視覺化設定程式碼

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 Mode 中選擇 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 的新功能來改善您的代理程式開發工作流程。
• 排解遷移與設定過程中的常見問題。