Planning, Reflection and Error Recovery
Use ReAct and plan-and-execute patterns, check results, and recover from errors with bounded retries and fallbacks.
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.
| Pattern | How it works | Useful when |
|---|---|---|
| ReAct-style loop | Reason about the next step, act once, inspect the observation, repeat | The next tool depends on what the last tool returned |
| Plan-and-execute | Create a structured plan, execute one step at a time, then re-plan if needed | The task has several known milestones |
| Reflection / verification | Compare a result with explicit checks and repair or escalate | Completeness or correctness needs a second check |
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.
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.
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.
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.
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.
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.
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.
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.
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.
| Condition | Safe response | Avoid |
|---|---|---|
| Transient read timeout | Bounded retry, then report unavailable | Retry forever |
| Authorization denied | Stop and explain access is needed | Ask the model to find another route |
| Conflicting source records | Show the discrepancy and escalate | Pick the more plausible value |
| No evidence for a claim | Ask a question or say it is unverified | Invent 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.
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.
- Define a small set of terminal states: complete, needs input, waiting for approval, failed, and timed out.
- Set maximum steps, per-tool timeout, total deadline, retry budget, and any spend or rate budget.
- Verify outputs with code-based checks wherever possible; record the check result and source references.
- Exercise invalid plans, empty results, rate limits, partial failures, and repeated execution in tests.
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.
Plan and Verify a Weekly Operations Report
Practice
An evidence-based plan with recovery
- Write a three-step structured plan to fetch, aggregate, and verify sample delivery data.
- Reject a plan containing an unregistered tool or more steps than the configured maximum.
- Add a deterministic check that catches a missing region or mismatched total.
- Simulate one timeout and verify the retry policy stops at its attempt cap.
- 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.
Spotted a mistake or something unclear? Suggest a fix on GitHub or email us. Select the text first and it is quoted for you.
Discussion
0Have a better approach? Found something outdated? Share it — your knowledge helps everyone learning here.
