Planning, Reflection and Error Recovery

Use ReAct and plan-and-execute patterns, check results, and recover from errors with bounded retries and fallbacks.

Est. 30 min Updated Suggest a fix
// Part 01 — From loop to plan

Multi-Step Work Needs Checkpoints

A one-tool request can often run as a simple observe–think–act loop. A task such as preparing a weekly delivery report needs several dependent steps: fetch orders, group by status, calculate totals, and verify that the report is complete. If the agent jumps straight to an answer, it may skip a source or confuse a tool failure with an empty result. Planning makes the intended work inspectable; checkpoints let the application catch a wrong turn.

A plan is not a guarantee. A tool can fail, the data can contradict an assumption, and the task can change while it runs. Keep steps small, tie them to evidence, and let the executor revise or stop when new observations invalidate the plan. Human review is appropriate when the next action has financial, privacy, or operational impact.

PatternHow it worksUseful when
ReAct-style loopReason about the next step, act once, inspect the observation, repeatThe next tool depends on what the last tool returned
Plan-and-executeCreate a structured plan, execute one step at a time, then re-plan if neededThe task has several known milestones
Reflection / verificationCompare a result with explicit checks and repair or escalateCompleteness or correctness needs a second check
💡 Note
Keep the model's internal reasoning private. Ask for structured decisions, brief evidence references, and a concise user-facing explanation; do not make a long chain-of-thought transcript your audit log.
// Part 02 — ReAct

Act in Small Steps and Use Real Observations

ReAct is shorthand for combining reasoning and acting in a repeated loop. At each turn, the agent receives the goal and observations, selects one allowed action, and then incorporates the tool result. The important engineering property is not the name: each action is grounded in an observation and executed through your validated tool boundary. If the tool returns no matching order, the next step should not invent one.

react_loop.py
python
from typing import Any


def run_react(goal: str, decide, tools: dict[str, Any], max_steps: int = 5):
    observations = []
    for step in range(max_steps):
        decision = decide(goal, observations)
        if decision["kind"] == "done":
            return {"status": "complete", "answer": decision["answer"], "steps": step}
        if decision["kind"] != "tool" or decision["tool"] not in tools:
            return {"status": "invalid_action", "steps": step}
        try:
            result = tools[decision["tool"]](**decision["args"])
            observations.append({"tool": decision["tool"], "result": result})
        except TimeoutError:
            observations.append({"tool": decision["tool"], "error": "timeout"})
    return {"status": "step_limit", "observations": observations}


def lookup_status(order_id: str) -> dict[str, str]:
    return {"order_id": order_id, "status": "Out for delivery"}


def local_decision(goal: str, observations: list[dict]):
    if observations:
        status = observations[-1]["result"]["status"]
        return {"kind": "done", "answer": "Current status: " + status}
    return {"kind": "tool", "tool": "lookup", "args": {"order_id": "A104"}}


result = run_react("Check order A104", local_decision, {"lookup": lookup_status})
print(result)

This example keeps the policy deterministic so you can test the runner without an LLM. A model-backed decision function would return a structured action request, but the loop should still validate the action, execute one step, append an observation, and enforce the cap. Never let a model update the observations list as if it were a tool result.

🎯 Pro Tip
Prefer one action per turn when a result can change what should happen next. A batch of independent, read-only lookups can be parallelised by ordinary application code after validation.
// Part 03 — Plan and execute

Represent Plans as Data

Ask for a plan with explicit steps, expected evidence, and a completion condition. A plan step can be a short label and permitted operation, not a paragraph of hidden reasoning. Validate the structure before execution: reject unknown tools, excessive step counts, or missing required arguments. The executor should re-check permissions at action time because a plan may be old or the user's access may have changed.

plan_execute.py
python
from dataclasses import dataclass

@dataclass
class Step:
    name: str
    tool: str
    args: dict[str, str]
    expected: str


def execute_plan(plan: list[Step], tools: dict, max_steps: int = 5):
    if not plan or len(plan) > max_steps:
        return {"status": "invalid_plan", "results": []}

    results = []
    for step in plan:
        if step.tool not in tools:
            return {"status": "blocked", "failed_step": step.name, "results": results}
        try:
            value = tools[step.tool](**step.args)
        except TimeoutError:
            return {"status": "retryable_failure", "failed_step": step.name, "results": results}
        results.append({"step": step.name, "expected": step.expected, "value": value})
    return {"status": "ready_for_verification", "results": results}


def fetch_orders(day: str) -> list[dict[str, str]]:
    return [{"status": "delivered"}, {"status": "in_transit"}]


plan = [Step("fetch", "orders", {"day": "today"}, "Orders are returned")]
print(execute_plan(plan, {"orders": fetch_orders}))

The date in a real report must come from an explicit timezone-aware request or trusted business context, not a guess made by the model. This small executor also stops at the first failed step. Whether the right response is retry, re-plan, ask for clarification, or escalate depends on the failure category and the operation's safety.

// Part 04 — Reflection

Verify Against Criteria, Not Vibes

Reflection means checking an intermediate or final result against criteria. For a report, checks might confirm that all requested regions appear, totals reconcile with source rows, and no division by zero occurred. Prefer deterministic assertions for facts that code can verify. A model can help notice an ambiguity or suggest a repair, but an ungrounded self-critique is not an independent correctness guarantee.

verify_report.py
python
def verify_report(expected_regions: set[str], report: dict, source_totals: dict[str, int]):
    problems = []
    actual_regions = set(report.get("regions", {}))
    if actual_regions != expected_regions:
        problems.append("Region coverage does not match the request")

    for region, expected_total in source_totals.items():
        actual = report.get("regions", {}).get(region, {}).get("orders")
        if actual != expected_total:
            problems.append("Order count mismatch for " + region)

    return {"ok": not problems, "problems": problems}


expected = {"Hyderabad", "Vijayawada"}
report = {"regions": {"Hyderabad": {"orders": 12}, "Vijayawada": {"orders": 8}}}
print(verify_report(expected, report, {"Hyderabad": 12, "Vijayawada": 8}))

If checks fail, keep the failure attached to the run. A repair step should identify what evidence is missing and whether a permitted operation can provide it. If the source data itself is inconsistent, stop and surface the discrepancy instead of asking the model to write a more persuasive explanation.

// Part 05 — Retries

Retry Only Failures That Can Recover

A timeout or transient service failure may recover if retried. A permission denial, invalid input, or missing record usually will not. Define error categories, retry only safe transient failures, and use exponential backoff with jitter when the underlying client does not already manage retries. Set an attempt cap and an overall deadline. Also consider idempotency: if a request timed out after the server performed a write, repeating it could duplicate the effect.

retry_policy.py
python
import random
import time


def retry_read(operation, attempts: int = 3, sleep=time.sleep):
    for attempt in range(attempts):
        try:
            return operation()
        except TimeoutError:
            if attempt == attempts - 1:
                raise
            delay = min(8.0, 0.5 * (2 ** attempt)) + random.random() * 0.25
            sleep(delay)


def read_status():
    return {"status": "Out for delivery"}


print(retry_read(read_status))

Retry logic should live at one well-defined boundary. If the SDK retries and your agent retries and the queue retries, a single request can multiply into many attempts. Include attempt counts in traces, set an overall request budget, and provide a fallback or escalation when the budget is used up.

⚠️ Important
Do not blindly retry writes such as issuing a refund. Use an idempotency key and check the operation's status, or require a person to resolve an ambiguous outcome before attempting it again.
// Part 06 — Fallbacks

Fail Safely and Make the Next Step Clear

A fallback is a controlled alternative, not a second chance to do anything. If a knowledge search is unavailable, the assistant can say it could not verify an answer and offer human support. If a required report source is missing, mark the report incomplete rather than filling gaps from model knowledge. If a low-risk tool fails temporarily, a bounded retry may be appropriate. Give each failure class a known status and user-facing response.

ConditionSafe responseAvoid
Transient read timeoutBounded retry, then report unavailableRetry forever
Authorization deniedStop and explain access is neededAsk the model to find another route
Conflicting source recordsShow the discrepancy and escalatePick the more plausible value
No evidence for a claimAsk a question or say it is unverifiedInvent a likely answer

A fallback must preserve the same permissions as the main path. Never downgrade to a broader search, another customer's record, or an unapproved external service simply because the preferred tool is down. Record the failure category, but keep raw personal content out of routine logs.

// Part 07 — Production

Keep Plans, Budgets and Evidence Auditable

A production run should expose its current step, status, attempt count, elapsed time, and verification outcome. Model-generated plans can change between runs, so store the validated plan snapshot alongside the run and record meaningful revisions. Protect that data with access controls and a retention policy. The person reviewing a task needs evidence about what happened, not an unrestricted dump of private reasoning.

  1. Define a small set of terminal states: complete, needs input, waiting for approval, failed, and timed out.
  2. Set maximum steps, per-tool timeout, total deadline, retry budget, and any spend or rate budget.
  3. Verify outputs with code-based checks wherever possible; record the check result and source references.
  4. Exercise invalid plans, empty results, rate limits, partial failures, and repeated execution in tests.
📌 Real World Example
For a Swiggy-style delivery dashboard, an agent can plan to fetch and summarise statuses. The application should calculate totals from the records and show which time window was queried; the model should not invent totals to make the summary look complete.
// Part 08 — Pitfalls

Common Mistakes

Trusting a plan because it sounds complete

Why: Plans can omit a data source, exceed permissions, or contain invalid steps.

Fix: Validate schema, tools, arguments, step count, and authorization before executing.

Using reflection as the only quality check

Why: A model can confidently approve its own unsupported result.

Fix: Use deterministic checks and source evidence; use model review only as an additional signal.

Retrying all errors or every operation

Why: Permanent errors never improve, and repeated writes can duplicate effects.

Fix: Classify failures, cap transient retries, and make writes idempotent or approval-gated.

Treating a fallback as permission to guess

Why: Unavailable evidence does not make model knowledge authoritative.

Fix: Stop, disclose uncertainty, ask for input, or route to a qualified person.

// Part 09 — Practice

Plan and Verify a Weekly Operations Report

Practice

An evidence-based plan with recovery

  1. Write a three-step structured plan to fetch, aggregate, and verify sample delivery data.
  2. Reject a plan containing an unregistered tool or more steps than the configured maximum.
  3. Add a deterministic check that catches a missing region or mismatched total.
  4. Simulate one timeout and verify the retry policy stops at its attempt cap.
  5. Create a fallback response for conflicting source records that does not invent a resolution.

Hint: Use fixture data and fake tools. Assert statuses and tool calls as well as the final report text.

🎯 Key Takeaways

  • ✓ReAct alternates a decision with an action and a real observation; plan-and-execute makes multi-step milestones explicit.
  • ✓Represent plans as validated data with permitted tools, expected evidence, and a completion condition.
  • ✓Verify with deterministic checks whenever possible; model reflection is not independent proof.
  • ✓Retry only recoverable failures, with attempt limits, deadlines, backoff, and idempotency for writes.
  • ✓Use fallbacks that preserve permissions and disclose uncertainty rather than guessing.
  • ✓Trace validated steps, outcomes, and verification results without storing unnecessary private reasoning or personal data.

Next

What comes next

You have the building blocks. Next, represent state and control flow explicitly as a graph that can route and checkpoint work.

Lesson 04 · Building Agent Workflows with LangGraph →

HELP US IMPROVE

How was this lesson?

Your note is shared with the Chaduvuko team for review. Please don’t include personal or sensitive information.

Choose your feedback

Spotted a mistake or something unclear? Suggest a fix on GitHub or email us. Select the text first and it is quoted for you.

Share

Discussion

0

Have a better approach? Found something outdated? Share it — your knowledge helps everyone learning here.

Continue with GitHub
Loading...