Ways to build an AI agent
Some work is better handed to an agent than done one prompt at a time. An agent is AI that pursues a goal by taking steps on its own, choosing and running tools, reading the result, and deciding what to do next, all within the bounds you set. This page is about designing that well: what the agent can reach, how it decides, and where it has to stop and hand back to a person.
Say it another way
What is an agent, in plain words? Usually you tell the AI one thing and it does that one thing. An agent is AI you hand a goal to instead, and it works out the steps itself, does them, checks how they went, and decides what to do next, until the goal is met. It is the difference between talking someone through a recipe step by step and simply asking them to make dinner. The real skill is deciding what it may do on its own, and where it has to stop and check with you.
What this will cover
The moves for designing and building agents: giving them well-described tools and only the ones they need; deciding what runs autonomously versus what pauses for a human; and handling errors so a single failure does not derail the whole run. I build in the open in the recipeCard project and the worked ideas grow alongside the writing.
Write tool descriptions the model can choose from
When you give an agent tools, the model never sees the code behind them. It picks which tool to use from the name and the description alone. So the description is not documentation. It is how the model chooses. A thin description and it picks the wrong one.
A good description says what the tool is for, what it takes in, what it gives back and when to use it instead of a similar one. Add an example. Do that for every tool and the right choice becomes obvious.
Two tools that sound the same are the usual trap. If their descriptions overlap the model cannot tell them apart, so it guesses. Rename one, or if you cannot rename it, rewrite its description so the difference is clear. If one tool tries to do too much, split it into single-purpose tools.
One more place to check is your own prompt. A word you keep repeating there can pull the model toward a tool on the keyword alone, even when the description points elsewhere. If the wrong tool keeps getting picked, read back over the prompt for the word steering it.
Let one agent hold the whole picture
Once a job is too big for one agent, split it. One agent coordinates and the others do the work. The coordinator organises the work and does not do it: it decides what the pieces are, who gets which one and what to do with the answers that come back.
The catch is that no help is coming from below. Each helper only ever sees its own piece, so none of them can tell you the split was wrong. Every piece can come back done and the job as a whole still be missed. The coordinator is the only one in a position to notice, because it is the only one holding the whole picture.
That makes the quality of the split the quality of the result. A list of what is required is a requirement. If a piece is not on the list then nobody does it. Nothing in the run will raise its hand to tell you.
Pass everything the helper needs
A helper does not inherit what you already said. It starts with nothing except the instruction you hand it at that moment. There is no shared memory sitting behind it and nothing carries over from the last one.
So if a fact is not passed, it does not exist for that helper. This is behind most of the "why did it forget" moments. It did not forget. It was never told.
The practical version: write the instruction as though to someone who has just walked into the room. Everything they need travels with the request, including the findings from the step before. Not a summary of those findings, the whole of them.
Send independent work out together
Two helpers run at the same time when you ask for both in the same breath. Ask for one, wait for the answer, then ask for the next and they run one after the other. Nothing is switched on to make this happen. It is about when you ask.
So the question to put to any two pieces of work is simply whether one needs the answer from the other. If it does not, send them out together. If it does, the second has to wait.
You can send four people to four different shops at once. You cannot bake the cake before somebody has bought the flour.
Part of Working with AI. The soft skills behind it: The soft skills of working with AI.
Why Claude. When this page carries tool-specific notes they use Claude Code, because it is one of the most widely used AI tools for building software. It is also what we build with day to day. The moves themselves are general and carry across to other capable AI tools.