Harness engineering

Why it matters

The same AI model can succeed or fail on the same task depending on what you build around it. Once the leading models became broadly capable, the gap between a demo and a system that works stopped being mostly about which model you picked. It became about the tools the model can reach, the environment it runs in, and the checks around it. Addy Osmani, an engineer at Google, put it plainly in April 2026: “A decent model with a great harness beats a great model with a bad harness.” That surrounding system is the harness, and designing it well is harness engineering.

This matters for anyone building agents rather than chatting with a model. The wording of a prompt and the choice of model are the parts people reach for first, but a growing body of practitioner writing through 2026 argues the harness is where most of the practical leverage now sits. It is also the least glamorous work: plumbing, sandboxes, permissions and error handling rather than clever prompts. Skipping it is why capable models still produce agents that stall, loop or do damage.

What is harness engineering?

Harness engineering is designing everything around the model that turns it into a working agent. The shorthand that spread through 2026, used by Osmani and by Databricks among others, is Agent = Model + Harness. The model reasons and decides. The harness is the rest: the tools the model can call, the sandbox or workspace it runs in, the memory it keeps, the guardrails and permissions that bound it, and the success criteria that tell it when a task is done. Hugging Face describes the harness as “the execution layer inside the agent: it calls the model, handles its tool calls, decides when to stop,” and harness engineering as “designing this layer well: deciding when the agent should stop, how errors get handled, and what guardrails keep it on track.”

The vocabulary is new. Wikipedia dates it to early 2026 and credits Mitchell Hashimoto of HashiCorp with popularising “harness engineering” in a February 2026 post about engineering fixes for the environment so an agent stops repeating a mistake. OpenAI pushed the phrase further around its Codex work. The idea underneath is older: an agent has always been a model plus the software that lets it act, but in 2026 that software became something teams design deliberately, with its own name.

How is it different from prompt, context and loop engineering?

They are four layers of the same stack, though harness sometimes gets used as an umbrella for the other three. Some writers, Osmani among them, treat context and loop as parts of the harness. This glossary keeps the four as peer layers, because two terms that swallow each other are no use to a reader. On that reading the split is clean. Prompt engineering is the wording of a single instruction. Context engineering is what information enters the model’s window on a given turn and what is left out. Loop engineering is the autonomous repetition wrapped around the whole thing, how the agent iterates without a human prompting each turn. Harness engineering is everything the agent operates within: its tools, its sandbox, its guardrails and its stopping criteria.

Hugging Face gives the sharpest boundary between the two that are easiest to confuse: “Harness controls the loop; context controls the input to each loop iteration.” Put another way, the harness is the machine; context is what you feed the machine each turn; the loop is the machine running again and again. If you find yourself writing about which documents reach the model, that is context engineering. If you are writing about which tools exist and what the sandbox allows, that is the harness.

What is in a harness?

A harness is made of a handful of parts that recur across the sources. Databricks groups them as tools, memory, workspace and guardrails; Wikipedia lists tool dispatch, memory and state, an isolated sandbox, context management and guardrails. Stripped down, four jobs matter most:

• Tools and tool dispatch: the APIs, code execution, search and databases the agent can call, plus the routing that turns a model’s request into a real action and feeds the result back. Anthropic calls tools the agent’s “interface for action and feedback.”
• Sandbox and workspace: the isolated environment, files and systems the agent is allowed to touch, so a bad run is contained and can be thrown away. Anthropic recommends sandboxed testing before an agent runs free.
• Guardrails and permissions: scoped permissions, approval tiers and monitoring that decide what the agent may do on its own and what needs a human. Anthropic’s version is pausing “for human feedback at checkpoints.”
• Success criteria and stopping: a definition of “done” the agent can check against, and a limit so it ends rather than runs on. Anthropic recommends a maximum number of iterations as a basic guardrail.

Databricks lists eight building blocks for a production harness: system prompts, tools and execution, sandboxes, durable filesystem storage, memory and context management, feedback loops and self-verification, guardrails with human-in-the-loop controls, and observability and logging. The list is a useful checklist for what “designing the harness” actually involves.

Inner harness and outer harness

Not all of the harness is yours to build. Birgitta Böckeler of Thoughtworks draws a line, reported in the Wikipedia article, between an inner harness and an outer harness. The inner harness is shipped by the model’s builder: an agent SDK, or a coding tool such as Cursor or Codex, with its own built-in loop, tool handling and stopping logic. The outer harness is what the user assembles on top: instruction files such as AGENTS.md, Model Context Protocol servers, custom skills and project-specific tools. Most harness engineering in practice is outer-harness work, tuning the layer you control around an inner harness you inherit. The distinction matters because it tells you what you can change and what you have to design around.

What does a good harness do?

A good harness treats each failure as a permanent signal rather than a one-off. Osmani’s rule is that “every line in a good AGENTS.md should be traceable back to a specific thing that went wrong”: when an agent makes a mistake, you change the harness so it cannot make that mistake again, rather than re-prompting and hoping. That turns harness engineering into a slow accumulation of fixes, each one closing a gap the agent fell into. Alongside that discipline, a few things recur in harnesses that work:

• Clear, well-described tools, because a tool the model cannot understand is a tool it will misuse.
• Real isolation, so the worst a bad run can do is spoil its own sandbox.
• Verification built in, so tool results and tests give the agent ground truth instead of its own say-so.
• Guardrails scoped to the task, tight enough to prevent damage without blocking the work.
• Observability, so when something goes wrong you can see which step did it.

Where do harnesses fail?

Harnesses fail quietly, and the failures are usually blamed on the model. A weak harness gives the agent tools it cannot use well, or no sandbox, so a mistake escapes into real systems. Leave out the stopping criteria and the agent never decides it is finished. Skip verification and the model’s own claim that a task succeeded goes unchecked. Anthropic warns that without guardrails agents carry “higher costs, and the potential for compounding errors.” Each of these looks like a model failure and is really a harness gap. The 6x-performance-gap figures that circulate for harness design are not sourced to any open primary study, so treat specific multipliers with caution. The direction is well supported; the exact numbers are not.

Harness engineering in practice

A concrete example from Databricks shows the harness at work. A coding agent is asked to fix a bug. The model proposes a code change; the harness executes it in an isolated sandbox and returns the test results. If the tests fail, the model reads what went wrong and tries again, and the cycle continues until the tests pass or a limit is hit. Notice how little of that is the model. The sandbox, the test runner, the way results are fed back and the stopping limit are all harness. The same agent with no sandbox would be dangerous, and with no test feedback would be guessing. Building those pieces well, so a capable model can actually finish the job, is the whole of harness engineering.

Frequently asked questions

Is harness engineering the same as context engineering?

No. Context engineering is about what the model sees on a given turn: the system prompt, the history, the documents retrieved into the window. Harness engineering is about the system the agent operates within: its tools, the sandbox it runs in, its guardrails and its definition of done. Hugging Face’s line captures it: the harness controls the loop, context controls the input to each loop iteration. They sit next to each other in the stack, and a good agent needs both.

What is the difference between a harness and a scaffold?

They are related but not the same. Hugging Face separates them: the harness is the execution layer that runs the model and handles its tool calls, while the scaffold is the behaviour-shaping layer around the model, its system prompt, tool descriptions and how its output is parsed. In loose usage the words blur, but if you need the distinction, the harness runs the agent and the scaffold shapes how it behaves.

Does harness engineering matter more than the model you choose?

Often, yes. The recurring claim across 2026 practitioner writing is that a good harness on a decent model beats a bad harness on a great one, in Osmani’s phrasing. The model sets the ceiling, but the harness decides how close to that ceiling you actually get on real tasks, because it controls the tools, the feedback and the limits. Specific performance multipliers that circulate for this are not sourced to an open study, so weigh the direction rather than the exact number.

Do I need to build the whole harness myself?

No. Much of it is inherited. Böckeler’s inner-harness idea is that the model’s builder ships a base harness, an agent SDK or a coding tool with its own loop, tool handling and stopping logic. Your work is mostly the outer harness on top: instruction files, Model Context Protocol servers, custom skills and project tools. Knowing which parts you control and which you inherit is a large part of the job.

Where should you start with harness engineering?

Start with tools and a sandbox. Give the agent a small set of well-described tools it can actually use, run it somewhere isolated so mistakes are contained, and add a clear definition of “done” with a hard limit on iterations. Then treat each failure as a permanent fix to the harness rather than a prompt to retry. That covers the parts, tools, isolation, stopping and error recovery, that most often decide whether an agent works.

Sources

• Hugging Face (Paniego & Gosthipaty): Harness, Scaffold, and the AI Agent Terms Worth Getting Right (May 2026) – the harness/context boundary and the “harness controls the loop” line.
• Databricks: What is an AI Agent Harness? – Agent = Model + Harness, the four components and the eight production building blocks.
• Wikipedia: Agent harness (2026) – definition, inner vs outer harness, and the term’s early-2026 origin.
• Addy Osmani: Agent Harness Engineering (April 2026) – Agent = Model + Harness and failures as permanent signals.
• Anthropic: Building Effective Agents (Schluntz & Zhang, Dec 2024) – tools as an interface for action and feedback, sandboxing, guardrails and stopping conditions.