> For the complete documentation index, see [llms.txt](https://docs.observal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.observal.io/use-cases/debug-agent-failures.md).

# Debug agent failures

AI failures rarely produce one reliable error code. Observal preserves the session transcript so you can inspect what the user asked, which tools ran, what results the harness recorded, and how the agent responded.

## 1. Find the session

Open `/traces` in the web UI or list recent sessions:

```bash
observal ops traces --limit 50
```

Filter by harness, agent, user, model, or time range. Select the session that matches the reported failure.

## 2. Inspect the event sequence

Expand the session to review prompts, assistant responses, tool calls, tool results, lifecycle events, and subagent activity in source order. The CLI can unfold the same session structure:

```bash
observal ops traces --turn --limit 10
```

Look for repeated tool calls, error results, missing inputs, unexpected model responses, or a stop event that occurred before the expected work completed.

## 3. Inspect recorded tool detail

The detail available for a tool call depends on the harness transcript. When present, Observal displays the tool name, input, result, and error indicators. Observal does not intercept MCP transport traffic or invent payload fields that the harness did not record.

## 4. Common patterns

| Session pattern                                          | Likely cause                                                                   |
| -------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Same tool called repeatedly with identical arguments     | The agent is stuck in a retry loop or is not consuming the result              |
| Tool result records an error and the assistant continues | Prompt or recovery policy did not handle the failure                           |
| Tool call has no matching result                         | Harness shutdown, interrupted process, or incomplete transcript delivery       |
| Session stops immediately after a prompt                 | Hook, model, permission, or harness configuration issue                        |
| Expected MCP call never appears                          | The model did not select the tool, or the harness transcript omits that detail |

## 5. Recover incomplete delivery

If the local harness still contains the session source, run:

```bash
observal reconcile
```

Reconciliation resumes from the acknowledged checkpoint and replays missing source records idempotently.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.observal.io/use-cases/debug-agent-failures.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.