在 AI Toolkit 中使用 Agent Inspector 開發智慧代理程式 (Agents)

本文說明如何使用 Agent Inspector 直接在 VS Code 中偵錯、視覺化並改善您的 AI 代理程式。按 F5 鍵即可在完整的偵錯工具支援下啟動您的代理程式、即時檢視串流回應，並查看多個代理程式如何協同運作。

優點

Agent Inspector 為您的代理程式開發工作流程提供了以下功能：

先決條件

• Agent Framework SDK：使用 agent-framework SDK 建置的代理程式
• Python 3.10+ 與 VS Code AI Toolkit 擴充功能

快速入門

選擇下列其中一個選項，快速開始將 Agent Inspector 用於您的代理程式專案：

選項 1：建立範本 (建議)

1. 在活動列選取 AI Toolkit > Agent and Workflow Tools > Agent Inspector。
2. 選取 Scaffold a Sample 以產生預先設定好的專案。
3. 依照 README 說明來執行與偵錯範例代理程式。

選項 2：使用 Copilot 建立新的代理程式

1. 在活動列選取 AI Toolkit > Agent and Workflow Tools > Agent Inspector。
2. 選取 Build with Copilot 並提供代理程式需求。
3. GitHub Copilot 會自動產生代理程式程式碼並設定偵錯。
4. 依照 Copilot 輸出的指示來執行與偵錯您的代理程式。

選項 3：從現有的代理程式開始

如果您已有使用 Microsoft Agent Framework SDK 建置的代理程式，請要求 GitHub Copilot 設定 Agent Inspector 的偵錯功能。

1. 從代理程式下拉式選單選取 AIAgentExpert。

2. 輸入提示詞 (Prompt)

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

聊天遊樂場 (Chat playground)

傳送訊息以觸發工作流程並即時檢視執行情形。

工作流程視覺化

針對 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() 執行。