What is Planner-Executor?
Planner-Executor is an AI agent architecture that creates a versioned, machine-readable plan for a goal, then executes and validates bounded steps through a separate component while preserving policy, state, budget, approval, and replanning controls.
Quick Facts
| Specification | Official Specification |
|---|
How It Works
Planner-Executor separates strategic task decomposition from tactical work. The Planner receives the goal, trusted constraints, available capability summaries, and relevant state, then produces a Plan Artifact. The Executor resolves ready steps, validates their preconditions, proposes concrete tool calls, records observations and postconditions, and returns evidence to a Replanner or terminal validator.
A useful Plan Artifact is more than a natural-language checklist. Give it a stable plan ID and version, objective, assumptions, ordered or graph dependencies, step IDs, expected inputs and outputs, success and stop criteria, capability requirements, risk class, budget estimate, and approval requirement. Keep private chain-of-thought out of the artifact. Plans are operational proposals that humans and software can inspect, diff, validate, and reject.
A plan is not authorization. The Planner cannot grant a tool, identity, tenant, resource, credential, or side effect merely by naming it. Before every step, trusted runtime code resolves current state, validates arguments and preconditions, applies policy, and obtains argument-bound approval where required. The Executor should receive only the capabilities needed for the current step and must report actual effects separately from model prose.
Execution can invalidate assumptions. Replanning should preserve verified facts, completed steps, committed effects, unresolved unknown outcomes, remaining budgets, and user constraints. Create a new plan version and record the diff and trigger instead of silently rewriting history. Re-authorize changed tools, resources, arguments, or risk. Bound replan count and equivalent-plan repetition to prevent oscillation.
Sequential plans are easy to inspect but can waste latency when independent work could run in parallel. A dependency DAG can expose ready steps, but fan-out requires concurrency limits, deterministic merge rules, cancellation, and partial-failure policy. The Executor may be deterministic code, one model, several specialists, or a ReAct loop; assigning a smaller model is a hypothesis to evaluate against end-to-end accepted outcomes, not a universal cost optimization.
Writes require stable operation keys, idempotency, and an Effect Journal. A dispatch timeout may be outcome_unknown; reconcile before retrying or replanning around it. If a later step fails, completed effects remain unless an explicit compensation action succeeds. Checkpoints, plan versions, and execution records must survive process restart.
Evaluate plan feasibility, completeness, assumptions, dependency correctness, unnecessary steps, and risk before execution. During and after execution, score precondition compliance, authorized tool use, plan adherence or justified deviation, replan quality, duplicate effects, final source-system outcome, latency, and cost. Compare the pattern with a simpler chain or ReAct baseline; added planning is worthwhile only when it improves accepted task outcomes.
Key Characteristics
- Versioned Plan Artifact separates task strategy from step execution
- Step contracts define dependencies, preconditions, expected outputs, postconditions, risk, and budget
- Runtime authorization remains independent from planner recommendations
- Replanning preserves facts, committed effects, constraints, budgets, and auditable plan diffs
- Sequential or DAG execution supports bounded concurrency, cancellation, merge, and failure policies
- Evaluation covers plan quality, execution fidelity, justified deviation, effects, cost, and final outcome
Common Use Cases
- Software migrations with inspect, edit, test, review, and rollback stages
- Research tasks with explicit evidence goals, query dependencies, and source verification
- Operations that require a reviewed plan before any consequential tool call
- Long tasks whose remaining steps must adapt to new observations without losing completed work
- Multi-tool jobs where independent steps can execute in a bounded dependency DAG
- Comparing planned actions with the recorded Agent Trajectory during regression evaluation
Example
Loading code...Frequently Asked Questions
Does Planner-Executor require two different models?
No. Planner and Executor are logical roles. They may use different models, the same model with different contracts, deterministic code, or specialist agents. Select them through evaluation, not a fixed large-planner/small-executor rule.
Does an approved plan authorize every step?
No. A plan describes intended work. Runtime and downstream services must authorize each concrete operation against current identity, resource, arguments, policy, and approval because conditions may change after planning.
When should the system replan?
Replan when a precondition fails, evidence contradicts an assumption, a dependency becomes unavailable, the user changes the goal, or the remaining plan cannot meet its contract. Preserve completed effects and version the change.
Can plan steps run in parallel?
Yes, when dependencies permit it. Represent the plan as a DAG, bound concurrency, define deterministic result merging, propagate cancellation, and specify how partial failures affect dependent steps.
How should Planner-Executor be evaluated?
Evaluate plan feasibility and risk, step preconditions, authorized execution, adherence or justified deviation, replan quality, duplicate effects, final outcome, latency, and cost against chain and ReAct baselines.