GUIDE · 10 MIN READ

How to Build Your First AI Agent With Claude Code in 30 Minutes

You don't need a framework to understand agents. You need one small, working loop. Here's the shortest path to one.

Most "build your first agent" tutorials start you off with a framework, a config file, and four new vocabulary words before you've written a single line that does anything. This one skips that. We're going to build a small agent that watches a folder of text notes, decides which ones need follow-up action, and drafts a response for each — using nothing but a loop and a couple of tools.

Step 1 — Define the goal, not the steps

The instruction to the model should describe the outcome, not the procedure. Compare these two prompts:

Bad: "Read note-1.txt, then read note-2.txt, then summarize each one."
Good: "Look at every file in ./notes. For each one that describes an unresolved
question, draft a short reply and save it to ./drafts with the same filename."

The second version leaves the model to decide how many files there are, which ones qualify, and when it's done. That decision-making is what makes it an agent instead of a script with an LLM step bolted on.

Step 2 — Give it exactly two tools

Resist the urge to expose everything. A first agent needs a way to read files and a way to write files — nothing else:

tools:
  - read_file(path)
  - write_file(path, content)

Every additional tool you add multiplies the number of ways the run can go somewhere you didn't expect. Start narrow.

Step 3 — Add the loop

This is the part tutorials usually skip past. The agent needs to: take an action, look at what happened, and decide the next action — repeating until the goal is met or a limit is hit.

while not done and steps < max_steps:
    action = model.decide(goal, history)
    result = run_tool(action)
    history.append((action, result))
    done = model.check_if_goal_met(goal, history)
    steps += 1

max_steps is not optional. Without a hard ceiling, a small misunderstanding early in the run can turn into a long, expensive loop of the model trying to correct a mistake it doesn't realize it made.

Step 4 — Log every step

Before you run it for real, add one line that writes every action and result to a log file. The first time an agent does something unexpected, this log is the only way you'll figure out why — the model won't reliably tell you afterward.

Run it once on a folder of test files you don't mind losing, not your real notes. Agents that write files should always get a dry run first.

Step 5 — Run it and read the log, not just the output

The output looks fine almost every time on the first try. The log is where you'll see the model take a reasonable-looking wrong turn — reading a file it didn't need, or deciding a note was "resolved" when it wasn't. That's normal for a first pass. It's also exactly the kind of thing a fixed script would never do, and exactly why bounding the loop in step 3 matters more than picking the "best" model.

What comes next

Once this pattern feels familiar, the frameworks stop being confusing — they're mostly conveniences for the same loop you just wrote by hand: memory management, tool registries, and multi-agent handoffs. See AI Agent Frameworks Compared for when each of those conveniences is actually worth the added complexity.