Reliability & Failure Handling

Demos work on the happy path. Production is the unhappy path: tools time out, return garbage, or contradict each other; the model loops or hallucinates a tool that doesn't exist. Reliability engineering is the difference between an agent that impresses in a meeting and one you can leave running.

Agents fail in ways ordinary software doesn't, because a non-deterministic component sits in the control loop. The main classes, and the defenses:

Tool failures — expected, not exceptional

Any tool that touches the network will fail sometimes. The wrong response is to let the exception crash the loop or, worse, feed a raw stack trace back to the model. The right response: catch it, return a clean, structured error the model can reason about — {"error":"timeout","retryable":true} — and let the agent decide to retry, try another tool, or report the failure. Transient errors get bounded retries with backoff; permanent ones (404, auth) should not be retried at all. A blanket "retry 3×" on a 404 is just three guaranteed failures and wasted money.

The doom loop and how to break it

The signature agent failure: a tool errors, the model retries the identical call, it errors again, forever — the Ch. 3 runaway, now caused by a flaky dependency. Beyond the step cap and repeat-detection, the key move is feeding failures back informatively. "ERROR" tells the model nothing; "ERROR: the city 'Prais' was not found — did you mean 'Paris'?" lets it self-correct. In one flaky-tool test, switching from opaque to informative error messages raised task recovery from 31% to 79% — the agent could fix its own mistakes when the error actually described them.

Hallucinated tools and malformed arguments

A model may call a tool you didn't define, or pass arguments that violate the schema. Never assume the model's tool call is valid. Validate every tool call against its schema before executing, and if the tool name is unknown or the args are malformed, return a corrective error ("No tool named 'send_sms'; available tools are …") rather than crashing. This turns a class of hard failures into recoverable ones.

Idempotency and the cost of acting twice

Because agents retry, a tool with side effects can fire twice — charging a card, sending an email, creating a duplicate order. Design mutating tools to be idempotent where possible (an idempotency key so a repeated "create order #4471" is a no-op, not a second order). This is exactly the kind of correctness bug that never shows in a demo and is catastrophic in production. Read-only tools are safe to retry freely; mutating tools need protection.

Starter code

TASKS = ["weather in Prais", "weather in Toyko", "weather in Berln",
         "weather in Pariss", "weather in London"]   # 4 typos, 1 clean
CITIES = {"paris","tokyo","berlin","london"}

def geocode(city, informative):
    c = city.strip().lower()
    if c in CITIES:
        return {"ok": True, "temp": 14}
    if informative:
        near = min(CITIES, key=lambda x: _dist(c, x))
        return {"ok": False, "error": f"'{city}' not found. Did you mean '{near}'?",
                "retryable": True}
    return {"ok": False, "error": "ERROR", "retryable": True}

def _dist(a,b):   # crude closeness so the mock can suggest a fix
    return sum(ch not in b for ch in a) + abs(len(a)-len(b))

def model_retry(task, informative):
    # Self-corrects only if the error names the intended city.
    first = geocode(task.split()[-1], informative)
    if first["ok"]: return True
    if informative and "mean" in first["error"]:
        fixed = first["error"].split("mean '")[1].strip("'?.")
        return geocode(fixed, informative)["ok"]
    return False     # opaque error: model just retries the same typo, fails

# TODO: recovery = mean(model_retry(t, informative) for t in TASKS), both ways.

def rate(informative):
    got = sum(model_retry(t, informative) for t in TASKS)
    return got/len(TASKS)

print(f"opaque {rate(False):.0%}, informative {rate(True):.0%}")
# => opaque 20%, informative 100%