从 Local Agent Playground 和 Local Visualizer 迁移到 Agent Inspector

在本文中，您将了解如何将现有的 AI 代理项目从 Local Agent Playground 和 Local Visualizer 迁移到 Foundry Toolkit 中的 Agent Inspector。Agent Inspector 将聊天、工作流可视化和调试支持整合到了单一体验中。

Foundry 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 Foundry Toolkit 扩展（Agent Inspector 是该扩展的一部分）。更多信息，请参阅安装 Foundry Toolkit。
• 您的代理是使用 Agent Framework SDK (agent-framework 包) 构建的。

第 1 步：更新您的可观测性代码

删除之前的可视化器设置代码

Agent Inspector 通过 agent-dev-cli 与您的代理服务器通信，不需要 OTEL 追踪。如果您只需要工作流可视化，请删除以下代码。如果您想继续在 Foundry 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 Foundry 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

故障排除

如需更多问题或反馈，请访问 Foundry Toolkit GitHub 存储库。

您学到了什么

在本文中，您学习了如何

• 从 Local Agent Playground 和 Local Visualizer 迁移到 Agent Inspector。
• 更新您的代理代码和 VS Code 配置以体验新的调试功能。
• 利用 Agent Inspector 的新功能改进您的代理开发工作流。
• 排查迁移和设置过程中的常见问题。