Module 10 — Evaluation, Observability & Debugging 📊

Goal of this module: Learn how to tell whether your agent is actually good, how to watch what it’s doing (observability), and how to debug it when it misbehaves. This is the difference between a demo that works once and an agent you can trust.

10.1 Why this matters

It’s easy to build an agent that works once, in a demo. It’s hard to build one that works reliably, on real users, again and again. The only way to know if your agent is genuinely good is to measure it — not just eyeball one lucky run.

Hard truth: “It worked when I tried it” is not evidence. Agents are non-deterministic (the same input can give different outputs), so you need real evaluation, not vibes.

This module has three parts:

Observability — seeing what the agent did.
Evaluation — scoring how well it did.
Debugging — fixing what went wrong.

10.2 Observability: seeing inside the agent

Observability means being able to look at everything the agent did — every thought, every tool call, every result — so nothing is a mystery black box.

For each agent run, you want to log (record):

The input (the user’s request)
Each thought (the reasoning at each step)
Each tool call (which tool, what inputs)
Each observation (what the tool returned)
The final output
Tokens used, time taken, and cost

RUN LOG (a "trace")
─────────────────────────────────────────────
 Input: "Cheapest flight to London Friday?"
 Step 1 ▸ Thought: "Search flights"
         Action: search_flights(dest="London", date="Fri")
         Observation: [12 flights...]   (0.8s, 320 tokens)
 Step 2 ▸ Thought: "Pick cheapest"
         Action: none
         Observation: —
 Output: "£90 at 7am."   (total: 1.4s, 540 tokens, $0.01)
─────────────────────────────────────────────

This full record of one run is called a trace. Tools that capture traces (LangSmith, LangFuse, Helicone, and others) are called observability or tracing tools. When something goes wrong, the trace tells you exactly where.

Beginner habit to build early: Log everything from day one. You cannot fix what you can’t see. A printed-out trace is your best friend.

10.3 Evaluation: scoring how good the agent is

Evaluation (eval) means measuring the quality of your agent’s output, ideally with numbers, across many examples. There are a few ways to evaluate.

(a) Did it get the right answer? (correctness)

For tasks with a known correct answer, compare the agent’s output to the expected one.

Math problems, factual lookups, classification: check if it matches.
Build a test set: a list of inputs paired with their correct outputs, and run the agent on all of them, then count how many it gets right. This is your accuracy.

Test set:
  "2+2?"               → expect 4   → got 4   ✅
  "Capital of Japan?"  → expect Tokyo → got Tokyo ✅
  "15% of 240?"        → expect 36  → got 35   ❌
  Score: 2/3 = 67% accuracy

(b) Did it follow the right process? (trajectory)

For agents, how it got the answer matters too. Did it use the right tools in a sensible order? Did it loop? Did it waste 10 steps? You evaluate the trajectory (the path), not just the final answer.

(c) Quality without a single right answer (LLM-as-judge)

Many tasks (writing, summarizing) have no single correct answer. A popular technique is LLM-as-judge: use another LLM to score the output against criteria (“Is this summary accurate, clear, and complete? Rate 1–5”).

✅ Scales to fuzzy tasks.
❌ The judge can be wrong too — spot-check it against human judgment.

(d) Human evaluation

Have real people rate outputs. The gold standard for quality, but slow and expensive. Use it to calibrate your automated evals.

10.4 What to measure (key metrics)

Beyond correctness, track these for a real agent:

Success rate: % of tasks completed correctly. The headline number.
Steps per task: Fewer is usually better (efficiency). Watch for runaway loops.
Latency: How long does it take? Users hate waiting.
Cost: Tokens/dollars per task. Multi-step agents can get expensive fast.
Tool-call accuracy: Did it pick the right tool with the right inputs?
Failure modes: How does it fail when it fails? (Loops? Wrong tool? Hallucination?)

A great agent isn’t just accurate — it’s accurate efficiently and affordably, and it fails gracefully.

10.5 Building an eval set (do this!)

The single most valuable practice: build a collection of test cases for your agent.

1. Collect 20–100 realistic example tasks your agent should handle.
2. For each, note the expected outcome (or quality criteria).
3. Run the agent on all of them.
4. Score the results (correctness, steps, cost).
5. Every time you change a prompt/tool, RE-RUN the eval set.

Why it’s powerful: when you tweak the agent, the eval set tells you instantly whether you improved it or broke it. Without it, you’re guessing. This is called catching regressions (things that used to work but now don’t).

Expert mindset: Treat your agent like software with a test suite. Change → run evals → check the score. Don’t ship changes on vibes.

10.6 Debugging: fixing what’s broken

When an agent misbehaves, use its trace to find the failure point. Common bugs and their usual causes:

Symptom	Likely cause	Where to look
Wrong final answer	Bad reasoning, or bad tool result	The trace — find the wrong step
Agent loops forever	No step limit; repeats same action	Add max-step cap; check why it repeats
Uses wrong tool	Vague tool description	Rewrite the tool description (Module 4)
Tool call crashes	Bad inputs or no error handling	Validate inputs; return clear errors
Ignores retrieved info	Too much context, or bad retrieval	Improve RAG; retrieve fewer, better chunks
Hallucinates facts	No grounding	Add/force tool use; tighten the prompt
Inconsistent results	Temperature too high	Lower temperature (Module 2)

The debugging recipe is always the same:

1. Reproduce the failure.
2. Open the trace and read it step by step.
3. Find the FIRST step that went wrong.
4. Form a hypothesis about why.
5. Fix it (prompt? tool? retrieval? limit?).
6. Re-run the eval set to confirm you fixed it without breaking others.

10.7 The improvement loop

Building a good agent is iterative. The whole cycle:

   Build/change agent
          │
          ▼
   Run on eval set  ◄─────────┐
          │                   │
          ▼                   │
   Observe traces & scores    │
          │                   │
          ▼                   │
   Find weaknesses → fix ─────┘

Round and round. Each loop, the agent gets a little better and a little more reliable. This loop is the real work of building agents — the first version is never the final one.

10.8 Common mistakes

Mistake	Result	Fix
No logging/tracing	Bugs are mysteries	Log everything from day one
Testing on one example	False confidence	Build a 20–100 case eval set
Only checking final answer	Miss bad/inefficient process	Evaluate the trajectory too
Trusting LLM-as-judge blindly	Hidden errors	Spot-check the judge with humans
Ignoring cost/latency	Slow, expensive agent	Track steps, tokens, time
Changing things on vibes	Silent regressions	Re-run evals after every change

10.9 Check yourself ✅

What is a “trace” and why is it useful?
What is an eval set, and why should you re-run it after every change?
What is “LLM-as-judge” and what’s its main risk?
Besides correctness, name two metrics worth tracking for an agent.

Answers

A trace is the full recorded log of one agent run (inputs, thoughts, tool calls, observations, output, cost). It shows exactly where things went wrong.
An eval set is a collection of test tasks with expected outcomes; re-running it after changes tells you whether you improved or broke the agent (catches regressions).
Using another LLM to score outputs against criteria; the risk is the judge can be wrong, so you should spot-check it against human judgment.
Any two of: success rate, steps per task, latency, cost, tool-call accuracy, failure modes.

10.10 Summary

Observability = seeing everything the agent did via traces (logs of each thought/action/observation). Log from day one.
Evaluation = scoring quality across many examples: correctness (vs. expected answers), trajectory (the process), LLM-as-judge (fuzzy tasks), and human eval (gold standard).
Track success rate, steps, latency, cost, tool accuracy, and failure modes.
Build an eval set and re-run it after every change to catch regressions.
Debug by reading the trace to the first wrong step, fixing the root cause, and re-evaluating.
Building a good agent is an iterative improvement loop, not a one-shot.

Next up: Module 11 — Safety, Guardrails & Security. Powerful agents can do real damage; let’s make them safe. 👉 11_Safety_Guardrails_And_Security.md