Sort by Symptom First, Then Find the Cause: A Triage Logic for Single Agents
Once a single AI agent goes to production, the most common pain is not the whole system going down—it is the agent occasionally giving absurd answers, getting stuck at a step, or failing to call external services, usually with no clear error stack to inspect. Failures are more frequent than most teams expect: τ-bench, published by the Sierra team in 2024, tested agents in simulated customer-service scenarios and found that even the strongest function calling agent at the time (GPT-4o) succeeded on less than 50% of tasks; AgentBench (ICLR 2024), from Tsinghua University and partner institutions, evaluated agents across 8 environments and likewise concluded that weak long-horizon reasoning and poor instruction following are the main obstacles to usable LLM agents. Instead of debugging from scratch every time, classify the failure by symptom first, then match it against common causes and fixes to narrow the scope fast.
This article does not cover incident severity levels or postmortem processes, nor multi-agent collaboration. It focuses only on the most common execution-level failures of a single agent, organized into three lookup tables of "symptom, likely cause, first response": hallucination and output quality, API and external dependencies, and deadlock and control flow. Treat it as a field manual for stopping the bleeding: restore the agent to a usable state first, then work on the root cause.
Hallucination and Output Quality: The Answer Looks Right but Is Made Up
This is the hardest failure class to detect: the program throws no error and the response reads fluently, yet the content is fabricated. And do not expect a model swap to cure it—Vectara's Hallucination Leaderboard uses HHEM to score whether a model's summary stays faithful to the source text. In the April 2025 edition, the best performer, Gemini 2.0 Flash, had a hallucination rate of just 0.7%; but after the November 2025 switch to a larger, harder domain-specific dataset, rates rose sharply across all models, with the leader only reaching 3.3%. If even a grounded task with source text available cannot reach zero, open-ended Q&A will only be worse. Format problems, by contrast, have a mature engineering fix: evaluations OpenAI published with the launch of Structured Outputs in August 2024 showed that models asked to produce complex JSON via prompting alone complied less than 40% of the time, while GPT-4o with schema-constrained decoding reached 100%. The first diagnostic step is to determine whether the problem is factual correctness or output structure—the responses differ completely.
| Symptom | Likely Cause | First Response |
|---|
| Fabricates nonexistent data or citations | No retrieval grounding, temperature too high, prompt does not allow "I don't know" | Add RAG retrieval and source attribution; require citations; lower temperature |
| Output format intermittently breaks (malformed JSON) | No structured output; model free-forms | Switch to function calling / JSON schema constraints; add output validation and retry |
| Answers off-topic or ignores instructions | Key instructions diluted inside overly long context | Trim and front-load key instructions; decompose the task; shorten each context |
| Same input, drifting inconsistent answers | Temperature too high, parameters not pinned | Lower temperature and pin parameters for consistency-critical tasks |
API and External Dependencies: The Agent Is Not Broken—What It Depends On Is
Agents almost always call LLM APIs, external tools, or internal services, and jitter in these dependencies is easily misdiagnosed as a problem with the agent itself. Dependency failure is the norm, not the exception: a 2025 empirical study published at ACM ICPE analyzed public incident records of major LLM services and found a median time-to-recovery of about 1.23 hours for the OpenAI API and about 0.77 hours for the Anthropic API—a single upstream incident often lasts tens of minutes or more, retries alone will not carry you through, and a degradation plan is mandatory. Official engineering practice reflects this reality: both OpenAI's and Anthropic's SDKs ship with built-in exponential-backoff auto-retry (2 retries by default) for timeouts, 429s, and 5xx errors—effectively treating "upstream will fail" as the default assumption. The diagnostic key is to separate the agent's reasoning from the things it calls, and confirm whether the error occurs before or after the request goes out.
| Symptom | Likely Cause | First Response |
|---|
| Intermittent timeouts | Upstream API latency, network jitter, oversized single prompt | Set sane timeouts and exponential-backoff retry; split long prompts |
| Sudden flood of 429s / throttling | Excessive concurrency, no rate control | Add rate limiting and a request queue; spread requests; request higher quota |
| Tool response format changes break parsing | Third-party API updated, missing fields | Schema-validate tool output; add defensive parsing and fallbacks |
| Cost or latency suddenly spikes | Retry storm, ever-growing context | Monitor token usage; cap retries; periodically compact conversation history |
Deadlock, Loops, and Control Flow: The Agent Freezes or Never Stops
Once an agent can autonomously call tools and reason over multiple turns, it can end up unable to stop. This is not an edge case: AgentBench's error analysis shows that "exceeding the turn limit" is the dominant failure mode, accounting for 67.9% of failures in the knowledge-graph tasks, caused precisely by circular behavior and long-horizon planning without backtracking. A 2026 arXiv study, "When Agents Do Not Stop," went further, statically scanning 6,549 open-source LLM agent projects and confirming 68 infinite-loop defects across 47 projects—the largest categories being unbounded retries and unbounded tool-call iteration, with API cost exhaustion and denial of service as the dominant impacts. The business cost of this failure class is tokens burned on idle spinning and users left waiting; but compared to hallucination it has one advantage: the symptoms are obvious and easy to catch in monitoring.
| Symptom | Likely Cause | First Response |
|---|
| Repeatedly calls the same tool, stuck in an infinite loop | No step cap; model misjudges the task as unfinished | Add max step/turn limits; define "done" explicitly |
| Freezes at a step with no response | Blocking tool call; waiting on an external response with no timeout | Set a timeout on every tool call; abort on expiry |
| Two tasks waiting on each other (deadlock) | Shared-resource contention; locks never released | Order and time-limit resource access; avoid holding locks long |
| Inconsistent state after mid-run interruption | No checkpoints; failures not rolled back | Introduce idempotent design and checkpoints; make failures safely replayable |
Three Questions to Localize a Fault—and Turn It into a Reusable Playbook
When a new failure appears, localize it with three questions. First: is this an output-content problem or an execution-flow problem? Second: does the error live in the agent's own reasoning, or in an external dependency it calls? Third: does the same input reproduce it consistently? The third question matters most, because agent failures are often probabilistic—τ-bench introduced the pass^k metric for exactly this, measuring the probability that all k consecutive runs succeed, and found GPT-4o passed 8 consecutive runs of the retail customer-service tasks less than 25% of the time. One success is far from reliability. Answer these three questions and you can map the failure to one of the classes above and apply the response directly—provided the agent has sufficient observability, logging every tool call, input, output, and token count; without that, even the best lookup table has nothing to match against.
More importantly, feed every diagnosed symptom and fix back into your team's own lookup table, so incident handling keeps getting faster and the same pit is never stepped in twice. Nerdtechnic provides AI adoption consulting and custom system development, helping companies build observable logging, fault lookup tables, and reliability design for single agents—so that an AI in production does not just run, but keeps running reliably for the long term.
References
- Sierra (Yao et al.), "τ-bench: A Benchmark for Tool-Agent-User Interaction in Real-World Domains," 2024. Source
- Liu et al. (Tsinghua University and collaborators), "AgentBench: Evaluating LLMs as Agents," ICLR 2024. Source
- Vectara, "Hallucination Leaderboard," April 2025 snapshot, 2025. Source
- Vectara, "Introducing the Next Generation of Vectara's Hallucination Leaderboard," 2025. Source
- OpenAI, "Introducing Structured Outputs in the API" (as reported by Okoone), 2024. Source
- Chu et al., "An Empirical Characterization of Outages and Incidents in Public LLM Services," ACM ICPE 2025. Source
- OpenAI, "OpenAI Python API Library" official docs (default retry behavior). Source
- Anthropic, "anthropic-sdk-python" source code (DEFAULT_MAX_RETRIES). Source
- Hou et al., "When Agents Do Not Stop: Uncovering Infinite Agentic Loops in LLM Agents," 2026. Source
Technical Sharing
