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

# Patterns

A common path: a Run failed, the failure is somewhere in the workflow graph, and you want the agent to triage it before you look at it yourself.

## How the agent diagnoses a failed Run

Given a Run UUID (or a Pipe name and cluster), the agent:

1. Calls `get_run` to fetch the Run's status, parameters, and overall metadata.
2. Calls `get_workflow_node` to walk the workflow node graph and identify the failed node(s).
3. Calls `get_run_logs` with a `nodeId` filter (and optional `grep` / `tail`) to pull the relevant log lines.
4. Reads the `pipekit://guides/debugging-a-failed-run` MCP resource if it needs to know more about how to interpret Argo node statuses.
5. Summarizes the root cause and suggests a remediation (re-submit with different params, fix YAML, escalate).

The agent never has to learn this flow from your chat. The MCP server ships with the guide as a resource, so the agent can fetch it on demand.

## Example: debug a Run by UUID

```
Run 266dfb27-0690-4ed3-bf53-26e9a96c6a87 just failed.
Look at it, find which node failed, pull the logs, and tell me what broke.
```

The agent will iterate through tool calls, possibly fetching the debugging guide too, and respond with a diagnosis.

## What the agent can't do (yet)

* Stream logs as a Run progresses. `get_run_logs` returns a snapshot. For live following, use the CLI's `pipekit logs -f` directly.
* Modify or re-author the failing workflow's YAML automatically. The agent can suggest changes, but you (or another tool call) need to re-submit.

## Permission notes

This pattern uses only read-only tools (`get_run`, `get_workflow_node`, `get_run_logs`). No approval prompt should fire in MCP-annotation-aware clients. For the full list of read-only tools, see [Tool Inventory](/ai/tool-inventory.md).