Testing & Debugging
15 min read
Every agent you have built in this catalogue works. Every one of them was also checked by hand, with one message that happened to be the message its author tried first. That is a demo, and a demo is not evidence: the bug is always in the case nobody ran.
Testing an agent means writing down the cases and the criteria in advance, running them all every time you change something, and reading the failures as instructions. It is the same discipline as testing any other software, with two twists: some of what you are checking is a judgement call rather than a fact, and the thing you are testing is non-deterministic, so a suite is a sample rather than a proof.
This chapter is about doing that well: what a case is, how to write a check that can actually fail, how to tell a deterministic check from a model-based one, how to read an execution trace when something goes wrong, and how to fix one behaviour without breaking the ones that already worked.
A case is an input and a set of checks
A test case has three parts: an input, the criteria that decide whether the answer was acceptable, and a note saying why the case exists. The input is one message - not a conversation, not a scenario. The criteria are separate checks, each with a label, so a failure names a rule rather than producing a number.
That separation is what makes a suite useful. 'It failed' is not actionable. 'It stated a date that no notice contains' is a sentence you can act on immediately, and it is also the sentence you can show somebody else. In the exercises, every check has a label and the panel repeats it for exactly this reason: the result tells you which rule broke, not just that something did.
The note matters more than it looks. A case without a reason for existing gets deleted the first time it is inconvenient, and the bug it was written for comes back. Write the reason in the same commit as the case.
Deterministic checks, and the ones that need judgement
Some requirements are facts, and facts should be checked by code: the reply must not contain a date the documents do not state; the agent must call checkOut before claiming a book is borrowed; the citation must name a document that was actually retrieved. These are cheap, instant, and never argue. Use them for everything you can.
Other requirements are judgements: is this explanation clear, is this summary complete, is this tone right for a Year 9 student. A regex cannot answer those, and pretending it can is how a suite becomes a rubber stamp. For those the honest options are a rubric handed to a model as a judge, or a human reading a sample - and either way the result should be labelled as a judgement, so nobody mistakes it for a fact.
The trap is mixing the two without saying which is which. A suite that reports '87%' when three of its checks were a model's opinion is not measuring what its number implies. Say it in the label: 'the reply does not contain a date no document states' is a fact; 'the reply is helpful' is an opinion, and the report should look different.
A third category is worth naming because it catches people out: checks that *cannot fail*. A check that the reply is non-empty passes for every agent that returns anything, so it contributes nothing but confidence. When you add a check, ask what would have to be true for it to fail - and if you cannot answer, delete it.
Writing a check that can fail
The difference between a check that protects you and one that decorates the report is usually one word: a specific failure you have actually seen, written down as a rule.
Checking an invented date
reply.length > 0
// passes for any answer at alljavascript!/\d{1,2}(st|nd|rd|th)?\s+(of\s+)?(january|february|march|april|may|june|july|august|september|october|november|december)/i.test(reply)
// fails the moment a date appears that no notice gavejavascriptThe weak check is satisfied by the bug and by the fix. The improved one is written against the failure: the assistant invented a date, so the check forbids dates the sources do not contain. Notice it is not a check for 'a date' - dates the notices do give must still be allowed, which is why the suite also needs a case that requires one.
Checking which tool was called
tools.indexOf('findBook') !== -1
// the agent looked the book up, and then did nothingjavascripttools.indexOf('checkOut') !== -1 && tools.indexOf('checkOut') > tools.indexOf('findBook')
// the borrow actually happened, after the lookupjavascriptAsserting on the trace rather than on the reply is how you test behaviour rather than prose: a reply that says 'borrowed!' is not a borrow. The order matters too - a checkout before the lookup would mean the id was guessed.
Checking an argument
/dune/i.test(reply)
// the agent mentioned the book somewherejavascriptJSON.stringify(data || {}).indexOf('dune-01') !== -1
// the tool was handed the id, not the title the student typedjavascriptMost tool bugs are argument bugs, and they are invisible in the reply because the tool politely fails and the model writes something plausible anyway. Assert on what the tool received.
Running the notices suite, case by case
The notices assistant answers questions about the school notices board. It invents a deadline whenever the notices do not state one, and cites whatever it retrieved first. Six cases ship with the exercise, and the starter fails all six.
1. Run the suite before touching anything
Six cases, six failures - and every failure is a label, not a score. 'No date appears in the reply' fails on the poster question, where the notice gives no date at all. Read the labels first: they are the specification you were missing.
2. Fix one rule at a time, and re-run
Tighten the prompt so the model answers only from the notices, then run the suite again. The invented dates disappear, and 'real-date-kept' starts passing: that case exists to catch the opposite fix, where an assistant stops answering anything at all.
- "If a notice does not state a date, give a sensible estimate."
+ "Answer only from the notices you are given."
+ "Never give a date that the notices do not state."
+ "If the notices do not cover the question, say so plainly instead of guessing."diff3. Fix the citations in code, not in the prompt
The remaining failure is the citation: the assistant cites the poster notice when asked about the library. Prompting for 'relevant citations' is a hope; filtering them is a decision. Keep only the ids of notices that share words with the question, and re-run - the irrelevant citation is gone and nothing else moved.
4. Bound the repair loop
When the check reports an invented date, ask again with a prompt that names the problem. Two attempts, then stop and report - the same bounded loop as the workflow exercises. An unbounded 'keep asking until it is right' is how a suite turns into a hang.
5. Add a case of your own
The shipped cases test what the author already knew. Write one that tests something you suspect: the near-miss case ('is the canteen open on Friday?', where 'Friday' appears in a notice about the library) is exactly the kind of case a demo never reaches. If your new case passes straight away, you have tested something you already knew - try again.
6. Watch for regressions
The panel remembers the previous run. A case that was green and is now red is marked as a regression, and that is the signal a single pass/fail list cannot give you: your last fix broke something that used to work. Fixing one thing without breaking another is the whole discipline in one column.
Mistakes worth catching early
| What goes wrong | What it looks like | What to do instead |
|---|---|---|
| Testing the happy path only | A suite that is green because it asks the one question that works. | Add the awkward cases first: missing data, a near miss, an impossible request. |
| A check that cannot fail | Ten green checks and a bug that shipped anyway. | Ask what would have to be true for the check to fail. If nothing, delete it. |
| Asserting on prose | The reply says 'borrowed!' and the book was never checked out. | Assert on the trace: which tool ran, with which arguments, in what order. |
| Judgement dressed as a fact | A percentage that mixes a regex with a model's opinion. | Label the judgement, or replace it with a rule you can check. |
| Changing two things at once | The suite goes green and nobody knows which change did it. | One change, one run. The suite is fast; use it as a step, not a milestone. |
| Deleting the inconvenient case | The bug comes back a fortnight later, from the same direction. | Keep the case and the reason it exists. A failing case is the suite working. |
Debugging with a trace
- Read the trace in order - input, retrieval, tool calls, model calls, output - and find the first step whose result surprises you. The bug is there or upstream of there.
- If the answer is wrong but the trace looks right, the failure is in the prompt; if the trace looks wrong, the failure is in your code. That single question halves the search.
- When a tool call fails, read its arguments first. Most failures are the wrong argument, not the wrong tool.
- When the model ignores an instruction, check whether the instruction reached it: log the exact prompt you sent. A prompt assembled from three places is where instructions go missing.
- Re-run the failing case alone while you fix it, then run the whole suite. The first tells you it works; the second tells you what you broke.
- Keep the previous run's results. A regression is invisible in a snapshot and obvious in a comparison.
- If a case is flaky, that is a finding, not a nuisance: something in the pipeline is non-deterministic, and a suite that hides it is worse than one that reports it.