---
title: "The Three Places an Agent Task Dies"
description: "Tell apart a missing doc, an unusable error, and an auth wall in an agent trajectory, and decide which failure to fix before you rerun."
canonical: "https://www.agentrail.co/blog/why-ai-agents-fail-tasks"
author: "Harsh Raj"
published: "2026-11-03T00:00:00Z"
last_updated: "2026-11-03T11:27:13.818Z"
---

# The Three Places an Agent Task Dies

Tell apart a missing doc, an unusable error, and an auth wall in an agent trajectory, and decide which failure to fix before you rerun.

![Three failed task cards on a dark green gradient, each marked with a red X: a gauge, a document, and a checklist](https://images.ctfassets.net/1htfyfnn1o5y/43dVa4cOHABWkAdNlcJ9Ci/d12f83e842a07bfa4fcad35c3939d3af/d3c1fe44-a31a-42e8-ab2c-2319cf313f63.png?w=1600&fm=webp&q=72)

Most failed agent tasks on a product die in one of three places: a missing doc, an unusable error, or an auth wall. The model may have planned poorly. The harness may have retried badly. On your side, the actionable stop is usually one of those three surfaces.

This page owns that diagnosis. Public benchmarks show that long-horizon agent tasks fail often. They do not tell you which of your pages or responses stopped the run. [Agent experience optimization](https://www.agentrail.co/blog/agent-experience-optimization) owns the edit once you can name the step. [How to measure agent experience](https://www.agentrail.co/blog/how-to-measure-agent-experience) owns the metric set around the stop. Here the job is to tell the three places apart and decide which one to fix before you spend another run.

> **Key Takeaways**
>
> • Write the stop as surface, action, and what the agent received before you open a pull request.
>
> • Benchmark success rates prove tasks are hard. They are not your product’s pass rate.
>
> • A missing doc means the needed fact was never fetchable in a usable form.
>
> • An unusable error means a call happened and the response could not steer the next attempt.
>
> • An auth wall means a gate stopped the task with a challenge a browser user might pass and an agent cannot.
>
> • Fix the earliest stop that made later steps impossible, then change that surface and rerun.

## A failed task is a stop you can name

A failed task is not a vibe. It is a moment in a trajectory. Name the surface (docs, SDK, API, MCP, website). Name the action (fetch, install, tool call, request). Name what came back (404, HTML login, opaque 400, empty body, wrong example).

[Agent journey analytics](https://www.agentrail.co/blog/agent-journey-analytics) is how those events become one task across website, docs, API, SDK, and MCP. The [dead step](https://www.agentrail.co/blog/how-to-measure-agent-experience) is the measurement name for that stop. Without the sentence, teams argue about “agents are flaky” and ship a new MCP server that the trajectory never touched.

Anthropic hit the same wall on their multi-agent research system. Users said agents missed information that looked obvious. The team could not tell bad queries from bad sources from tool failures until they had the production trace ([How we built our multi-agent research system](https://www.anthropic.com/engineering/multi-agent-research-system), 13 June 2025). Class the stop first. The class decides the edit.

[Agent analytics](https://www.agentrail.co/blog/agent-analytics) is the category practice for reconstructing those outside-agent tasks. This essay stays on the three product-side places that dominate actionable failures.

## Public benchmarks show failure is common; they do not diagnose your product

Scripted environments are useful because they make end-to-end failure visible. They are the wrong number to paste onto your dashboard as “why agents fail on us.”

[WebArena](https://arxiv.org/abs/2307.13854) (Zhou and colleagues) evaluates functional correctness of web tasks in a built environment. The best GPT-4-based agent in the paper reached an end-to-end task success rate of 14.41%, against human performance of 78.24%. Cite that pair as a 2023–2024 baseline on those tasks. Do not cite it as the rate of agents on your signup flow.

[OSWorld](https://arxiv.org/abs/2404.07972) (Xie and colleagues) evaluates open-ended computer tasks in real OS environments. Humans accomplished over 72.36% of the tasks. The best model in their reported evaluation reached 12.24% success, with primary struggles in GUI grounding and operational knowledge. That is a desktop-and-app baseline. It is not a verdict on your OpenAPI.

[SWE-Bench Pro](https://arxiv.org/abs/2509.16941) stresses long-horizon software engineering. Under a unified scaffold, widely used coding models stayed below 25% Pass@1 in the paper’s reported evaluation, with GPT-5 at 23.3% as the highest score they cite in the abstract. Their failure-mode discussion includes wrong solutions, tool errors, syntax errors, and context overflow depending on the model. Useful as evidence that coding agents still break mid-task. Useless as your production [agent task completion rate](https://www.agentrail.co/blog/agent-task-completion-rate).

A later audit of computer-use benchmarks makes a second caution. Among 150 released trajectories scored as FAIL across five benchmarks, 15.3% of those FAIL verdicts were wrong (evaluator false negatives or broken tasks), and among genuine failures, verification and planning issues dominated execution errors ([How Benchmarks Mis-Score Computer-Use Agents](https://arxiv.org/abs/2607.28367), 2026). Even “failed” is sometimes a scoring story. On your product, prefer a stop you can re-check against state: the doc returned, the error body, the auth challenge.

None of these papers invents a house pass rate for Agentrail or for your API. They only justify the posture: assume the task can die, then find where.

## Place 1: the missing doc

A missing doc is a stop where the fact the agent needed was never available in a form it could fetch and use. The trajectory never loaded the right page, or it loaded a page that did not contain the fact.

Typical signs:

- The agent never requested the quick start, the auth guide, or the OpenAPI document that held the answer.
- It requested a URL that returned a directory listing, a marketing shell, or an outdated install path.
- The fact exists only after client-side rendering, so a plain fetch never sees it.
- An `llms.txt` is absent, empty of the job’s links, or too large to scan, so the evidence page never enters the path.

The diagnosis question is narrow. If the correct page had been fetchable markdown (or a linked contract) at the moment of the stop, would the next action have been possible? If yes, you have a missing-doc class stop. Finding the doorway is [agent discoverability](https://www.agentrail.co/blog/agent-discoverability). Making the map and the pages usable is documentation work. The fix itself belongs in [agent experience optimization](https://www.agentrail.co/blog/agent-experience-optimization). Do not rerun a preference or efficacy suite until the fact is on a URL the agent can open.

## Place 2: the unusable error

An unusable error is a stop where the agent did call your product and the response could not steer the next attempt. The call happened. The feedback failed.

Typical signs:

- A 400 or 422 with an opaque code and no correction.
- An HTML error page meant for a browser.
- A stack trace that names internal modules and no valid example.
- Repeated calls with the same invalid arguments, or a wrong-tool loop that never gets a clarifying signal.
- A huge payload that truncates mid-thought and leaves no instruction for a smaller request.

Anthropic’s guidance on tools is direct. When a tool call raises an error during input validation, engineer the error response to communicate specific, actionable improvements, not opaque codes or tracebacks ([Writing effective tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents), 11 September 2025). The same essay treats tool descriptions as prompt surface area. Lots of invalid-parameter errors usually mean the description or examples are thin. Lots of repeated calls usually mean pagination, filters, or defaults are wrong.

The diagnosis question: did the agent receive enough information to change the next call productively? If the body only said “invalid request,” you have an unusable-error stop even when the HTTP status was “correct” from an API-design textbook. Fix the contract of the response before you blame the model for retrying.

## Place 3: the auth wall

An auth wall is a stop where a gate blocked the task and the gate was illegible or impassable for an agent. Humans can click through a login form, solve a CAPTCHA, or copy a key from a dashboard. Agents often cannot.

Typical signs:

- 401 or 403 responses that return an HTML login page.
- OAuth or SSO flows that assume a browser session and a human click.
- Bot challenges or CAPTCHAs mid-docs or mid-API.
- API key creation that exists only in a JavaScript UI with no documented non-interactive path.
- A paywall interstitial that never states, in machine-readable form, what credential would unblock the call.

Separate a correct refusal from a broken wall. If the agent lacks permission and your response says which scope is required and how to obtain it, that can be a successful refusal under a terminal-state scheme. If the agent hits a silent challenge page and retries until the context fills, that is an auth-wall failure. Terminal-state language lives with the [measurement set](https://www.agentrail.co/blog/how-to-measure-agent-experience). The diagnosis here is whether the gate taught the next legal step.

## Which place to fix before you rerun

Fix the earliest stop that made later steps impossible. Order the three places by dependency.

1. **Missing doc first**, when the trajectory never had the fact. Improving an error body will not help an agent that never found the endpoint name.
2. **Auth wall next**, when the fact was available and a gate still blocked every privileged call. Clear error copy on a public endpoint will not unblock a key the agent cannot create.
3. **Unusable error when the call already happens**, and the feedback is what wastes the remaining budget.

If two stops appear in one trajectory, change one surface before you rerun. Microsoft’s AX practice holds profile and tasks fixed and changes one thing at a time so you can tell lift from noise. The same discipline applies after a diagnosis: one class, one edit, same tasks, then compare. How to make the edit is [agent experience optimization](https://www.agentrail.co/blog/agent-experience-optimization). Do not start that essay until the stop sentence is written.

| Place | How it looks | Fix before rerun |
| --- | --- | --- |
| Missing doc | Needed URL never loaded, or loaded without the fact | Publish a fetchable page or contract with the fact |
| Unusable error | Call returned; next attempt could not improve | Return a specific correction the agent can apply |
| Auth wall | Gate returned a human-only challenge or silent 401 HTML | Provide a machine-readable credential path or a clear refusal |

## Frequently asked questions

### Is a wrong recommendation the same as a failed task?

No. A wrong recommendation is a propensity miss: the agent named someone else on an unaided job. A failed task is an outcome miss on a job that engaged your surfaces (or should have). They can share a docs trail. They are different measurements.

### What if the agent never reached my product?

Then you do not yet have one of these three product-side stops. You have a discovery or preference problem upstream. Reconstruct nothing on your API until a fetch or a call exists. Preference design is a different tutorial.

### Do WebArena or OSWorld rates apply to my API?

No. Those rates use tasks the benchmark authors wrote and graders they defined. Your [task completion rate](https://www.agentrail.co/blog/agent-task-completion-rate) uses tasks that started on your product and an outcome rule you can re-check. Borrow the humility, not the percentage.

### How many times should I rerun after a fix?

Enough to see a stable pattern on the same agent profile. Microsoft’s working guidance for AX evals is at least five runs per scenario. Use more when the effect is small. One lucky success is not a diagnosis confirmed.

## Class the stop, then change that surface

Why AI agents fail tasks on your product is often simpler than a model paper suggests. The trajectory hit a missing doc, an unusable error, or an auth wall. Write that sentence. Fix the earliest place that blocked the rest. Leave the edit playbook to [agent experience optimization](https://www.agentrail.co/blog/agent-experience-optimization), and leave the scoreboard to the measurement set.

We reconstruct agent journeys across website, docs, API, SDK, and MCP so the stop is observable. Journeys include 100 free per organization per month, then $0.10 each. Readiness scans and ranked recommendations are included. Details are on [pricing](https://www.agentrail.co/pricing).