在 AI Toolkit 中使用 Agent Inspector 开发智能体

本文介绍了如何使用 Agent Inspector 直接在 VS Code 中调试、可视化并优化您的 AI 智能体。按 F5 键即可在完整的调试器支持下启动智能体，实时查看流式响应，并观察多个智能体如何协同工作。

优势

Agent Inspector 为您的智能体开发工作流提供了以下功能：

先决条件

• 智能体框架 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. 从 Agent 下拉菜单中选择 AIAgentExpert。

2. 输入提示词

   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 将智能体框架事件转换为兼容 OpenAI 的 SSE 格式，Python 调试器 (debugpy) 附加在 5679 端口上以进行单步调试。您的智能体或工作流通过 Agent Framework SDK 的 run_stream() 运行。