Plan-Execute Control Flow
A plan that cannot survive a failure is a script. A script that can replan is an agent. Build the replanner first.
Learning Objectives
- Represent a plan as an ordered list of typed steps so the executor can reason about progress and outcome.
- Execute steps sequentially with a controlled failure handoff back to the planner.
- Replan from the current cursor with the prior error in the context so the next plan is informed.
- Emit a plan diff on each revision so a downstream tracer or UI can show why the plan changed.
- Enforce two budgets: a hard step ceiling and a hard replan ceiling.
Plan and execute, not chain-of-thought
A chain-of-thought agent emits tokens and lets the loop guess where the tool call ends. A plan-and-execute agent emits a structured plan first, then executes each step deterministically. The plan is data the harness can introspect. The execution is the harness running that data through a dispatcher.
Two pieces. A planner that produces a plan. An executor that runs the plan. The interesting work is what happens when the executor hits a failure. Three options:
1. Abort (return failed, surface the error)
2. Skip (mark step failed, continue with the rest)
3. Replan (hand the error to the planner, get a new plan from the cursor)Replan is the one that turns a script into an agent.
The Step shape
Step
id : int (monotonic within a plan revision)
tool_name : str
args : dict
expected_outcome: str (planner's stated success condition)
result : Any | None
error : str | Noneexpected_outcome is a short sentence the planner emits alongside the step. It is not enforced by the executor. It is for two things: the replanner reads it when revising the plan; the event stream emits it so a tracer can show "this step was supposed to do X."
The planner shape
def planner(goal: str, history: list[Step], last_error: str | None) -> list[Step]:
...A pure function. goal is the user goal. history is the steps already executed (with results and errors filled in). last_error is None on the first call and the most recent failure message on every subsequent call. The planner returns the next plan starting from the cursor.
The planner does not know about the executor. It does not know about retries. It does not know about timeouts. It produces a plan. That is all.
The executor
The executor is a small state machine. Each step runs through the dispatcher. The outcome is one of three things: success, failure-replannable, failure-fatal. Replannable failures hand back to the planner. Fatal failures (budget exceeded, replan ceiling hit) return a FAILED session result.
Plan diffs on revision
When the planner returns a new plan after a failure, the executor emits a plan.diff event with three fields.
removed: list of step ids that were in the old plan and are not in the new
added : list of step ids in the new plan that were not in the old
revised: list of step ids whose tool_name or args changedA tracer or UI can render this as a strikethrough on the removed steps and a highlight on the added ones. The point is not the diff format. The point is that revision is a visible event, not a silent rewrite.
Two budgets, both hard
max_steps caps total step executions across the whole session, including replans. Default is twelve. A linear five-step plan that replans twice and adds three steps each time hits sixteen executions and would exceed the budget. The executor will refuse the replan and return FAILED.
max_replans caps the number of times the planner is called after the first plan. Default is five. This is the more important limit. A planner that returns the same broken plan five times in a row would otherwise loop until the step budget catches it. Capping replans makes the failure faster and the reason clearer.
The deterministic planner in this lesson
We do not call a model in this lesson. The lesson ships a deterministic planner that picks a plan based on last_error.
last_error is None -> emit a four-step plan
last_error matches X -> emit a three-step plan that routes around X
last_error matches Y -> emit a two-step plan that gives up gracefully
otherwise -> return [] (signals nothing to replan)This is enough to test the executor's behavior on every transition path: success, replan-once, replan-twice, replan-exhaustion, and step-budget exhaustion.
Result shape
SessionResult
status : "completed" | "failed"
reason : str ("goal_met" | "step_budget" | "replan_budget" | "no_plan")
history : list[Step]
revisions : list[PlanDiff]
events : list[Event]The harness loop from lesson twenty can read this directly. The dispatcher from lesson twenty-three is what executes each step. The registry from lesson twenty-one validates each step's args. The transport from lesson twenty-two would surface this whole flow over JSON-RPC to a model client.
How to read the code
code/main.py defines PlanExecuteAgentStepPlanDiffSessionResultand the deterministic planner. The executor is a single run(goal) method that returns a SessionResult. The plan diff is computed by comparing step ids and (tool_name, args) tuples.
code/tests/test_agent.py covers a linear success, a mid-plan failure that replans once, replan exhaustion that returns failed:replan_budgetstep-budget exhaustion, and the plan-diff event format.
Going further
Two extensions you will want once you wire this to a real model. First, partial-plan caching: when a plan succeeds for the first three of six steps and then fails, you do not want to re-run the first three. The executor already keeps history; the planner just needs to read it. Second, parallel branches: the current executor is strictly sequential. A planner that emits an independent branch (gather_step instead of next_step) can run two tool calls concurrently through the dispatcher.
Both add real complexity. Both are easier to add once the linear executor is pinned. That is what this lesson does.
Check what you learned
7 questions. Answer each one to see why.
What is the planner's responsibility in a plan-execute agent?
The full code
Every file for this lesson. Copy it, run it, then change it.
"""Plan-and-execute agent with replan on failure, plan diffs, and dual budgets.
Conceptual references:
- ./docs/en.md (this lesson)
- Phase 14 lesson 01 (agent loop fundamentals)
- Phase 13 lesson 02 (tool protocols overview)
Stdlib only. Run: python3 code/main.py
"""
from __future__ import annotations
import json
import time
from dataclasses import dataclass, field
from typing import Any, Callable
@dataclass
class Step:
id: int
tool_name: str
args: dict
expected_outcome: str
result: Any | None = None
error: str | None = None
def signature(self) -> tuple:
return (self.tool_name, json.dumps(self.args, sort_keys=True))
@dataclass
class PlanDiff:
revision: int
removed: list[int]
added: list[int]
revised: list[int]
def to_dict(self) -> dict:
return {
"revision": self.revision,
"removed": list(self.removed),
"added": list(self.added),
"revised": list(self.revised),
}
@dataclass
class Event:
type: str
payload: dict
ts: float = field(default_factory=time.time)
@dataclass
class SessionResult:
status: str
reason: str
history: list[Step]
revisions: list[PlanDiff]
events: list[Event]
def to_dict(self) -> dict:
return {
"status": self.status,
"reason": self.reason,
"history": [
{"id": s.id, "tool": s.tool_name, "args": s.args,
"result": s.result, "error": s.error}
for s in self.history
],
"revisions": [r.to_dict() for r in self.revisions],
"events": [{"type": e.type, "payload": e.payload, "ts": e.ts} for e in self.events],
}
Planner = Callable[[str, list[Step], str | None], list[Step]]
ToolExecutor = Callable[[str, dict], Any]
class ToolFailure(Exception):
pass
def _diff_plans(old: list[Step], new: list[Step], revision: int) -> PlanDiff:
old_ids = {s.id for s in old}
new_ids = {s.id for s in new}
removed = sorted(old_ids - new_ids)
added = sorted(new_ids - old_ids)
revised: list[int] = []
old_by_id = {s.id: s for s in old}
for s in new:
if s.id in old_ids and old_by_id[s.id].signature() != s.signature():
revised.append(s.id)
return PlanDiff(revision=revision, removed=removed, added=added, revised=revised)
class PlanExecuteAgent:
"""Sequential plan executor with replan on failure."""
def __init__(
self,
planner: Planner,
executor: ToolExecutor,
*,
max_steps: int = 12,
max_replans: int = 5,
) -> None:
self._planner = planner
self._executor = executor
self.max_steps = max_steps
self.max_replans = max_replans
self._events: list[Event] = []
def _emit(self, etype: str, payload: dict) -> None:
self._events.append(Event(type=etype, payload=payload))
def run(self, goal: str) -> SessionResult:
self._events = []
history: list[Step] = []
revisions: list[PlanDiff] = []
steps_taken = 0
replans_used = 0
last_error: str | None = None
plan = self._planner(goal, history, None)
self._emit("plan.commit", {"revision": 0, "steps": _summarize(plan)})
if not plan:
self._emit("session.complete", {"reason": "no_plan"})
return SessionResult(
status="failed", reason="no_plan",
history=history, revisions=revisions, events=list(self._events),
)
cursor = 0
revision = 0
while cursor < len(plan):
if steps_taken >= self.max_steps:
self._emit("session.complete", {"reason": "step_budget"})
return SessionResult(
status="failed", reason="step_budget",
history=history, revisions=revisions, events=list(self._events),
)
step = plan[cursor]
self._emit("step.start", {"step_id": step.id, "tool": step.tool_name})
try:
step.result = self._executor(step.tool_name, step.args)
self._emit("step.end", {"step_id": step.id, "outcome": "ok"})
history.append(step)
cursor += 1
steps_taken += 1
continue
except Exception as exc:
step.error = f"{type(exc).__name__}: {exc}"
self._emit("step.end", {"step_id": step.id, "outcome": "error", "error": step.error})
history.append(step)
steps_taken += 1
last_error = step.error
if replans_used >= self.max_replans:
self._emit("session.complete", {"reason": "replan_budget"})
return SessionResult(
status="failed", reason="replan_budget",
history=history, revisions=revisions, events=list(self._events),
)
replans_used += 1
revision += 1
new_plan = self._planner(goal, history, last_error)
self._emit("plan.draft", {"revision": revision, "steps": _summarize(new_plan)})
if not new_plan:
self._emit("session.complete", {"reason": "no_plan"})
return SessionResult(
status="failed", reason="no_plan",
history=history, revisions=revisions, events=list(self._events),
)
diff = _diff_plans(plan[cursor:], new_plan, revision)
revisions.append(diff)
self._emit("plan.diff", diff.to_dict())
plan = new_plan
cursor = 0
self._emit("plan.commit", {"revision": revision, "steps": _summarize(plan)})
self._emit("session.complete", {"reason": "goal_met"})
return SessionResult(
status="completed", reason="goal_met",
history=history, revisions=revisions, events=list(self._events),
)
def _summarize(plan: list[Step]) -> list[dict]:
return [{"id": s.id, "tool": s.tool_name, "outcome": s.expected_outcome} for s in plan]
def make_deterministic_planner(fail_step_id: int | None, recovery: str = "route_around") -> Planner:
"""Planner used in the demo and tests.
When ``fail_step_id`` is given, the planner inserts a ``_force_fail`` marker
into that step's args on the initial plan. Executors that honor the marker
raise on that step, exercising the replan path. The marker is removed on the
revised plan so the route-around can succeed.
"""
def planner(goal: str, history: list[Step], last_error: str | None) -> list[Step]:
if last_error is None:
initial = [
Step(1, "fetch", {"key": "input"}, "loaded user input"),
Step(2, "transform", {"mode": "v1"}, "computed v1 form"),
Step(3, "render", {}, "rendered output"),
Step(4, "submit", {}, "submitted to backend"),
]
if fail_step_id is not None:
for s in initial:
if s.id == fail_step_id:
s.args = {**s.args, "_force_fail": True}
return initial
if recovery == "route_around" and "transform" in last_error:
return [
Step(2, "transform", {"mode": "v2"}, "computed via fallback"),
Step(3, "render", {}, "rendered output"),
Step(4, "submit", {}, "submitted to backend"),
]
if recovery == "give_up":
return [
Step(98, "log_failure", {"why": last_error or ""}, "logged failure"),
Step(99, "notify_user", {}, "told the user"),
]
return []
return planner
def _demo() -> None:
counters = {"transform_v1_calls": 0}
def executor(tool: str, args: dict) -> Any:
if args.get("_force_fail"):
counters["transform_v1_calls"] += 1
raise ToolFailure(f"{tool} marker-forced failure")
if tool == "fetch":
return {"k": "v"}
if tool == "transform":
if args.get("mode") == "v1":
counters["transform_v1_calls"] += 1
raise ToolFailure("transform v1 backend down")
return {"ok": True}
if tool == "render":
return "html"
if tool == "submit":
return {"id": 1}
if tool in ("log_failure", "notify_user"):
return "logged"
raise ToolFailure(f"unknown tool {tool}")
agent = PlanExecuteAgent(
planner=make_deterministic_planner(fail_step_id=2, recovery="route_around"),
executor=executor,
max_steps=12, max_replans=5,
)
res = agent.run("ship the report")
print(json.dumps({
"status": res.status,
"reason": res.reason,
"history": [(s.id, s.tool_name, bool(s.error)) for s in res.history],
"revisions": [r.to_dict() for r in res.revisions],
"events": [e.type for e in res.events],
"transform_v1_calls": counters["transform_v1_calls"],
}, indent=2))
if __name__ == "__main__":
_demo()