Agent Step Failure Classification Prompt Template

This prompt is for agent runtime developers and platform engineers who need to turn raw step failures into structured, machine-actionable decisions. The core job is classification: given a failed step's context, error message, and execution history, the prompt must output a failure record that downstream recovery logic can consume without ambiguity. The ideal user is someone wiring this into an agent harness where retry policies, circuit breakers, and escalation paths depend on consistent failure categorization. Required context includes the step's intended purpose, the raw error output, the retry count so far, and any tool or API contract that defines normal behavior.

Do not use this prompt when you need a decision rather than a classification. If your system already knows the failure type and needs to choose between retry, skip, or abort, use the sibling Retry Decision Prompt for Failed Tool Calls or Skip vs Abort Decision Prompt for Agent Workflows instead. This prompt is also inappropriate for user-facing error messages—it produces structured records for machine consumption, not human-readable explanations. Avoid using it for failures where the root cause is already known and deterministic; classification adds latency and token cost without benefit when the error type is unambiguous from the status code alone.

Before integrating this prompt into your agent loop, define your failure taxonomy and wire the output into a recovery dispatch layer. The classification record should feed directly into retry logic, escalation queues, or monitoring dashboards. Start by running this prompt against a labeled dataset of known failure modes and measure inter-rater consistency across multiple runs—classification drift under temperature sampling is a common failure mode. If your agent operates in a regulated domain or on mutable resources, require human review for any failure classified as permanent with severity: critical before automated rollback or state mutation occurs.

This prompt template is designed to be copied directly into your agent runtime's error-handling module. It takes raw failure context from a failed agent step and produces a structured classification record. The template uses square-bracket placeholders that you must replace with live data from your execution environment: the original step description, the error details, the current retry count, and your operational constraints. The output is a machine-readable JSON object that downstream retry logic, escalation routers, and monitoring dashboards can consume without additional parsing.

textCopy
You are an agent step failure classifier. Your job is to analyze a failed agent step and produce a structured classification record that downstream systems can use to decide on recovery actions.

## INPUT
[STEP_DESCRIPTION]
[ERROR_DETAILS]
[RETRY_COUNT]
[TOKEN_BUDGET_REMAINING]
[STEP_CRITICALITY]

## CONSTRAINTS
[CONSTRAINTS]

## OUTPUT_SCHEMA
Return a single JSON object with these exact fields:
- failure_category: string, one of "transient", "permanent", "permission", "timeout", "malformed_output"
- retry_eligible: boolean
- severity: string, one of "critical", "high", "medium", "low"
- recommended_action: string, one of "retry", "retry_with_backoff", "skip", "abort", "escalate", "fallback_tool"
- confidence: float between 0.0 and 1.0
- justification: string, brief explanation of the classification
- blast_radius: string, one of "isolated", "downstream_steps", "full_plan"
- retry_strategy: string or null, if retry_eligible, specify "immediate", "exponential_backoff", or "fixed_delay"
- escalation_reason: string or null, required if recommended_action is "escalate"

## CLASSIFICATION RULES
- Transient: errors likely to resolve on retry (network timeouts, rate limits, temporary unavailability)
- Permanent: errors that will not resolve on retry (invalid arguments, unsupported operations, data corruption)
- Permission: authorization, access denied, or scope errors
- Timeout: step exceeded its time budget but may have partial results
- Malformed Output: step completed but produced unparseable or schema-invalid output

## RETRY ELIGIBILITY
- Retry only if failure_category is "transient" or "timeout" AND retry_count is below the limit specified in constraints
- Never retry "permission" errors without human intervention
- "malformed_output" may be retried once with stricter output format instructions

## SEVERITY ASSESSMENT
- Critical: step is required for plan completion and failure blocks all downstream work
- High: step failure degrades output quality significantly or causes cascading failures
- Medium: step failure has moderate impact, workaround possible
- Low: step is optional or has minimal impact on overall plan success

## INSTRUCTIONS
1. Analyze the error details against the step description
2. Consider the retry count and remaining token budget
3. Factor in step criticality when assigning severity
4. If confidence is below 0.7, lean toward escalation
5. Output only the JSON object, no markdown fences, no additional text

To adapt this template for your environment, replace each placeholder with live data from your agent runtime. [STEP_DESCRIPTION] should include the original objective and expected output schema for the failed step. [ERROR_DETAILS] must capture the raw error message, stack trace, HTTP status code, or tool response that triggered the failure. [RETRY_COUNT] tracks how many times this specific step has already been retried. [TOKEN_BUDGET_REMAINING] helps the classifier decide whether retrying is affordable. [STEP_CRITICALITY] should be a label from your plan's dependency graph indicating whether downstream steps depend on this step's output. The [CONSTRAINTS] placeholder should contain operational limits like maximum retries, latency budgets, and escalation thresholds. Before deploying, validate that your harness populates all placeholders completely—missing context produces unreliable classifications. For high-risk workflows, add a human review gate when severity is "critical" or confidence is below 0.7, and log every classification decision alongside the raw failure data for postmortem analysis.

Integrating the failure classification prompt into an agent runtime requires a thin harness that captures the failing step's context, invokes the model, validates the structured output, and routes the result to the appropriate recovery handler. The harness should be called immediately after a step failure is detected—before any retry, skip, or escalation logic executes. This ensures that every recovery path operates on a consistently classified failure record rather than raw error strings that vary across tools, APIs, and model providers. The harness is not a replacement for exception handling in your application code; it is a classification layer that translates heterogeneous failures into a uniform contract that downstream recovery prompts and decision nodes can consume reliably.

The harness must enforce a strict output schema. After calling the model with the classification prompt, validate that the response contains all required fields: failure_category (one of transient, permanent, permission, timeout, malformed_output), retry_eligible (boolean), severity (one of critical, high, medium, low), recommended_action (one of retry, skip, escalate, abort), and a justification string. If parsing fails or required fields are missing, implement a retry loop with a maximum of two additional attempts, appending the parse error to the prompt context so the model can self-correct. After three total failures, default to permanent / retry_eligible: false / severity: high / recommended_action: escalate and log the raw response for later debugging. For high-risk domains, route the escalation decision to a human review queue before any automated abort or skip action is taken.

Wire the harness into your agent's error-handling middleware so that every tool call, model inference, and data retrieval step is wrapped. Log the classification output alongside the step trace for observability. Use these structured records to build dashboards that track failure category distributions, retry eligibility rates, and severity trends over time. This data is essential for tuning retry budgets, identifying brittle integrations, and deciding when to invest in fallback tooling. Avoid the temptation to skip classification for 'obvious' errors—ad-hoc error handling creates drift between what your recovery prompts expect and what your runtime actually delivers, leading to silent stalls and misrouted escalations in production.