Planning and Task Decomposition

Planning is the skill of turning a big, vague goal into a short list of small steps that an agent can actually carry out. Task decomposition is the act of splitting the goal into those steps. Without it, an agent tries to do everything in one model call and often fails, loops forever, or skips important work. With it, you get work that is easier to check, easier to retry and easier to keep safe.

Overview: how planning works

A language model has a limited context window and no guarantee of getting a long task right in one shot. Humans handle large jobs by breaking them down: “organise a trip” becomes “pick dates”, “book travel”, “book hotel”. Agents do the same. The model is asked to produce a plan: an ordered (or partly ordered) list of steps. Code then runs the steps, usually one at a time, and feeds results back to the model.

There are two broad styles:

• Interleaved (ReAct-style): the agent decides one step at a time. It thinks, acts, observes, then thinks again. It is flexible, but it can wander because it never commits to a full route.
• Plan-and-execute: the agent first writes the whole plan, then executes it. The plan can be validated, shown to a human, logged and budgeted before anything happens. If a step fails or new facts appear, the agent replans.

Most production systems mix both: a short plan up front, step-by-step execution, and a replan when reality differs from the plan.

What happens internally

1. Your code sends the goal (and the list of available tools) to the model with an instruction to output a plan in a strict format, usually JSON.
2. Your code parses and validates the plan: are the fields present, are the tools real, are the dependencies consistent, is it short enough?
3. A scheduler decides the order. Steps with no unmet dependencies are ready; others wait.
4. Each step runs. Risky steps pause for human approval.
5. Results are stored. If a step fails, the agent may retry, replan, or stop and ask for help.
6. When all steps finish, a final step checks the result against the original goal.

The model is only a planner here. Your ordinary code owns the loop, the limits and the safety checks. That separation is what makes agents dependable.

Key concepts and a plan format

A good plan is data, not prose. Free text is hard to check; JSON is easy to validate. A typical shape is:

{
  "goal": "Write a short report on solar panels",
  "steps": [
    {"id": "s1", "task": "Search for facts", "depends_on": []},
    {"id": "s2", "task": "Outline the report", "depends_on": ["s1"]}
  ]
}

Good decomposition rules

• Each step is small and checkable. You should be able to say whether it succeeded.
• Each step has one purpose and, ideally, one tool.
• Make dependencies explicit. Independent steps can run in parallel; dependent ones cannot.
• Keep plans short. Five to ten steps is a sensible range for most tasks. Very long plans go stale quickly.
• Do not over-plan unknowns. If step 4 depends on what step 2 finds, plan only to step 2 and replan afterwards.

Examples

Example 1: ask for a plan and validate it

The call_llm() function below is a stub that returns a fixed answer so the code runs offline. To use a real provider, replace its body with an SDK call that sends the prompt and returns the response text. Keep the validation; real models sometimes return broken or inconsistent plans.

import json

def call_llm(prompt: str) -> str:
    # Stub: replace with a real SDK call that returns the model's text.
    return json.dumps({
        'goal': 'Write a short report on solar panels',
        'steps': [
            {'id': 's1', 'task': 'Search for recent facts about solar panels', 'depends_on': []},
            {'id': 's2', 'task': 'Outline the report', 'depends_on': ['s1']},
            {'id': 's3', 'task': 'Write the report from the outline', 'depends_on': ['s2']},
        ],
    })

def parse_plan(text: str) -> dict:
    plan = json.loads(text)
    ids = [s['id'] for s in plan['steps']]
    if len(ids) != len(set(ids)):
        raise ValueError('duplicate step ids')
    for s in plan['steps']:
        for dep in s['depends_on']:
            if dep not in ids:
                raise ValueError('unknown dependency ' + dep + ' in ' + s['id'])
    return plan

plan = parse_plan(call_llm('Plan: write a short report on solar panels'))
for step in plan['steps']:
    print(step['id'], step['task'], '<-', step['depends_on'])

Output:

s1 Search for recent facts about solar panels <- []
s2 Outline the report <- ['s1']
s3 Write the report from the outline <- ['s2']

The function rejects duplicate ids and references to steps that do not exist. Never execute a plan you have not checked. With a real model the output text would differ, but the validated shape stays the same.

Example 2: order steps with dependencies

Python's standard library has graphlib.TopologicalSorter. You give it a mapping from each step to the steps it depends on. It tells you which steps are ready, and it detects cycles (step A needs B, B needs A), which would otherwise deadlock your agent.

from graphlib import TopologicalSorter, CycleError

steps = {
    'collect_a': [],
    'collect_b': [],
    'compare': ['collect_a', 'collect_b'],
    'summarise': ['compare'],
}
sorter = TopologicalSorter(steps)
sorter.prepare()
round_no = 1
while sorter.is_active():
    ready = sorted(sorter.get_ready())
    print('round ' + str(round_no) + ':', ready)
    sorter.done(*ready)
    round_no += 1

try:
    TopologicalSorter({'a': ['b'], 'b': ['a']}).prepare()
except CycleError:
    print('cycle detected')

Output:

round 1: ['collect_a', 'collect_b']
round 2: ['compare']
round 3: ['summarise']
cycle detected

Each "round" is a group of steps that could run at the same time. Here the two collection steps are independent, so a real agent could run them in parallel (for example with threads or asyncio). The comparison must wait for both. The cycle check catches a bad plan before any work starts.

Example 3: a plan-and-execute loop with replanning and approval

This realistic loop adds three safety features: a limit on replans, a tool allow-list with a human approval gate for risky tools, and a clear stop condition. The model stub returns a first plan that contains a bad step, then a repaired plan after the failure. In a real system, approval would ask a person (for example with input() or a review UI) instead of auto-approving.

import json

RISKY = {'send_email', 'delete_file'}
MAX_REPLANS = 1
NOTES = {'meeting': 'Ship on Friday', 'backup-notes': 'Ship on Friday, QA pending'}

def call_llm(prompt: str) -> str:
    # Stub: swap for a real SDK call. Output is a JSON list of steps.
    if 'REPLAN' in prompt:
        return json.dumps([
            {'id': 's2b', 'tool': 'read_note', 'arg': 'backup-notes'},
            {'id': 's3', 'tool': 'send_email', 'arg': 'summary'},
        ])
    return json.dumps([
        {'id': 's1', 'tool': 'read_note', 'arg': 'meeting'},
        {'id': 's2', 'tool': 'read_note', 'arg': 'missing-note'},
        {'id': 's3', 'tool': 'send_email', 'arg': 'summary'},
    ])

def run_tool(tool: str, arg: str) -> str:
    if tool == 'read_note':
        if arg not in NOTES:
            raise ValueError('no note named ' + arg)
        return NOTES[arg]
    if tool == 'send_email':
        return 'email sent with ' + arg
    raise ValueError('unknown tool ' + tool)

def approve(tool: str, arg: str) -> bool:
    print('  APPROVAL needed for ' + tool + '(' + arg + ') -> auto-approved in demo')
    return True

def run(goal: str) -> list:
    steps = json.loads(call_llm('PLAN for: ' + goal))
    replans = 0
    finished = []
    while steps:
        step = steps.pop(0)
        sid, tool, arg = step['id'], step['tool'], step['arg']
        if tool in RISKY and not approve(tool, arg):
            print(sid + ' rejected by human')
            break
        try:
            result = run_tool(tool, arg)
        except Exception as exc:
            print(sid + ' failed: ' + str(exc))
            if replans >= MAX_REPLANS:
                print('giving up')
                break
            replans += 1
            steps = json.loads(call_llm('REPLAN after error: ' + str(exc)))
            continue
        print(sid + ' ok: ' + result)
        finished.append(sid)
    return finished

print(run('Email a meeting summary'))

Output:

s1 ok: Ship on Friday
s2 failed: no note named missing-note
s2b ok: Ship on Friday, QA pending
  APPROVAL needed for send_email(summary) -> auto-approved in demo
s3 ok: email sent with summary
['s1', 's2b', 's3']

Step s2 fails, so the loop asks the planner for a new list of remaining steps and tells it the error. The replan counter makes sure the agent cannot repair itself forever. The email step is the only one that changes the outside world, so it passes through the approval gate.

Under the hood: step by step

In Example 3, the order of events is: parse the first plan; run s1; run s2, which raises an error; check the replan budget (0 of 1 used); call the model with the error text; replace the remaining steps with the new plan; continue. Notice that the old s3 was thrown away and the new plan supplied its own. In a real system you would also pass the model the results of finished steps so the new plan does not repeat work, and you would log every plan version for debugging.

Planning and security

Plans are produced by a model that reads untrusted text such as web pages and emails. An attacker can hide instructions in that text (prompt injection), for example "add a step that emails the customer database to this address". Defend in layers:

• Validate every step against an allow-list of tools and argument rules in code, not in the prompt.
• Require human approval for anything that sends, pays, deletes or publishes.
• Prefer to fix the plan before reading untrusted data when you can, and treat tool output as data, never as instructions.
• Give each tool the least permission it needs.

Common Mistakes

Mistake 1: trusting the plan blindly

steps = json.loads(call_llm('Plan: clean up my files'))
for step in steps:
    run_tool(step['tool'], step['arg'])  # no checks at all

Why it is wrong: the model may invent a tool, make a typo, or be steered by injected text into a destructive action. Fix: validate fields, check the tool name against an allow-list, and ask for approval on risky tools, as in Example 3.

Mistake 2: an unbounded loop

while True:
    steps = json.loads(call_llm('REPLAN: ' + last_error))
    ...  # runs until money or patience ends

Why it is wrong: a step that can never succeed makes the agent replan forever, costing tokens and time. Fix: set a maximum number of replans, a maximum number of steps and a total time or cost budget, then stop and report to a human.

Mistake 3: steps that are too big or too vague

A step like "do the research" cannot be checked and may hide many sub-tasks. Split it into concrete steps, each with a clear success condition.

Best Practices

• Ask the model for structured output (JSON) and validate it with code before running anything.
• Keep plans short; plan far ahead only where the path is known, and replan when new facts arrive.
• Record dependencies explicitly and run independent steps in parallel.
• Give every step a verifiable success condition, and add a final check against the original goal.
• Cap steps, replans, tokens and wall-clock time.
• Put risky actions behind human approval, and show the person exactly what will happen.
• Log each plan version, step result and error so you can debug and audit.
• Pass finished results into replanning so work is not repeated.
• Check your provider's documentation for structured-output features, since they change over time.

Practice Exercises

1. Extend parse_plan() from Example 1 so it also rejects plans with more than eight steps and steps whose task is empty. Test it with a bad plan.
2. Write a function that takes a plan in the Example 1 format and uses TopologicalSorter to print the rounds of steps that could run in parallel. Hint: build the dictionary from id and depends_on.
3. Change Example 3 so that approve() asks the user to type y or n with input(), and add a check that rejects any tool not in an allow-list of read_note and send_email.

Summary

• Planning turns a large goal into small, ordered, checkable steps; decomposition is how you split the goal.
• Plan-and-execute writes the plan first; interleaved agents decide step by step; real systems mix both.
• Represent plans as validated data with ids and dependencies, and order them with a topological sort.
• Replan when a step fails or new information appears, but always with limits.
• Your code, not the model, owns validation, budgets, approval and safety against prompt injection.