Short answer. An agent harness is everything in an AI agent except the model: the loop that lets the model act, the tools it can call, the context it is given, the memory it keeps, the permissions and approvals around it, and the checks that catch its mistakes. The shorthand is Agent = Model + Harness. Harness engineering is the work of improving that wrapper, so that each mistake the agent makes is fixed once, in the system, instead of every time in a prompt.
What is an agent harness?
A large language model on its own only turns text into more text. To do work it needs something around it that sends it a task, runs the tools it asks for, feeds the results back, decides when to stop and stops it from doing things it should not. That surrounding system is the harness.
LangChain puts it bluntly: "If you're not the model, you're the harness. A harness is every piece of code, configuration, and execution logic that isn't the model itself." Birgitta Böckeler of Thoughtworks, writing on Martin Fowler's site, uses the same formula: the term means "everything in an AI agent except the model itself". A July 2026 study of eleven coding agents describes it as the runtime that couples a model to the world "through a loop, tools, context management, safety controls, orchestration, and extension surfaces."
You have probably used one. Claude Code, OpenAI's Codex CLI, Cursor's agent, Gemini CLI and open-source tools such as OpenHands, Aider and Pi are all harnesses around a model. So are the SDKs you build your own agents with: Anthropic describes the Claude Agent SDK as "a powerful, general-purpose agent harness", and LangChain calls Deep Agents a "batteries-included, general purpose agent harness". If the difference between an agent and a chatbot is new to you, start with agentic AI vs AI agents.
What an agent harness is made of
- Part: Agent loopWhat it does: Sends the task, runs requested tools, returns results, decides when to stopWho usually owns it: Vendor or SDK
- Part: Tools and MCP connectionsWhat it does: Let the model read and change your systems: CRM, store, ERP, filesWho usually owns it: You
- Part: Context managementWhat it does: Chooses what goes into the window; compacts old historyWho usually owns it: Vendor, tuned by you
- Part: Memory and stateWhat it does: Notes, progress files and logs that outlive one sessionWho usually owns it: You
- Part: Permissions and approvalsWhat it does: Which actions run alone, which wait for a personWho usually owns it: You
- Part: SandboxWhat it does: Where code and commands run without touching productionWho usually owns it: Vendor or you
- Part: Guides and sensorsWhat it does: Instructions before the agent acts; tests, linters and evals afterWho usually owns it: You
- Part: OrchestrationWhat it does: Subagents, handoffs, routing easy steps to cheaper modelsWho usually owns it: Vendor or you
- Part: TracingWhat it does: A record of every call, tool result and decisionWho usually owns it: Vendor, read by you
| Part | What it does | Who usually owns it |
|---|---|---|
| Agent loop | Sends the task, runs requested tools, returns results, decides when to stop | Vendor or SDK |
| Tools and MCP connections | Let the model read and change your systems: CRM, store, ERP, files | You |
| Context management | Chooses what goes into the window; compacts old history | Vendor, tuned by you |
| Memory and state | Notes, progress files and logs that outlive one session | You |
| Permissions and approvals | Which actions run alone, which wait for a person | You |
| Sandbox | Where code and commands run without touching production | Vendor or you |
| Guides and sensors | Instructions before the agent acts; tests, linters and evals after | You |
| Orchestration | Subagents, handoffs, routing easy steps to cheaper models | Vendor or you |
| Tracing | A record of every call, tool result and decision | Vendor, read by you |
Böckeler's split is a useful way to think about the checks. Guides steer the agent before it acts (instructions, rules, examples). Sensors check its work after (tests, type checkers, an AI reviewer). Both can be plain code or another model. Her point on people is worth keeping: a good harness "should not necessarily aim to fully eliminate human input, but to direct it to where our input is most important."
What is harness engineering?
Mitchell Hashimoto named it in February 2026: "anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again." The fix goes into the harness, a new test, a tool that returns clearer errors, a rule in the project file, rather than into a longer prompt.
OpenAI's Ryan Lopopolo described what that looks like at scale. A team started an empty repository in late August 2025 and, five months later, it held about a million lines of code with no manually written code. Three engineers driving Codex merged roughly 1,500 pull requests, about 3.5 per engineer per day. Their summary: "Humans steer. Agents execute." The engineers' job became "to design environments, specify intent, and build feedback loops", and when the agent struggled they looked for what was missing, "tools, guardrails, documentation", and added it to the repository.
Prompt vs context vs harness engineering
- : Prompt engineeringWorks on: The instructions in one messageTypical fix: Rewrite the instructionQuestion it answers: How do I ask?
- : Context engineeringWorks on: Everything that lands in the windowTypical fix: Retrieve better documents, trim historyQuestion it answers: What does the model see?
- : Harness engineeringWorks on: The runtime around the modelTypical fix: Add a tool, a test, an approval gate, a retryQuestion it answers: What happens when it is wrong?
| Works on | Typical fix | Question it answers | |
|---|---|---|---|
| Prompt engineering | The instructions in one message | Rewrite the instruction | How do I ask? |
| Context engineering | Everything that lands in the window | Retrieve better documents, trim history | What does the model see? |
| Harness engineering | The runtime around the model | Add a tool, a test, an approval gate, a retry | What happens when it is wrong? |
The three stack rather than replace each other. The system prompt is one part of the harness, and context engineering is one of its jobs. What harness engineering adds is the assumption that the model will make mistakes, and a system that catches them.
Does the harness matter more than the model?
Not usually, but it matters more than most buyers think. The evidence so far:
- Same model, better harness. LangChain kept GPT-5.2-Codex fixed and changed only the harness of its deepagents CLI: the Terminal-Bench 2.0 score went from 52.8 to 66.5, from outside the top 30 to the top 5.
- Same model, different products. In the Terminal-Bench paper, Claude Opus 4.5 scored 57.8% in the Terminus 2 harness, 52.1% in Claude Code and 51.9% in OpenHands. Token use differed even more.
- A small model with a strict harness. In the AutoHarness paper, 78% of Gemini 2.5 Flash's chess losses came from illegal moves. A harness that blocked illegal moves let Flash beat the larger Gemini 2.5 Pro.
- Cost. A test published on Martin Fowler's site in October 2026 found a cheap model passing 3 of 10 runs alone and 10 of 10 with a harness, at 33% less than the larger model without one.
The same Terminal-Bench paper warns that "model selection is usually more important than agent scaffold", and the best harnesses on another benchmark sat within six points of each other. So pick the model first. Then the harness decides how much of that model you actually get, how often it fails safely, and what each task costs. We work through the money side in AI agent development cost.
A harness pattern from Anthropic: long-running agents
Anthropic's engineers found that even a frontier model in a loop "will fall short of building a production-quality web app if it's only given a high-level prompt." It tried to do everything at once and ran out of context, or a later session declared the job done too early. The fix was in the harness, not the model:
- An initializer agent sets up the environment: a start script, a progress log file and a first commit, plus a feature list (over 200 features in their test, all marked failing).
- A working agent then takes one feature per session. It starts by reading the progress file and the history, and ends with a commit and an update to the log.
- Both agents share the same system prompt, tools and harness. Only the first message differs.
The business lesson travels well beyond code: keep the state of the work outside the model, in files, tickets or records the next session can read, and give the agent one clear unit of work at a time.
What a business owns in the harness
When you buy or build an agent, the loop is the commodity part. Claude Code, Codex and the SDKs will keep improving it, and you can swap it. The parts that carry your business are the ones in the "You" rows of the table above:
- Tools into your systems. Usually an MCP server per system, so any harness can use it: Claude, Codex or Cursor.
- Rules as code. For Horeca Papatya, a hotel and restaurant supplier, we built a Shopify MCP server where bulk jobs run as a dry run first, new products start as drafts and deletes need explicit approval. Because the rules live in the server, every harness obeys them.
- Evals. A set of real tasks with known good results, re-run whenever you change the model or the prompt.
- Memory and logs. What the agent did and why, in a place you can audit.
A prompt that says "be careful" disappears the day you switch harness or model. Put approvals, limits and dry runs in the tools themselves.
How to judge a vendor’s harness
- Ask to see a trace of a real task: every model call, tool call and result.
- Ask which actions need human approval, and where that rule is enforced: in a prompt or in code.
- Ask for the eval set and the score before and after the last change.
- Ask what one task costs in tokens, and how that changes if the model is swapped.
- Ask whether the tools and rules are yours to keep if you change vendor.
Frequently asked questions
What is an agent harness?
An agent harness is all the code around a language model that turns it into an agent: the loop that runs tools, context management, memory, permissions and approvals, sandboxing, checks and tracing. In short, Agent = Model + Harness.
What is harness engineering?
Harness engineering is the practice of improving the system around an AI agent so that each mistake it makes is fixed once and for all, with a tool, a test, a rule or an approval step, rather than by rewriting prompts. Mitchell Hashimoto coined the term in February 2026.
Is Claude Code an agent harness?
Yes. Claude Code wraps Claude models in a loop with tools, permissions, memory files, hooks and MCP connections. Anthropic's Claude Agent SDK exposes the same tools, agent loop and context management for building your own agents.
What is the difference between an agent harness and an agent framework?
A framework gives you building blocks to assemble an agent. A harness is a working runtime with the loop, tools and safety controls already in place. Many products, such as LangChain Deep Agents, now ship as a harness on top of a framework.
What does LLM harness mean?
It has two meanings. In agents, it is the harness described here. In model testing, an evaluation harness such as EleutherAI's lm-evaluation-harness is the code that runs a model through benchmark tasks and scores it.
Do I need to build my own harness?
Rarely from scratch. Use an existing harness or SDK for the loop and build the parts that are specific to you: the tools into your systems, the approval rules, the evals and the logs.
Sources
- LangChain: The Anatomy of an Agent Harness and Improving Deep Agents with harness engineering
- Birgitta Böckeler: Harness engineering for coding agent users (April 2026)
- Mitchell Hashimoto: My AI Adoption Journey (5 February 2026)
- OpenAI: Harness engineering, leveraging Codex in an agent-first world
- Anthropic: Effective harnesses for long-running agents
- Terminal-Bench paper (arXiv 2601.11868) and AutoHarness (arXiv 2603.03329)
- AI agent
- Agent harness
- Harness engineering

