What is an agent harness, and why does it matter as much as the model?

What sits inside the harness

The cleanest way to see the boundary is to list what a model cannot do on its own. A model takes input and produces output. It has no memory between calls, no loop, and no ability to actually execute a tool it names. Everything that fills those gaps belongs to the harness.

LangChain's breakdown lists the concrete pieces: system prompts, the tools and skills and MCP servers along with their descriptions, bundled infrastructure such as a filesystem and a sandbox and a browser, orchestration logic such as subagent spawning and handoffs and model routing, and hooks or middleware that run deterministic steps like compaction and lint checks.

Claude Code's own documentation states the same relationship from the product side: it serves as the agentic harness around Claude, supplying the tools, the context management, and the execution environment. The loop it describes has three phases that blend into each other - gather context, take action, verify results - repeated until the task is done.

Harness or scaffold: the distinction that causes most confusion

The two words are used almost interchangeably in practice, and that is the main source of confusion when reading agent discussions.

Hugging Face's glossary draws the sharper line. Scaffolding is the behavior-defining layer the model works from: the system prompt, the tool descriptions, how responses get parsed, and what carries across steps. The harness is the execution layer: it calls the model, handles the tool calls, and decides when to stop. Scaffolding is what the model reads; the harness is what runs.

The distinction matters most when you need to reason about the two separately, which is common in a training pipeline. When people talk about a product like Claude Code or Codex CLI, they normally mean the whole thing, and the broad usage of harness as everything that is not the model is correct in that context.

Why the harness can change results without changing the model

This is the load-bearing claim, and it is the one worth checking against evidence rather than accepting on vibes.

LangChain reports that on the Terminal-Bench 2.0 leaderboard the same model scores differently across harnesses, with Opus 4.6 running inside Claude Code placing below Opus 4.6 running in other harnesses, and describes moving their own coding agent from roughly Top 30 to Top 5 on that benchmark by changing the harness alone. Anthropic's engineering write-up makes a narrower but well-documented version of the same point: a frontier model looping on a high-level prompt across multiple context windows still failed to produce a production-quality app until the harness added an initializer stage and a progress artifact.

Treat these as vendor-reported results on coding benchmarks, which is the setting where the strongest controlled evidence currently exists. They do not establish that the harness matters more than the model in every domain. What they do establish is that agent performance depends on both, and that the harness half is the half you can edit.

Guides and sensors: a usable mental model

If you use a coding agent rather than build one, the useful framing comes from Birgitta Boeckeler's article on Martin Fowler's site. Part of the harness ships with the product, but you build an outer harness around your own codebase, and it has two kinds of controls.

Guides are feedforward: they steer the agent before it acts, raising the chance the first attempt is right. Sensors are feedback: they observe after the agent acts so it can self-correct. Each kind splits again by execution type. Computational controls are deterministic and fast - tests, linters, type checkers, structural analysis. Inferential controls are slower, more expensive, and non-deterministic - semantic analysis, AI code review, LLM-as-judge.

The practical takeaway is that a harness with only guides never learns whether its rules worked, and a harness with only sensors keeps catching the same mistake forever. Both directions have to exist.

• Guides, computational: type systems, formatters, codemods, project scripts the agent can run
• Guides, inferential: instruction files, architecture principles, how-to docs, reference examples
• Sensors, computational: test suites, linters, build output, structural analysis run after every edit
• Sensors, inferential: AI code review passes and semantic checks on the diff

What counts as a harness, and what does not

Because the term is used loosely, it helps to have an inclusion test. The arXiv preprint by de Macedo proposes four conditions that all have to hold: an iterative loop that interleaves reasoning, action, and observation where the next step depends on the last result; a tool interface that can actually change an external environment rather than only read it; active context management that curates what the model sees rather than truncating by length; and control mechanisms whose effectiveness does not depend on the model choosing to obey.

That last condition is the one that separates a harness from a well-written prompt. A limit, a verifier, or a deterministic handler works whether or not the model cooperates. An instruction telling the model to be careful does not.

Applying the test excludes several neighbours. An agent framework is a way to build harnesses, not a harness. An SDK provides building blocks without assembling the runtime loop. An evaluation harness measures an agent from outside after execution instead of managing its loop. A fixed pipeline that chains prompts in a predetermined order fails the loop condition because the steps do not adapt to what was observed.

Limits of this answer

The vocabulary is genuinely unsettled. Different vendors, papers, and glossaries draw the harness and scaffold boundary in different places, and none of them is authoritative. Read the definition each source is using before comparing their claims.

The benchmark evidence is concentrated in coding agents. Terminal-Bench and SWE-bench style results say relatively little about voice agents, browser agents, or data pipelines, and the ranking gaps reported by a framework vendor about its own agent deserve the scepticism you would apply to any first-party benchmark claim.

RepoRadar has not independently rerun any of these benchmarks. Nothing here is a hands-on test result, and no pricing, adoption, or performance number appears in this answer that is not attributed to a named source above.

A useful next action

Pick the coding agent you already use and write down which of the four conditions it satisfies and where each one lives - what its loop is, what tools can change your repository, what it does when the context window fills, and which controls stop it regardless of what the model wants.

Then add exactly one computational sensor that does not exist yet. A test command or a lint rule the agent runs after every edit, with its failure text fed straight back, is usually the cheapest improvement available, and it works with whichever model you switch to next.