Debugging an AI agent can be difficult because one user request may trigger several model calls, tools, and application steps.

Microsoft Foundry provides tracing and an Agent Inspector to make these execution details easier to examine. Agent Inspector is designed for inspecting a local agent through a browser-based interface, while Foundry tracing provides broader visibility into agent runs, tool calls, latency, errors, and token usage.

What Is Agent Inspector?

Agent Inspector is a browser-based interface for interacting with a Microsoft Foundry agent running locally.

It can:

  • Send requests to the local agent

  • Display requests and responses

  • Replay messages

  • Help inspect prompts and tools while developing

  • Make it easier to reproduce an agent behavior

This is useful when developing an agent because you can test changes without deploying the agent first.

For production-style debugging, Foundry tracing provides a deeper execution view.

Agent Inspector vs Tracing

These features solve related but different problems.

Feature

Agent Inspector

Foundry Tracing

Main purpose

Local development

Observability and debugging

Interactive testing

Yes

Limited

Replay requests

Yes

Not its main purpose

Tool execution visibility

Yes

Yes

Latency analysis

Basic

Detailed

Failed runs

Useful during testing

Strong production visibility

Application Insights

Not required for local inspection

Used for trace storage

Foundry tracing can capture inputs and outputs, tool usage, retries, token consumption, latency, and errors.

Finding a Slow Tool Call

Consider an agent that performs this workflow:

User Request
     |
     v
Agent
     |
     +-- Model Call       1.1s
     |
     +-- Search Tool      0.6s
     |
     +-- Database Tool    4.8s
     |
     +-- Model Call       0.9s
     |
     v
Response

The total request may take several seconds, but the database tool is the obvious place to investigate.

Tracing makes these individual operations visible instead of showing only the total request duration.

Foundry traces expose timing information for agent operations and tool calls, making this type of investigation possible.

Finding Failed Runs

A failed agent run should be investigated from the execution path rather than only from the final error message.

For example:

Agent Run
 |
 +-- Model Call       Success
 |
 +-- Search Tool      Success
 |
 +-- Database Tool    Failed
 |
 +-- Retry            Failed
 |
 +-- Agent Run        Failed

This immediately tells you that the database operation was involved in the failure.

Foundry tracing records errors and execution metadata that can help identify where a problem occurred.

Setting Up Tracing

Foundry tracing uses Azure Monitor Application Insights to store telemetry.

At a high level:

AI Agent
   |
   v
OpenTelemetry
   |
   v
Application Insights
   |
   v
Foundry Traces

For supported Foundry agents, server-side tracing can be enabled through the project configuration without changing the agent's application code.

For applications where you need visibility into your own code, client-side instrumentation can be added.

For .NET applications, the required packages can include:

dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Projects.Agents
dotnet add package Azure.Identity
dotnet add package Azure.Monitor.OpenTelemetry.Exporter

The exact packages depend on the application and tracing approach being used.

Creating a Useful Agent Trace

A good trace should show the relationship between operations.

For example:

Agent Run
 |
 +-- invoke_agent
      |
      +-- Model Call
      |
      +-- execute_tool
      |      |
      |      +-- Search
      |
      +-- execute_tool
      |      |
      |      +-- Database
      |
      +-- Model Call

OpenTelemetry semantic conventions provide standardized concepts for agent invocations and tool execution, which helps keep telemetry consistent. (Microsoft Learn)

What Should Developers Look For?

When investigating a slow or failed agent, check these areas first.

1. Tool Duration

Look for tools that consistently take longer than expected.

2. Failed Operations

Check whether a tool, model request, or downstream service failed.

3. Retries

Multiple attempts may explain unexpected latency.

4. Tool Selection

Confirm that the agent called the tool that the task actually required.

5. Token Usage

Large inputs or outputs can contribute to both latency and cost.

6. Execution Order

A tool may be unnecessarily called before another operation that could have answered the request directly.

A Simple Debugging Process

When an agent behaves unexpectedly, use this process:

  1. Reproduce the request.

  2. Open the corresponding trace or inspection session.

  3. Check the execution order.

  4. Find slow operations.

  5. Look for failed or repeated tool calls.

  6. Inspect relevant inputs and outputs.

  7. Fix the agent or tool configuration.

  8. Run the same scenario again.

This is more reliable than changing prompts randomly and testing again.

Troubleshooting Missing Traces

If traces do not appear, check the basic configuration first.

Agent executed
      |
      v
Tracing enabled?
      |
      +-- No --> Configure tracing
      |
      +-- Yes
           |
           v
Application Insights connected?
           |
           +-- No --> Connect resource
           |
           +-- Yes
                 |
                 v
Wait for telemetry ingestion

Microsoft notes that traces may take a few minutes to appear after an agent execution.

For framework-based agents, missing spans can also occur when the appropriate instrumentation has not been enabled.

Protect Sensitive Data

Tracing can capture user inputs, model outputs, tool arguments, and tool results.

That means telemetry should be treated as production data.

Avoid putting secrets directly into prompts, tool arguments, or span attributes.

Also consider minimizing or redacting personal and sensitive information before it reaches telemetry storage.

Common Mistakes

Looking Only at the Final Error

The actual failure may have happened several steps earlier.

Ignoring Tool Latency

A slow tool can make the entire agent appear slow.

Recording Everything

More telemetry is not always better. Sensitive or unnecessary content should not be collected.

Testing Only Successful Runs

Failed and unusual executions are often the most useful debugging cases.

Ignoring Retries

Repeated calls can hide the original failure and increase execution time.

Best Practices

  1. Use Agent Inspector during local development.

  2. Use tracing to understand complete agent execution.

  3. Trace model and tool operations separately.

  4. Track latency and failures.

  5. Inspect retries and repeated operations.

  6. Use consistent telemetry attributes.

  7. Keep sensitive data out of traces where possible.

  8. Reproduce issues before changing the implementation.

  9. Compare traces before and after a fix.

Advantages and Limitations

Advantages

  • Easier local agent testing

  • Clearer visibility into tool calls

  • Faster identification of slow operations

  • Better understanding of failed runs

  • Useful execution history for debugging

Limitations

  • Detailed telemetry can increase storage and monitoring costs.

  • Trace data needs appropriate access controls.

  • Some agent and workflow capabilities can have different tracing availability.

  • Local inspection and production observability solve different problems.

Conclusion

Microsoft Foundry Agent Inspector is useful for interactively testing and inspecting agents during development, while Foundry tracing provides a broader view of agent execution.

When an agent is slow or fails unexpectedly, inspect the complete execution path rather than focusing only on the final response.

A practical workflow is:

Reproduce
   |
   v
Inspect Trace
   |
   v
Find Slow or Failed Step
   |
   v
Inspect Tool / Model
   |
   v
Fix
   |
   v
Run Again

This approach makes AI agent debugging more systematic and helps developers understand what actually happened during an agent run.