Most agent frameworks ship with a retry default: if a call fails, wait a fixed interval and try again. That default is a reliability feature inside a single program. In a multi-agent workflow it is a governance problem, because a retry is not free and it is not neutral — it spends against a plan, it can repeat an action whose side effects already happened, and it can quietly re-attempt work that was blocked on purpose. A developer once documented a runaway agent loop burning over $700 in 72 hours with no budget controls. Nothing about that incident required a sophisticated failure. It required a loop, a retry, and the absence of a policy that said when trying again is allowed. This AI agent timeout and retry policy template draws that line before production does it for you.
What a timeout actually bounds¶
A timeout bounds one thing well: how long a single step may run before it is stopped. Set per step, not per whole run, it keeps one slow tool call from consuming the plan's entire time window, and it gives you a clean point at which to record what happened.
A timeout does not bound any of the things that actually hurt:
- It is not a spend limit. A step can time out cheaply or expensively; only a per-plan cost ceiling, counted in real time, bounds what a run may spend.
- It is not an attempt limit. A timed-out step can be retried once or a thousand times. The timeout says nothing about which.
- It is not evidence. A timeout does not tell you whether the underlying action partly succeeded, was blocked for missing evidence, or should never run again without a human decision.
So a timeout is the smallest bound in the stack, not the policy. It has to sit inside the wider plan bound — identity, grants, data class, time window, egress, storage, cost ceiling, and expiry — and the retry rules have to know about all of them.
The retry decision: three kinds of failure¶
The core of the policy is a classification. Every failure lands in one of three classes, and each class has a different retry rule.
Transient failures are retryable, inside the plan. A network hiccup, a temporary service outage, a step that timed out before producing side effects — these may be retried up to a named maximum number of attempts, with a named backoff, while the plan is unexpired and spend remains under its ceiling. Each attempt is counted and recorded like any other action.
Bound failures are not retryable until the evidence changes. The plan hit its cost ceiling, the plan expired, a grant is missing or expired, required approval evidence is absent. Retrying changes none of those facts — a timer is not evidence. The action fails closed: it is blocked, the block is recorded with its exact reason, and it stays blocked until new evidence arrives: a raised ceiling approved by a human, a reissued grant, a fresh plan. When a ceiling is reached, the blocked action is never retried automatically.
Hard-gated failures are never auto-retried. Money movement, accepting contracts or terms, external outreach, reading or transmitting credentials, changing agent permissions, and actions with legal consequences always require a recorded human approval, and the acting agent can never approve its own action. A retry loop that re-presents a hard-gated action until it slips through has converted a gate into a suggestion. These actions wait for a human decision; a denied or missing approval produces a recorded block, never a silent retry.
Treat a ceiling hit the way the third class treats a missing approval and the $700 loop becomes structurally difficult: the loop exhausts its own plan, the next attempt is blocked and recorded, and the block — not another spend — is what reaches the owner.
The fill-in template¶
Copy this into your repo or wiki, fill every bracket, name an owner, and set an effective date. A template with brackets still in it is a draft, not a policy.
TIMEOUT & RETRY POLICY — [TEAM NAME]
Version [VERSION] · Effective [DATE] · Owner: [POLICY OWNER]
1. Every step carries a timeout of [STEP TIMEOUT]. Timeouts are set per
step, never only per run, and must fit inside the plan's time window.
2. Transient failures may be retried up to [MAX ATTEMPTS] attempts with
[BACKOFF — e.g. exponential backoff starting at X seconds].
3. Every retry counts against the plan's cost ceiling of
[AMOUNT] [CURRENCY] per plan, counted in real time. There is no
separate, uncounted retry budget.
4. When a ceiling is reached or a plan passes its expiry
([EXPIRY RULE]), the action FAILS CLOSED: blocked, recorded as
blocked, and never retried automatically.
5. A blocked action may be attempted again only when new evidence
exists — [EVIDENCE LIST: e.g. approved ceiling raise, reissued
grant, recorded human approval]. A retry requires new evidence,
not a timer.
6. Hard-gated actions ([HARD-GATED LIST]) are excluded from automatic
retry entirely. Each attempt requires its own recorded human
approval under the Hard-Gated Action Policy.
7. Every attempt — first, retried, timed out, or blocked — writes an
audit row. Blocked and rejected rows carry the exact reason.Setting the timeout itself¶
Four practical rules keep timeouts honest. First, set the timeout per step: a research fetch, a model call, and a file write have different normal durations, and one run-level number is either too long for the fast steps or too short for the slow ones. Second, tie the timeout to the plan: the step timeout, the plan's time window, and the plan's expiry are one decision, and a step that would finish after expiry should not start. Third, a timed-out step writes an audit row with the reason, like any other outcome — a timeout that leaves no row is a gap in the evidence exactly where an incident is most likely to start. Fourth, if your framework has no native budget or timeout controls, run it behind a meter so spend is at least counted against the plan in real time; unmetered execution is where retry loops do their damage unseen.
How retries interact with spend ceilings and audit rows¶
Retries and ceilings meet at one rule: a retry is an action, so it is counted, gated, and recorded as one. Spend counting does not pause because the previous attempt failed — the failed attempt already spent its tokens, its calls, and its time, and the retry spends again on top. That is why the ceiling in the template applies per plan with no separate retry budget: a "free" retry budget is a second, invisible ceiling that doubles the first.
The audit trail is what makes the policy checkable. Every request, approval, block, and outcome writes a hash-linked audit row, and blocked or rejected rows require a reason. Read back after an incident, those rows answer the only questions that matter: how many times did the agent try, what did each attempt cost, which bound stopped it, and what evidence — if any — justified the next attempt. If the rows cannot answer that, the retry policy existed on paper only.
Before you ship the policy¶
- Every failure class — transient, bound, hard-gated — has a named retry rule, and no class falls through to a framework default.
- Max attempts and backoff are numbers in the policy, not settings nobody remembers choosing.
- Every plan the policy covers has a per-plan cost ceiling and an expiry, and retries count against both.
- Blocked actions are never retried automatically; a retry requires new evidence, not a timer.
- Hard-gated actions are excluded from automatic retry, and raising a ceiling to let a retry through is itself a hard-gated approval with a recorded reason.
- Missing evidence — identity, grant, approval, budget headroom — produces a block with a reason, never a warning that work proceeds past.
- Every attempt writes a hash-linked audit row, including timed-out and blocked attempts.
- The policy names its owner, and the owner is the person the block notification reaches.
If any line is missing, the default you ship is the framework's default — retry on error, forever, at your expense. The Governed Agent Mesh Playbook — Studio Edition gives you the full system this template plugs into: the six policy templates (identity, grants, hard-gated actions, spend limits and expiry, fail-closed blocks, audit-row retention), the plan-bound and audit-row JSON schemas, the risk-tier classification worksheet, and the 14-day rollout that installs them in order. Set the retry policy while the loop is still hypothetical, and it stays that way.