AI Agents & Harnesses, explained

1. From chatbot to agent

Ask a chatbot why a test fails, and you get an answer: probably this, try that. Then you do the work.

Ask an agent to fix the failing test, and it does the work. It runs the tests, reads the code, makes a change, runs the tests again, and tells you once they pass.

That's the whole difference. A chatbot answers once. An agent acts, looks at the result, and decides what to do next, again and again, until the job is done.

Claude Code, Codex, Cursor and GitHub Copilot's cloud agent all work this way. So do browser agents that click through websites for you, and research agents that read dozens of pages before they answer.

2. The agent loop

Here's the part that surprises most people: the model can't run anything itself. It only writes text. When it wants to run the tests, it writes a tool call: a structured request that names a tool and its input. The software around the model runs the tool and sends the result back. Then the model decides the next step.

For the failing test, one run looks like this:

1. The model asks to run the tests. The harness runs them: two tests fail in auth.ts.
2. The model asks to read auth.ts. The harness sends back the file.
3. The model asks to change one line and run the tests again. The harness does both: all tests pass.
4. The model asks for no more tools and writes its answer: what was wrong, and what it fixed.

In code, the whole idea fits in five lines:

history = [task]
while model_wants_to_continue(history):
    tool_call = model.next_step(history)  # the model decides
    result = run(tool_call)               # the harness acts
    history += [tool_call, result]

The loop stops when the model answers without asking for another tool, when it hits a limit you set, or when you interrupt it.

3. "Agentic" is a dial, not a switch

Not everything with AI inside is an agent. What matters is who decides the next step.

Workflows are great when the steps are always the same: they're predictable and cheap. Agents shine when the next step depends on what they find, like when debugging. Anthropic's advice is to use the simplest option that works, and sometimes that's no agent at all.

So be careful with the label. Analysts at Gartner have a name for chatbots and old automation tools that get renamed as agents without really being ones: agent washing.

4. The harness

If the model only writes text, who runs the tests, reads the files and remembers your project rules? The harness. The harness is everything in an agent that isn't the model. Claude Code's docs put it like this:

Claude Code is the layer around the model that provides the tools and manages the context the model sees. This surrounding layer is what the term agentic harness refers to.

What those parts do:

• Instructions: the system prompt, plus your own rules in files like CLAUDE.md or AGENTS.md.
• Tools: reading and editing files, running commands, searching the web.
• The loop: calling the model, running its tool calls, deciding when to stop.
• Context management: choosing what the model sees, and summarizing older parts when its context window fills up.
• Permissions and sandbox: what the agent may do without asking, and what it can't reach at all.
• Extensions: skills, MCP servers, subagents and hooks that add knowledge, tools and checks.

Philipp Schmid uses a comparison that makes the roles easy to remember:

Model

is the CPU: the raw thinking power.

Context window

is the RAM: what the model can see right now.

Harness

is the operating system: it manages memory, runs programs and guards access.

Agent

is the app running on top.

Claude Code, Codex, Cursor, Gemini CLI and OpenCode are all harnesses, and many of them can run different models. To build your own agent, SDKs like the Claude Agent SDK or the OpenAI Agents SDK give you a ready-made harness to start from.

The word comes from testing, where a test harness is the setup that runs your code under controlled conditions. You'll also see scaffold, an older word for the same idea.

5. Why the harness matters

The same model can do very different work in different harnesses. On Terminal-Bench 2.0, a benchmark of real command-line tasks, Claude Opus 4.6 scored anywhere from 58% to 80%, depending on the harness around it. LangChain moved its coding agent from the top 30 to the top 5 on that benchmark by changing only the harness.

Don't overread that. Most leaderboard entries come from the harness makers themselves, and the benchmark's own authors found that picking the model usually matters more. A good harness won't turn a weak model into a strong one, but a bad harness can waste a strong one.

The harness also makes up for what models can't do. A model remembers nothing from one session to the next. Anthropic compares it to a software project "staffed by engineers working in shifts, where each new engineer arrives with no memory of what happened on the previous shift." Memory files like CLAUDE.md are the handover notes.

Where it can go wrong

• Mistakes add up. Each step builds on the last, so one wrong assumption early on can send the agent down the wrong path.
• It costs more. Anthropic found that agents use about four times as many tokens as a chat.
• Prompt injection. Text the agent reads, like a web page or a README, can contain instructions you never wrote.

That's why good harnesses ask before risky actions, let you decide what's allowed, and can run commands in a sandbox that limits which files and network addresses the agent can reach.

6. The parts you control

You don't need to build a harness to shape one. In Claude Code or Codex, these parts are yours:

• Instructions: CLAUDE.md or AGENTS.md, loaded in every session.
• Skills: know-how the agent loads only when a task needs it. See my guide to agent skills.
• MCP servers: connections to your other tools and services. See what's new in MCP.
• Permissions: what the agent may do without asking you first.

A few lines of instructions already change how the agent works in your project:

# Project rules
- Run `pnpm test` after every change and fix what fails.
- Reuse the form components in src/lib/forms.
- Never edit files in migrations/ by hand.

There's a name for improving these parts: harness engineering. Mitchell Hashimoto describes it as "the idea that anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again."

That's the habit that pays off most. When your agent gets something wrong, don't just fix the result. Add the rule, the skill or the check that prevents it next time. My Claude Code guide shows where to start.

Glossary

Tool

Something the agent can use, like reading a file or running a command.

Tool call

The model's structured request to use a tool. The harness runs it.

Context window

Everything the model can see at once: instructions, conversation and tool results.

Context engineering

Choosing what goes into the context window, so the model has what it needs and no more.

MCP

An open standard for connecting agents to tools and services.

Skill

A folder of instructions and scripts the agent loads when a task needs it.

Subagent

A helper agent with its own context window, started by the main agent for a subtask.

Agentic

How much a system decides on its own. A matter of degree, not a yes or no.