AI agents: what they are and how to build one with Claude Code

An AI agent, in one sentence

An AI agent is a program in which a language model decides for itself which steps to take and which tools to use to reach a goal: it reads, acts, looks at the result, and starts again until the task is done or it needs you. The difference from a simple chatbot is that it does not only answer: it acts.

Anthropic, the company behind Claude, offers a distinction I find very useful in its article Building effective agents (December 2024). Workflows are systems where the model and the tools follow paths written in advance in code. Agents are systems where the model directs its own process and its own use of tools. “Agent” is a very popular marketing word right now; this definition helps you sort the claims.

Agent, chatbot or automation: what is the difference?

Three things often get mixed up. Here is how I tell them apart when someone talks to me about “an AI agent”:

My view, in line with Anthropic’s in the same article: start with the simplest solution. If a workflow does the job, you do not need an agent. An agent costs more, is slower and harder to control. It is worth it when the task cannot be described step by step in advance.

Claude Code is already an agent

Good news: to experiment, you do not need to build an agent from scratch. Claude Code is one. When you ask it to fix a bug, it decides which files to read, which commands to run and which changes to propose. You stay in the loop: by default, it asks for your permission before editing a file or running a command.

If you have never used it, start with my Claude Code beginner’s guide, then come back here.

A worked example: a small team of subagents

Claude Code lets you create subagents: specialised assistants, each with its own instructions and allowed tools. According to the subagents documentation, each subagent runs in its own context window: it does not clutter the main conversation with every file it read, and only returns its result.

A concrete case: you are building the website of a small restaurant in Fès, and you want someone to review the code after every change and someone to check that the page stays readable on a phone. Let’s create two subagents.

1. Where subagents live

A subagent is a Markdown file with a YAML header. Two locations are possible:

• .claude/agents/ in your project, for subagents specific to that project (and shareable with your team through Git);

• ~/.claude/agents/ in your home folder, for the ones you want in every project.

The /agents command in Claude Code lets you create and manage them without writing the file by hand.

2. The reviewer

Create .claude/agents/reviewer.md:

---
name: reviewer
description: Reviews recent changes and flags bugs, missed cases and unnecessary code. Use after every code change.
tools: Read, Grep, Glob
---

You are a demanding but kind code reviewer.
Read the changed files and list, most serious first:

1. likely bugs;
2. missed cases (empty field, mobile, network error);
3. what can be simplified.
   You do not edit any file. Answer in under 15 lines.

The name and description fields are required. The description matters a lot: it is what helps Claude Code decide when to call this subagent. The tools field limits what it is allowed to do: here, read and search, but not write. It is a simple and effective guardrail.

3. The mobile tester

Create .claude/agents/mobile-tester.md:

---
name: mobile-tester
description: Checks that HTML and CSS pages stay readable on a phone screen. Use after a layout change.
tools: Read, Grep, Glob
---

You check the layout for a 375 px wide screen.
Look for: text too small, elements overflowing, buttons too close together,
images without a maximum width. Suggest precise fixes,
without applying them.

4. Put them to work

In Claude Code, ask for example:

Add a “Today’s menu” section to index.html with three dishes and their price in dirhams. Then have the reviewer review the change and the mobile-tester check the layout, and fix what they report.

Claude Code makes the change, delegates the review and the check to the two subagents, collects their notes and proposes the fixes. You approve each change as usual.

It is not magic: it is a way of organising the work. But it is exactly the principle of a multi-agent system, at a scale you can understand and control.

Limits, guardrails and real costs

The limits

• An agent makes mistakes. It can misunderstand the request, stick to a wrong path, or claim a test passes without running it. Review and test.

• More autonomy, less visibility. The more steps you let an agent chain without you, the harder it is to know why it made a choice.

• Context is not infinite. On a large project, it does not “see” everything at once. Subagents help precisely by splitting the work.

The guardrails I always set

1. Git first. Every step that works gets committed. An agent that breaks everything is undone with one command.

2. Minimum tools. A review subagent does not need to write files. Give each one only the tools it needs.

3. Never direct access to production. No real database password, no payment key in plain text, no automatic deployment without review.

4. Written rules. A CLAUDE.md file at the root of the project says what is forbidden (for example: “never change the payments/ folder without asking”).

5. A human signs off. For anything touching money, customer data or what gets published, a person says yes.

Costs

An agent uses more than a single question: it reads files, makes several round trips, and every subagent has its own context. With a Claude subscription, that means reaching usage limits sooner; with the API, a higher bill. Exact prices change: check them on Claude’s pricing page.

My practical advice: start with one subagent, measure what it saves you, and only add a second one if the first is really useful.

Learning to build agents

Building agents does not require being an engineer, but it does require solid basics: the terminal, Git, reading code, and the habit of breaking a task down. That is the path my self-paced Claude Code course follows: we start from the terminal and finish, in the last lessons, with a small team of subagents working on a real project, with its guardrails. For a company that wants to apply this to its own processes, I also run team workshops built on your use cases.

Summary

• An AI agent chooses its own steps and tools to reach a goal; a workflow follows a path written in advance.

• Start with the simplest solution: an agent is only worth it when the task cannot be described step by step.

• Claude Code is already an agent, and its subagents let you build a small specialised team with a plain Markdown file.

• Limit each subagent’s tools, work with Git, and keep a human to approve what matters.

Sources checked on 16 October 2026: Anthropic’s article “Building effective agents” and the official Claude Code documentation on subagents.