Tool failure recovery
Tool failure recovery is the agent's pattern for handling tool calls that fail (the API returns 500, the auth token expired, the network timed out). A well-designed agent retries, falls back, or escalates to the user; a brittle one reports success when nothing happened.
Why it matters
Tool calls fail. APIs go down, tokens expire, network blips happen, downstream services rate-limit. A production AI agent has to assume tool calls fail at some non-trivial rate and design accordingly. Without explicit recovery patterns, the failure mode is silent: the agent calls the tool, gets an error, and either (a) reports false success, (b) silently drops the action, or (c) panics in a way the user cannot recover from.
Good recovery looks like:
- Retry with backoff for transient failures (timeouts, 5xx errors). One or two retries usually clears the issue.
- Refresh and retry for auth errors. If the token expired, refresh it and retry the call once.
- Fall back if the failure is structural. If a write tool fails, attempt the same action through a different tool or surface the failure clearly.
- Escalate to user if recovery is not possible. Tell the user the action did not happen; ask if they want to retry or do something else.
The anti-pattern: the agent narrates success ("I sent the invoice") while the underlying tool returned an error. This is one form of hallucination. The defense is mechanical: the agent's report should be derived from the tool's actual response, not from the agent's narration of intent.
How Ajeris handles this
Ajeris's agent loop treats tool failures as first-class events. Transient failures retry with backoff. Auth failures refresh tokens and retry. Structural failures (the tool says "no, this is not allowed" or "the resource does not exist") surface to the user with a clear explanation. Every tool call writes to the audit trail with success or failure status.
When an action queued for approval fails on execution, the user gets an SMS within seconds: "I tried to send the invoice but Stripe returned an error; want me to try again or do you want to do this from your phone?"
