Phase 7: AI Agents & Tool-Using Systems · 100 min · OpenAI Agents SDK tracing · LangSmith · Phoenix/Arize

Agent Evals, Observability, and MCP

If you cannot inspect the run, you cannot improve the agent.

Hiring signal: Can measure, debug, and integrate agents using production observability patterns

The Problem

An agent fails a user task. The final answer is wrong, but no one knows why.

Possibilities:

The model selected the wrong tool.
The right tool returned bad data.
The tool input was malformed.
The agent stopped too early.
The agent exceeded step budget.
A human approval was denied.
A prompt-injection string changed behavior.
The external API timed out.

Without traces and evals, every fix is a guess.

The Concept

Why Agent Debugging Is Different From Regular Debugging

When a regular program fails, you read a stack trace. The error tells you the file, line, and function where things went wrong. You reproduce the bug, set a breakpoint, inspect variables, and fix it.

Agent debugging is fundamentally different. An agent's behavior is path-dependent — the same input can produce different outputs because the model makes probabilistic decisions at each step. A query that works perfectly 9 times might fail on the 10th because the model chose a different tool, phrased a tool input differently, or interpreted an observation differently. You cannot reproduce failures by re-running the same query.

This means you need two things that regular programs don't need:

Observability — a complete record of every step the agent took, so you can replay the exact trajectory that led to a failure. Not just "the agent failed" but "the agent called tool X with input Y, got output Z, then decided to call tool W instead of stopping."

Evaluation — a systematic way to score agent behavior against expected outcomes, so you can measure whether changes improve or degrade performance across a test suite, not just on the one query you happened to look at.

What to Log: The Trace Event Schema

Agent observability records the execution path — every decision, every tool call, every observation:

Each node in this diagram is a trace event. A good trace records:

Model generation: what the model was prompted with, what it output, and which tokens were generated (for debugging reasoning)
Tool call: which tool was selected, what input was passed, and why the model chose it (from the model's response)
Tool output: what the tool returned, how long it took, and whether it succeeded or errored
Guardrail decision: whether any safety/policy check triggered and what it decided
Handoff/approval: whether a human was asked to approve, and what they decided
Final result: what the agent returned to the user

Without this level of detail, "the agent gave a wrong answer" is unactionable. With it, you can see exactly which step introduced the error.

What to Evaluate: Agent Quality Metrics

Agent evaluation scores the behavior against expected outcomes:

Did the task finish? (completion rate)
Did the agent pick the right tools? (tool selection accuracy)
Were tool inputs valid? (input correctness)
Did it stay within budget? (step count, token cost, latency)
Did it ask for approval when required? (policy compliance)
Did it avoid forbidden tools? (safety)
Did the final answer reflect tool outputs? (faithfulness/grounding)

Observability tells you what happened. Evaluation tells you whether it was good. You need both — traces without evals mean you can see failures but not measure them; evals without traces mean you know something is wrong but can't find the cause.

MCP (Model Context Protocol)

The Model Context Protocol is a standard way to expose tools to LLMs. Instead of writing custom tool integration code for each agent framework, you define tools once using the MCP specification, and any MCP-compatible client (Claude, Cursor, custom agents) can use them. MCP standardizes the tool description format, the input/output schema, and the transport layer (stdio, HTTP, SSE). This matters for observability because it gives you a consistent interface to log — every tool call goes through the same protocol, so your tracing code works across all tools without per-tool custom logic.

Your agent occasionally produces wrong answers but you can't reproduce the failure. Users report it "sometimes gets confused." What do you need to diagnose and fix this?

Agent failures are path-dependent — the same query can take different tool paths and produce different results. Without full traces (each model call, tool input/output, and decision point), you can't see WHERE the agent went wrong. Tracing lets you replay the exact failing trajectory, identify the bad step, and fix the specific cause (bad tool output, ambiguous prompt, wrong tool selection).

Unlock the full lesson

You've read the first 2 sections. The rest of this lesson covers Build It, Use It, Model Context Protocol, Ship It, Evaluation Metrics, Debugging Workflow, Common Mistakes, Common Pitfalls, Evaluation, Exercises, Key Terms, Interview Framing — plus a hands-on lab, quiz, and project artifact.

Create a free account to unlock Phase 0 and Phase 1 of every course — no credit card.