Your First Agent: Build the Smallest Useful One

The usual first agent project is too ambitious: many tools, a plan-and-execute structure, memory, and a framework, before anyone has watched a single loop run. It half-works, nobody can tell which part is wrong, and the conclusion drawn is about agents rather than about the design.

A better first project is deliberately small — one that does something genuinely useful with three tools, and that you understand completely.

Pick the right first task

Four properties make a good first agent:

• The steps vary by input. Otherwise you're writing a workflow, and you'll learn nothing about agents.
• The tools are read-only. Nothing destructive while you're learning what it does.
• You can tell whether the answer is right, immediately, without an expert.
• It's useful enough that you'll actually run it and notice its failures.

Good candidates: something that searches your own notes or documents and answers questions with citations; something that checks a few systems' status and summarizes; something that looks up an entity across two or three services and assembles a picture.

Poor candidates: anything writing to production, anything requiring a large tool surface, anything where correctness needs a domain expert to assess.

Build the loop yourself

Sixty lines, no framework, for the first one:

messages = [system, user_request]
for turn in range(MAX_TURNS):
    reply = model(messages, tools=TOOL_SPECS)
    if not reply.tool_calls:
        return reply.text
    messages.append(reply)
    for call in reply.tool_calls:
        result = dispatch(call)          # your three functions
        messages.append(result)
return "Turn limit reached: " + summarize(messages)

You'll adopt a framework later if you need one. Writing this once means you understand what a framework is doing on your behalf — which is the difference between using one and being confused by one.

Add these three things from the start

They're what separate a demo from something that teaches you:

1. Print the raw array on every turn. Behind a flag. This single habit does more for understanding agents than anything else — you see the context grow, watch tool results land, and notice what's missing when something goes wrong.

2. A turn limit with an honest ending. Not a crash: a return that says how far it got. Otherwise runaway loops are silent and expensive.

3. Tool results formatted for the model. Explicit units, a reason with any empty result, errors that say what to do. Get this right at three tools and it becomes habit at thirty.

Then break it on purpose

The fastest way to learn what matters:

• Make a tool fail. Return an error and watch what the agent does. Then improve the error message and watch it do better. This is the most instructive five minutes available.
• Return an empty result. See whether it concludes "nothing exists."
• Make a tool return far more data than expected. Watch the context balloon and the answer degrade.
• Give two tools overlapping descriptions. Watch selection get unreliable, then sharpen the descriptions and watch it recover.
• Ask an ambiguous question. See whether it asks or guesses — then add the instruction that makes asking available, and see the difference.

Each of these takes minutes and teaches something you'd otherwise learn during an incident.

What not to add yet

⚠️ Resist, until the simple version works and you've felt its limits:

• A second agent. You'll add a lossy boundary before you understand the first agent's failures.
• Memory. It adds a whole class of subtle problems and solves none of your current ones.
• A framework. Adopt it to solve a specific thing you don't want to build.
• Write tools. Once you're confident about the read-only version, and with a policy check in the handler.
• Planning steps. The loop plans implicitly; explicit planning helps in cases you haven't reached yet.

✅ When it's working, then what

Signals that you're ready for more: you can predict what the agent will do; when it fails you know which of context, selection, arguments, or reasoning is at fault; and you've hit a specific limitation you can name.

That last one is what should drive the next addition. "Runs are too long and it loses the constraint" points at context management. "It keeps needing a fact it can't reach" points at another tool. "I need it to survive a restart" points at durable state. Each addition then solves something you've actually experienced.

The takeaway

Three read-only tools, a loop you wrote, the raw array printed on every turn, and a task where you can tell whether the answer is right. Break it deliberately — failing tools, empty results, oversized payloads, overlapping descriptions — and fix each. You'll understand more about agents in a day than from any amount of building the complicated version first, and everything you add afterwards will be solving a problem you've met.