AI 101 — What is an agent harness?

When a coding agent fixes a bug in your repository, the useful part is not the sentence it types back. It is the loop around that sentence: reading the file, running the tests, seeing them fail, editing again, and knowing when to stop. That loop has a name, and it is not the model.

An agent harness is everything around a language model that turns it into something that can act: the code that builds its context, dispatches its tool calls, runs them in a sandbox, feeds the results back, and decides when the task is done. The term is now standard enough to have its own encyclopedia entry, which defines the harness as the software infrastructure surrounding a model — tool use, memory, state persistence, execution environment — as distinct from the model's internal reasoning.

The short version engineers have settled on is blunter: an agent is a model plus a harness, and if you are not the model, you are the harness.

Why this matters right now

For three years the question "which model should we use?" had one variable. This year it has two, and the second one is where the differences are hiding.

SemiAnalysis made that explicit when it published GDPx, a 206-task benchmark spanning chip design, legal work, finance and cybersecurity. The top score in the world is roughly 12%. But the detail that matters here is the method: models run inside their native harness — Claude Code for Claude Opus 5.5, Codex for OpenAI's models — rather than through one shared test rig, as SemiAnalysis set out in the report. The same report argues that Opus 5.5 and GPT-6 Astra had their scores dragged down by safety classifiers firing on cyber and biology tasks, and that the best "cyber model" available is not a frontier flagship at all but one that refuses less. Read that alongside the harness detail and you get the punchline: a leaderboard number is a measurement of a pairing, not a property of a model.

That is why the same model can feel excellent inside one product and useless inside another. Swap the harness and you change the tools it can reach, how much of its own history survives when the context fills up, and what it is forbidden to touch.

A mental model in one paragraph

Picture the loop. The harness assembles the model's input: a system prompt, a description of available tools, the task, and a compressed record of what has happened so far. The model returns either an answer or a request to call a tool. The harness validates that request, executes it — reading a file, running a query, clicking a button — and appends the result to the conversation. Then it does the part nobody advertises: it decides whether to keep going, whether to summarise the history to make room, whether the action needs a human's approval, and what to write to disk so a crashed session can resume tomorrow. Repeat until done or out of budget. Every interesting engineering decision in an agent lives in that "repeat", and almost none of it is in the weights.

The kitchen

Think of the model as a very good cook and the harness as the kitchen. The cook supplies skill and judgment. The kitchen supplies the knives, the stocked fridge, the order tickets, the smoke alarm, and the house rule that the deep fryer is off-limits after midnight.

A brilliant cook in a kitchen with no running water and a broken stove will serve you something sad, and it will not be the cook's fault. An average cook in a well-organised kitchen will turn out food that is fine. Most of the work in shipping an agent is kitchen work — and like a real kitchen, the parts you notice are the ones that failed. Nobody compliments the extractor fan.

Common misconceptions

"A harness is a framework." Not quite. A framework is a library you build with — it hands you components and leaves the wiring to you. A harness is the assembled, running thing, with opinions baked in: these tools, this sandbox, these stop conditions, this approval prompt. Anthropic's account of building agents makes the practical point that the most successful implementations it saw across dozens of teams were not the ones with elaborate frameworks, but the ones built from simple, composable patterns with well-documented tools, per its engineering write-up. The harness is the product decision, not the dependency.

"It is neutral plumbing." Every part of a harness encodes a guess about what the model cannot do on its own — a summary step because context runs out, a retry because tool calls malform, a permission gate because a shell command can delete a drive. Those guesses are editorial. Addy Osmani's survey of the practice puts the scope plainly: system prompts and instruction files, the bundled filesystem and browser, subagent orchestration, hooks that force compaction or linting, all of it is the harness, and all of it is your surface area, not the model provider's.

"A better model fixes a bad harness." Sometimes, and that is exactly the trap. Harness components go stale: a workaround added because one model drifted off task becomes dead weight, or an active hindrance, once the next model stops drifting. If you maintain an agent, the honest maintenance job is periodically deleting the parts that are no longer load-bearing.

"Benchmarks compare models." They compare model-plus-harness pairings under a fixed budget, which is why two evaluations of the same model can disagree by a wide margin and both be correct. Our explainer on what an AI benchmark actually measures covers the rest of that gap.

Where to learn more

The cheapest way to understand a harness is to build a small one: a loop, three tools, a token budget, and a rule that stops it after N turns. You will hit every problem the literature describes within an afternoon — the model forgetting what it already tried, a tool returning more text than fits, an action you did not want it to take. If any of those terms are new, start with what an AI agent is and what tool calling does; then read how the harness keeps that history under control in what a context window is.

Related reading: What is an LLM router? — the other half of the layer that sits between your request and a model — and What is a sandbox escape?, which is what happens when the harness's execution environment fails at the one job it cannot fail at.

Would you rather have a great model in a mediocre harness, or the reverse? Write to us via our contact page.