What Is an AI Agent Harness? (2026 Engineering Guide)

Every team shipping agents in 2026 has run the same experiment by accident: they swapped in a better model and the agent got barely better. The reason is that most of what an agent does happens outside the model. Birgitta Böckeler, writing on Martin Fowler's site in April 2026, pinned down the name and formula that had been emerging as shorthand: a harness is everything in an AI agent except the model itself, so Agent = Model + Harness. This guide gives you the contested definitions laid side by side, a two-sided experiment that pins down how much the harness is really worth, a map from harness components onto the Model Context Protocol primitives that are quietly absorbing them, and a build checklist. Our own benchmark supplies one half of that experiment.

What a harness actually is

Start with the definition worth anchoring on. Birgitta Böckeler, a Distinguished Engineer at Thoughtworks, writing on Martin Fowler's site on 2 April 2026, records the shorthand that has emerged — a harness is everything in an AI agent except the model itself — and formalizes it as Agent = Model + Harness. That subtraction is the whole insight. You do not build agents. You buy a model and build a harness, and the harness is the part with your name on it.

Böckeler's taxonomy is the part most summaries drop, and it is the most useful bit. She splits harness elements into guides, which are feedforward controls that steer the model before it acts, and sensors, which are feedback controls that let the agent self-correct after acting. Each operates in either a computational mode (deterministic, fast, cheap) or an inferential mode (semantic, AI-based, expensive). Her warning is that you need both halves, or you get, in her words, an agent that keeps repeating the same mistakes (feedback-only) or an agent that encodes rules but never finds out whether they worked (feedforward-only).

Now the part almost every article papers over: the term is genuinely contested, and respectable sources scope it differently. Knowing which definition a source is using is the difference between reading it correctly and arguing with a strawman.

Two honest caveats on that table. The last row is worth pausing on, because it is a common misattribution: both of Anthropic's harness posts use the word freely without ever defining it, so if you see a definition of harness credited to Anthropic, it was invented by whoever wrote the sentence. And the HuggingFace row is a narrower sense rather than a rival one — the same post reports Agent = Model + Harness as the community framing, calls everything-that-isn't-the-model the legitimate broad use, and says outright that its goal is not to enforce one correct vocabulary. Its scaffold/harness split matters most when you need to reason about the two separately, as in a training pipeline. This guide uses Böckeler's broad definition — everything except the model — because it is the one that makes the rest of the article cohere. If you hold the HuggingFace definition, mentally read the sections below as covering harness plus scaffold.

Databricks supplies the most usable component list under that broad reading, with eight parts: system prompts; tools and tool execution; sandboxes and execution environments; filesystem and durable storage; memory and context management; feedback loops and self-verification; guardrails and human-in-the-loop controls; and observability and logging. Their thesis matches what the data below shows: strong harnesses make average models useful, and weak harnesses waste the best models.

The two-sided experiment

Here is where most harness articles stop being useful. They cite one number — LangChain's — and declare that the harness matters. But one number is half an experiment. To actually establish that variance has migrated out of the model and into the harness, you need both directions: hold the model fixed and vary the harness, and hold the harness fixed and vary the model. The second half has been missing from the discourse. We happen to have run it.

Panel B, the harness side. On 17 February 2026 LangChain published a clean natural experiment on its deepagents-cli. Terminal-Bench 2.0 score went from 52.8% to 66.5% — 13.7 points — and rank went from just outside the Top 30 to Top 5. Their own line: they only tweaked the harness and kept the model fixed, at gpt-5.2-codex. What changed was system prompts, tools, and middleware. The named techniques are worth stealing: a Build & Self-Verify flow in four phases (Planning & Discovery, Build, Verify, Fix), a PreCompletionChecklistMiddleware, a LoopDetectionMiddleware that catches doom loops via tool-call hooks, a LocalContextMiddleware that injects environment context, and a technique they call the reasoning sandwich. For context on the benchmark itself: Terminal-Bench is a Stanford and Laude Institute evaluation of terminal agents in isolated Docker containers, 89 tasks across 16 categories, each with an instruction, sandboxed workspace, executable test script, and reference solution. One honest caveat — a v2.1 now exists, and LangChain's numbers are on 2.0, so do not read 66.5 as a current v2.1 leaderboard standing.

Panel A, the model side. This is the half nobody publishes. In July 2026 we ran 13 models against 9 coding tasks where the model generates code and the code is executed against hidden tests. Look at what that setup is: one-shot, no loop, no tools, no verification, no retries. It is a no-harness control condition. The result: 10 of the 13 models scored a perfect 9/9. Under those conditions the models are essentially indistinguishable on quality and differ only in price and latency — Qwen3 Coder Next at $0.10 per 1,000 tasks versus GPT-5.5 at $8.83 for the same 9/9, an 88x spread, with DeepSeek V4-Flash at $0.13 and Claude Opus 4.8 at $4.05 in between. The fastest was Mistral Medium 3.5 at 2.9 seconds per task, also a 9/9.

Anthropic supplies a third leg, from a different angle again: same model, harness off versus on. Their engineering post on harness design for long-running apps states plainly that harness design has a substantial impact on the effectiveness of long-running agentic coding, and backs it with a retro game task — 20 minutes and $9 solo, but shipped broken with entities unresponsive to input, versus 6 hours and $200 under a full harness, and functional.

Now the qualifier, because the tempting conclusion is wrong. None of this shows that model choice stopped mattering. Panel A is nine tasks, one-shot, well-specified, non-agentic. Terminal-Bench is agentic and long-horizon, and there the model spread is large — which is precisely why LangChain pinned its experiment to a frontier model instead of a cheap one. Our own benchmark's FAQ says it directly: frontier models earn their price on hard, ambiguous, long-horizon agentic work that a nine-task one-shot test does not capture, so they are worth escalating to, not defaulting to. The defensible claim is narrower and more interesting than the hype version:

Raw code generation on standard one-shot work has converged, so for that tier of work the harness is the remaining lever. Frontier models still separate on exactly the long-horizon agentic work a harness is built for. Those two facts are not in tension — they explain each other. The harness is what turns a long-horizon problem into a sequence of short-horizon ones, and short-horizon problems are the ones every model can already do. If you are still choosing a model for agent work, our roundup of the best LLM for AI agents in 2026 is the companion piece; the difference in kind between the two tiers of work is the subject of vibe coding vs agentic coding.

Components mapped to MCP

Generic component lists are cheap — Databricks has eight, Böckeler has guides and sensors. Here is a mapping nobody else has drawn: each harness component against the Model Context Protocol surface that is standardizing it, verified against spec version 2025-11-25, which is current as of this writing. (If an article cites 2025-06-18 or 2025-03-26 as the latest spec, it is stale: 2025-06-18 is the immediately preceding revision — the one that added elicitation, structured tool output and the RFC 8707 requirement — and 2025-03-26 is what a server should assume when the MCP-Protocol-Version header is absent.)

One governance note first, because it is the single most-repeated error in this space: MCP is not Anthropic's protocol. It was donated to the Agentic AI Foundation, described as a directed fund under the Linux Foundation, announced 9 December 2025. The AAIF was co-founded by Anthropic, Block and OpenAI, with support from Google, Microsoft, AWS, Cloudflare, and Bloomberg. The opposite error is also worth avoiding: the donation post states the governance model will remain unchanged and the maintainers continue to prioritize community input, so this was not a handover to a committee.

The insight that falls out of the table is the forward-looking one: the harness components the industry is hand-rolling in middleware are being absorbed into the protocol. Tasks is the clearest case. The spec introduced it in version 2025-11-25 and describes tasks as durable state machines that carry information about the underlying execution state of the request they wrap, with tasks/get, tasks/result, tasks/list, tasks/cancel, and a notifications/tasks/status notification, plus a per-tool execution.taskSupport declaration of required, optional, or forbidden. That is durable execution, budgets, cancellation, and status tracking becoming standard surface — precisely the things LangChain implemented as custom middleware. Tasks is explicitly experimental, and the spec says its design and behavior may evolve in future protocol versions, so build on it with that in mind rather than as settled infrastructure.

A few spec details worth having right, since most write-ups have them stale. There are exactly two standard transports, stdio and Streamable HTTP; clients SHOULD support stdio whenever possible, and Streamable HTTP replaces the deprecated HTTP+SSE transport from 2024-11-05. Authorization is OPTIONAL, not mandatory — and implementations using stdio SHOULD NOT follow the authorization spec at all, retrieving credentials from the environment instead. Where it does apply it is OAuth 2.1 (still an IETF draft), with RFC9728 Protected Resource Metadata, RFC8707 resource indicators, and PKCE with S256 all as MUSTs. Dynamic Client Registration, which nearly every 2025-era tutorial presents as the path, is now only a MAY, included for backwards compatibility; the preferred route is OAuth Client ID Metadata Documents using an HTTPS URL as the client_id. Official SDKs number ten, tiered: TypeScript, Python, C#, and Go at tier 1; Java and Rust at tier 2; Swift, Ruby, PHP, and Kotlin at tier 3. The official Registry exists at registry.modelcontextprotocol.io but is still in preview, with breaking changes or data resets possible before general availability — do not build production discovery on it yet. On ecosystem size, Anthropic's donation post cites more than 10,000 active public MCP servers and 97M+ monthly SDK downloads across Python and TypeScript; both are December 2025 figures, so treat them as a dated floor rather than a current count.

What a harness costs

The harness literature has a vendor-flavored habit of quoting the quality gain and hiding the bill. Anthropic's own numbers cut both ways, and the full picture is more useful than the flattering half.

The retro game task: solo run, 20 minutes and $9, core functionality broken — entities unresponsive to input. Full harness, 6 hours and $200, functional. That is roughly 22x the cost and 18x the wall-clock time. A DAW build under an updated harness landed at 3 hours 50 minutes and $124.70. The harness in question was three agents — Planner, Generator, Evaluator — where the evaluator used the Playwright MCP server to click through the running application the way a user would, testing UI features, API endpoints, and database states against hard thresholds, across up to three QA rounds.

So the honest framing is: a harness buys correctness with money and time. It is not a free win, and that reframes the build decision entirely. If your task is one-shot and well specified, a harness is pure overhead — panel A says the cheap model already gets 9/9, so spend $0.10 and move on. If your task is long-horizon and the failure mode is quietly shipping something broken, then 22x on a run that would otherwise be worthless is not a 22x markup, it is the price of the only run that counts.

The decision rule: build a harness when the cost of a plausible-looking wrong answer exceeds roughly 20x the cost of the naive run. Below that line, buy the cheapest model that clears your bar and skip the machinery. Above it, spend on the harness first and escalate the model second — that ordering is what the two-sided evidence supports.

A build checklist

Synthesized from Anthropic's harness and Agent SDK engineering posts, LangChain's Terminal-Bench write-up, and Böckeler's guides-and-sensors taxonomy. Nothing here is speculative — each item traces to something a named source actually shipped.

1. The loop, stated verbatim. Anthropic's canonical shape is: gather context, take action, verify work, repeat. If your agent does not visibly do all four, name which one is missing before adding anything else.
2. A plan artifact the agent can read back. Anthropic's long-running-agents harness used a JSON feature-list file — 200+ features in their example — as the durable spec. This is the same instinct as spec-driven development: the plan is a file, not a memory.
3. A progress log. Their harness wrote claude-progress.txt. Two of their four named failure modes were undocumented progress or bugs and premature feature marking — both are log-shaped problems.
4. A startup script. An init.sh so a fresh session can run the app. Their fourth failure mode was lack of app-running knowledge.
5. A specialized first session. They split an initializer agent from the subsequent coding agent. The first session's job is different from every session after it.
6. Verification with teeth, in all three modes. Anthropic names three: rules-based, where the best form of feedback is providing clearly defined rules for an output; visual feedback via screenshots or renders; and LLM-as-judge. Their instruction to the agent was blunt — self-verify all features, only mark features as passing after careful testing. Wire a browser-driving MCP server (they used Puppeteer in one post, Playwright in the other) so verification means clicking the real app, not asserting that you clicked it.
7. A pre-completion checklist and a loop detector. LangChain's PreCompletionChecklistMiddleware and LoopDetectionMiddleware, the latter catching doom loops through tool-call hooks. These are Böckeler's sensors made concrete.
8. Commit discipline. Git commits with descriptive messages, so a bad run is recoverable rather than archaeological.
9. Context management that is more than compaction. The Claude Agent SDK automatically summarizes previous messages as the context limit approaches, and agentic search lets the agent grep or tail to load selectively. Anthropic's key finding: for their multi-window build, compaction alone was not sufficient. That is why items 2 and 3 exist — externalized state beats summarized state. Anthropic's context-engineering post frames the underlying problem well: an agent running in a loop generates more and more data that could be relevant to the next turn, and this information must be cyclically refined; meanwhile context rot means recall degrades as tokens grow. Our context engineering guide covers the budgeting side in depth.
10. Subagents for parallelism and context isolation. Anthropic notes subagents enable parallelization and use their own isolated context windows. The division of labor is the subject of our orchestrator-executor pattern piece — and it is where the mixed-model routing below pays off.
11. Both control directions, deliberately. Böckeler's test: an agent with only sensors repeats its mistakes; an agent with only guides never learns whether its rules worked. Audit your harness component by component and label each one guide or sensor. An empty column is a diagnosis.

Running a harness across models

Here is where the two-sided evidence becomes an architecture. If the harness is the lever on standard work and the model is the lever on the hard long-horizon steps, then the right build routes different steps to different models under one harness — a frontier model for the planning and evaluation steps where the spread is real, and a cheap 9/9 model for the high-volume generation and subagent steps where the spread is 88x in price and zero in quality.

That only works if swapping the model underneath the harness is a config change rather than an integration project. One OpenAI-compatible endpoint lets you point the Planner at Claude Opus 4.8, the Generator at Qwen3 Coder Next or DeepSeek V4 Flash, and latency-sensitive checks at Mistral Medium 3.5, all on one key. If you drive your harness through Claude Code specifically, Claude Code Router covers the routing mechanics.

One disclosure you deserve up front, since we are the gateway in question. A claim you will see recycled everywhere is that every MCP tool eats your context and N servers blow up your window. Under Claude Code defaults that is false: tool search is on by default and, per the docs, keeps MCP context usage low by deferring tool definitions until Claude needs them, loading only tool names and server instructions at session start (it requires Sonnet 4.5, Haiku 4.5, Opus 4.5 or later, which emit tool_reference blocks). But the docs also state that tool search is disabled when ANTHROPIC_BASE_URL points to a non-first-party host, since most proxies do not forward tool_reference blocks. That is us. Route Claude Code through DataLLM Lab and you pay full tool-definition cost unless you set ENABLE_TOOL_SEARCH=true, or ENABLE_TOOL_SEARCH=auto to load schemas upfront when they fit within 10% of the context window and defer only the overflow; per-server alwaysLoad forces upfront loading where you want it. We would rather you learn that here than discover it in a bill. It is a real trade: one key across 300+ models, against a tool-definition tax you can mitigate with one environment variable.

The larger point stands regardless of whose gateway you use. The harness is the asset you own. Models will keep converging at the floor and keep separating at the ceiling, and the only way to exploit both facts at once is to build the harness so the model is a parameter — then run the experiment yourself, on your tasks, with your numbers.

FAQ