What is an AI agent and how to test one, step by step

What is an AI agent? It’s a program built on a language model that doesn’t just answer, but does the task itself: it picks tools (files, terminal, browser), looks at the result of every step and decides what to do next until it’s done. A chatbot gives us text, an agent gives us finished work, like a fixed test or a commit in the repository.

In this tutorial I explain how it works under the hood, and then we get practical: installing an agent in the terminal, a first task, and the settings that protect us from surprises. The commands come from the official documentation of Claude Code and Codex CLI.

What is an AI agent in practice?

The shortest definition comes from Anthropic in Building effective agents: agents are “typically just LLMs using tools based on environmental feedback in a loop”.

In the same piece, Anthropic separates agents from so-called “workflows”:

1. A workflow is a system where the model and tools follow a path predefined in code. The developer sets the steps, the model fills in the gaps.
2. An agent is a system where the model directs its own process and chooses its own tools. The developer gives the goal, and the model decides how many steps it needs and which ones.

According to Anthropic, agents shine where it’s hard to predict the number of steps up front. For simple tasks, it’s better to stick with a simpler solution.

How is an agent different from a chatbot?

It comes down to tools. The Claude Code documentation says that without tools Claude can only respond with text, while with tools it can act: read code, edit files, run commands, search the web and connect to external services.

An example from the same docs shows it well. We ask the agent to “fix the failing tests”, and it:

1. runs the tests to see what’s failing,
2. reads the error messages,
3. searches for the relevant source files,
4. reads them to understand the code,
5. edits the files,
6. runs the tests again to check that the fix works.

A chatbot would stop at suggesting a fix. An agent applies it and checks the result on its own.

How does the agent loop work?

The Claude Code docs describe this as the so-called “agentic loop” with three phases: gathering context, taking action and verifying results. The phases blend together, and after every step the model decides what it needs next, chaining even dozens of actions.

An agent is made of two things:

1. The model, which reasons and plans (in Claude Code these are Claude models, which we switch with the /model command).
2. The agentic harness, the layer around the model that gives it tools and manages context. That’s the documentation’s own term (“agentic harness”).

Claude Code’s built-in tools fall into five groups: file operations, search, command execution, web, and code intelligence. On top of that we can add MCP servers (connections to external services), skills and subagents.

Interestingly, some of these building blocks are already open standards. On October 22, Anthropic donated the Agent Skills standard to the Agentic AI Foundation under the Linux Foundation, which it had earlier given MCP as well. According to Anthropic, the standard is supported by more than 70 agent platforms, including ChatGPT, Cursor and GitHub Copilot.

Why is there so much buzz about AI agents right now?

Because they went from curiosity to everyday tool. According to the Octoverse report GitHub presented on October 28 at its Universe conference, in September more than 40% of pull requests started from a draft written by an agent, up from 17% in March (The Next Web’s coverage).

Agents are also moving beyond code. I’ve already written about Claude Duet, which shows up on its own with a morning briefing and keeps an eye on your inbox, and about four Gemini agents that beat Minecraft all the way to the Ender Dragon.

Step 1: how to install an AI agent in the terminal?

The easiest way to watch an agent at work is a coding agent in the terminal. I’ll show Claude Code, which I use for this site, and for comparison OpenAI’s Codex CLI.

Claude Code requires a paid Claude plan (Pro, Max, Team or Enterprise) or a Claude Console account with API credits. Installation on macOS, Linux and WSL:

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

The installer doesn’t show progress. When it’s done, open a new terminal window and check:

claude --version

We install Codex CLI on macOS and Linux like this:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

On first launch, Codex offers to log in with a ChatGPT account (“Sign in with ChatGPT”). I covered the installation step by step, with login and the CLAUDE.md file, in my Claude Code tutorial.

Step 2: how to give an agent its first task?

Go into any project’s directory and start the agent:

cd /path/to/project
claude

(Codex starts the same way, with the codex command.) On first launch, Claude Code will ask you to log in through the browser.

Let’s start with a question that changes nothing but shows the agent loop right away:

what does this project do?

The agent browses the files on its own and comes back with a summary. We don’t have to paste or point to anything.

Then a small task that does change something:

add a hello world function to the main file

Claude Code will find the right file and show the change. If it asks for permission, choose Yes. You can also write requests in your own language; the examples above come straight from the documentation.

Step 3: how to set what the agent can do on its own?

This is the most important part, because the agent runs on our computer. In Claude Code, this is decided by the permission mode, which we cycle with Shift+Tab:

1. Manual: the agent asks before every file edit and terminal command. A good start.
2. Accept edits: the agent edits files and performs simple file operations without asking, but still asks about other commands.
3. Plan: the agent only explores the code and proposes a plan, it changes nothing in the source files.
4. Auto: a background classifier reviews actions and blocks the risky ones instead of asking us.

The second safety net is checkpoints. Before every edit, Claude Code snapshots the file, and pressing Esc twice rewinds the changes. There’s one limitation: checkpoints only cover files, so they can’t undo actions on databases, APIs or deployments (which is why we should keep such operations in a mode that asks for permission).

We can also interrupt the agent at any time with Esc, or type a correction while it’s working, and the agent will take it into account in its next step.

Step 4: how to write tasks for an agent?

The documentation advises treating the agent like a capable colleague: give it context and a goal, and leave the details to it. Three rules that work:

1. Specifics instead of generalities: “fix the login bug where users see a blank screen after entering a wrong password”, not “fix the bug”.
2. A bigger task broken into steps: first the database table, then the API endpoint, finally the page.
3. Explore first, change later: ask the agent to analyze the code before it changes anything (Plan mode is great for this).

Standing project rules go in the CLAUDE.md file. The /init command generates its first version.

What to watch out for?

First, costs. Anthropic says plainly that agents’ autonomy means higher costs and the risk of compounding errors. An agent taking dozens of steps uses far more tokens than a single chat reply.

Second, security. An agent with terminal access sees what we see, including API keys in .env files. Anthropic recommends testing in a sandboxed environment with appropriate guardrails, and I covered the sandbox itself, permission rules and spending limits in my guide to AI agent security. That this isn’t theory is shown by the story of agents that escaped their sandbox during training at OpenAI.

Third, verification. The agent checks its own work, but the review before merge is still on us ;)

FAQ

What is an AI agent in simple terms?

It’s an AI model that gets a goal and carries out the steps to reach it on its own: it uses tools, checks the results and corrects itself until it’s done. A chatbot only answers the question.

Is an AI agent free?

Claude Code requires a paid Claude plan or API credits. Codex CLI logs in with a ChatGPT account, and availability depends on the plan. We can also run a model locally for free, which I cover in my guide on how to run AI locally.

Can an AI agent break something on my computer?

It can, because it runs real commands. That’s why we should start in Manual or Plan mode and undo file changes with checkpoints or git.

How is an AI agent different from a workflow?

In a workflow, the developer sets the steps and the model only fills them in. An agent decides on its own which steps to take and in what order.