Integrate monitoring into deployed agents, evaluate agent behavior, and perform error analysis
AI-103 › Unit 2: Implement generative AI and agentic solutions › Build agents by using Foundry › Integrate monitoring into deployed agents, evaluate agent behavior, and perform error analysis
Integrate monitoring into deployed agents, evaluate agent behavior, and perform error analysis
A deployed agent fails in more ways than a deployed model, because a run is a chain: understand the request, select a tool, build arguments, use the result, stay on task. Monitoring an agent means being able to say which link broke — and the agent evaluator family exists precisely to name each link.
Why This Matters
A quality score is not a diagnosis. "Responses got worse" is a symptom. Whether retrieval returned nothing, a tool errored, or the instructions changed is a different fix each time, and only per-link measurement distinguishes them.
The agent evaluators are unusually fine-grained. Selection, input accuracy, output utilization, and call success are four separate scores for what feels like one behaviour. That granularity is the whole point.
Traces answer the question scores raise. A score tells you something is wrong; the trace shows the tool call, its arguments, and what came back.
Prerequisites
- OpenTelemetry tracing into Application Insights.
- The evaluator families and their required inputs.
- That continuous evaluation samples production traffic and scheduled evaluation uses a fixed dataset.
- Cluster analysis as failure grouping.
Learning Objectives
By the end of this lesson you will be able to:
- Instrument a deployed agent with tracing and read an agent run's spans.
- Apply the agent evaluators to localise a failure.
- Choose continuous against scheduled evaluation, and add scheduled red teaming.
- Run an error analysis loop from alert to root cause to regression case.
- Set alerts that are actionable rather than noisy.
Building Blocks
Tracing. Foundry emits OpenTelemetry telemetry to Application Insights. An agent run appears as a tree of spans: the run, model calls, tool calls with inputs and outputs, latencies, and errors. Traces are sampled and retention-bound — diagnosis, not a system of record.
The agent evaluators.
| Evaluator | Answers |
|---|---|
| Intent Resolution | Did it understand what was asked? |
| Tool Selection | Was the right tool chosen? |
| Tool Call Accuracy | Was the call correct overall? |
| Tool Input Accuracy | Were the arguments right? |
| Tool Call Success | Did the call succeed? |
| Tool Output Utilization | Was the result actually used? |
| Task Adherence | Did it follow instructions and stay on task? |
| Task Completion | Did it finish the task? |
| Task Navigation Efficiency | Did it get there without wandering? |
Post-production modes. Operational metrics (latency, errors, throughput, token spend), continuous evaluation on sampled production traffic, scheduled evaluation against a fixed dataset — which is what detects drift — scheduled red teaming, and Azure Monitor alerts on quality thresholds and harmful content.
Cluster analysis groups failing cases so a pattern is visible rather than a list of scores.
Evaluation level. "turn" (default) or "conversation" — and levels cannot be mixed in one run. Agent behaviour that only exists across a thread — staying on task, resolving the intent by the end — needs "conversation".
Three post-production signals
| Attribute | |||
|---|---|---|---|
| Measures | Latency, errors, tokens | Quality on live traffic | Quality on fixed inputs |
| Detects | Outages, cost, throttling | Live degradation | Drift |
| Input | All traffic | Sampled traffic | A fixed dataset |
| Attributable? | Yes | No — traffic changes | Yes — inputs held constant |
Deep Dive
Reading an agent run
An agent trace is a tree, and its shape carries the diagnosis before any score does.
The run span contains model calls and tool calls. Each tool span shows the arguments sent and the result returned, plus timing and any error. Three shapes are worth recognising immediately.
A tool span with an error, followed by a confident answer. The agent ignored a failure — a Tool Output Utilization problem, fixed by instructing explicitly what to do when a call fails.
A retrieval span returning nothing, followed by an answer. The same failure in the retrieval path: the model answered from parametric knowledge. Both cases produce fluent output, which is why neither is visible without the trace.
Many tool spans for a simple request. Wandering — Task Navigation Efficiency — usually caused by overlapping tool schemas or a missing termination condition.
Traces are sampled and retention-bound, so they are the diagnostic layer and not the record. Conversation content that must be retained belongs in your own Cosmos DB.
The error analysis loop
Alert
An Azure Monitor alert on a quality threshold or harmful content, or a scheduled evaluation regression.
Localising with the evaluator chain
The value of the agent family is that each evaluator implicates a different layer, so a score tells you where to work.
Intent Resolution low — the agent misunderstood. Instructions or the request-handling prompt, not the tools.
Tool Selection low — schema overlap, or descriptions saying what a tool is rather than when to use it. Fix the schemas, or split the agent if the surface is simply too large.
Tool Input Accuracy low — parameter schemas without types, enums, or descriptions.
Tool Call Success low — not an agent problem at all: transport, permission, or downstream availability. Worth separating precisely because the fix is outside the agent.
Tool Output Utilization low — the result came back and was not used, which nearly always means no instruction for empty or failed results.
Task Adherence or Task Completion low with the rest healthy — the instructions themselves: an unclear goal, or rules conflicting with it.
Task Navigation Efficiency low — wandering: overlapping tools, missing termination, or an over-broad goal.
Because several of these only make sense across a whole thread, remember evaluation_level: use "conversation" for adherence and intent-over-time, "turn" for per-exchange quality, and never mix them in one run — measuring both means two runs.
Continuous, scheduled, and red teaming
These answer different questions and are frequently confused.
Continuous evaluation scores sampled production traffic. It tells you how the live system is doing right now and catches degradation on real usage. What it cannot do is isolate a cause, because the traffic changes underneath you — a score drop may be a worse agent or simply harder questions.
Scheduled evaluation runs a fixed dataset on a schedule. Because the inputs are held constant, a score movement is attributable — which is why this, and not continuous evaluation, is what detects drift after a model version, prompt, or tool change.
Scheduled red teaming probes adversarially on PyRIT, returning a comparable scorecard. Risk can reappear when a model or prompt changes, so this belongs on a schedule and not only at release.
Operational metrics sit underneath all three. Latency, error rate, throughput, and token spend catch the failures that never produce a bad answer — throttling, a downstream outage, a runaway loop.
Closing the loop
Error analysis that does not change the test set repeats itself.
Every diagnosed failure should become a case in the fixed evaluation dataset. That converts a one-off investigation into a permanent regression check, and it is how the scheduled run gains the power to prove a fix held.
Two practices go with it. Re-baseline after a change: modifying instructions or the model shifts every score, so comparing against a stale baseline reads as improvement or regression that did not happen. And keep the configuration record: agent versions are automatically snapshotted, and a pinned toolbox version fixes the tool surface — together they answer "what was live when this ran", which is the first question in any real investigation.
Worked Examples
Example 1 — confident answers after failures. Users report plausible but wrong pricing answers. Traces show the pricing tool returning errors for some regions.
Tool Output Utilization — the result came back and was ignored. Fix instructionally: state explicitly what to do when a call fails or returns nothing. Add the case to the fixed dataset so the next scheduled run proves it stays fixed. Tool Call Success would also be low here, pointing at the regional failures as a separate downstream issue.
Example 2 — worse after an upgrade, cause unknown. Continuous evaluation shows a quality drop after a model version change, but the team cannot tell whether the model or the traffic changed.
Scheduled evaluation on a fixed dataset — inputs held constant, so the movement is attributable to the version. Continuous evaluation samples live traffic and cannot separate the two. Add scheduled red teaming, since risk can reappear with a version change.
Example 3 — an agent that wanders. A support agent reaches correct answers after many tool calls, and latency and cost are high.
Task Navigation Efficiency. Traces will show many spans for simple requests. The usual causes are overlapping tool schemas — make them disjoint or split the agent — and a missing termination condition. Correct final answers mean adherence and completion may look healthy, which is exactly why efficiency is measured separately.
Visual Explanations
The chain and its evaluators:
The monitoring loop:
Common Mistakes
Treating a quality score as a diagnosis. It names a symptom; evaluators name the link.
Collapsing the tool evaluators into one. Four separate layers, four fixes.
Missing that Tool Call Success points outside the agent.
Using continuous evaluation to detect drift. Drift needs a fixed dataset.
Paging on raw quality scores. Noise, then muting, then nothing monitored.
Mixing evaluation levels in one run. Not permitted.
Diagnosing without adding a regression case. The investigation repeats.
Comparing against a stale baseline after changing instructions or the model.
Treating traces as a record. Sampled and retention-bound.
Practice Exercises
- Map each symptom to its evaluator: misunderstood the request; wrong tool; malformed arguments; ignored the result; wandered.
- Why can continuous evaluation not attribute a quality drop, and what can?
- What should and should not trigger an alert?
- Which evaluator points at a problem outside the agent, and why is that useful?
- What two things must follow every diagnosed failure?
▶Answers
- Misunderstood → Intent Resolution. Wrong tool → Tool Selection (schema overlap or descriptions lacking "when"). Malformed arguments → Tool Input Accuracy (unconstrained parameters). Ignored the result → Tool Output Utilization (no instruction for empty or failed calls). Wandered → Task Navigation Efficiency (overlapping tools or missing termination).
- Because it scores sampled production traffic, which changes with user behaviour — a drop may be a worse agent or harder questions. Scheduled evaluation on a fixed dataset holds inputs constant, making the movement attributable.
- Should: operational signals (error rate, latency, token spend), harmful content, and scheduled evaluation regressions on constant inputs. Should not: raw continuous-evaluation quality scores, which move with traffic mix and produce noise that leads to muting.
- Tool Call Success — a low score points at transport, permission, or downstream availability rather than the agent's reasoning. Useful because no amount of schema or instruction work will fix it.
- A regression case added to the fixed evaluation dataset, so the scheduled run proves the fix holds; and a re-baseline if instructions or the model changed, since every score shifts and a stale baseline misreports the result.
Summary & Concept Map
Monitoring an agent means localising failures along a chain. Traces into Application Insights show the run as spans — arguments, results, errors, latency — and three shapes are diagnostic on sight: an error followed by a confident answer, an empty retrieval followed by an answer, and many spans for a simple request. The agent evaluators name the link: Intent Resolution, Tool Selection, Tool Input Accuracy, Tool Call Success, Tool Output Utilization, Task Adherence, Task Completion, Task Navigation Efficiency — with evaluation_level set to turn or conversation and never mixed. In production, operational metrics catch failures that never produce a bad answer, continuous evaluation tracks live quality without attributing it, scheduled evaluation on a fixed dataset detects drift, and scheduled red teaming re-probes risk. The loop closes by turning each diagnosed failure into a regression case and re-baselining after change.
Sources and freshness
Written against current Microsoft Learn documentation for the AI-103 skills measured (16 April 2026), reviewed 2026-08-20. Microsoft Learn controls every changing product contract — availability, preview status, quotas, limits, regional support, naming, and retirement dates all move independently of this lesson. Where a scenario turns on a specific number or a GA/preview boundary, confirm it against the product's own page before relying on it.