Agent State Reconciliation Prompt After Tool Error

This prompt is designed for the moment an agent's internal state becomes unreliable—when a tool call returns an error, a partial payload, or a timeout, and the agent's scratchpad or memory now contains conflicting, incomplete, or stale information. The job-to-be-done is state reconciliation: producing a single, coherent summary of what is true, what is complete, and what must happen next. The ideal user is an AI reliability engineer or agent-framework builder who needs the agent to resume execution safely without discarding all prior progress. Required context includes the original goal, the last stable state snapshot, the failed tool call and its error, and any partial results that were returned.

Do not use this prompt when the failure is catastrophic and the entire trajectory is suspect—for example, when the agent's core reasoning loop itself produced the error or when the environment has changed so much that prior state is no longer valid. In those cases, a full re-plan or human escalation is more appropriate. This prompt is also not a substitute for proper error handling in the tool layer; if the tool error is transient and the agent can retry with corrected arguments, use a narrower tool-call retry prompt instead. Reserve state reconciliation for moments when the agent's understanding of what happened is the primary thing that broke.

Before wiring this prompt into your harness, ensure you have a reliable mechanism for capturing the agent's state before the failed tool call. The prompt's effectiveness depends on the quality of the pre-failure snapshot. If your harness cannot distinguish between completed steps, in-progress steps, and steps that never started, the reconciliation output will be unreliable. Implement a state-diff check after the model responds: compare the reconciled state to the pre-failure snapshot and flag any contradictions—such as a completed step being re-marked as pending or a constraint being dropped. For high-stakes agent workflows, route contradictions to a human reviewer before the agent resumes execution.

This prompt is designed to be injected into an agent harness immediately after a tool call returns an error or a partial result that may have corrupted the agent's internal state. Its job is to force the model to explicitly list what it believes is still true, what is now uncertain, and what the next safe action should be. Do not use this prompt for simple retries where the state is clearly unchanged; it is intended for cases where the agent's understanding of the world may have diverged from reality.

textCopy
SYSTEM: You are an agent state reconciliation module. Your task is to repair the agent's internal state after a tool error.

CONTEXT:
- Original Goal: [ORIGINAL_GOAL]
- Plan Before Error: [PLAN_BEFORE_ERROR]
- Last Action Attempted: [LAST_ACTION]
- Tool Called: [TOOL_NAME]
- Error Received: [ERROR_MESSAGE]
- Partial Output (if any): [PARTIAL_OUTPUT]
- State Before Action: [STATE_BEFORE_ACTION]

INSTRUCTIONS:
1.  **State Audit:** List every fact the agent believed to be true before the error. For each fact, classify it as:
    - CONFIRMED: Still valid.
    - UNCERTAIN: May have been invalidated by the error.
    - INVALIDATED: Proven false by the error or partial output.
2.  **Gap Analysis:** Identify any critical information that is now missing and was required for the next step in the plan.
3.  **Reconciliation:** Produce a new, concise state object in valid JSON format that represents the best-known state of the world. Use `null` for any field whose value is now unknown.
4.  **Continuation Plan:** Propose the single next action to take. This can be:
    - A retry of the failed action with corrected arguments.
    - A new action to gather the missing critical information.
    - A request for human intervention if the path forward is blocked.

OUTPUT SCHEMA:
{
  "state_audit": [
    {
      "fact": "string",
      "status": "CONFIRMED | UNCERTAIN | INVALIDATED",
      "rationale": "string"
    }
  ],
  "missing_critical_info": ["string"],
  "reconciled_state": {},
  "continuation_plan": {
    "action_type": "RETRY | NEW_ACTION | ESCALATE",
    "action_description": "string",
    "tool_name": "string | null",
    "tool_args": {} | null,
    "escalation_reason": "string | null"
  }
}

CONSTRAINTS:
- Do not invent facts to fill gaps; use null for unknowns.
- The continuation plan must be a single, atomic action.
- If the error indicates a fundamental plan flaw, action_type must be ESCALATE.

To adapt this template, replace the square-bracket placeholders with runtime values from your agent's execution context. The STATE_BEFORE_ACTION should be a snapshot of the agent's working memory or a structured representation of known facts. The OUTPUT_SCHEMA is a contract for your harness; parse the reconciled_state JSON and use it to overwrite the agent's current state before executing the continuation_plan. If the action_type is ESCALATE, your harness must route the escalation_reason to a human operator or a dead-letter queue and halt the agent loop. For high-risk domains, always log the full audit trail and require human approval before executing any RETRY or NEW_ACTION that modifies external systems.

This prompt is designed to be called by an agent harness immediately after a tool returns an error or a partial result that leaves the agent's internal state inconsistent. The harness should not proceed to the next planning step until it receives a validated reconciled state from this prompt. The prompt expects three inputs: the agent's pre-error state snapshot, the tool call that failed, and the raw error or partial result payload. The harness must capture these inputs atomically before invoking the reconciliation prompt to avoid state drift during the recovery window.

Wire the prompt into a dedicated recovery step within your agent loop. When a tool call returns a non-2xx status, a timeout, or a malformed payload that fails schema validation, the harness should: (1) freeze the current agent state and log the pre-error snapshot to an append-only state journal, (2) call this reconciliation prompt with the frozen state, the failed tool invocation, and the error payload, (3) validate the output against a strict reconciliation schema that requires reconciled_state, continuation_plan, and missing_fields arrays, and (4) diff the reconciled state against the pre-error snapshot to detect contradictions or silent field loss. If the diff reveals a contradiction—such as a field value changing without an explicit correction note—reject the reconciliation and escalate to a human operator or a higher-cost model for review. Log every reconciliation attempt with the pre-error state hash, the error type, the reconciled state hash, and the diff result for observability.

Retry logic must be bounded. If the reconciliation prompt itself fails—returns malformed JSON, exceeds token limits, or produces a state that fails the contradiction diff—retry once with the same inputs and a stronger constraint instruction appended to the prompt. If the second attempt also fails, stop retrying and escalate. Do not loop reconciliation attempts; the cost of a corrupted agent state is higher than the cost of human intervention. For high-risk domains such as healthcare or finance, require human approval on any reconciliation that modifies more than three state fields or alters a field tagged as critical in the agent's state schema. Model choice matters: use a model with strong instruction-following and structured output capabilities (e.g., GPT-4o, Claude 3.5 Sonnet) for reconciliation tasks. Avoid smaller or older models that are more likely to hallucinate state changes or miss contradictions.