Agent Step Failure Attribution Prompt Template

This prompt is built for agent developers and platform engineers who need to move beyond the surface-level symptom of 'the agent failed' and perform a structured, step-level diagnosis of a multi-step execution trace. The job-to-be-done is offline debugging: you have a recorded agent trace—including the initial plan, tool calls, their raw outputs, the agent's observations, and any internal state updates—that ended in a wrong outcome, a timeout, or an unexpected halt. Your goal is not to fix the code yet, but to produce a precise, evidence-backed blame assignment that pinpoints the exact step and root cause category of the failure before you touch a single line of application logic. The ideal user is an engineer who understands the agent's architecture and has access to its execution logs, not a non-technical stakeholder looking for a summary.

To use this prompt effectively, you must provide a complete and structured trace as input. This means the trace should be a chronological log containing distinct entries for each planning phase, tool invocation (with function name and arguments), the raw tool response, the agent's interpreted observation, and any state mutation. The prompt is designed to reason over this structured evidence and attribute failure to one of four primary categories: a planning error (wrong task decomposition or ordering), a tool execution error (the tool returned an error or unexpected output), an observation interpretation error (the agent drew a wrong conclusion from a valid tool response), or a state update error (the agent corrupted its own memory or context). The output is a step-level blame assignment with a direct quote from the trace as supporting evidence, making the diagnosis auditable and actionable.

There are clear situations where this prompt should not be used. Do not use it for live, user-facing agents where latency is critical; this is an offline evaluation tool meant for a test harness. It is not a replacement for a general-purpose logging or observability platform—it requires a pre-parsed, structured trace as input, not raw unstructured logs. Avoid using this prompt for agents with a single tool call or trivial linear execution where the failure is obvious; its value is in diagnosing complex, multi-step failures where the root cause is obscured by a chain of cascading errors. Finally, this prompt diagnoses what failed and why, but it does not generate the code fix. Your next step after receiving the attribution report should be to use the pinpointed step and category to guide a targeted code change, a prompt adjustment, or a tool contract revision.

This template is designed to be pasted directly into your debugging harness or an LLM playground. It accepts a structured trace of an agent's execution—including its plan, tool calls, observations, and state updates—and returns a step-level blame assignment. The model is instructed to act as a deterministic debugger, not a creative assistant, so it must ground every attribution in explicit evidence from the provided trace. Before using this template, ensure you have recorded the full execution trace, including any error messages, unexpected null returns, or state mutations that occurred during the failed run.

textCopy
You are an agent execution debugger. Your task is to analyze a multi-step agent trace and attribute the failure to a specific step and root cause category. You must ground every finding in explicit evidence from the trace. Do not speculate beyond the provided data.

## INPUT
[AGENT_TRACE]

## FAILURE SYMPTOM
[OBSERVED_FAILURE]

## OUTPUT SCHEMA
Return a valid JSON object with the following structure:
{
  "failure_step_index": <integer, the 0-based index of the step where the root cause occurred>,
  "root_cause_category": "planning" | "tool_selection" | "tool_argument_error" | "tool_execution_error" | "observation_interpretation" | "state_update_error" | "context_loss" | "other",
  "evidence": [
    {
      "trace_line_reference": "<exact quote or line number from the trace>",
      "explanation": "<why this evidence supports the attribution>"
    }
  ],
  "confidence": "high" | "medium" | "low",
  "alternative_hypothesis": "<brief description of the next most likely cause, or null if confidence is high>"
}

## CONSTRAINTS
- Only use evidence present in [AGENT_TRACE].
- If the trace is ambiguous, set confidence to "low" and provide an alternative hypothesis.
- Do not invent tool outputs or state that are not in the trace.
- If the failure is a symptom of an earlier step's error, attribute to the earliest causal step.
- For "tool_execution_error", distinguish between a tool returning an error (execution) and the agent passing bad arguments (tool_argument_error).

After pasting the template, replace [AGENT_TRACE] with the full JSON or text log of your agent's execution steps, including timestamps, tool call payloads, responses, and any state snapshots. Replace [OBSERVED_FAILURE] with a concise description of the incorrect final output, exception, or unexpected behavior. The output is a structured JSON object that can be parsed by your monitoring pipeline to trigger automated retries, escalate to a human reviewer, or update a failure taxonomy dashboard. For high-risk agent workflows—such as those mutating production data or making financial decisions—always log the attribution output alongside the trace and require human review for any "confidence": "low" result before taking corrective action.

The Agent Step Failure Attribution prompt is designed to be called programmatically after an agent run produces a failure signal. It expects a structured trace as input, not raw logs. Before calling the model, assemble the trace into the [AGENT_TRACE] placeholder: include the original task, the agent's plan steps, tool call requests and responses, observation summaries, and the final state or error. The prompt works best when the trace is complete and timestamped—partial traces produce unreliable attributions. If your agent framework emits spans or events, write a pre-processing step that serializes them into the trace format described in the prompt template's [TRACE_SCHEMA] block.

Wire the prompt into a post-execution hook or a separate debugging service. When an agent run returns a failure status, extract the trace, populate the template, and call a capable reasoning model (GPT-4o, Claude 3.5 Sonnet, or equivalent). Validate the output against the expected [OUTPUT_SCHEMA] before accepting it: check that failure_step references a step that exists in the trace, that attribution_category is one of the allowed enum values (planning, tool_execution, observation_interpretation, state_update, external, ambiguous), and that evidence contains direct quotes or step references from the trace. If validation fails, retry once with the validation error appended to the prompt as additional context. If the second attempt also fails validation, escalate to a human reviewer with the raw trace and both model outputs. Log every attribution result—including validation failures and retries—to your observability platform so you can track attribution accuracy over time and detect model drift.

For high-stakes agent workflows (financial transactions, healthcare actions, infrastructure changes), do not rely on this prompt alone. Implement a trace replay test harness: store the failing trace, replay it through the agent with instrumentation enabled, and compare the model's attribution against a human-annotated ground-truth label. Run this harness on a labeled dataset of known failure traces before deploying attribution into production debugging pipelines. The prompt is a diagnostic aid, not a root-cause oracle—it reduces mean time to diagnosis but does not replace engineering investigation. Avoid using smaller or faster models for this task; attribution quality degrades sharply when the model cannot reason over multi-step causal chains. If cost is a concern, sample a percentage of failures for attribution rather than downgrading the model.