|
| 1 | +--- |
| 2 | +ContentId: 7ea83c06-5ed4-41ff-8929-fc1c6ab5ffee |
| 3 | +DateApproved: 03/17/2026 |
| 4 | +MetaDescription: Debug, visualize, and iterate on AI agents with the Agent Inspector in AI Toolkit. |
| 5 | +--- |
| 6 | +# Develop agents with Agent Inspector in AI Toolkit |
| 7 | + |
| 8 | +This article describes how to use the Agent Inspector to debug, visualize, and improve your AI agents directly in VS Code. Press F5 to launch your agent with full debugger support, view streaming responses in real time, and see how multiple agents work together. |
| 9 | + |
| 10 | + |
| 11 | + |
| 12 | +## Benefits |
| 13 | + |
| 14 | +Agent Inspector provides the following capabilities for your agent development workflow. |
| 15 | + |
| 16 | +| Benefit | Description | |
| 17 | +|---------|-------------| |
| 18 | +| **One-click F5 debugging** | Launch your agent with breakpoints, variable inspection, and step-through debugging. | |
| 19 | +| **Auto-configured by Copilot** | GitHub Copilot generates agent code and configures debugging, endpoints, and environment. | |
| 20 | +| **Production-ready code** | Generated code uses Hosted Agent SDK, ready to deploy to Microsoft Foundry. | |
| 21 | +| **Real-time visualization** | View streaming responses, tool calls, and workflow graphs between agents. | |
| 22 | +| **Quick code navigation** | Double-click workflow nodes to jump to corresponding code. | |
| 23 | + |
| 24 | +## Prerequisites |
| 25 | + |
| 26 | +- **Agent Framework SDK**: Agent built using `agent-framework` SDK |
| 27 | +- **Python 3.10+** and **VS Code AI Toolkit** extension |
| 28 | + |
| 29 | +## Quick start |
| 30 | + |
| 31 | +Choose one of the following options to quickly start using Agent Inspector with your agent project. |
| 32 | + |
| 33 | + |
| 34 | + |
| 35 | +### Option 1: Scaffold a sample (Recommended) |
| 36 | + |
| 37 | +1. Select **AI Toolkit** in the Activity Bar > **Agent and Workflow Tools** > **Agent Inspector**. |
| 38 | +1. Select **Scaffold a Sample** to generate a preconfigured project. |
| 39 | +1. Follow the README to run and debug the sample agent. |
| 40 | + |
| 41 | +### Option 2: Use Copilot to create a new agent |
| 42 | + |
| 43 | +1. Select **AI Toolkit** in the Activity Bar > **Agent and Workflow Tools** > **Agent Inspector**. |
| 44 | +1. Select **Build with Copilot** and provide agent requirements. |
| 45 | +1. GitHub Copilot generates agent code and configures debugging automatically. |
| 46 | +1. Follow the instructions from Copilot output to run and debug your agent. |
| 47 | + |
| 48 | +### Option 3: Start with an existing agent |
| 49 | + |
| 50 | +If you already have an agent built with Microsoft Agent Framework SDK, ask GitHub Copilot to set up debugging for the Agent Inspector. |
| 51 | + |
| 52 | +1. Select **AIAgentExpert** from the Agent dropdown. |
| 53 | +1. Enter prompt: |
| 54 | + |
| 55 | + ```prompt-AIAgentExpert |
| 56 | + Help me set up the debug environment for the workflow agent to use AI Toolkit Agent Inspector |
| 57 | + ``` |
| 58 | + |
| 59 | +1. Github Copilot generates the necessary configuration files and instructions to run and debug your agent using the Agent Inspector. |
| 60 | + |
| 61 | +## Configure debugging manually |
| 62 | + |
| 63 | +Add these files to your `.vscode` folder to set up debugging for your agent, and replace `${file}` with your agent's `entrypoint` python file path. |
| 64 | + |
| 65 | +<details> |
| 66 | +<summary><b>tasks.json</b></summary> |
| 67 | + |
| 68 | +```json |
| 69 | +{ |
| 70 | + "version": "2.0.0", |
| 71 | + "tasks": [ |
| 72 | + { |
| 73 | + "label": "Validate prerequisites", |
| 74 | + "type": "aitk", |
| 75 | + "command": "debug-check-prerequisites", |
| 76 | + "args": { "portOccupancy": [5679, 8087] } |
| 77 | + }, |
| 78 | + { |
| 79 | + "label": "Run Agent Server", |
| 80 | + "type": "shell", |
| 81 | + "command": "${command:python.interpreterPath} -m debugpy --listen 127.0.0.1:5679 -m agentdev run ${file} --port 8087", |
| 82 | + "isBackground": true, |
| 83 | + "dependsOn": ["Validate prerequisites"], |
| 84 | + "problemMatcher": { |
| 85 | + "pattern": [{"regexp": "^.*$", "file": 0, "location": 1, "message": 2}], |
| 86 | + "background": { "activeOnStart": true, "beginsPattern": ".*", "endsPattern": "Application startup complete|running on" } |
| 87 | + } |
| 88 | + }, |
| 89 | + { |
| 90 | + "label": "Open Inspector", |
| 91 | + "type": "shell", |
| 92 | + "command": "echo '${input:openTestTool}'", |
| 93 | + "presentation": {"reveal": "never"}, |
| 94 | + "dependsOn": ["Run Agent Server"] |
| 95 | + }, |
| 96 | + { "label": "Terminate All", "command": "echo ${input:terminate}", "type": "shell", "problemMatcher": [] } |
| 97 | + ], |
| 98 | + "inputs": [ |
| 99 | + { "id": "openTestTool", "type": "command", "command": "ai-mlstudio.openTestTool", "args": {"port": 8087} }, |
| 100 | + { "id": "terminate", "type": "command", "command": "workbench.action.tasks.terminate", "args": "terminateAll" } |
| 101 | + ] |
| 102 | +} |
| 103 | +``` |
| 104 | +</details> |
| 105 | + |
| 106 | +<details> |
| 107 | +<summary><b>launch.json</b></summary> |
| 108 | + |
| 109 | +```json |
| 110 | +{ |
| 111 | + "version": "0.2.0", |
| 112 | + "configurations": [{ |
| 113 | + "name": "Debug Agent", |
| 114 | + "type": "debugpy", |
| 115 | + "request": "attach", |
| 116 | + "connect": { "host": "localhost", "port": 5679 }, |
| 117 | + "preLaunchTask": "Open Inspector", |
| 118 | + "postDebugTask": "Terminate All" |
| 119 | + }] |
| 120 | +} |
| 121 | +``` |
| 122 | +</details> |
| 123 | + |
| 124 | +## Use the Inspector |
| 125 | + |
| 126 | +### Chat playground |
| 127 | +Send messages to trigger the workflow and view executions in real-time. |
| 128 | + |
| 129 | + |
| 130 | +### Workflow visualization |
| 131 | +For `WorkflowAgent`, view the execution graph with message flows between agents. You can also: |
| 132 | +1. Select each node to review agent inputs and outputs. |
| 133 | +1. Double-click any node to navigate to the code. |
| 134 | +1. Set breakpoints in the code to pause execution and inspect variables. |
| 135 | + |
| 136 | +## Troubleshooting |
| 137 | + |
| 138 | +| Issue | Solution | |
| 139 | +|-------|----------| |
| 140 | +| **API errors** | Agent Framework is evolving. Copy terminal errors to Copilot for fixes. | |
| 141 | +| **Connection failed** | Verify server is running on expected port (default: 8087). | |
| 142 | +| **Breakpoints not hit** | Ensure `debugpy` is installed and ports match in launch.json. | |
| 143 | + |
| 144 | +## How it works |
| 145 | + |
| 146 | +When you press F5, the Inspector: |
| 147 | + |
| 148 | +1. **Starts the agent server:** The `agentdev` CLI wraps your agent as an HTTP server on port 8087, with debugpy attached on port 5679. |
| 149 | +1. **Discovers agents:** The UI fetches available agents/workflows from `/agentdev/entities`. |
| 150 | +1. **Streams execution:** Chat inputs go to `/v1/responses`, which streams back events via SSE for real-time visualization. |
| 151 | +1. **Enables code navigation:** Double-click workflow nodes to open the corresponding source file in the editor. |
| 152 | + |
| 153 | +### Architecture overview |
| 154 | + |
| 155 | +The `agentdev` CLI launches a local TestToolServer that wraps your agent as an HTTP server on port 8087. The Inspector UI (a VS Code webview) communicates with this server over HTTP and WebSocket to list agents, stream SSE responses, and trigger code navigation in the editor. An EventMapper converts Agent Framework events into OpenAI-compatible SSE format, and a Python debugger (debugpy) attaches on port 5679 for step-through debugging. Your agent or workflow runs via `run_stream()` through the Agent Framework SDK. |
| 156 | + |
| 157 | + |
0 commit comments