使用 Foundry Toolkit 中的 Agent Inspector 开发智能体
本文介绍如何直接在 VS Code 中使用 Agent Inspector 来调试、可视化和改进你的 AI 智能体。按下 F5 键即可在完整调试器支持下启动智能体、实时查看流式响应，以及观察多个智能体如何协同工作。
优势
Agent Inspector 为你的智能体开发工作流提供以下功能：
| 优势 | 描述 |
|---|---|
| 一键 F5 调试 | 启动智能体并支持断点、变量检查和单步调试。 |
| 由 Copilot 自动配置 | GitHub Copilot 可生成智能体代码，并配置调试、端点和环境。 |
| 生产就绪的代码 | 生成的代码使用托管智能体 SDK (Hosted Agent SDK)，可随时部署到 Microsoft Foundry。 |
| 实时可视化 | 查看流式响应、工具调用以及智能体之间的工作流图。 |
| 快速代码导航 | 双击工作流节点即可跳转到相应的代码。 |
前提条件
- Python 3.10+ 和 VS Code Foundry Toolkit 扩展
- 用于支持调试的 VS Code Python 扩展（如果使用 Python）
快速入门
选择以下选项之一，快速开始在智能体项目中使用 Agent Inspector。
选项 1：搭建示例脚手架（推荐）
- 在活动栏中选择 Foundry Toolkit > Developer Tools > Build > Agent Inspector。
- 选择 Try a Sample 生成预配置的项目。
- 按照 README 运行和调试示例智能体。
选项 2：使用 Copilot 创建新智能体
- 在活动栏中选择 Foundry Toolkit > Developer Tools > Build > Agent Inspector。
- 选择 create with Copilot 并提供智能体需求。
- GitHub Copilot 会自动生成智能体代码并配置调试。
- 按照 Copilot 输出中的说明运行和调试你的智能体。
选项 3：从现有智能体开始
如果你已经使用 Microsoft Agent Framework SDK 构建了智能体，请让 GitHub Copilot 为 Agent Inspector 设置调试。
-
从智能体下拉菜单中选择 AIAgentExpert。
-
输入提示词
Help me set up the debug environment for the workflow agent to use Foundry Toolkit Agent Inspector -
GitHub Copilot 会生成必要的配置文件和说明，以便使用 Agent Inspector 运行和调试你的智能体。
手动配置调试
将这些文件添加到你的 .vscode 文件夹中以设置智能体调试，并将 ${file} 替换为你的智能体 entrypoint python 文件路径。
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"
}
]
}
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"
}
]
}
使用 Inspector
聊天演练场
发送消息以触发工作流并实时查看执行情况。
工作流可视化
对于 WorkflowAgent，查看包含智能体之间消息流的执行图。你还可以
- 选择各个节点以查看智能体的输入和输出。
- 双击任意节点即可导航至代码。
- 在代码中设置断点以暂停执行并检查变量。
疑难解答
| 问题 | 解决方案 |
|---|---|
| API 错误 | Agent Framework 正在不断演进。将终端错误复制给 Copilot 以获取修复方案。 |
| 连接失败 | 验证服务器是否正在预期端口上运行（默认：8087）。 |
| 断点未命中 | 确保已安装 debugpy 且端口在 launch.json 中匹配。 |
工作原理
当你按下 F5 时，Inspector 将执行以下操作：
- 启动智能体服务器：
agentdevCLI 将你的智能体包装为运行在 8087 端口上的 HTTP 服务器，并在 5679 端口上附加 debugpy。 - 发现智能体：UI 从
/agentdev/entities获取可用的智能体/工作流。 - 流式传输执行过程：聊天输入发送到
/v1/responses，该端点通过 SSE 流式传输返回事件以实现实时可视化。 - 启用代码导航：双击工作流节点可在编辑器中打开相应的源文件。
架构概述
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() 运行。
