← AI Agent Exploration · ← Previous

AI Agent Error Recovery & Self-Correction — Teaching Agents to Fix Their Own Mistakes

Every Agent builder hits this moment: the Agent calls a tool, and it returns an error. Now what?

If the Agent sees the error, understands what happened, tries a different approach, and eventually succeeds — that's a self-healing Agent. If it sees the error and either gives up or hallucinates an answer — that's an unreliable Agent.

This article is about making your Agent go from fragile to robust.

What Kinds of Errors Do Agents Make

First Line of Defense: Make Tools Return Useful Errors

Error recovery doesn't start with the Agent's code — it starts with the quality of your tools' error messages. The model can only make decisions based on the information you give it. Feed it garbage error messages, and you get garbage decisions.

# ❌ Useless error
def read_file(path):
    try:
        return open(path).read()
    except:
        return "Error"     # Model: what error? what do I do?

# ✅ Helpful error
def read_file(path):
    try:
        return open(path).read()
    except FileNotFoundError:
        return json.dumps({
            "success": False,
            "error": f"File not found: {path}",
            "suggestion": "Try listing the directory to verify the path",
            "parent_dir": str(Path(path).parent)
        })
    except PermissionError:
        return json.dumps({
            "success": False,
            "error": f"Permission denied: {path}",
            "suggestion": "Check file permissions or try a different path"
        })

Second Line: Exponential Backoff Retry

For transient errors like network timeouts and API rate limits, the Agent doesn't need to "think" — just retry.

import time, random

def retry_with_backoff(fn, max_retries=3, base_delay=1):
    """Exponential backoff: 1s → 2s → 4s."""
    for attempt in range(max_retries):
        try:
            return fn()
        except (TimeoutError, ConnectionError) as e:
            if attempt == max_retries - 1:
                raise  # Last attempt, let it fail
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)
    return None

Wrap all potentially transient-failing tools:

def search_web_robust(query):
    return retry_with_backoff(lambda: search_web(query))

def run_python_robust(code):
    return retry_with_backoff(lambda: run_python(code), max_retries=5)

Third Line: Self-Healing Loop

Errors that retry can't fix — wrong parameters, incorrect paths, bad tool choices — require the Agent to understand the error and adjust its behavior. That's the self-healing loop.

The key change: feed errors back to the model structured, so it can decide its next move.

def run_agent_with_recovery(user_input: str, max_turns: int = 15):
    messages = [{"role": "system", "content": SYSTEM_PROMPT},
                {"role": "user", "content": user_input}]

    consecutive_errors = 0

    for turn in range(max_turns):
        response = client.chat.completions.create(
            model="gpt-4o", messages=messages, tools=TOOLS
        )
        msg = response.choices[0].message

        if not msg.tool_calls:
            return msg.content

        for tool_call in msg.tool_calls:
            fn_name = tool_call.function.name
            fn_args = json.loads(tool_call.function.arguments)

            result = execute_tool(fn_name, fn_args)

            # Parse any errors
            error_info = parse_error(result)
            if error_info:
                consecutive_errors += 1
                # Feed structured error back to the model
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": json.dumps({
                        "success": False,
                        "tool": fn_name,
                        "error": error_info["message"],
                        "suggestion": error_info["suggestion"],
                        "attempts_left": 3 - consecutive_errors
                    })
                })

                # Too many consecutive failures → abort
                if consecutive_errors >= 3:
                    return f"Failed {consecutive_errors} times in a row. Last error: {error_info['message']}. Needs human review."
            else:
                consecutive_errors = 0  # Success resets counter
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": result
                })

        messages.append(msg)

    return "Max turns reached. Task incomplete."

System Prompt: Teaching the Model How to Handle Errors

Mechanisms alone aren't enough — the model needs to know "what to do when errors happen." Add explicit error-handling guidance to the system message:

SYSTEM_PROMPT = """You are the user's AI assistant. You can use tools to complete tasks.

## Error Handling Rules
1. When a tool returns "success": false, do not give up.
2. Read the error field to understand what happened.
3. Follow the suggestion field to adjust your approach.
4. If suggestion says to try a different path, list the directory to find the correct one.
5. If suggestion says to retry, try again with different parameters.
6. After 3 consecutive failures, honestly tell the user what happened. Never fabricate results.

## Tool Usage Principles
- Always confirm files/directories exist with ls/list_dir before operating
- Network operations may timeout — have a backup plan
- When unsure about parameter format, check documentation or help first"""

Fourth Line: Reflection

Some errors aren't at the tool-call level — they're at the reasoning level. The Agent completed the task, but the result is wrong.

Reflection makes the Agent review its own work before delivering the final answer:

def reflect_and_refine(task, result, tools_used):
    """Have the model reflect on result quality."""
    reflection_prompt = f"""You just completed the following task:
Task: {task}
Tools used: {tools_used}
Result: {result}

Check:
1. Does the result fully answer the task?
2. Any subtasks missed?
3. Is the data accurate (no unrelated data used)?
4. Is there a better approach?

If everything is fine, reply "OK".
If there are issues, explain and provide the corrected version."""

    check = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": reflection_prompt}]
    ).choices[0].message.content

    if "OK" in check[:50]:
        return result
    return check  # Use the reflection-corrected version

The Four Defense Lines at a Glance

You don't need all four on day one. Start with ① — write good error messages in your tools, and your Agent is already more reliable than 90% of implementations out there.

📖 Next: Multi-Agent Orchestration — getting multiple Agents to collaborate on complex tasks