What to do when an agent fails: a non-technical decision tree

Start here: did anything leave the dashboard?

Before you classify anything, answer the root question of the tree: between starting the run and seeing the error, did the agent send, publish, pay, delete, or change a record in an outside system? That single fork decides your next move.

• Maybe, or you are not sure → stop the workflow. Do not retry yet. Open the activity log and the affected system, and reconcile what actually happened before you touch anything.
• Clearly no — it failed while reading, searching, or drafting → nothing has left your control, so you are safe to move to the next step and name the failure.

This ordering matters because retrying is only free when the action is idempotent—when doing it twice has the same result as doing it once. Reading a page is idempotent. Sending an email is not. How to judge it: if you cannot say for certain that a repeat would change nothing outside the dashboard, treat the answer as “maybe” and stop. Failure case: a payment run times out on the confirmation screen, the owner assumes it never went through and retries, and two charges land on the same customer. The timeout was a slow reply, not a failed action. The trade-off: stopping to reconcile costs a few minutes now; a duplicated irreversible action can cost an afternoon of apologies.

If nothing left the dashboard, name the failure

Once you know the run was safe, resist the urge to just rerun it. Most failures fall into one of five types, and each has a different smallest fix. Naming the type before you act is what stops you from changing five settings to solve one problem.

• Missing information: the task did not have an input it needed. Tell: the agent asks for something, guesses, or leaves a field blank.
• Expired connection: a linked account or tool lost access. Tell: the error names a service, or the same step worked last week and fails everywhere now.
• Unclear instruction: two reasonable readings of the task were possible. Tell: the output is confident but not what you meant.
• Temporary outage: an outside service was briefly unavailable. Tell: the error mentions timeouts or “try again,” and a later run just works.
• Unsafe request: the task tried to cross an approval boundary. Tell: the run stopped at a send, payment, or deletion and waited.

Why it matters: the fix for an expired connection (reconnect it) does nothing for a missing input, and vice versa. How to judge it: if you can point to the one tell above that matches, you have the type. Failure case: an owner reads “failed” as a bad instruction and spends twenty minutes rewriting a perfectly good task, when a linked mailbox had simply expired overnight. The trade-off: spending thirty seconds to classify feels slower than clicking retry, but it saves you from fixing the wrong thing.

Choose the smallest recovery — and change one thing

Each failure type has a matching, minimal recovery: reconnect the expired account, add the one missing input, clarify the single ambiguous rule, or simply wait before retrying an outage. Make that one change and rerun.

Why it matters: if you change the task, the model, the permissions, and the schedule all at once and the run succeeds, you have learned nothing—you cannot tell which change helped or whether the outage just ended on its own. Changing one variable at a time turns a lucky rerun into a repeatable fix. How to judge it: the recovery worked if the next run passes and you can name the single change that made the difference. Failure case: an owner swaps the model, tightens permissions, and rewrites the prompt together; the run works, breaks again next week, and now three suspects are tangled together. The trade-off: one change per run is slower on a stubborn problem, but every attempt teaches you something instead of adding noise.

Know when to stop instead of retry

Some failures should never be met with an automatic retry, even when the fix looks obvious. Stop and investigate by hand if the run may have produced any of these:

• A duplicate message or post that reached a person or the public.
• An incorrect or repeated payment, refund, or credit.
• A deletion or overwrite of a record that is slow to rebuild.
• Exposure of private data to the wrong recipient.
• An unexplained change to permissions or a connection you did not make.

Why it matters: these actions leave your control the instant they happen, so a second run does not fix the first—it repeats it. How to judge it: ask whether a person could undo the result in under a minute with no outside consequence; if not, it belongs on the stop list. Failure case: a nightly cleanup errors halfway, an automatic retry runs it again, and the second pass deletes records the first had already moved. The trade-off: a delayed result is visibly annoying, but it is far cheaper than a repeated irreversible action that you now have to reverse by hand.

Turn the failure into a rule

Recovery ends the incident; it does not prevent the next one. After the run is healthy again, add the one small guardrail that would have caught this exact failure: a required-input check before the task starts, an approval step before the risky action, a warning when a connection is close to expiring, or a cap on how many times a run may retry itself.

Why it matters: the same five failure types recur, and a rule you write once quietly handles every future instance so you are not doing triage at 7 a.m. again. How to judge it: a good guardrail turns the failure you just saw into a clear pause or a plain-language message instead of a red error. Failure case: an owner fixes the missing input by hand, adds no check, and hits the identical blank-field failure a month later on a busier morning. The trade-off: every guardrail adds a small amount of friction, so add them where a failure was costly or confusing—not on every step—and test each new rule once with a harmless example before trusting it.