Agent architectures

What an architecture is made of

So far, Patch is one loop that calls the model, runs tools, and repeats. Now suppose Patch must also fix CI failures at night and wait hours for a person to approve a database change. One loop in a terminal cannot do that, so you add parts around it: a trigger, saved state, or helper agents. How you arrange those parts is the architecture.

Every arrangement answers the same four questions:

• Who decides the next step? Your code, the model, or a mix of both.
• How is the work split? One loop, several workers, or a tree of managers.
• What starts a run? A person, an event such as a webhook, or a schedule.
• What survives a crash? Nothing, a saved plan, or a checkpoint after every step.

In the diagrams, blue names are your code and purple names are the model. An agent is a blue loop that calls the purple model.

Single agent

The user asks Patch to fix a failing test. One loop does the whole job: Patch runs the test, reads the file, edits it, and runs the test again.

User
  ↓
Agent loop (your code)  ⇄  Model
  ↓ ↑
Tools

This is the easiest shape to build and debug, because one context holds every decision. But all the work shares that context, so long or messy work fills it up. Use it for open-ended tasks that fit in one context, which covers most coding tasks. Avoid it when big subtasks could run in parallel. It is usually interactive, with the run in memory, but the same loop can be queued and checkpointed when the work must wait.

Planner and executor

The user asks Patch to change how session tokens are stored. First, a planner step asks the model for a numbered plan. The plan picks a hash function, updates the code that creates and checks tokens, and runs the tests. Then an executor loop carries out the steps, and a failed step sends the plan back to the planner.

Planner step    asks the model for a numbered plan
  ↓
Executor loop   works through the steps with the model
  ↓ ↑
Tools
  (a failed step sends the plan back to the planner)

A person can approve the plan before any file changes, and your code can save it and resume at step 3. But it costs an extra call, and a plan written before exploring is partly a guess. Use it for long tasks with dependent steps, or for risky changes that need approval first. Skip it when each step depends on what the last one found, as in debugging (chapter 6).

Manager and workers

The user asks Patch to find every call to parse_legacy_token() in three services: api, billing, and admin. A manager agent hands each service to a worker. Each worker is a separate loop with its own context and tools (chapter 7). The workers search at the same time and send back short summaries, which the manager combines.

              Manager loop
           /        |        \
api worker   billing worker   admin worker

each loop is your code, and each one calls the model

This works well when the parts are independent, because the workers run in parallel and each context stays small. But the shape uses more model calls, and the summaries lose detail. The bigger risk is that workers cannot see each other's choices, so avoid this shape when the parts share decisions or files.

Published results show both sides. Anthropic's research system, a Claude Opus 4 lead with Claude Sonnet 4 helpers, beat a single Claude Opus 4 agent by 90.2% on an internal research eval. But multi-agent systems like it use about 15 times the tokens of a chat. Anthropic also notes that most coding tasks have fewer truly parallel parts than research. Cognition argues for one agent by default: "Actions carry implicit decisions, and conflicting decisions carry bad results."

Hierarchical agents

Some jobs are too big for one manager. Say a team wants a long report on the health of its 40 services. A director splits the report into chapters for leads, and each lead splits its chapter into sections for workers. Results flow back up, and each level summarizes what it received.

            Director
           /        \
     Lead A          Lead B       managers
     /    \          /    \
  W1      W2     W3      W4     workers

every box is a loop in your code that calls the model

A hierarchy can handle more work than one manager can track, because each level holds only its own part. But every level adds model calls and another summary that can drop a detail. A mistake at the top also spreads to everything below it. Use it only for very large jobs that split into areas. Many copies of one job, such as one change in 300 repositories, need a flat queue (chapter 20).

Graph workflow

Suppose Patch handles every bug report the same way: research the code, plan a fix, make the change, and review it. A failed review sends the work back to research. Steps that depend on each other like this fit a graph better than parallel workers. You draw them as boxes (nodes) for steps and arrows (edges) between them. Some steps call the model, and others run plain code, such as the tests.

Research → Plan → Execute
    ↑                 ↓
    └────── Review ───┘

your code runs every step; research, plan, and review call the model

Graphs are predictable and easy to audit. Your code decides the known steps, so no model call is spent on them. With a configured store, it can also save progress after each step, retry a step, or stop for a person at a fixed point. But a fixed arrow cannot say "read one more file and try again", so graphs handle open-ended work badly. When one step is open-ended, make that step run an agent loop.

Event-driven agent

At 02:10, CI fails on the main branch and sends a webhook, an HTTP request that one service sends another when something happens. Nobody is awake to start Patch, so the webhook starts the run. A handler loads the saved state for that branch, runs the loop, and saves the state again. Between events, nothing runs.

webhook     chat message     schedule
     \            |             /
      v           v            v
          queue of events
                 |
                 v
handler: load state → run the loop → save state

This shape lets work start without a person. If the handler also saves state between events, a long wait costs nothing. The cost is that you now run a distributed system (chapter 12). Events can arrive twice, so the handler must claim each event once. An atomic write keyed by the delivery id does that. Use it for agents that react to the world over days, such as CI fixers. Skip it when a person waits at the keyboard.

The four choices underneath

Patch's unattended mode shows how the choices combine:

CI failure / labeled issue / chat message / nightly schedule
                 |                                what starts it: events
                 v
      event handler  (claims each event once)
                 |
                 v
triage → fix step → test step → approval step     who decides: code outside
             |       (code only)   (saves the exact request)
             v
    Patch: agent loop                             who decides: model inside
       /            \
explorer          reviewer                        split: read-only helpers

checkpoint after every step                       survives a crash

• What starts a run: events, because nobody is at the keyboard.
• Who decides the next step: your code runs the outer steps, and the model decides inside the fix.
• How the work is split: one agent writes files, and two read-only helpers explore and review.
• What survives a crash: every finished step. The unfinished step may run again, so outside actions carry an operation key (chapter 12).

Overnight, the run stops at "fix ready, approval requested". It saves the exact pull request and exits, and a person's approval of that same request resumes it (chapter 11).

Most of the six shapes answer the first two questions, and event-driven answers the third. The trigger and the crash behavior are presets you choose separately. So any shape can be interactive and in memory, or queued and checkpointed:

Workflow patterns on the same map

Anthropic's guide "Building effective agents" (December 2024) names five workflow patterns. Each one fits the same four choices.

Why more agents can mean less reliability

Splitting a job across agents does not change which parts must succeed, but it adds hand-offs that can fail. Say a job has three required parts, each done right 90% of the time:

one agent, 3 required parts    0.90 ** 3                 = 0.73
manager and 3 workers          0.73 * 0.98 * 0.96 ** 3   = 0.63

The second line adds the hand-offs. Say the manager splits and merges the work correctly 98% of the time. Each summary keeps the needed detail 96% of the time. These numbers are made up, and the math assumes independent failures with no checks or retries. Anthropic's guide lists "the potential for compounding errors" among the costs of agents.

Checks and retries do much better than this math. But failures with a shared cause, such as one bad instruction sent to every worker, fail again on every retry (chapter 15).

Explore: the same task in different shapes

Pick a shape and a situation, then press Next to follow the task one step at a time. The picture lights up the part that acts, and the verdict says whether the shape helps. It opens on manager and workers with edits that depend on each other. Compare that with a single agent, and find where the conflict starts.

No shape helps in every situation. A hierarchy never helps in these four, because none of the tasks is too big for one manager.

Choosing an architecture

Anthropic's guide recommends "finding the simplest solution possible, and only increasing complexity when needed." So start with one loop or a fixed workflow, and add a part only when the task gives you a reason:

When the reason is real, extra parts can be worth their cost. In an Anthropic experiment, a single agent spent 20 minutes and $9 on a retro game maker that did not work. A harness with separate planner, generator, and evaluator agents spent 6 hours and $200, and its game worked. That task was long, and a separate evaluator could check the work.

Running example: Patch's architecture

Patch stays a single agent with two read-only helpers from chapter 7, an explorer and a reviewer, so only the main loop writes files. In unattended mode, that loop is the fix step of the graph above, and each run stops at a pull request waiting for approval. Patch gets no hierarchy, because one agent can handle one bug.

# before: a person starts one loop
- answer = run_agent(task, tools=TOOLS)
# chapter 14: one writer with read-only helpers, inside an event-driven graph
+ fix = agent(tools=TOOLS + [delegate],
+             helpers={"explorer": READ_ONLY, "reviewer": READ_ONLY})
+ graph = Graph([triage, fix, test_step, approval_step, open_pr],
+               checkpoint="every_step")   # approval_step saves the request and exits
+ on_event(["ci_failed", "issue_labeled"], start=graph, claim_once="delivery_id")

Design checkpoint 4: the expense agent

What goes wrong

You decide, AI builds

Check yourself

Takeaways

• Start with one loop or a fixed workflow, and add a part only for a reason you can name.
• Split work across agents only when the parts are independent. Work that shares decisions needs one agent that writes.
• Every hand-off adds model calls and another place to fail, so check results where they are handed over.

Going deeper

• Building effective agents (Anthropic, December 2024). The five workflow patterns.
• How we built our multi-agent research system (Anthropic, June 2025). When parallel helpers pay off, and their cost.
• Don't Build Multi-Agents (Cognition, June 2025). Why parallel agents make conflicting decisions.