Migrate from Local Agent Playground and Local Visualizer to Agent Inspector

In this article, you learn how to migrate your existing AI agent projects from Local Agent Playground and Local Visualizer to Agent Inspector in AI Toolkit. Agent Inspector combines chat, workflow visualization, and debugging support into a single experience.

AI Toolkit consolidates the Local Agent Playground and Local Visualizer into a single, unified experience called Agent Inspector. This transition improves your AI agent development workflow.

Developer-centric benefits of Agent Inspector

Agent Inspector provides several improvements over the previous tools.

Key improvements

Agent Inspector offers the following improvements over Local Agent Playground and Local Visualizer.

1. Unified experience: Agent Inspector combines chat and tracing into a single interface, so you no longer need to switch between separate tools.

2. Debugging support: Set breakpoints in your agent code, pause execution, inspect variables, and step through your workflow logic. The separate tools didn't offer these capabilities.

3. Copilot-assisted setup: GitHub Copilot can automatically generate the debugging configuration, endpoints, and environment setup, reducing manual configuration errors.

4. Code navigation: When viewing workflow execution graphs, double-click any node to immediately open the corresponding source file in your editor.

5. Consistent with production: The agentdev CLI and Agent Framework SDK used in Agent Inspector are the same foundation you use for deploying to Microsoft Foundry, ensuring your local development matches production behavior.

What changes for your workflow

Migration guide: existing projects

If your project uses the Local Visualizer (via the Microsoft Foundry extension) or the Local Agent Playground, follow these steps to migrate to Agent Inspector.

Prerequisites

Before you start, make sure you have:

• Python 3.10+ installed
• VS Code AI Toolkit extension installed (Agent Inspector is part of this extension). For more information, see install AI Toolkit.
• Your agent built with the Agent Framework SDK (agent-framework package).

Step 1: Update your observability code

Remove the previous visualizer setup code:

Agent Inspector communicates with your agent server through agent-dev-cli and doesn't require OTEL tracing. Remove the following code if you only need workflow visualization. If you want to keep using tracing features in AI Toolkit, change the port to 4317.

from agent_framework.observability import setup_observability
setup_observability(vs_code_extension_port=4319)

Step 2: Add VS Code debug configuration

Use GitHub Copilot to generate the debug files, or add them manually:

Option A: Let GitHub Copilot configure it (recommended)

1. Open GitHub Copilot in VS Code.
2. Select AIAgentExpert from Agent Mode.
3. Enter this prompt:

   Help me set up the debug environment for the workflow agent to use AI Toolkit Agent Inspector
   

4. GitHub Copilot generates the .vscode/tasks.json and .vscode/launch.json files for you.

Option B: Manual configuration

Create or update your .vscode folder with these files:

.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"
    }
  ]
}

Step 3: Install required dependencies

Install debugpy and agent-dev-cli:

pip install debugpy agent-dev-cli

Step 4: Run your agent with Agent Inspector

1. Press F5 to start debugging.
2. Agent Inspector automatically:
   • Starts your agent server on port 8087
   • Attaches the Python debugger on port 5679
   • Opens the Inspector UI with the chat playground and workflow visualization

Troubleshooting

For additional questions or issues, visit the AI Toolkit GitHub repository.

What you learned

In this article, you learned how to:

• Migrate from Local Agent Playground and Local Visualizer to Agent Inspector.
• Update your agent code and VS Code configuration for the new debugging experience.
• Use the new capabilities of Agent Inspector to improve your agent development workflow.
• Troubleshoot common issues during migration and setup.