Who asks whom, in what order, and what has to be true before that arrangement is worth building
Twelve steps, four parts, three runnable quarters — six shapes, eight decisions, and an exit at the fourth.
- All 12 steps, read online
- Runnable labs to download (plain Python, runs offline)
- Free updates whenever it's revised
- 14-day refund (conditions)
Introduction
You are about to choose a shape for an agent system — one agent with tools, a pipeline, a router, a planner, a checker, a fan-out — and you have read six articles each recommending a different one with equal confidence.
All six can be right. This volume runs the same job through six shapes on three workloads, and gets three different cheapest shapes with no shape winning twice. That is a fact about workloads, not about architectures.
What a shape is
Agent architecture is the practice of deciding who asks whom, in what order, and what has to be true before that arrangement is worth building.
The six shapes here run the same job, on the same input, against the same 9 checks, using the same model with the same instructions. The only thing that differs is the arrangement — and that difference is worth up to a factor of four in cost and the difference between a right and a wrong answer.
| why it is not the shape | |
|---|---|
| the model | hold it fixed and the six shapes still cost different amounts. Every figure here is measured with one scripted model, so the arrangement is the only variable |
| the prompt | the wording is the same in every shape. What differs is how many times it is sent and what is in scope each time |
| the tools | all six read the same files and look rates up in the same table. Reading a file is free; asking about it is not |
| the framework | a framework is an implementation of a shape, usually of one shape. Choosing a framework before choosing a shape is choosing the answer before the question |
The result, up front
| quarter | lines | kinds of problem | cheapest shape | cost |
|---|---|---|---|---|
A · quiet | 22 | 2 | fixed stages tied with split and rejoin | 2.10 |
B · messy | 140 | 6 | do, then check | 23.42 |
C · busy | 4000 | 2 | sort first, then handle | 45.19 |
The three things that cost money
Three things, and only three. Reading files, looking rates up, adding the totals and running the checks are arithmetic and free — so a shape is priced by what it asks, not by what it does.
| what costs money | why |
|---|---|
| ask the model a question | tokens, priced per call and per word |
| send one thing to a person | somebody's attention, priced per item |
| get an answer wrong | whatever a wrong answer costs you, which only you can supply |
| everything else | free. Reading, looking up, adding, sorting, comparing, and running every check |
Eight decisions, and an exit at the fourth
The first four come before any shape is chosen. None of them mentions a shape and all four are answerable in an afternoon. Decision 4 is an exit, and on one of the three quarters it fires.
| # | the decision | what answering it costs |
|---|---|---|
| 1 | what proves the work is right | writing the checks |
| 2 | what must a person decide, whatever you build | naming the cases |
| 3 | how many different kinds of work are actually in here | counting them |
| 4 | can the simplest shape do it | running it once |
| 5 | one fixed order, or kinds that need different handling | a route per kind |
| 6 | does anything have to be planned before it can be done | a plan first |
| 7 | is a wrong answer expensive enough to pay for a second opinion | a second look |
| 8 | is there enough work to split, and what does rejoining cost | batches |
Is this for you?
| if… | then |
|---|---|
| you are choosing between a pipeline and a router | step 6 — but run step 4 first, because it may not matter |
| your input is large, so you are reaching for a router | step 9. Volume and variety are different properties and choose different shapes |
| your checks all pass and you want to know if that means anything | step 10. On one quarter it means nothing at all |
| somebody asked you to justify a second-opinion step | step 7, and then the premise sweep in step 11 |
| you have picked a framework already | step 1. A framework is an implementation of one shape |
The three quarters
Same shop, same rules file, same checks, same six shapes. Only the lines differ — and the property that decides the winner is not size.
| quarter | lines | kinds of problem | checks that fail | what it teaches |
|---|---|---|---|---|
A · quiet | 22 | 2 | 0 | the exit fires |
B · messy | 140 | 6 | 6 | variety, not volume |
C · busy | 4000 | 2 | 0 | volume, and a wrong answer nothing can see |
The large quarter has fewer kinds of problem than the middle one, deliberately. Give them the same kinds and one of them is waste: one is about volume, the other about variety, and they have different winners for that reason.
How to read the source labels
| label | means |
|---|---|
| concept | argued from first principles, quotes nothing from a lab |
| measured | a lab compares configurations and reports the difference |
| hands-on | you run it on your own material |