DEV Community

AgentBasics
AgentBasics

Posted on

The 5 failure modes killing your AI agent (and the 10-line fix for each)

Every agent that calls external APIs meets the same five killers. Not model failures — plumbing failures. And they're the same five, in every language, for every framework, because they come from the network and the runtime, not the LLM.I got burned by all five in production (a 300-second runtime timeout that killed a 40-step run at step 41; an API that silently truncated "all 60 results" to 10 with no error; JSON cut mid-string by max_tokens; the same ValueError retried five times until a hard stop). So I extracted the fixes into five zero-dependency Python modules. MIT core: https://github.com/AgentBasicsHQ/agentops-autopilot## 1. The wall-clock killer (dies at step 41)The story: your agent runs fine for 40 steps, then the platform's 300s turn limit fires. Everything is lost. No partial work, no status, nothing.The fix: a turn budget shared across every call, with a reserve, and a ship-partial policy.

pythonfrom turn_budget import TurnBudgetbudget = TurnBudget(total_s=280, reserve_s=20)for step in plan: if not budget.can_afford(estimate_s=15): ship_partial(status="ran out of time", done=completed, remaining=plan[i:]) break do(step)

The rule that matters: reserve_s. Without a reserve you discover the deadline inside the last call, which is how you get zero output instead of 80% output.## 2. Silent API truncation ("all results" → 10 results, no error)The story: you ask an API for everything. It returns a page. No error, no "more available" flag you bothered to check. Your agent reports a confident, wrong number.The fix: semantic validation inside the retry wrapper — validate shape and count, not just "it returned".

pythonfrom resilient_call import resilient_callr = resilient_call( lambda: fetch_page(cursor), name="fetch_all", validate=lambda x: len(x["items"]) > 0 and "cursor" in x, retries=3, timeout=30,)

A validate= that encodes your expectation ("non-empty", "has next cursor", "count matches the header") turns a silent wrong-answer into a loud retryable failure. This one check is worth the whole module.## 3. Truncated JSON (max_tokens cuts mid-string)The story: the model returns 95% of a JSON document and stops. json.loads blows up, your retry loop re-asks the whole thing, you pay double, and sometimes the model truncates at exactly the same spot.The fix: a deterministic repair ladder — fence-strip, trailing-comma removal, Python-literal conversion, then bracket-closure for truncated docs — with an honesty report telling you which rung fixed it.

pythonfrom json_repair import repair_jsonobj, report = repair_json(llm_output)if report.rung == "truncation": # recovered what exists; re-ask ONLY the missing scope log.warning("truncated at %s; partial recovered", report.detail)

strict_json=True in resilient_call catches the same failure one level earlier: if your call returns a string that isn't valid JSON, the call fails instead of returning the broken string three steps downstream.## 4. The retry spiral (same failure, five times, then a hard stop)The story: a call fails. The retry logic retries. It fails identically — it's a ValueError, not a network flake — and burns your whole turn before the platform kills the run.The fix: two parts. (a) Retry an allowlist of transient classes, never a blanket except. (b) An anti-spin counter: if this exact (kind, step) failure has happened 3 times today, stop and escalate.

pythonfrom failure_journal import FailureJournaljournal = FailureJournal("logs/failures.jsonl")# inside the failure branch:if journal.same_failure_count_today(r.failure["kind"], step_name) >= 3: raise SystemExit(f"anti-spin: {step_name} failed 3x today — stop and report")

Bonus: journal.top_failures() gives you a ranked list of what actually breaks your agent, which is how you prioritize fixes instead of guessing.## 5. Silent context exhaustion (amnesia before the crash)The story: the context window fills gradually. Your agent doesn't crash — it forgets. Early instructions quietly vanish, and it hallucinates continuity. The crash is loud; the amnesia is silent, and it's worse.The fix: a pressure gauge with graduated actions, checked between steps.

pythonfrom context_pressure import ContextPressurecp = ContextPressure(model_window=128_000, system_overhead=3_000)cp.add("tool", tool_output) # every message goes throughmatch cp.action(): # leading indicator, not post-mortem case "prune_tool_results": cp.prune_tool_results(keep_last=5) case "summarize_oldest_turns": summarize_and_replace(oldest=8) case _: checkpoint_and_restart() # hard_stop_ship_partial

Pruning tool results (usually 70% of your tokens) buys back most of the window for free. Do it before the API returns a context error, not after.---## The boring synthesisNone of these are model problems. They're the same failure classes that network programmers solved decades ago — timeouts, budgets, backoff, validation, logging — re-applied to a system where the "network call" is an LLM and the failure modes include silent semantic truncation.All five modules are stdlib-only, Python 3.10+, 18-check test suite: https://github.com/AgentBasicsHQ/agentops-autopilot (MIT core).If you want the production templates (agent loop, cron pipeline, gateway wrapper, eval harness) + the 12-failure-mode runbook, that's the paid tier on the site — but the free core is genuinely useful on its own, and I'd rather you test it first.What failure mode am I missing? Genuinely asking — the runbook is a living doc and the next addition comes from comments.

Top comments (0)