How to Build Your First Agent. One That Works.
A beginner-friendly visual guide to building your first AI agent in Claude Code, based on questions from my readers.
TL;DR: Building your first AI agent takes one narrow job, a folder of markdown files, and a loop. This guide explains how to build your first agent from zero: what agents are and are not, how agents differ from skills, automations, and prompts, 15 beginner questions answered straight, and a complete file-by-file build of a PRD critic agent in Claude Code. Co-authored with Dheeraj Sharma, who has built 30+ agents for his content operation. The core principle comes from Anthropic and OpenAI: workflows follow predefined code paths, agents decide their own.
Before we even start, let me say this: I doubt, quite seriously, that anyone alive has built a first agent without making a few mistakes. Not even Boris Cherny.
Since agents are new, it follows as a matter of plain logic that we’re also new to them.
I’m starting here because I’ve talked to people in my community who treat their mistakes as evidence they don’t belong here. They do. We all do. We’re all early adopters.
Dheeraj Sharma, whom I invited to co-author today’s article has built upwards of 30 agents and arrived at a conclusion I share entirely: the best way to avoid getting frustrated when building your first agent is to start small. Scrambled eggs before soufflé.
Or, in Dheeraj’s words:
The first agent worth building is not a genius that does everything. Build a critic that does one thing exceptionally well: it reviews your work and tells you what is wrong with it before anyone else sees it.
We wrote this article primarily for the complete beginner.
Those with an agent already ticking along will still find plenty of value here, but the mental model itself is built for someone who has never once done this. A category most of us occupied not so long ago.
What’s Inside
Hey, I’m Karo Zieminski 🤗.
I’m an AI PM and builder. I write Product with Attitude, an AI newsletter for tens of thousands of readers across 146 countries, helping them develop critical AI literacy the only way it sticks: through practice.
Today’s article was written by 2 people, but shaped by many more. Before we drafted it, I asked my readers what questions they had. And wow, did they deliver. Thank you to everyone who contributed!
Before You Read The Rest
We split this article into two parts.
Part one, written by me, focuses on making sure you understand the core concepts. They are not as scary or as technical as they seem, but you do need to understand them.
Part two, written by Dheeraj, walks you through the actual build process.
Read both.
Part 1: AI Agent Basics, Explained Once and for All
What are Agents vs Skills vs Automations vs Prompts
An agent is software that can operate semi-independently on your behalf, with your approval for key steps and decisions. It can take a goal, decide the next steps, use tools, and produce the outcome you asked for.
Anthropic defines agents as systems where LLMs dynamically direct their own processes and tool usage. OpenAI defines them as systems that independently accomplish tasks on your behalf.
I’ve been searching for a way to explain all of this in one coherent metaphor. The train metaphor holds the entire argument together rather neatly.
Agent = the train driver
He can make decisions during the journey. There are only two decision-makers in this system: the agent and his boss (you!)
Skill = the driver’s specialist training
It’s the occupational knowledge. The driver knows how to drive through the mountains, or how to handle dangerous cargo.
Automation = the train schedule
At 8:00, the train leaves. It stops at Station A and Station B. It always drives on the same track, to the same destination.
Prompt = the instruction handed to the driver for this specific journey
Things like:
Go!
Pause the driving schedule for today.
In Dheeraj’s words:
An agent does three things a skill cannot or I shall say should not.
It reads context from your files, instead of waiting for you to paste it.
It remembers across runs, so it gets sharper instead of starting from zero every time.
And it acts, taking a real step in a real tool, instead of just returning text you then have to do something with.
What Is NOT An Agent
OpenAI's guide explains what fails to qualify: simple chatbots, single-turn LLM calls, and sentiment classifiers are not agents. Neither does a prompt with 40 rules crammed into it, a contraption I confess to having built myself, with some pride at the time. If the model never controls what happens next, we’re looking at a workflow.
15 Questions About AI Agents You’re Absolutely Allowed to Ask
Non-technical language is not the same as non-technical explanation.
It’s easy for people in tech to assume that explaining technology simply means replacing technical words with friendlier ones.
But after talking to my readers, I know that simpler words don’t automatically create a working picture in your head. When people learn a new concept, they look for a familiar container. A website is familiar. A chat window is familiar. “Agent” is not.
1. Does it have an interface, like an app?
It can have one, if you decide to build it. But most of the time it really is like our train driver: you don’t need to see them to know the train is moving.
2. How do I give it instructions?
You can give an agent instructions through a chat window, a terminal, Slack, iMessage, or an API. All of these are design decisions you can test later.
3. Where does it live?
An agent is just software. It lives wherever that software runs. That can be your laptop, a rented server, or a cloud environment. For your first agent, do not overthink this. Your laptop will do perfectly well.
4. Can I move an agent after I’ve built it?
Yes, you can. It’s called migration. But don’t worry about it today.
5. Can it communicate back to me?
Yes! It can give you updates on the projects, or let you know when it gets stuck.
6. Can it make decisions?
Small ones, yes. Big ones should always belong to you. OpenAI's guidance is this: human approval before high-risk, irreversible actions. Payments, deletions, anything you can't undo.
7. Can it do things on my computer?
Yes, but only if you give it access. It can work with your files, apps, browsers etc.
8. Can it delete stuff?
Technically yes. It all depends on the access level you give it. Your first many agents should absolutely not be allowed to delete anything. Anthropic's trustworthy agents framework sorts every tool into three buckets: always allowed, needs approval, or never available. Deletes live in "never" until your agent has earned your trust. Mine still haven't.
9. How do I know what it did?
You can look at the logs, at what changed in the files, and ask for summaries.
In fact, do all three things until you trust it.
10. Will it make mistakes?
Yes. Build assuming it will.
11. Does it need to be online all the time?
Only if you want it to keep working when your laptop is asleep. Today, we’re going to build one that doesn’t.
12. Do all agents run on schedule?
No. Some of the agents I have built run when I prompt them (trigger = prompt).
Others wake up when a new file appears in a folder (trigger = file change).
My Linear agent begins work once I change a task’s status to “For Agent” (trigger = status change).
And yes, scheduled agents exist too. My email summary agent, for example, starts every morning at 6 a.m. (trigger = schedule).
13. Can I test different models for my agent?
Yes, you can, and it’s a fun task to do.
14. What do I have to do, so my agent doesn’t drift?
I think we should write a whole post about this topic.
15. What makes a good candidate for agents?
These three things: a task that happens repeatedly, has a clear goal, and can be judged against a standard.
Dheeraj suggests a four-question delegation framework:
3 Last Things Before We Build
What are agent tools?
In our train metaphor, the agent is the driver. Tools are everything within the driver’s reach: the switches, the signals, the doors, the brakes, and the radio.
They are what let the driver do more than just thinking, do anything at all: switch tracks, read railway signals, open doors, stop the train, or send a message to the next station.
What confuses many beginners is that, in everyday language, tools are usually things (nouns). A switch. A control.
But in agent language, tools often show up as actions: read, write, search, send messages, call APIs.
Side note: Anthropic wrote a whole post about how badly described tools are a primary source of agent failures. I recommend that you read it and learn to describe each tool like you're explaining it to someone smart who has zero context. Because that's exactly who's reading it.
What is an agent loop?
Your agent in action is simply a loop. The model decides what to do next, uses a tool, checks what happened, and repeats until the task is complete. This pattern has an academic name: ReAct, short for Reason + Act. LangChain, CrewAI, and the OpenAI Agents SDK all use some version of it.
What is an agent architecture?
Here’s where my train metaphor started failing me.
Architecture is easiest to understand if you think about building architecture. Someone draws where everything goes, from walls to windows.
With AI Agents, we also need to decide where everything goes:
which folders hold the instructions, which ones hold the outputs
where we file details about the agent’s tools
where we keep logs, and decisions
where the agent is allowed to read, write, or change things
In Part 2, Dheeraj will walk you through the exact architecture of the agent we’re building.
Join tens of thousands of readers from 146 countries using AI with attitude.
 | A guest post by
|