Agent Architecture Concepts › What an agent's shape is, and what it isn't
01 · part 1, conceptsconcept

What an agent's shape is, and what it isn't

An agent’s shape is how the work is arranged: who asks the model, how many times, in what order, and who decides what happens next.

The definition

Six shapes appear in this volume. They all do the same job: fill in a shop’s nine-box sales-tax return from its sales and purchase lines. They run on the same lines, against the same checks, with the same model and the same instructions.

Only the arrangement differs. That alone can triple the cost, and decide whether the answer is right.

the job the same lines in, the same nine boxes out, every time lines in nine boxes out one agent with tools shape 1 of 6 fixed stages shape 2 of 6 sort first, then handle shape 3 of 6 plan, then carry out shape 4 of 6 do, then check shape 5 of 6 split and rejoin shape 6 of 6 the arrangement changes completely the model is the same the prompt is the same the tools are the same and it can triple the cost
The same job, drawn six ways. Lines go in on the left and nine boxes come out on the right.
Nothing in this drawing is measured. It shows what a shape is; step 5 prices the six.
  • The lines in and the boxes out never change.
  • The arrangement in the middle changes completely.
  • The model, the prompt and the tools are the same in all six.
shapeoften calledthe arrangement
one agent with toolsa single agentone agent, asked about each line in turn, with tools to read files and look up rates
fixed stagesa pipelineread, sort, work out the tax, check: always in that order, with one question per batch of lines
sort first, then handlea routerdecide which kind each line is, and send each kind down its own route
plan, then carry outa plannerask for a plan, then carry it out
do, then checka second opiniondo the work, then take a second look at it before handing it in
split and rejoina fan-outsplit the lines into batches, handle each one separately, then put the results back together

Four things a shape isn’t

why it isn’t the shape
the modelkeep the model the same and the six shapes still cost different amounts. Every figure here uses one scripted model, so the arrangement is the only thing that changes
the promptthe wording is the same in every shape. What differs is how many times it’s sent, and what’s in it each time
the toolsall six read the same files and look rates up in the same table. Reading a file is free; asking the model about it isn’t
the frameworka framework is one way of building a shape, usually one particular shape. Choosing a framework first is choosing the answer before the question

Most writing on this subject names a shape and recommends it. Six articles can name six different shapes and all be right, each about some workload. That’s a fact about workloads, not about shapes.

Why the arrangement is the expensive decision

It’s the one you can’t change later without rebuilding. You can swap the model in an afternoon and the prompt in a minute. Who asks whom is what you live with. That’s why step 4 has you answer four questions before you commit to one.
Try it. In the labs folder, run:
python3 lab.py quiet

Part 3 runs all six shapes on the same quarter, with the same model, and prices each one.