Agentic Architectures

Catalogue / Tools & Action

As-Needed Decomposition

Try the task whole, and split only the part that failed

Shape
loop
Model calls
1 per attempt + 1 planner call per failed task that is split (1 to about 25)
Latency
medium
Complexity
medium

Also known as ADaPT, Decompose on failure

1

Why plan a task in pieces before knowing whether it is hard?

A plan written first guesses how hard each step is. Some steps turn out too hard for the executor, and others never needed splitting. Here the executor tries the task as given. Only when it fails does a planner split that task, and each sub-task goes through the same try-then-split procedure.

You may need it if

  • Plans split easy tasks into steps that one executor pass would have handled.
  • A run fails because one planned step was too big, and nothing breaks that step down further.
  • The same executor handles some tasks whole and gets lost on others, and you cannot tell which in advance.
2

When is trying first, and planning only after a failure, a bad idea?

Use it when

  • Task difficulty varies a lot and cannot be judged before an attempt.
  • A failed attempt costs time and nothing else, so trying first is safe.
  • The executor can tell, or a check can tell, whether an attempt reached its goal.

Avoid it when

  • An attempt has effects that cannot be undone, such as deleting data or sending a message. Trying before planning is then unsafe.
    Use Dry Run instead
  • Nothing reliable says whether an attempt succeeded. The executor's own report decides everything here.
    Use Plan–Execute–Verify instead
  • The steps are known before starting and someone should see them before any work is done.
    Use Planning instead
  • The executor nearly always succeeds on the first attempt. The planner and the recursion are never used.
    Use ReAct instead

What it costs

Model calls
1 per attempt + 1 planner call per failed task that is split (1 to about 25)
Latency
medium
Complexity
medium
3

How does a failed attempt turn into smaller attempts?

The executor attempts the task and reports success or failure. On success the task is done. On failure, and if depth remains, the planner splits that task into a few sub-tasks joined by all or any. Each sub-task re-enters the same loop one level deeper. Plain code combines the outcomes.

failed,depth leftfirst sub-task,one level downnext sub-taskin the treeroot taskresolved asdoneroot taskresolved asfailedTask: The task to accomplish. The executor's tools are already configured.TaskExecutor: Attempts the task it is given with its tools, then reports completed or failed with a short result.ExecutorSucceeded?: Plain code. Records the report, combines sub-task outcomes with all or any, and checks the depth limit.Succeeded?Task tree: The root task and every sub-task created so far, with its level, its all or any rule and its outcome.Task treePlanner: Called only for a task that failed. Splits it into a few sub-tasks and says whether all are needed or any one is enough.PlannerResult: The root task is done. Carries the results of the attempts that succeeded and the task tree.ResultFailed: The root task could not be completed within the depth limit. Carries the tree and the task that blocked it.Failed
  1. Step 1 of 7

    Try the whole task first

    For "Build the quarterly churn table from the data warehouse", nothing is planned. The executor gets the task as written and attempts it with its query tools.

  2. Step 2 of 7

    The attempt fails

    The executor cannot find where cancellations are stored and reports "task failed". Plain code records this in the tree. The task is at level 1 of 3, so it may be split.

  3. Step 3 of 7

    Only the failed task is split

    The planner splits it into three sub-tasks, all needed, in order: get cancellations per month, get active accounts per month, compute the rates and write the table.

  4. Step 4 of 7

    Each sub-task is tried the same way

    The executor attempts the first sub-task as if it were the whole job. When it succeeds, its result is recorded and passed to the next sub-task. A sub-task that succeeds is never split.

  5. Step 5 of 7

    A sub-task fails too

    Say the first sub-task fails. The planner splits it again, at level 3, into two alternatives where any one is enough: read the billing cancellations table, or derive cancellations from subscription end dates.

  6. Step 6 of 7

    Outcomes are combined upwards

    An any-group is done at its first success. An all-group is done when every member is. When this makes the root task done, the run returns the results of the successful attempts.

  7. Step 7 of 7

    The depth limit ends the descent

    A task that fails at level 3 is not split again. If it was needed and no alternative remains, the failure rises to the root and the run ends as failed, with the blocking task named.

What each part does
Task
The task to accomplish. The executor's tools are already configured.
Executor
Attempts the task it is given with its tools, then reports completed or failed with a short result.
Succeeded?
Plain code. Records the report, combines sub-task outcomes with all or any, and checks the depth limit.
Task tree
The root task and every sub-task created so far, with its level, its all or any rule and its outcome.
Planner
Called only for a task that failed. Splits it into a few sub-tasks and says whether all are needed or any one is enough.
Result
The root task is done. Carries the results of the attempts that succeeded and the task tree.
Failed
The root task could not be completed within the depth limit. Carries the tree and the task that blocked it.
  • Executor → Succeeded?: completed or failed
  • Succeeded? → Task tree: outcome of the task
  • Succeeded? → Planner: failed, depth left
  • Planner → Task tree: sub-tasks, all or any
  • Planner → Executor: first sub-task, one level down
  • Task tree → Executor: next sub-task, earlier results
  • Succeeded? → Executor: next sub-task in the tree
  • Succeeded? → Result: root task resolved as done
  • Succeeded? → Failed: root task resolved as failed

Where it connects

Entry
task
Task

A task whose attempts can be judged as completed or failed, and whose failed attempts leave nothing behind that must be undone.

Exit
result
AnswerOutcome

When: The root task is resolved as done, directly or through its sub-tasks.

The results of the attempts that succeeded, in order, then the task tree with the level, the all or any rule and the outcome of every task.

Exit
failed
Verdict

When: A needed task still fails at the depth limit, or the attempt budget runs out.

A failure notice naming the task that blocked the run, with the task tree and the partial results of sub-tasks that did succeed.

Working memory for one run
task-tree
PlanOutcome

Every task and sub-task with its level, its parent, the all or any rule of its group, its outcome and the short result of its attempt.

4

What do I ask my assistant to set up?

The agents to launch

Executor

Attempt the task you are given with your tools, as if it were the whole job. Work step by step. End with exactly one verdict: completed, with a short result, or failed, with what blocked you. Do not report completed unless the goal of the task was reached. Do not split the task yourself.

Sees: One task or sub-task, and the results of earlier sub-tasks that succeeded. Not the task tree and not earlier failed attempts.

Planner

The executor failed on this task. Split it into two to five smaller sub-tasks, each one something the executor could attempt alone. State whether all of them are needed, in the order given, or whether they are alternatives and any one is enough. Do not carry out any sub-task.

Sees: The failed task and the results of earlier sub-tasks that succeeded. It is never called for a task that succeeded.

A prompt you can paste

Works with any assistant that can launch sub-agents. It contains the agents, the procedure and the stop rule above.

Framework-agnostic prompt
You are the orchestrator of a multi-agent workflow that follows the "As-Needed Decomposition" architecture.
Launch every agent listed below as a separate sub-agent with its own context. Give each agent only the context stated for it. Do not do an agent's work yourself. If you cannot launch sub-agents, play each agent in a clearly separated turn and never let it use what is withheld from it.

# Task
[Describe your task here]

# As-Needed Decomposition
Try the task whole, and split only the part that failed.
Input: the task above. It must provide: A task whose attempts can be judged as completed or failed, and whose failed attempts leave nothing behind that must be undone. If something essential is missing, ask for it before starting.

Agents to launch:
- Executor: Attempt the task you are given with your tools, as if it were the whole job. Work step by step. End with exactly one verdict: completed, with a short result, or failed, with what blocked you. Do not report completed unless the goal of the task was reached. Do not split the task yourself.
  Context for this agent: One task or sub-task, and the results of earlier sub-tasks that succeeded. Not the task tree and not earlier failed attempts.
- Planner: The executor failed on this task. Split it into two to five smaller sub-tasks, each one something the executor could attempt alone. State whether all of them are needed, in the order given, or whether they are alternatives and any one is enough. Do not carry out any sub-task.
  Context for this agent: The failed task and the results of earlier sub-tasks that succeeded. It is never called for a task that succeeded.

Procedure:
1. Check that a failed attempt leaves nothing to undo. If attempts have lasting effects, do not use this procedure.
2. Launch the executor on the task as given, at level 1. Record its verdict and result in the task tree.
3. If it reports completed, that task is done. Never split a task that succeeded.
4. If it reports failed and the task is above level 3, launch the planner on that task. Record the sub-tasks and their rule, all or any.
5. Run this same procedure on each sub-task in order, one level deeper, passing along the results of earlier sub-tasks that succeeded.
6. Combine in plain code. With all, the parent is done when every sub-task is done, and failed at the first failure. With any, it is done at the first success.
7. A task that fails at level 3 is not split. Report it as failed to its parent.

Stop rule: Stop when the root task is resolved as done or failed. Tasks are split down to level 3 at most, with the root at level 1. End the run as failed after 20 executor attempts.

Exits:
- `result`, when: The root task is resolved as done, directly or through its sub-tasks. Deliver: The results of the attempts that succeeded, in order, then the task tree with the level, the all or any rule and the outcome of every task.
- `failed`, when: A needed task still fails at the depth limit, or the attempt budget runs out. Deliver: A failure notice naming the task that blocked the run, with the task tree and the partial results of sub-tasks that did succeed.

# Final deliverable
The outcome of the root task, done or failed. Then the results of the successful attempts in order and the task tree. If failed, name the task that blocked the run.

The same thing in code

LangGraph, python, package langgraph
from typing import Literal, TypedDict

from langchain.chat_models import init_chat_model
from langchain_core.messages import HumanMessage, SystemMessage
from langgraph.graph import END, START, StateGraph
from pydantic import BaseModel

MAX_DEPTH, MAX_ATTEMPTS = 3, 20

EXECUTOR = ("Attempt the task you are given, as if it were the whole job. End with one verdict: completed, with "
            "a short result, or failed, with what blocked you. Do not report completed unless the goal was "
            "reached. Do not split the task yourself.")
PLANNER = ("The executor failed on this task. Split it into two to five smaller sub-tasks it could attempt alone. "
           "Say 'and' if all are needed in the order given, 'or' if they are alternatives. Do no sub-task yourself.")


class Attempt(BaseModel):
    completed: bool
    result: str  # what was done, or what blocked it


class Split(BaseModel):
    subtasks: list[str]
    logic: Literal["and", "or"]


class State(TypedDict):
    task: str
    depth: int
    context: list[str]  # results of earlier sub-tasks that succeeded
    completed: bool
    result: str
    split: Split | None
    log: list[dict]  # the task tree, flattened: one entry per attempt


model = init_chat_model("anthropic:claude-sonnet-5-5")
attempts = 0  # the attempt budget, shared by every level of one run


async def executor(state: State) -> dict:
    global attempts
    if attempts >= MAX_ATTEMPTS:
        return {"completed": False, "result": "not attempted: attempt budget used up"}
    attempts += 1
    prompt = f"Task: {state['task']}\nEarlier results:\n" + ("\n".join(state["context"]) or "(none)")
    a = Attempt.model_validate(await model.with_structured_output(Attempt).ainvoke([SystemMessage(EXECUTOR), HumanMessage(prompt)]))
    entry = {"level": state["depth"], "task": state["task"], "completed": a.completed, "result": a.result}
    return {"completed": a.completed, "result": a.result, "log": [entry]}


def succeeded(state: State) -> str:
    # the gate: only a failed task is split, and only while depth and budget remain
    return END if state["completed"] or state["depth"] >= MAX_DEPTH or attempts >= MAX_ATTEMPTS else "planner"


async def planner(state: State) -> dict:
    prompt = f"Failed task: {state['task']}\nEarlier results:\n" + ("\n".join(state["context"]) or "(none)")
    return {"split": Split.model_validate(await model.with_structured_output(Split).ainvoke([SystemMessage(PLANNER), HumanMessage(prompt)]))}


async def subtasks(state: State) -> dict:
    split, done, log = state["split"], [], list(state["log"])
    assert split is not None
    for sub in split.subtasks:  # each sub-task re-enters the same graph, one level down
        child = await graph.ainvoke({"task": sub, "depth": state["depth"] + 1, "context": state["context"] + done,
                                     "completed": False, "result": "", "split": None, "log": []})
        log += child["log"]
        if child["completed"]:
            done.append(f"{sub}: {child['result']}")
        if child["completed"] and split.logic == "or":
            return {"completed": True, "result": child["result"], "log": log}
        if not child["completed"] and split.logic == "and":
            return {"completed": False, "result": f"blocked by: {sub}", "log": log}
    ok = split.logic == "and"  # every 'and' member succeeded, or no 'or' alternative did
    return {"completed": ok, "result": "\n".join(done) if ok else f"no alternative worked for: {state['task']}", "log": log}


builder = StateGraph(State)
builder.add_node("executor", executor)
builder.add_node("planner", planner)
builder.add_node("subtasks", subtasks)
builder.add_edge(START, "executor")
builder.add_conditional_edges("executor", succeeded, ["planner", END])
builder.add_edge("planner", "subtasks")
builder.add_edge("subtasks", END)
graph = builder.compile()


async def run(task: str) -> dict:
    global attempts
    attempts = 0
    s = await graph.ainvoke({"task": task, "depth": 1, "context": [], "completed": False, "result": "", "split": None, "log": []})
    return {"completed": s["completed"], "result": s["result"], "tree": s["log"], "attempts": attempts}

The executor here is one structured call; in practice make it a tool loop over your environment. The module-level counter is for one run at a time.

Claude Agent SDK, python, package claude-agent-sdk
from typing import Literal

from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, ResultMessage, query
from pydantic import BaseModel

MAX_DEPTH, MAX_ATTEMPTS = 3, 20


class Attempt(BaseModel):
    completed: bool
    result: str  # what was done, or what blocked it


class Split(BaseModel):
    subtasks: list[str]
    logic: Literal["and", "or"]


AGENTS = {
    "executor": AgentDefinition(
        description="Attempts one task and reports completed or failed.",
        prompt="Attempt the task you are given, as if it were the whole job. End with one verdict: completed, with "
               "a short result, or failed, with what blocked you. Do not report completed unless the goal was "
               "reached. Do not split the task yourself.",
    ),
    "planner": AgentDefinition(
        description="Splits a task the executor failed on.",
        prompt="The executor failed on this task. Split it into two to five smaller sub-tasks it could attempt alone. "
               "Say 'and' if all are needed in the order given, 'or' if they are alternatives. Do no sub-task yourself.",
    ),
}


async def delegate[T: BaseModel](agent: str, message: str, schema: type[T]) -> T:
    # one fresh session per call, so each sub-agent sees only the message it is given
    options = ClaudeAgentOptions(
        agents=AGENTS,
        allowed_tools=["Agent"],
        output_format={"type": "json_schema", "schema": schema.model_json_schema()},
    )
    prompt = f"Delegate this to the {agent} agent, passing it verbatim, and return its reply unchanged:\n\n{message}"
    async for msg in query(prompt=prompt, options=options):
        if isinstance(msg, ResultMessage):
            return schema.model_validate(msg.structured_output)
    raise RuntimeError("no result")


async def solve(task: str, depth: int, context: list[str], log: list[dict]) -> tuple[bool, str]:
    if depth > MAX_DEPTH or len(log) >= MAX_ATTEMPTS:
        return False, "not attempted: depth limit or attempt budget reached"
    earlier = "\n".join(context) or "(none)"
    attempt = await delegate("executor", f"Task: {task}\nEarlier results:\n{earlier}", Attempt)  # try first
    log.append({"level": depth, "task": task, "completed": attempt.completed, "result": attempt.result})
    if attempt.completed:  # a task that succeeded is never split
        return True, attempt.result
    if depth == MAX_DEPTH:  # the depth limit ends the descent
        return False, attempt.result
    split = await delegate("planner", f"Failed task: {task}\nEarlier results:\n{earlier}", Split)
    done: list[str] = []
    for sub in split.subtasks:  # each sub-task goes through the same procedure, one level down
        ok, result = await solve(sub, depth + 1, context + done, log)
        if ok:
            done.append(f"{sub}: {result}")
        if ok and split.logic == "or":
            return True, result
        if not ok and split.logic == "and":
            return False, f"blocked by: {sub}"
    if split.logic == "and":
        return True, "\n".join(done)
    return False, f"no alternative worked for: {task}"


async def run(task: str) -> dict:
    log: list[dict] = []  # the task tree, flattened: one entry per attempt
    completed, result = await solve(task, 1, [], log)
    return {"completed": completed, "result": result, "tree": log, "attempts": len(log)}

Give the executor definition the tools of your environment. Its own verdict decides success here; swap in a coded check where one exists.

OpenAI Agents SDK, python, package openai-agents
from typing import Literal

from agents import Agent, Runner
from pydantic import BaseModel

MAX_DEPTH, MAX_ATTEMPTS = 3, 20


class Attempt(BaseModel):
    completed: bool
    result: str  # what was done, or what blocked it


class Split(BaseModel):
    subtasks: list[str]
    logic: Literal["and", "or"]


executor = Agent(
    name="Executor",
    instructions="Attempt the task you are given, as if it were the whole job. End with one verdict: completed, with "
                 "a short result, or failed, with what blocked you. Do not report completed unless the goal was "
                 "reached. Do not split the task yourself.",
    output_type=Attempt,  # add tools=[...] for your environment
)
planner = Agent(
    name="Planner",
    instructions="The executor failed on this task. Split it into two to five smaller sub-tasks it could attempt alone. "
                 "Say 'and' if all are needed in the order given, 'or' if they are alternatives. Do no sub-task yourself.",
    output_type=Split,
)


async def solve(task: str, depth: int, context: list[str], log: list[dict]) -> tuple[bool, str]:
    if depth > MAX_DEPTH or len(log) >= MAX_ATTEMPTS:
        return False, "not attempted: depth limit or attempt budget reached"
    earlier = "\n".join(context) or "(none)"
    attempt = (await Runner.run(executor, f"Task: {task}\nEarlier results:\n{earlier}")).final_output_as(Attempt)  # try first
    log.append({"level": depth, "task": task, "completed": attempt.completed, "result": attempt.result})
    if attempt.completed:  # a task that succeeded is never split
        return True, attempt.result
    if depth == MAX_DEPTH:  # the depth limit ends the descent
        return False, attempt.result
    split = (await Runner.run(planner, f"Failed task: {task}\nEarlier results:\n{earlier}")).final_output_as(Split)
    done: list[str] = []
    for sub in split.subtasks:  # each sub-task goes through the same procedure, one level down
        ok, result = await solve(sub, depth + 1, context + done, log)
        if ok:
            done.append(f"{sub}: {result}")
        if ok and split.logic == "or":
            return True, result
        if not ok and split.logic == "and":
            return False, f"blocked by: {sub}"
    if split.logic == "and":
        return True, "\n".join(done)
    return False, f"no alternative worked for: {task}"


async def run(task: str) -> dict:
    log: list[dict] = []  # the task tree, flattened: one entry per attempt
    completed, result = await solve(task, 1, [], log)
    return {"completed": completed, "result": result, "tree": log, "attempts": len(log)}

Give the executor the tools of your environment. Its own verdict decides success here; swap in a coded check where one exists.

Vercel AI SDK, typescript, package ai
import { anthropic } from '@ai-sdk/anthropic';
import { Output, ToolLoopAgent } from 'ai';
import { z } from 'zod';

const MAX_DEPTH = 3;
const MAX_ATTEMPTS = 20;
const model = anthropic('claude-sonnet-5-5');

const executor = new ToolLoopAgent({
  model, // add tools for your environment
  instructions:
    'Attempt the task you are given, as if it were the whole job. End with one verdict: completed, with ' +
    'a short result, or failed, with what blocked you. Do not report completed unless the goal was ' +
    'reached. Do not split the task yourself.',
  output: Output.object({
    schema: z.object({ completed: z.boolean(), result: z.string().describe('what was done, or what blocked it') }),
  }),
});

const planner = new ToolLoopAgent({
  model,
  instructions:
    'The executor failed on this task. Split it into two to five smaller sub-tasks it could attempt alone. ' +
    "Say 'and' if all are needed in the order given, 'or' if they are alternatives. Do no sub-task yourself.",
  output: Output.object({ schema: z.object({ subtasks: z.array(z.string()), logic: z.enum(['and', 'or']) }) }),
});

type Entry = { level: number; task: string; completed: boolean; result: string };
type Outcome = { ok: boolean; result: string };

async function solve(task: string, depth: number, context: string[], log: Entry[]): Promise<Outcome> {
  if (depth > MAX_DEPTH || log.length >= MAX_ATTEMPTS) {
    return { ok: false, result: 'not attempted: depth limit or attempt budget reached' };
  }
  const earlier = context.join('\n') || '(none)';
  // try first
  const { output: attempt } = await executor.generate({ prompt: `Task: ${task}\nEarlier results:\n${earlier}` });
  log.push({ level: depth, task, completed: attempt.completed, result: attempt.result });
  if (attempt.completed) return { ok: true, result: attempt.result }; // a task that succeeded is never split
  if (depth === MAX_DEPTH) return { ok: false, result: attempt.result }; // the depth limit ends the descent
  const { output: split } = await planner.generate({ prompt: `Failed task: ${task}\nEarlier results:\n${earlier}` });
  const done: string[] = [];
  for (const sub of split.subtasks) {
    // each sub-task goes through the same procedure, one level down
    const child = await solve(sub, depth + 1, [...context, ...done], log);
    if (child.ok) done.push(`${sub}: ${child.result}`);
    if (child.ok && split.logic === 'or') return child;
    if (!child.ok && split.logic === 'and') return { ok: false, result: `blocked by: ${sub}` };
  }
  if (split.logic === 'and') return { ok: true, result: done.join('\n') };
  return { ok: false, result: `no alternative worked for: ${task}` };
}

export async function run(task: string) {
  const log: Entry[] = []; // the task tree, flattened: one entry per attempt
  const { ok, result } = await solve(task, 1, [], log);
  return { completed: ok, result, tree: log, attempts: log.length };
}

Give the executor the tools of your environment. Its own verdict decides success here; swap in a coded check where one exists.

Snippets are generated when the site is built and type-checked against the SDK versions listed in the repository. Treat them as a starting skeleton.

What goes wrong

  • The executor judges its own success and tends to say completed too easily. Where you can, replace its verdict with a check in code, such as a test or a row count.
  • An attempt that half-finishes before failing leaves a changed state for the sub-tasks. Use this only where failed attempts are harmless.
  • Without a depth limit and an attempt budget, a task the executor cannot do is split again and again.
  • Sub-tasks that do not receive earlier results redo work or contradict it. Pass each one what its finished siblings produced.

Chain it

Its result can feed

Source