> tpl_air_037
Planner-Executor Contract
Formal interface and state machine contract governing decomposed multi-step agentic systems, standardizing task decomposition DAG schemas, step precondition validation, intermediate state scratchpads, dynamic replanning triggers upon tool failures, and deterministic loop-termination bounds.
Agent orchestration contract standardizing task decomposition DAGs, scratchpads, tool failure replanning, and loop bounds.
Important Tech Document Template & Operational Notice
TinyCTO.tv Tech Document Template Notice: This template is a general educational and operational starting point. It is not legal, tax, accounting, investment, procurement, regulatory, security or certification advice. Requirements vary by jurisdiction, organization, contract and risk. Review and adapt it with qualified professionals before relying on it.
Problem Solved
Monolithic single-prompt agents attempt to reason and execute tools simultaneously, resulting in chaotic hallucinations, forgotten intermediate steps, unhandled API error loops, and catastrophic non-deterministic execution failure.
When to Use
- •Architecting complex, multi-step autonomous AI workflows requiring distinct planning, tool execution, and reflection stages
- •Implementing LangGraph or Temporal state machines where an agent must decompose a large goal into an acyclic task graph
- •Establishing deterministic error-handling and dynamic replanning when tools fail or return unexpected results
When NOT to Use
- •For simple, single-turn conversational chatbots without multi-step tool dependencies
- •For registering individual API endpoints and tool parameter schemas (use TPL-AIR-035)
5 Template Sections & Structural Outline
Decoupling the high-reasoning Planner (generates the execution DAG) from the fast Executor (invokes tools and captures outputs). Preventing context pollution and tool hallucinations.
Formal Pydantic schema for task decomposition: Step ID, sequential dependencies, target tool name, required input parameters, expected schema of the result, and timeout bounds.
Centralized state blackboard (LangGraph State / Postgres / Redis): Storing completed step outputs, scratchpad notes, raw tool payloads, and token consumption metrics.
Handling execution friction: When a tool returns 4xx/5xx errors or unexpected schema, the state machine triggers a "Replan Event", providing the planner with error context to formulate an alternative sub-DAG.
Fail-safe termination: Hard ceilings on execution (e.g. Max 10 steps, Max 50,000 tokens, Max 120 seconds execution time). Deterministic exit states: SUCCESS, PARTIAL_SUCCESS, REPLAN_EXHAUSTED, TIMEOUT.
Completion Instructions
Independent Review Checklist
- All mandatory sections completed
- No secrets or passwords included
- Executive sponsor sign-off obtained
Planner-Executor Contract - Worked Case Study
Fictional Entity: Multi-Step Autonomous Financial Compliance Agent Auditing Global Supplier Invoices
Real-world production case study demonstrating complete operational adoption for Multi-Step Autonomous Financial Compliance Agent Auditing Global Supplier Invoices.
- •Decomposed complex 8-step auditing goal into a validated DAG with explicit dependency gating
- •Handled ERP API rate-limit failure via automated dynamic replanning using cached secondary endpoints
- •Enforced a strict 10-step ceiling preventing runaway agent execution loops and budget overruns
Frequently Asked Questions
Why is decoupling the Planner from the Executor strictly necessary in agentic workflows?
When a single prompt attempts to simultaneously reason about high-level strategy and execute low-level tool parameters, the context window quickly becomes cluttered with tool outputs, causing the model to forget its original goal or hallucinate fictitious arguments. A dual-brain architecture assigns planning to a high-reasoning model and execution to an efficient tool-calling loop.
How does dynamic replanning operate when an intermediate tool invocation fails?
If an executor tool call returns an unrecoverable error (e.g., API 500 or resource not found), the executor does not retry blindly. It captures the error signature, halts the local DAG branch, and dispatches an exception event back to the Planner. The Planner evaluates the scratchpad, discards the blocked branch, and generates an alternative sub-DAG.
What prevents Planner-Executor architectures from burning thousands of dollars in infinite loops?
Production agent contracts enforce strict deterministic resource bounds: 1. A maximum step budget (e.g. 10 steps), 2. A hard token expenditure ceiling (e.g. 50k tokens), 3. A wall-clock timeout (e.g. 120 seconds), and 4. A maximum replanning limit (2 replans). If any threshold is breached, the state machine forcibly aborts with an EXHAUSTED status.
Download Tech Document Pack
Auth RequiredDownload all blank templates, worked scenarios, and verification manifests in a single verified archive.
Authoritative Sources
- ReAct: Synergizing Reasoning and Acting in Language ModelsYao et al. / Princeton University & Google Research • OFFICIAL REQUIREMENT
- Plan-and-Solve Prompting: Improving Zero-Shot Chain-of-Thought ReasoningWang et al. / ACL 2023 • OFFICIAL REQUIREMENT
- LangGraph: Multi-Agent State Machine and Cyclic Graph ArchitectureLangChain AI • OFFICIAL REQUIREMENT