What is an agent harness?
An agent harness is everything in an AI agent except the model: the prompts, tools, sandbox, hooks and checks that turn a model into an agent.
An agent harness is everything in an AI agent except the model. Birgitta Böckeler uses that definition, and Addy Osmani spells it out as every piece of code, configuration and execution logic that is not the model itself. Osmani credits Viv Trivedy with the formula “Agent = Model + Harness.”
The model supplies the reasoning. The harness decides what the model sees, which tools it can call, what happens to the output and when the run stops. That makes it the practical layer of an AI agent architecture.
What a harness contains
Osmani lists the parts:
| Part | Examples |
|---|---|
| Instructions | System prompts, instruction files such as CLAUDE.md and AGENTS.md, skills, subagent prompts |
| Tools | Tools, skills and MCP servers, including their descriptions |
| Infrastructure | A filesystem, a sandbox, a browser |
| Orchestration | Spawning subagents, handoffs, model routing |
| Hooks and middleware | Deterministic steps such as compaction, continuation and lint checks |
| Observability | Logs, traces, cost and latency metering |
Anthropic’s Claude Agent SDK is an example of a packaged one: Justin Young calls it “a powerful, general-purpose agent harness adept at coding.”
Guides and sensors
Böckeler splits the controls a user adds on top of a coding agent into two kinds. Guides are feedforward: they steer the agent before it acts so the first attempt is better. Sensors are feedback: they observe after it acts and help it correct itself, and they work best when their output is written for an LLM, such as a linter message that includes fix instructions.
She also separates computational controls (tests, linters, type checkers), which are deterministic and fast, from inferential ones (AI code review, an LLM as judge), which are semantic, slower and less deterministic. She sorts harnesses by what they regulate: maintainability, architecture fitness and behaviour. Behaviour is the hard one. She calls it “the elephant in the room” and says relying on AI-generated tests for it is “not good enough yet.”
She also argues that codebases differ in how easy they are to harness: strong typing gives you a type checker as a sensor, and clear module boundaries support architectural rules.
How teams build one
Three published accounts show the practice.
- Long-running work. Anthropic’s Justin Young describes an initializer agent that sets up an init script, a progress file, a first git commit and a feature list with every feature marked failing. Later sessions take one feature at a time, read the progress notes and git log, run a basic end-to-end check and commit. He calls the key problem getting agents to “quickly understand the state of work when starting with a fresh context window”, which ties to context rot. The deep agents pattern builds on the same idea.
- Separate worker and judge. Anthropic’s Prithvi Rajasekaran found that agents praise their own work when asked to grade it, and that tuning a standalone evaluator to be skeptical is “far more tractable” than making a generator self-critical. His evaluator drives the running app with Playwright and fails a sprint if any criterion falls below its threshold.
- Repository as the interface. InfoQ’s summary of an OpenAI team’s account describes a five-month experiment with roughly one million lines of code and no manually written source. It says a structured docs directory served as the single source of truth for agents, and structural tests enforced a fixed order of dependency layers. Latent Space’s summary of an interview with Ryan Lopopolo says that when an agent failed, the team asked “what capability, context, or structure is missing?”
Working rules practitioners give
- Turn each failure into a rule. Osmani writes that every line in a good AGENTS.md should be traceable to something that went wrong.
- Keep hooks quiet on success. Osmani agrees with a principle HumanLayer highlights: “success is silent, failures are verbose.”
- Remove what the model no longer needs. Rajasekaran wrote that every component encodes an assumption about what the model cannot do alone, and with Opus 4.6 he removed the sprint construct from his harness. He repeats Anthropic’s earlier advice to “find the simplest solution possible, and only increase complexity when needed.”
- Expect coupling to the model. Osmani notes that models are often post-trained with specific harnesses, so the best harness for your task may differ from the one a model was trained in.
Where the term gets fuzzy
“Harness engineering” is new and the word is used loosely. A June 2026 paper by Sanderson Oliveira de Macedo says usage is “loose and polysemous”: it can mean a whole product such as Claude Code or Codex CLI, an evaluation scaffold that runs an agent against tasks, or something conflated with a framework, SDK, IDE plugin or orchestrator. Latent Space introduced its interview with Lopopolo by casting harness engineering as the successor to context engineering, while Osmani calls harnesses “largely delivery mechanisms for good context engineering.” For that discipline see context engineering.
The terms around it have separate pages: agent orchestration covers coordinating agents, and agentic coding covers the coding use case most harness writing is about. For the benchmark behind the Top 5 claim, see Terminal-Bench.
See what your harness is doing
A harness change is only an improvement if you can see its effect. Check the behaviour with tests for the agent and watch live runs through agent tracing. If your harness is Claude Code, HoneyHive’s Claude Code integration uses Claude Code hooks to trace each session’s prompts and tool calls, and the docs also cover giving coding agents such as Codex CLI access to HoneyHive’s docs.
FAQ
What is an agent harness?
It is everything in an AI agent except the model. Addy Osmani defines it as every piece of code, configuration and execution logic that is not the model itself.
What is harness engineering?
It is the work of designing and improving the harness around a model. Birgitta Böckeler frames it as building guides that steer a coding agent before it acts and sensors that let it self-correct after.
What is the difference between an agent harness and an agent framework?
The terms overlap and usage is loose. One 2026 paper notes the word is sometimes used for a whole product such as Claude Code, sometimes for an evaluation scaffold, and sometimes conflated with a framework, SDK or orchestrator.
Does the harness matter as much as the model?
Practitioners say it can. Osmani reports that changing only the harness moved a coding agent from about the Top 30 to the Top 5 on Terminal Bench 2.0, a secondhand account of Viv Trivedy's team.
Do harness components stay useful as models improve?
Not always. Anthropic's Prithvi Rajasekaran wrote that every component in a harness encodes an assumption about what the model cannot do alone, and those assumptions should be stress-tested as models improve.