Diagnose and improve

Works out why an agent didn't do what you expected, and stages a fix as a version you test before it goes live.

Skills for your coding agent

Test and diagnose an agent

Ask your AI client#

The invoice exceptions agent registered a supplier query on INV-4471, and the contract allows that difference. Find out why, and save a fix as a new version for me to test. Don't activate anything.

Skill: mindset-test-agent

What you get back#

A named cause, the run that shows it, and a fix saved as a new version that isn't live. Saving puts nothing in front of people. Activating does, and that stays your call.

Which of eight things happened#

Start at the top. Most reports of "the agent is broken" are settled in the first three.

What you see	Usually	Fix
No output at all	It never ran	The trigger, not the agent. Check the schedule is on in the active version
It ran and nothing changed	A write is still pending approval, or a script's `$ask` is waiting on a person	Approve the write, or answer the question
It stopped part way	A phase's exit condition didn't hold, or the turn reached a limit	Reword the condition so a real answer can meet it. See Runs for limits
It finished and the answer is wrong	A condition can be met without the work	Tighten the condition so meeting it needs the work, such as naming a contract clause
It did something too early	That phase held the operation	Take the write operation off every phase except the last
An error naming an outside system	The credential expired, or is scoped too narrowly	Replace it on the connection, then run one read on its own
Plausible output built on wrong data	The connection points at the wrong account, or a function reads fields that don't exist	Check the account, then run the function on one invoice and see which step returns nothing
Right most times, wrong sometimes	Too much left to the model	Split the phase, say the number, add a judged gate where quality matters

When the answer is right and the numbers aren't: a slow tail on a connection the agent calls means the outside system is slow, and no prompt change fixes it. A high Avg input tok/call means it sends too much. See See and control cost.

What you decide#

Whether the cause is the one you'd stake the fix on. Change one thing at a time, or you won't know which fix worked.
Whether to stop it now. Withdraw approval on a write, or Disable on a connection, takes effect on the next call. See Approve what agents can do.
Whether to re-run a run that stopped part way. A write happens when it's called, so check what it already changed first.

Done when#

You named which of the eight it was before you changed anything.
The fix is a saved version, tested, then activated.
An acceptance test now covers the failure. Save as acceptance test on the session drafts one from the real conversation.

In the Studio#

Open the session in Log → Sessions and read Steps, the run record for that conversation. Make the fix by telling the Agent Builder, docked on every tab of the agent, what to change. Save as version records it, and Activate on Versions & Availability puts it live.