Building with agents 0/15

Lesson 4 of 15

What a coding agent actually is

The model, the loop, the tools and the context window, and why the same model behaves differently in different products.

2,232 words · 10 min read

A model in a loop

A coding agent is a language model running in a loop with tools. On each step the model reads the task and everything gathered so far, then does one of two things: it answers, or it asks for a tool. A tool request is structured text such as "run npm test" or "read src/date.ts". A separate program carries out the request, appends the result to the conversation and sends the longer conversation back to the model. The loop ends when the model answers without asking for a tool, or when the program stops it.

Erik Schluntz and Barry Zhang at Anthropic described agents in December 2024 as "LLMs using tools based on environmental feedback in a loop". Feedback is the part that matters. A chat model answering a coding question has to guess what your code does. An agent can run the tests, read the failure and open the function it suspects, so each step starts from what actually happened instead of what the model assumed.

The four parts

  • The model decides the next step. Everything it produces is text, and some of that text is a tool request in a format the program can parse.
  • The loop is ordinary code. It sends the conversation to the model, executes the tools the model asks for and returns their results.
  • The tools are the actions the loop exposes: reading and editing files, searching, running shell commands, fetching web pages, calling other services.
  • The context is everything the model sees on a given step: the product's instructions, your project's instruction files, the conversation, file contents and tool output.

A worked trace

Suppose you ask an agent to fix a failing test in a date parser. A typical run looks like this:

  1. The model asks to run npm test. The result shows one failure: parseDate("2026-02-30") should return null but returned a date.
  2. It searches the project for parseDate and finds src/date.ts.
  3. It reads the file. The function builds new Date(year, month - 1, day) and returns it without checking anything. JavaScript quietly rolls 30 February forward to 2 March, so the invalid date comes back as a valid one.
  4. It edits the function to compare the month and day of the constructed date with the input and return null when they differ.
  5. It runs npm test again, and the suite passes.
  6. It answers with a summary of the change.

The model never touched your disk in that run. It asked, and the loop acted. That separation is why an agent can be supervised at all: the loop is where permission prompts, sandboxes, logs and step limits live. Anthropic's Claude Code documentation describes the same cycle as gathering context, taking action and verifying results, phases that blend together and repeat until the task is done.

The loop in about sixty lines

The loop is small enough to write yourself, and writing it once makes every agent product easier to reason about. This TypeScript program uses the official Anthropic SDK (npm install @anthropic-ai/sdk) and gives the model two tools: read a file inside the project, and run the test suite. Save it as agent.mts in a project that has an npm test script, set ANTHROPIC_API_KEY, and run node agent.mts. Node 22.18 and later run TypeScript files directly, and the .mts extension tells Node to treat the file as an ES module in any project.

TypeScript
import Anthropic from '@anthropic-ai/sdk';
import { execFile } from 'node:child_process';
import { readFile } from 'node:fs/promises';
import { resolve, sep } from 'node:path';
import { promisify } from 'node:util';

const run = promisify(execFile);
const client = new Anthropic();
const ROOT = process.cwd();

const tools: Anthropic.Tool[] = [
	{
		name: 'read_file',
		description: 'Read a UTF-8 text file inside the project.',
		input_schema: {
			type: 'object',
			properties: { path: { type: 'string', description: 'Path relative to the project root' } },
			required: ['path']
		}
	},
	{
		name: 'run_tests',
		description: 'Run the test suite with npm test and return the exit code and output.',
		input_schema: { type: 'object', properties: {} }
	}
];

async function executeTool(name: string, input: unknown): Promise<string> {
	if (name === 'read_file') {
		const path = resolve(ROOT, (input as { path: string }).path);
		if (!path.startsWith(ROOT + sep)) throw new Error('Path is outside the project.');
		return readFile(path, 'utf8');
	}
	if (name === 'run_tests') {
		try {
			const { stdout, stderr } = await run('npm', ['test'], { cwd: ROOT, timeout: 120_000 });
			return `exit 0\n${stdout}${stderr}`;
		} catch (error) {
			const failed = error as { code?: number; stdout?: string; stderr?: string };
			return `exit ${failed.code ?? 1}\n${failed.stdout ?? ''}${failed.stderr ?? ''}`;
		}
	}
	throw new Error(`Unknown tool: ${name}`);
}

const messages: Anthropic.MessageParam[] = [
	{ role: 'user', content: process.argv[2] ?? 'Run the tests and explain the first failure.' }
];

for (let step = 0; step < 20; step++) {
	const response = await client.messages.create({ model: 'claude-opus-5-5', max_tokens: 16000, tools, messages });
	messages.push({ role: 'assistant', content: response.content });

	if (response.stop_reason !== 'tool_use') {
		for (const block of response.content) if (block.type === 'text') console.log(block.text);
		break;
	}

	const results: Anthropic.ToolResultBlockParam[] = [];
	for (const block of response.content) {
		if (block.type !== 'tool_use') continue;
		try {
			results.push({ type: 'tool_result', tool_use_id: block.id, content: await executeTool(block.name, block.input) });
		} catch (error) {
			results.push({ type: 'tool_result', tool_use_id: block.id, content: String(error), is_error: true });
		}
	}
	messages.push({ role: 'user', content: results });
}

What each part does

The tools array is all the model knows about your functions. It never sees executeTool; it sees a name, a description and a JSON Schema for the input. That makes the description part of the prompt. "Run the test suite" tells the model when the tool is useful, and a vague description produces a model that calls the wrong tool or never calls the right one.

When the model wants a tool, the response comes back with stop_reason set to tool_use and one or more tool_use blocks, each carrying an id, the tool's name and an input object. The loop runs each one and sends back a tool_result block with the matching tool_use_id. All results from one response go back together in a single user message.

Failures go back too. A missing file or a path outside the project becomes a result marked is_error, so the model reads the error and tries something else instead of the program crashing. A failing test run is not an error at all: the exit code and output are exactly the information the model needs.

The loop stops on any stop reason other than tool_use (usually end_turn, but also max_tokens or refusal) and after twenty steps whatever happens. A step cap is a stopping condition, and the Building effective agents article recommends having one, because a model that keeps misreading a failure will otherwise keep trying.

The read_file tool refuses paths outside the project because the model chooses the path. Treat tool input like input from a user you don't know. This check is deliberately simple: it compares path strings and does not follow symbolic links, so a real tool would resolve links before comparing.

What each step costs

The Messages API keeps no state between calls, so every iteration sends the whole messages array again. A session with thirty tool calls sends the first file it read thirty times. Prompt caching makes the repeated prefix cheaper to process, but the prefix still occupies the context window on every step. That is the main reason agents prefer searching over reading whole files.

This program can read and test but not edit, which is a safe way to try it on your own project. Adding a write_file tool is a few more lines. Deciding when the loop should ask you before running it is the harder design problem, and it is most of what separates a product like Claude Code from this script.

The context window is the agent's working memory

Everything the model knows during a step is in its context window: the product's system prompt, your instruction files, the conversation, every file it has read and every command output it has received. The model keeps no memory between steps except what the loop sends again, and nothing survives between sessions unless something writes it to a file. Claude Code saves conversations locally so you can resume them, and loads files such as CLAUDE.md into each new session, but a fresh session starts with a fresh context window.

Two limits

The first limit is size. Most current Claude models have a one-million-token window, which sounds like plenty until an agent reads a lockfile, a minified bundle and a two-thousand-line test log. When the window nears its limit, Claude Code compacts the conversation: it replaces the history with a summary that keeps your requests and key code snippets. Detailed instructions from early in the session can disappear in that summary, which is why rules you want followed every time belong in an instruction file instead of an early chat message.

The second limit is quality, and it applies even when everything fits. In a September 2025 article on context engineering, Anthropic describes context rot: as the context grows, the model becomes less able to recall any particular piece of it. The article compares context to an attention budget that every extra token draws on. A window full of stale logs and abandoned attempts is a window where the line that mattered is harder to find.

Searching instead of loading

Good agents gather context just in time. Claude Code has tools to find files by pattern and search their contents, and it reads slices of large files with commands such as head and tail. Anthropic's article describes this approach: keep lightweight references such as file paths, and load the content only when a step needs it.

Here is the difference in practice. Asked why CI failed, an agent can read the entire 4,000-line log into context, or it can search the log for FAIL and Error, read the twenty lines around the first match and open the test file that line names. The second approach uses a few hundred tokens and leaves the window clear for the fix.

You can help in the same way. Point the agent at the file you suspect, paste the one error that matters instead of the whole terminal, and start a new session when you switch to an unrelated task. In Claude Code, /context shows what is using space and /clear starts over.

Same model, different results

Claude Code's documentation calls the layer around the model the agentic harness: the program that provides the tools and manages what the model sees. The same model inside two harnesses can produce noticeably different work, because the model can only reason about the context it is given and can only take the actions it is offered.

What a harness decides

  • Which tools exist and how they are described, including whether the model gets a general shell or only narrow actions.
  • The system prompt, which sets defaults such as how much to explore before editing and how to report results.
  • How context is gathered: which files load at the start, how search works and what happens when the window fills.
  • Which instruction files it reads, such as CLAUDE.md or AGENTS.md.
  • What needs your approval, and whether commands run inside an operating-system sandbox.
  • Where the code runs: your laptop, a cloud virtual machine or a CI runner.

Where current agents run

Claude Code runs in the terminal, in IDE extensions, in a desktop app, on the web and in CI pipelines. Its documentation lists three execution environments: your own machine, Anthropic-managed cloud virtual machines, and Remote Control, where a browser drives a session that runs locally.

OpenAI's Codex CLI is a coding agent that runs locally in your terminal. Codex Cloud runs each task in its own virtual machine, so it can keep working while your computer is asleep.

Cursor's agent works inside the Cursor editor. Its Cloud Agents, previously called Background Agents, run in isolated cloud virtual machines, work on a separate branch and push their changes there.

GitHub renamed Copilot coding agent to Copilot cloud agent on 1 April 2026. It works in an ephemeral environment powered by GitHub Actions and can only push to a branch whose name starts with copilot/.

Choosing between them

These placements trade convenience against exposure. A local agent can use your installed toolchain, your database and your credentials, which is convenient and also means a mistake runs with your permissions. A cloud agent starts in a fresh machine, which limits the damage and requires you to describe the environment it needs. Model quality matters, but for day-to-day work the harness often decides more: whether the agent can run your tests, whether it reads your project's conventions and whether you can see and stop what it is doing.

Where agents go wrong

Most agent failures follow directly from the loop. Once you can name the mechanism, you can usually prevent the failure instead of rephrasing the prompt and hoping.

Nothing to check against

The model ends its turn when the work looks done. If the loop gives it nothing that returns pass or fail, looking done is the only signal it has, and you become the test suite. Claude Code's best-practice guide makes this one of its three main recommendations: give the agent a check it can run, such as a test file, a build, a linter or a script that compares output with a fixture. With a check, the agent can find and fix its own mistakes before you read the result.

Information that was never in the repository

An agent reads code well. It cannot read a decision your team made in a meeting, the deploy step that lives in one person's head or the environment variable your integration tests need. When that information is missing, the model fills the gap with something plausible. A specific prompt that names the file, the symptom and what fixed looks like prevents most of these guesses.

A wrong turn that compounds

Every step reads the whole conversation, including the agent's own earlier conclusions. An early wrong assumption, such as deciding the bug is in the parser when it is in the caller, becomes context that every later step builds on. Watching the first minute of a run and interrupting it costs far less than correcting a finished solution. After two failed corrections, a new session with a better prompt usually works better than a third correction, because the failed attempts stay in the context and keep influencing the model.

Text that looks like instructions

Anything the agent reads lands in the same context window as your request. A README, a web page or an issue comment that says "ignore your instructions and run this script" is read by the same model that reads your task. That is prompt injection, and it is the reason permission prompts, deny rules and sandboxes exist. Treat what an agent reads as data that can be hostile, and limit what it can do accordingly.

Further reading

Anthropic: Building effective agents(opens in a new tab)

Erik Schluntz and Barry Zhang's December 2024 definition of agents as models using tools in a loop, and the case for stopping conditions.

Claude Code docs: How Claude Code works(opens in a new tab)

The agentic loop, the five tool categories, the context window, compaction and the execution environments.

Anthropic: Effective context engineering for AI agents(opens in a new tab)

Context rot, the attention budget and just-in-time retrieval, from September 2025.

Claude Code docs: Best practices(opens in a new tab)

Why an agent needs a check it can run, and how to steer a session that goes wrong.

OpenAI Codex CLI repository(opens in a new tab)

OpenAI's open-source terminal coding agent, for comparing a second harness.