A silent wrong output is treated as a failure, not a success.
Agent operations
Design a fallback path for a flaky tool
Classify how a dependency fails, decide what retries and what escalates, and write the runbook before the tool goes down at the wrong moment.
You are designing a fallback for a workflow that depends on [TOOL].
Inputs:
- Workflow: [WORKFLOW]
- Observed and likely failures: [FAILURES]
- Constraints: [CONSTRAINTS]
Work in this order:
1. Classify each failure: transient (retry likely works), degraded (slow or partial), hard down, or silent wrong output.
2. For each class, define: detection signal, retry policy with a cap, fallback, human escalation, and the data risk of each option.
3. Write what the user or client sees at each stage. “Internal error” is not a status.
4. Write a runbook: the commands or links a person needs, in order, with the decision point for stopping.
5. Define how to test the fallback with a simulated failure. Do not wait for a real outage to find out.
6. Name what should not be automated, and why.
Rules:
- Do not retry a non-idempotent write without an idempotency key or a manual check.
- Do not silently switch to a fallback that changes the meaning of the output. Label it.
- Do not invent a status page, an API limit or a support channel. Mark unknown values.
- Keep secrets out of logs, prompts and the runbook.
| Variable | What to put there |
|---|---|
[TOOL] | The dependency and what you use it for: model inference, payments, email, storage, search, a scheduling API. |
[WORKFLOW] | The steps before and after the tool call. The fallback has to preserve the contract at the boundary. |
[FAILURES] | What you have seen and what you fear: 429s, timeouts, partial writes, wrong model output, expired tokens. |
[CONSTRAINTS] | Latency budget, cost ceiling, data residency, client promise. These decide which fallback is acceptable. |
Run it
How to use this template
List the failures before the fallbacks. A fallback for the wrong failure is a new failure.
Define the detection signal first. If you cannot tell a slow call from a wrong answer, you cannot route it.
Cap retries and make them visible. Silent retries turn an incident into a mystery.
Test by injecting the failure in a staging environment. A runbook that has never been run is a guess.
Checks
Guardrails before you trust the output
Retries are capped and never applied to a non-idempotent write without a key.
Every fallback is labelled in the output.
The runbook contains no secret and has a named owner.
Adapt
Variations worth keeping
If the dependency is a model provider
Add a second provider only if you have tested the prompt on it. A fallback model that follows instructions differently can change the output more than an outage.
If the dependency is a payment or email service
Add a reconciliation step and a human check before resending. A duplicate charge or email is worse than a delay.
Why design the failure before the feature
A workflow that works on a good day is a demo. A workflow that fails visibly, retries safely and escalates to a person is a system. The difference is designed before the first outage, not during it.
The most dangerous failure is not the hard down. It is the silent wrong output: a plausible answer from a degraded model, a partial write that looks complete, an email that says it sent. Those failures need a detection signal, not just a retry.
What good looks like
The classification is short and specific. “Timeout after 10 seconds” is a signal; “the API is flaky” is a mood. The fallback is labelled in the output so a reader knows which path produced it.
The runbook fits on one page and names the person who decides to stop. If it needs a meeting to interpret, it is not a runbook.
Adapt it to your work
For a client workflow, agree the failure behaviour in writing before launch: what the client sees, who is called, and what is not retried. For a solo workflow, the runbook can be a note to yourself with the exact commands.
Failure modes
- Retry everything. Retries amplify a rate limit and can duplicate a write.
- Fallback changes the meaning. A cheaper model or a cached answer is not the same product. Label it.
- No test. The first real outage is a bad time to discover the fallback path is broken.
Related templates
This page is part of the free library.
The prompt is also in the Markdown mirror at
/prompts/design-a-fallback-path.md. If the scenario is close but not right, send the gap to the help desk with the output you expected.
Found a gap in the library?
Send the scenario, the prompt that failed, or the harness change that broke your setup. The help desk takes questions and corrections from humans and agents, and every accepted fix updates the page date.