Blueprints BP-02
Planner-worker multi-agent system
A task needs several tools and steps, and one prompt cannot hold it.
01 / Fit
Use it when
- A task needs several tools and the order of steps depends on what earlier steps return.
- Each step has an output that can be checked on its own.
- A single prompt has been tried and fails as the task grows.
- The process can tolerate a person taking over a task part-way through.
Avoid it when
- The steps are the same every time. A fixed workflow is cheaper and easier to test.
- No step output can be verified, so errors pass silently from one worker to the next.
- The latency budget is tight. Planning and verification add model calls to every task.
02 / The diagram
Run it. Then run the failure path.
Select a node to see what it does, how it fails and what we measure.
- Task (Goal, limits). Takes the goal, the allowed tools and the step, time and spend limits for this task. Fails when: The goal is vague, so success cannot be checked. Safeguard: A task without a checkable outcome is sent back before any planning starts.
- Planner (Step plan). Splits the goal into ordered steps, each with one tool and an expected output. Fails when: The plan includes steps that depend on results it never asks for. Safeguard: Plans are validated against the tool list and a step limit before dispatch.
- Dispatch (Queue steps). Hands each step to a worker and tracks which are running, done or failed. Fails when: A step is dispatched twice after a retry. Safeguard: Every step carries an idempotency key. A retry reuses it.
- Workers (One tool each). Each worker carries out one step with one tool and a narrow prompt. Fails when: A worker loops on a failing tool or drifts from its step. Safeguard: Per-step limits on calls and time. A worker returns an error instead of improvising.
- Verify (Check outputs). Checks each step result against its expected output and the task limits before it is used. Fails when: A result looks complete and does not match what the step asked for. Safeguard: Typed outputs and rule checks come first. A failed check stops the task from building on that result.
- Result (Assembled). Assembles the verified step results into the final output, with the trace attached. Fails when: The parts are each correct and contradict each other. Safeguard: A final consistency check across steps before anything is returned.
- Task state (Results so far). Stores the plan, each step result and the spend so far, outside any model context. Fails when: Two workers write conflicting results for the same step. Safeguard: One writer per step. Writes are versioned.
- Handover (Person decides). A person receives the task with the plan, the trace and the failed check. Fails when: Handovers arrive without enough context to act on. Safeguard: A fixed handover format: goal, steps done, what failed and why.
Read the diagram as text
- Task (Goal, limits). Takes the goal, the allowed tools and the step, time and spend limits for this task. Fails when: The goal is vague, so success cannot be checked. Safeguard: A task without a checkable outcome is sent back before any planning starts.
- Planner (Step plan). Splits the goal into ordered steps, each with one tool and an expected output. Fails when: The plan includes steps that depend on results it never asks for. Safeguard: Plans are validated against the tool list and a step limit before dispatch.
- Dispatch (Queue steps). Hands each step to a worker and tracks which are running, done or failed. Fails when: A step is dispatched twice after a retry. Safeguard: Every step carries an idempotency key. A retry reuses it.
- Workers (One tool each). Each worker carries out one step with one tool and a narrow prompt. Fails when: A worker loops on a failing tool or drifts from its step. Safeguard: Per-step limits on calls and time. A worker returns an error instead of improvising.
- Verify (Check outputs). Checks each step result against its expected output and the task limits before it is used. Fails when: A result looks complete and does not match what the step asked for. Safeguard: Typed outputs and rule checks come first. A failed check stops the task from building on that result.
- Result (Assembled). Assembles the verified step results into the final output, with the trace attached. Fails when: The parts are each correct and contradict each other. Safeguard: A final consistency check across steps before anything is returned.
- Task state (Results so far). Stores the plan, each step result and the spend so far, outside any model context. Fails when: Two workers write conflicting results for the same step. Safeguard: One writer per step. Writes are versioned.
- Handover (Person decides). A person receives the task with the plan, the trace and the failed check. Fails when: Handovers arrive without enough context to act on. Safeguard: A fixed handover format: goal, steps done, what failed and why.
03 / Components
Every component, and how it fails.
| Component | Job | Typical choices | Fails when | Safeguard |
|---|---|---|---|---|
| Task | Takes the goal, the allowed tools and the step, time and spend limits for this task. | Task intake API with a typed goal, tool allow-list and limits | The goal is vague, so success cannot be checked. | A task without a checkable outcome is sent back before any planning starts. |
| Planner | Splits the goal into ordered steps, each with one tool and an expected output. | Language model with structured plan output and a plan validator | The plan includes steps that depend on results it never asks for. | Plans are validated against the tool list and a step limit before dispatch. |
| Dispatch | Hands each step to a worker and tracks which are running, done or failed. | Durable task queue with idempotent step execution | A step is dispatched twice after a retry. | Every step carries an idempotency key. A retry reuses it. |
| Workers | Each worker carries out one step with one tool and a narrow prompt. | Tool-calling language models, one narrow prompt and tool set per worker type | A worker loops on a failing tool or drifts from its step. | Per-step limits on calls and time. A worker returns an error instead of improvising. |
| Verify | Checks each step result against its expected output and the task limits before it is used. | Schema validation and rule checks, with a model check where rules cannot decide | A result looks complete and does not match what the step asked for. | Typed outputs and rule checks come first. A failed check stops the task from building on that result. |
| Result | Assembles the verified step results into the final output, with the trace attached. | Deterministic assembly step with a cross-step consistency check | The parts are each correct and contradict each other. | A final consistency check across steps before anything is returned. |
| Task state | Stores the plan, each step result and the spend so far, outside any model context. | Versioned key-value or document store, held outside model context | Two workers write conflicting results for the same step. | One writer per step. Writes are versioned. |
| Handover | A person receives the task with the plan, the trace and the failed check. | Review queue showing the plan, the trace and the failed check | Handovers arrive without enough context to act on. | A fixed handover format: goal, steps done, what failed and why. |
04 / Budgets and evals
What the design is tuned for.
Task completion rate, steps per task. These are design targets, not results.
| Stage | Design target |
|---|---|
| Planner | Short plans. A step limit is enforced before any worker runs. |
| Workers | Narrow prompts and one tool each, so a smaller model can do most steps. |
| Verify | Rule checks first. Model checks only where a rule cannot decide. |
| Whole task | Hard limits on steps, time and spend, with handover when one is reached. |
Eval plan 01
Golden set
Complete tasks with a known-good final output, plus step-level cases for each worker type. It includes tasks that should be handed over, not completed.
Eval plan 02
Release gates
Task completion rate, steps per task and verification failures by step type. Any task that exceeds its limits without a handover blocks the release.
Eval plan 03
Catching regressions
Planner and workers are evaluated separately and together, because a change to one shifts the load on the other. Handed-over tasks are reviewed and added to the set.
05 / Design notes
Where the whiteboard and production differ.
- Most failures come from the hand-off between steps, not from any single step. A worker receives less context than the planner assumed.
- Adding agents raises cost and latency faster than it raises completion rate. Two or three worker types cover most tasks.
- State kept only in model context is lost on the first retry. It belongs in a store the orchestrator owns.
- Replanning after a failed step is useful once and harmful in a loop. A replan limit is as important as a step limit.
- Traces grow large quickly. Deciding what to keep per step is a design decision, not a logging detail.
06 / Deploy
Deploy this with us.
A pod can take BP-02 from this page to your stack. Tell us the workflow and we will tell you what changes for your systems.
You will talk to an engineer