Agent bugs have a special flavor. The reply sounds fine. The customer thinks something happened. Your CRM says nothing happened. Somebody asks you to “check the AI,” which is about as precise as “check the internet.”
It got faster at this the day Start logging every tool call like you would log every SQL query in a sketchy service.
If you cannot see the tools, you are debugging folklore.
Why transcripts lie by omission
A transcript shows words. It does not show:
- which KB chunks were retrieved
- that calendar create returned 409
- that the model called the same tool four times
- that the agent skipped the tool and freestyled a confirmation
Words without tool traces are how you get confident ghosts.
What to log for each tool call
Minimum viable honesty:
- session id / conversation id
- turn number
- tool name
- arguments (redacted where needed)
- latency
- success / error / timeout
- response hash or truncated body
- model and prompt version
- retries
For retrieval tools, also log document ids and scores. “It used the knowledge base” is not a debug statement. “It used doc hours-downtown@v3” is.
Redaction is part of the design
Operators in regulated spaces cannot just dump everything into a DIY log viewer and call it culture.
I plan redaction up front:
- strip secrets and tokens
- mask phone numbers and emails in shared dashboards when possible
- keep raw payloads in a tighter access tier if needed for true incident work
- set retention that legal and security can live with
If logging feels unsafe, people turn it off. Then you are blind again. Design logs people are allowed to keep.
The weirdness patterns logs make obvious
Once you have traces, you see the greatest hits:
Looping. Model calls search, gets nothing, calls search again with the same args, burns tokens, apologizes eloquently.
Silent failure. Tool errors, model says “all set.”
Wrong tool, right vibe. Updates the wrong record because arguments were sloppy and validation was weaker than hope.
Hallucinated success. No tool call at all, but the sentence claims a booking exists.
Each of those has a different fix. Without logs you apply random prompt perfume to all of them.
How to debug a bad session
- Pull session by id
- Read the user turns and assistant turns
- Align tool events on the same timeline
- Ask: did it retrieve? did it write? did the write succeed?
- Reproduce with the same prompt version and similar inputs in staging
- Patch the smallest thing (schema validation, better error message to the model, retry policy, KB doc, prompt)
Refuse to start with a full prompt rewrite unless the logs say the reasoning itself is the bug. Often the bug is a 401 and a model trying to be “helpful.”
Make logs useful to humans at 1am
Store them where on-call already looks, or give them a tiny UI:
- paste session id
- see timeline
- expand tool payloads
- jump to related deploy / prompt version
Pretty graphs are optional. A readable timeline is not.
Feed failures back into evals
Every real incident becomes two fixtures:
- the conversation inputs
- the expected tool sequence and outcome
Next prompt change runs those fixtures. That is how you stop whack-a-mole.
If you only fix forward with vibes, the same ghost returns on a new model version wearing a new hat.
Cost and performance bonus
Tool logs also show you expensive stupidity: giant retrieved contexts, unnecessary calls, retries that should fail once.
Optimization without traces is mostly superstition. Optimization with traces is just engineering.
Bottom line
Agents are applications that talk. Debug them like applications.
Log the tools. Redact with intent. Timeline the session. Fix the smallest break. Promote the failure into an eval.
Do that and “the AI is being weird” turns into “the calendar tool timed out and the model fibbed.” One of those you can ship a patch for before lunch. The other one will haunt your standups forever.
