Build your first agent that does one thing reliably
Narrow scope, real tools, and a loop that terminates. The rest is decoration.
Before you start
- Comfort with an API and a scripting language
- A task with a checkable result
What you will be able to do
- Scope an agent task so success is verifiable
- Give it tools that fail safely and report honestly
- Bound the loop so it terminates on the bad path too
An agent is a model in a loop with tools. That is the entire idea, and everything difficult about it is operational rather than conceptual.
Start with something narrow enough that you can tell when it is wrong, because you cannot debug what you cannot evaluate.
Choose a task where you can check the answer
If you cannot verify the output cheaply, you cannot iterate.
Good first tasks have a checkable result: reconcile these two lists, find the customers matching this criterion, produce a report from these three sources.
Open-ended research tasks are the popular demo and the worst starting point — you cannot tell a good run from a confident bad one, so you never find out whether your changes helped.
Give it few tools, described precisely
Two or three. Each with a clear contract and a real error path.
Each tool needs an unambiguous description of what it does, what it needs, and what it returns — including what it returns on failure. Models choose tools from these descriptions, and a vague one produces confident misuse.
Return errors as structured data the model can read and act on. A tool that throws and dies removes the agent's ability to recover, which was the reason to build an agent rather than a script.
- Exposing twenty tools at once. Selection accuracy falls off sharply and the failures are hard to attribute.
Warning Bound the loop three ways
Max steps, max spend, and a wall-clock timeout.
Set a hard maximum on iterations, a spend ceiling, and a timeout — before the first real run.
The classic failure is an agent that cannot complete its task and retries the same tool with slightly different arguments forever. It is not an infinite loop in any way your code would catch; it is a very expensive one that looks like progress in the logs.
Log the whole trace and read it
Every thought, call, argument and result. You will need all of it.
Persist the full trace of each run. When an agent produces a wrong answer, the interesting information is always in the middle — the tool that returned something unexpected and the reasoning that accommodated it rather than flagging it.
Read traces from successful runs too, especially early on. A right answer reached by a wrong route is a failure waiting for a slightly different input.
- Store traces even for successful runs. The first genuinely puzzling failure is much easier to understand next to three good traces.
One job, two or three tools, a hard step limit, and a full trace. Add capability only after it has run a week without surprising you.
Common questions
Was this guide useful?
96% of readers found this useful
Read next
Know when an agent is the wrong answer
A surprising share of agent projects would work better, cheaper and more reliably as a script with one model call in it.
Give an agent tools without giving it your whole account
An agent with your API key has your permissions. Since its instructions can come from text it reads, those permissions are effecti…
Write tests first and let AI fill in the implementation
The hardest part of using AI for code is knowing whether the result is right. A test written before the code answers that question…
Choose your first AI assistant without overthinking it
Every comparison table lists twenty differences and only three of them change your day. Here is how to pick in ten minutes and get…
