Develop agents with Agent Inspector in Foundry Toolkit
AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. 🎬 Watch The Story of VS Code! VS Code is now on Instagram, follow @vscode.ig for updates, tips, and more. Rewatch GitHub Copilot Day. Develop agents with Agent Inspector in Foundry Toolkit View as Markdown Ask in VS Code Ask in VS Code Insiders When an agent returns an unexpected answer, the response alone might not explain what went wrong.
Agent Inspector in Foundry Toolkit for VS Code lets you send requests to a local agent, inspect model and tool activity, and debug your code before deploying a change. This is useful when developing a hosted agent: an agent you build in code and deploy to Microsoft Foundry Agent Service. You maintain its logic and dependencies, while Foundry manages the hosting infrastructure. Use local inspection to debug your agent code before deployment.
Before production use, also test the deployed agent with its runtime identity, configuration, and network access. For a comparison with prompt agents, see Choose an agent type . In this article, you connect to a local agent, investigate a request, and preserve diagnostic events for further analysis. The main path uses the Responses protocol for conversational requests. The available views depend on the protocol and the diagnostics your agent server provides.
The following example shows a local Responses agent with tool calls, a latency waterfall, and a run timeline. Prerequisites Visual Studio Code with the current public Foundry Toolkit extension. See Install Foundry Toolkit . A local agent project with its dependencies, model configuration, and credentials set up. To start from a sample, follow Create and deploy a hosted agent through its local testing section. The debugger required by your project.
The Python sample uses the Python extension and debugpy . Other languages and samples have different requirements. For help adapting an existing project, use the Foundry Toolkit Copilot tools . Review the generated configuration and follow the project's README.md rather than replacing its launch files with a generic configuration. Important A local agent can call cloud models and live tools. Use non-sensitive test inputs, check tool permissions, and account for charges from the configured services.
Inspector doesn't replace tools with mocks. Connect and debug Start the agent server before connecting Inspector. Use your project's generated launch configuration to ensure that the server, working directory, interpreter, and debugger are all aligned. Start your agent using its documented debug configuration. For the hosted-agent Python sample, follow Run and test locally . Its Debug Local Agent HTTP Server configuration opens Inspector when you press F5 .
If Inspector isn't open, select Foundry Toolkit in the Activity Bar, then Developer Tools > Build > Agent Inspector . Check the endpoint in the Inspector header. The current Python scaffold uses http://localhost:8088 . If your server uses a different port, select the pencil button beside the endpoint, enter that port, and select Connect . Confirm that the header shows Connected . When the endpoint is reachable, Inspector automatically detects the Responses or Invocations protocol.
You don't need to select it manually. Set a breakpoint in your agent code, send a message in the playground, and use the debugger to inspect variables when execution pauses. After continuing, review the response and diagnostics as described in Use the Inspector . Opening Inspector alone doesn't launch a server or attach a debugger. The generated Python configuration uses port 5679 for the debugger and port 8088 for agent HTTP requests.
These are separate from the OTLP tracing ports described in Tracing in Foundry Toolkit . Generic Responses endpoints Inspector can connect to a local generic Responses endpoint without the full development diagnostics interface. You can inspect the Responses events the server sends, but the workflow graph and its input and output view aren't available. A successful connection doesn't mean the server supplies source locations, token usage, or reasoning.
Send an HTTP invocation Use HTTP Invocations when your agent accepts a custom request body rather than a conversational message. The server's request format and response protocol determine how Inspector sends and displays the result. Connect to your running HTTP Invocations server. Inspector detects the protocol automatically. Enter the request body required by your agent. When the server exposes a compatible OpenAPI specification, Inspector can fill in an example.
Review that example before sending it, and follow the sample's request format if no example is available. Select the Request settings gear beside the input to set Content-Type and Accept as required by the server. For example, use application/json for a JSON body and text/event-stream as the accepted response type when the server supports streaming. Select Send and inspect the response status and body. Switch between Preview for formatted output and Raw for the underlying response.
The Invocations details pane also includes I/O and LLM Calls . Model, tool, and token details depend on recognized events from the server, so not every response fills every tab. Inspector handles a normal HTTP response, a stream of server-sent events, or an asynchronous response. For an asynchronous 202 Accepted response, Inspector polls the invocation until it completes or fails. Selecting a response format doesn't add streaming or asynchronous support to your server.
For a streaming response, Stop disconnects the client stream. For a polled invocation, Cancel sends a cancellation request to the server. Neither action guarantees that the agent process or an external tool operation has stopped. This view isn't a WebSocket client. Activity Protocol samples use a different playground. See Choose another protocol or sample for the appropriate local testing path. Use the Inspector Start with one request that exercises the behavior you want to understand.
For example, if you're investigating a weather tool, ask for information that requires that tool rather than a general answer the model can produce without it. Send the request in the playground and review the streaming response. Use the details tabs to find the slow or failing operation. Inspect the relevant event or tool call, change your code or configuration, and repeat the request. In the input, press Enter to send or Shift+Enter to add a newline.
To recall an earlier request, place the caret at the start of the input and press Up . Press Down at the end of the input to move toward newer requests and return to your unsent draft. You can edit a recalled request before sending it. This input history is a convenience within Inspector, not a durable store of saved prompts. The Responses details tabs answer different questions: View Use it to Overview Follow the latency waterfall and ordered run timeline.
Select all runs or one run to distinguish model and tool activity from time spent waiting between runs. Tokens Review the input and output token usage reported for responses. Missing usage data isn't a zero-token result. Events Inspect the parsed Responses events, including errors, function calls, and results. Search by event type or JSON content and filter by category. Tools Inspect tool calls grouped by response run, including status, call ID, arguments, and results.
The response footer shows model, duration, token usage, and timestamp information when provided. Reasoning text and reasoning summaries appear in separate collapsible sections when the agent emits them. Inspector doesn't generate missing reasoning or expose information the model provider doesn't return. Inspect tools and permissions Use Tools to check whether the agent called the expected tool with the expected arguments and received a result.
A successful model resp
The rest of this page is on the live site.