从 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 的新功能来优化您的智能体开发工作流。
• 排查迁移和设置过程中遇到的常见问题。