Action Failure Recovery Prompt for Autonomous Agents

This prompt is designed for a specific failure mode inside an autonomous agent's execution loop: a single tool call returns an error. The job-to-be-done is not to re-plan the entire task or question the agent's objective, but to produce a structured, machine-readable diagnostic of the failure and a single corrected action attempt. The ideal user is an AI reliability engineer or agent-framework builder who has already instrumented their harness to capture the original goal, the failed action's intent, the exact function name, the arguments sent, and the raw error payload (status code, exception message, or malformed response body). The prompt assumes this context is available and injectable via placeholders.

Use this prompt when the agent's tool execution fails with a clear error signal—such as a 4xx/5xx HTTP status, a ValidationError, a TimeoutException, or a response that fails a schema check. The harness should invoke this prompt immediately after catching the error and before checking the retry budget. The output is a diagnostic summary (error classification, root cause hypothesis) and a corrected action (revised arguments or a null action if the tool is fundamentally unusable). The harness then validates the corrected arguments against the tool's schema and, if valid, retries the call. Do not use this prompt for plan-level deviations, multi-step rollbacks, or cases where the agent has lost track of the overall objective. Those scenarios require re-anchoring or re-planning prompts instead, as they involve a broader context collapse that a single-step recovery cannot address.

A concrete implementation check: before wiring this prompt into your agent loop, ensure your harness can distinguish between a tool error and a plan error. A tool error means the agent knew what to do but the external system rejected the attempt. A plan error means the agent's chosen action no longer makes sense given new observations. Feeding a plan error into this prompt will produce a syntactically valid but semantically useless corrected action—the model will fix arguments for a call that shouldn't be made. To avoid this, gate the prompt behind an error-type classifier. If the error is a tool failure, proceed. If it's a plan deviation, route to a re-anchoring prompt instead. Additionally, always run the corrected arguments through a JSON Schema validator before retrying. If the model hallucinates a new parameter or omits a required field, the harness should treat that as a second failure and either re-invoke this prompt with the validation error or escalate to a human reviewer if the retry budget is exhausted.

Next, integrate this prompt into your retry budget logic. A common failure mode is an infinite retry loop where the model repeatedly suggests the same broken correction. To prevent this, the harness should track the hash of the corrected arguments and compare it against previous attempts. If a duplicate is detected, break the loop and escalate. Finally, log the full prompt input, model output, and validation result for every recovery attempt. These traces are essential for debugging why certain error patterns resist self-correction and for building a golden dataset to evaluate future prompt versions. Avoid using this prompt in high-stakes financial transactions or clinical actions without a mandatory human approval step after the first retry failure.

This prompt template is designed to be injected into your agent harness immediately after a tool call returns an error. Its job is to produce a structured diagnostic summary and a corrected action attempt, preventing the agent from hallucinating a recovery or blindly retrying the same broken call. Replace the square-bracket placeholders with runtime values from your agent's execution context before sending the prompt to the model.

textCopy
You are an agent recovery module. Your task is to analyze a failed tool execution and produce a corrected action attempt.

## ORIGINAL GOAL
[ORIGINAL_GOAL]

## FAILED ACTION
- Tool: [FAILED_TOOL_NAME]
- Arguments: [FAILED_TOOL_ARGUMENTS]
- Error Code: [ERROR_CODE]
- Error Message: [ERROR_MESSAGE]
- Timestamp: [TIMESTAMP]

## RECENT ACTION HISTORY
[ACTION_HISTORY]

## AVAILABLE TOOLS
[AVAILABLE_TOOLS_SCHEMA]

## CONSTRAINTS
- Do not retry the exact same call without modifying the arguments.
- If the error indicates a permanent failure (e.g., invalid resource ID, permission denied), do not retry. Escalate instead.
- Preserve the original goal. Do not change the objective.
- If the error is transient (e.g., timeout, rate limit), you may suggest a retry with backoff.

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "error_classification": "TRANSIENT" | "PERMANENT" | "UNCLEAR",
  "diagnosis": "A concise explanation of what went wrong, citing the error message.",
  "recovery_action": "RETRY" | "SUBSTITUTE_TOOL" | "REPLAN" | "ESCALATE",
  "corrected_action": {
    "tool_name": "string",
    "arguments": {},
    "retry_count": 0,
    "backoff_seconds": 0
  },
  "escalation_reason": "If recovery_action is ESCALATE, explain why. Otherwise null."
}

Before deploying this prompt, ensure your harness validates the output against the schema. If the model returns an invalid recovery_action or a corrected_action that duplicates the failed call, increment a retry counter and re-invoke the prompt with the validation error appended as additional context. After a configurable retry budget is exhausted (typically 3 attempts), the harness should escalate to a human operator or a higher-level replanning agent. Log every recovery attempt, including the model's diagnosis and the final outcome, to build a dataset for evaluating recovery accuracy over time.

The Action Failure Recovery Prompt is designed to be invoked by an agent harness immediately after a tool execution returns an error or an unexpected result. The harness should intercept the tool response, classify the failure type (e.g., timeout, invalid argument, permission denied, empty result), and inject the error context into the prompt's [ERROR_CONTEXT] and [FAILED_ACTION] placeholders. This prompt is not a standalone chatbot instruction; it is a structured recovery step within a larger agent loop. The harness must preserve the original [GOAL], [PLAN_STATE], and [COMPLETED_STEPS] so the model can diagnose the failure without losing sight of the overall objective.

Wire the prompt into your agent's execution loop as a post-error hook. After a tool call fails, construct the prompt payload by merging the error payload, the original action arguments, and the agent's current plan state. Send the prompt to a model with strong instruction-following and structured output capabilities (e.g., GPT-4o, Claude 3.5 Sonnet). The harness must validate the model's output against the [OUTPUT_SCHEMA] before acting on it. At minimum, validate that diagnosis.error_type is a recognized failure class, corrected_action.tool_name is a valid tool in the agent's registry, and corrected_action.arguments conform to the tool's input schema. If validation fails, increment a retry counter and re-invoke the prompt with the validation error appended to [ERROR_CONTEXT]. Do not execute the corrected action until validation passes.

Implement a retry budget with a hard cap (e.g., 3 attempts per action failure). Track each recovery attempt in structured logs that include the original error, the model's diagnosis, the corrected action, and the validation result. If the retry budget is exhausted, the harness must escalate to a human-in-the-loop queue or invoke a fallback policy—do not loop indefinitely. For high-risk domains such as finance, healthcare, or infrastructure, require human approval before executing any corrected action that modifies state, transfers funds, or alters configurations. Log every recovery attempt with a correlation ID that ties the original action, the error, the recovery prompt invocation, and the final outcome together for observability and postmortem analysis.

When deploying this prompt in production, pair it with an evaluation harness that measures error interpretation accuracy and argument correction validity. Run offline evals using a golden dataset of known tool failures and expected corrections. In production, monitor the recovery success rate, the average retry count before success or escalation, and the rate of validation failures on the model's output. These metrics will surface when the prompt needs tuning or when the underlying tool contracts have drifted. If the recovery success rate drops below a defined threshold, trigger an alert and review recent failure patterns before updating the prompt or the tool schemas.