Guide · Equip
What is an AI agent harness? The software that turns a model into an agent
What an AI agent harness is, what it does that the model can’t, why the same model scores differently in different harnesses, and what to ask vendors.
The short answer
An AI agent harness is the software around an AI model that turns it into an agent: the loop in which it plans and acts, the tools it can call, the context and memory it works from, and the permissions, checks and logs that keep it safe. In short, agent = model + harness. The same model can perform very differently in different harnesses, and the harness is where a company’s rules, knowledge and approvals take effect.
Key takeaways
- An agent is a model plus a harness. The model decides the next step; the harness runs the loop and supplies the context, tools, memory, permissions, checks and logs.
- The same model can score very differently in different harnesses. Judge an agent as a model-and-harness pair, on your own work.
- The harness is where governance lives. Your rules, knowledge, permissions, approvals and audit trail make agents useful and safe, whichever model you use.
What is an AI agent harness?
An AI agent harness is the software around an AI model that turns it into an agent. On its own, a model can only read what it is given and write a reply. It can’t open your ERP, remember last week or ask anyone for approval. The harness gives it those abilities, and sets their limits.
People who build agents sum it up as “agent = model + harness.” Vivek Trivedy of LangChain puts it in one line: “If you’re not the model, you’re the harness.” Anthropic’s engineers define an agent the same way, as a model plus the software scaffolding around it.
The loop, run by the harness
- Assemble the contextHarness
- Decide the next stepModel
- Run the toolHarness
- Check the resultHarness
Repeat until the task is done or a stop rule applies
Helps the model do the work
- ContextWhat the model sees at each step: instructions, the task, documents and results.
- ToolsWhat it can do: search, read and update records, run code, call your systems.
- MemoryWhat carries over: notes, progress files and past decisions.
Keeps the work safe and accountable
- Permissions and sandboxWhat it may touch, where it runs, and what needs a person’s approval.
- Checks and stop rulesTests its work must pass, limits on time and spend, and when to escalate.
- LogsA record of every step, input and approval.
What your company plugs in
- Instructions and SOPs
- Skills
- Connections to your systems
- Who owns what, and the rules
- Approvers
Take an agent that matches supplier invoices to purchase orders. The model reads each invoice and decides whether it matches. The harness does the rest: it fetches the purchase order, lets the agent read the ERP but not change it, checks the totals, sends any mismatch to the right person and logs every step.
What does the harness do that the model can’t?
At the center is a loop. The harness gives the model the task and the context, the model picks the next step, and the harness runs that step and feeds back the result. In OpenAI’s Codex, Michael Bolin explains, this repeats until the model stops asking for tools and replies to the user. Claude Code’s documentation describes the same cycle in three phases: gather context, take action and verify results.
Everything else in the harness shapes that loop. The model proposes; the harness decides what actually happens.
| Job | The model | The harness |
|---|---|---|
| Understand the task and choose the next step | Does this | Asks for that decision at each step |
| Decide what the model sees | Asks for files or records | Assembles instructions, knowledge and results |
| Act in your systems | Requests an action | Runs it, within its permissions |
| Remember | Only what is in front of it | Keeps notes, progress and history |
| Stay within the rules | Follows instructions, imperfectly | Enforces permissions, sandboxes and approvals |
| Check the work | Reviews its own output | Runs tests and rules, then blocks or escalates |
| Stop | Says when it thinks it’s done | Enforces limits on time, spend and steps |
| Record what happened | No role | Logs every step, input and approval |
Small harness choices add up. Anthropic’s team noticed that models sometimes mixed up relative file paths, so they made the file tool require full paths. They call it error-proofing the tool, and argue that tools for models deserve as much design attention as tools for people.
Birgitta Böckeler of Thoughtworks sorts a harness’s controls into guides, which steer the agent before it acts, such as instructions and skills, and sensors, which check its work afterward, such as tests and reviews.
What are examples of agent harnesses?
The most familiar harnesses today belong to coding agents. Each pairs a model with its own loop, tools and controls:
- Claude Code. Anthropic’s docs describe Claude Code as the layer around the model that provides the tools and manages what the model sees, and call that layer the agentic harness. It reads project instructions from CLAUDE.md files, keeps an automatic memory, connects to outside systems through MCP and loads skills when a task needs them. Its permission modes include asking before every edit, and an automatic mode in which a classifier blocks risky actions.
- OpenAI Codex. Bolin describes the Codex harness as the agent loop plus the logic that carries out each step. Codex reads AGENTS.md instruction files and compacts long conversations. On your own machine, it runs commands in an operating-system sandbox, with no network access and writes limited to the workspace by default, plus an approval policy for when it must stop and ask.
- Cursor. Cursor describes its harness as instructions, tools and the model you pick, and tunes the instructions and tools for every frontier model. Its engineers Stefan Heule and Jediah Katz write that they spend weeks fitting the harness to each new model. OpenAI’s models are trained to edit files with patches and Anthropic’s with string replacement, so each model gets the tool format it knows.
The same design works beyond code. Anthropic says the harness behind Claude Code can power other kinds of agents, such as finance, customer support and research agents, and renamed its SDK the Claude Agent SDK to match. Only the tools and rules change. An accounts payable agent’s tools are ERP lookups instead of a terminal, its context is the vendor file and the payment policy, and its stop rule is a person’s approval before money moves.
Does the harness matter as much as the model?
It can. The same model can score very differently depending on the harness around it. The team behind Terminal-Bench 2.0, a benchmark of 89 hard tasks done in a computer terminal, ran models through several harnesses and published every result.
GPT-515.7-point spread
Gemini 2.5 Pro16.9-point spread
Claude Sonnet 4.52.7-point spread
Show the data
| Model · harness | Tasks resolved |
|---|---|
| GPT-5 · Codex CLI | 49.6% ± 2.9% |
| GPT-5 · OpenHands | 41.5% ± 2.8% |
| GPT-5 · Terminus 2 | 35.2% ± 3.1% |
| GPT-5 · Mini-SWE-Agent | 33.9% ± 2.9% |
| Gemini 2.5 Pro · Terminus 2 | 32.6% ± 3.0% |
| Gemini 2.5 Pro · Mini-SWE-Agent | 26.1% ± 2.5% |
| Gemini 2.5 Pro · Gemini CLI | 19.6% ± 2.9% |
| Gemini 2.5 Pro · OpenHands | 15.7% ± 2.6% |
| Claude Sonnet 4.5 · Terminus 2 | 42.8% ± 2.8% |
| Claude Sonnet 4.5 · Mini-SWE-Agent | 42.5% ± 2.8% |
| Claude Sonnet 4.5 · OpenHands | 40.3% ± 2.6% |
| Claude Sonnet 4.5 · Claude Code | 40.1% ± 2.9% |
In those results, the choice of harness was worth 15.7 points for GPT-5, more than the 13.3 points gained by upgrading to GPT-5.2 inside Codex CLI. For Gemini 2.5 Pro, the best harness roughly doubled the worst. For Claude Sonnet 4.5, all four landed within three points. The authors conclude that the model usually matters more for raw performance. A fair summary: the model sets the range, and the harness decides where in that range you land.
GPT-4’s score on SWE-bench Lite, a set of real issues from open-source projects, with the weakest and the strongest scaffold on the public leaderboard.
Source: OpenAI, August 2024
LangChain’s coding agent on Terminal-Bench 2.0 after changes to the harness alone, such as clearer instructions and automatic self-checks. The model, GPT-5.2-Codex, stayed the same.
Two lessons follow for buyers. Judge an agent as a model-and-harness pair, on your own cases, with a personalized benchmark. A model’s leaderboard rank says little about the agent you will actually run. And expect pairings to differ: the Terminal-Bench authors note that many harnesses are built around particular models, especially when one company makes both.
What is context engineering?
Context engineering is deciding what the model sees at each step, and it is much of what a harness does. Anthropic’s Applied AI team treats context as a scarce resource. The more a context window holds, the less reliably a model recalls what is in it, an effect known as context rot. The team’s advice is to give the model the smallest set of information that does the job.
The same post describes four techniques that harnesses use:
- Load just in time. Keep pointers, such as file paths or saved queries, and pull in the data only when it’s needed.
- Compact. When the context window fills up, summarize it and carry on from the summary.
- Take notes. Have the agent write notes outside the context window and read them back later.
- Split the work. Give sub-agents a clean context for a focused job, and have them report back a short summary.
Long jobs need more. Each new session starts with no memory of the last, as Justin Young writes in Anthropic’s post on harnesses for long-running agents. His team’s fix works like a good shift handover:
- List the workThe first session writes every feature to a file, each marked as failing.
- Get up to speedEach new session reads the progress notes and the history.
- Pick one itemWork on a single feature at a time.
- Test it as a user wouldMark it as passing only once it works end to end.
- Leave a clean handoffCommit the work and update the progress notes.
The team reports that browser testing tools, which let the agent check each feature as a user would, greatly improved its results. The post’s examples come from building software, but Anthropic thinks some of the lessons likely apply to work such as financial modeling. Picture a month-end close: a checklist of reconciliations marked pass or fail, notes on what is done and what is open, one account at a time, each checked before it is marked complete.
How do skills, tools and company knowledge plug into a harness?
A harness ships with general-purpose tools. What makes an agent useful in your company is what you plug into it:
- Connections to your systems. The Model Context Protocol (MCP), which Anthropic open-sourced in November 2024, is a standard way to connect AI to the systems where data lives. Anthropic’s first ready-made connections included Google Drive, Slack, GitHub and Postgres.
- Skills. Skills are folders of instructions, scripts and resources that an agent loads only when a task calls for them. Anthropic likens building one to writing an onboarding guide for a new hire. Claude Code and Codex both use them. See our guide to AI skills.
- Standing instructions. Files such as CLAUDE.md and AGENTS.md hold the rules and conventions an agent should follow in every session.
- Company knowledge. Who owns what, how work flows, which system is the source of truth, and which rules apply. A new hire picks this up from colleagues; an agent needs it written down, in a digital org it can look up. That is what good agent experience means.
Two cautions. Every connection is also a way in, so it needs permissions like any other tool. Codex, for example, sandboxes its own shell commands, but Bolin notes that tools from MCP servers must enforce their own guardrails. And a skill is instructions and code written by someone else, so Anthropic advises installing skills only from trusted sources and auditing the rest.
Why is the harness where AI governance lives?
The model decides how to reason. The harness decides what the agent can see, what it can touch, who approves what and what gets recorded. Those decisions make an agent safe, and your company should make them rather than accept a vendor’s defaults. Today’s coding harnesses show the controls to look for:
- Permissions. Claude Code checks each tool call against deny, ask and allow rules, in that order, and administrators can deploy settings that users and projects can’t override.
- Sandboxes. Codex keeps commands inside the current workspace, with network access off unless you turn it on.
- Approvals. Both can require a person to approve chosen actions, the core of human-in-the-loop design. In business work, that is the person who signs off on a payment, a discount or a customer email.
- Rules that always run. Claude Code’s hooks run your own commands at set points, so certain actions always happen instead of depending on the model.
- A record. Claude Code can export usage, cost and tool activity through OpenTelemetry to your own monitoring systems.
For a business agent, write the same controls in business terms. An accounts payable agent might read the ERP but never post to it, draft payments but never release them, send any invoice that doesn’t match its purchase order to a person, and record every document it read and every check it ran in an audit trail. Because the harness enforces those rules, they apply to every agent and every model that runs in it.
The harness is also where your company’s learning compounds. Böckeler’s advice is to improve the harness whenever a problem recurs, with a better instruction or a new check, so the problem becomes less likely. Models will keep changing. The rules, skills, checks and knowledge you build into the harness stay with you.
What should you ask a vendor about its harness?
Whether you buy an agent or build one, get answers to these questions before it touches real work:
- Which models does the harness support, and is it tuned and tested for each one?
- How does the model-and-harness pair perform on cases like ours, and can we test it on our own?
- What does the agent see at each step, and can we add our instructions, skills and knowledge?
- Which tools can it call, and how do we connect our own systems, for example over MCP?
- What can it do without asking, and can we set allow, ask and deny rules for the whole company?
- What runs in a sandbox, and which tools must enforce their own guardrails?
- Where do approvals happen, and can we route each one to the right person?
- How does it check its own work, and when does it stop or hand off to a person?
- What does it remember between sessions, and can we see and correct that memory?
- Is every step logged, and can we export the logs to our own monitoring and audit tools?
Then check the answers on your own work. Run the agent in shadow mode on real cases before it acts, compare it with how your people do the work today, and keep the people who own each decision in the approval path.
Questions people ask
What is the difference between an AI model and an AI agent?
A model takes in what it is given and returns a response; on its own, it can’t act. An agent is a model running inside a harness that gives it tools, context, memory and rules, and loops until the task is done or a stop rule applies. One model can power many different agents.
Is an agent harness the same as an agent framework or SDK?
They overlap. A framework or SDK is a kit for building harnesses. A harness is the setup a particular agent actually runs in: its loop, tools, instructions, permissions and checks. Anthropic’s Claude Agent SDK, for example, packages the harness behind Claude Code so developers can build other agents on it.
Can we switch models without changing the harness?
Often, but test before you switch. Harnesses are usually tuned to particular models: Cursor, for example, tunes its instructions and tools for each frontier model it supports. Re-run your own evals whenever the model or the harness changes.
Who should own the harness in a company?
Treat it like any production system. Engineering or IT can run it, but the business should own its rules: what agents may do, who approves what, and what “correct” means. Security and compliance should review the permissions and logs before an agent touches real work.
What is harness engineering?
Harness engineering is improving an agent by changing everything except the model: its instructions, tools, context, checks and controls. LangChain, for example, raised its coding agent’s score on a public benchmark this way while keeping the model the same.
Sources
- Vivek Trivedy. “The Anatomy of an Agent Harness.” LangChain, March 10, 2026.
- Erik Schluntz. “Raising the bar on SWE-bench Verified with Claude 3.5 Sonnet.” Anthropic, January 6, 2025.
- Michael Bolin. “Unrolling the Codex agent loop.” OpenAI, January 23, 2026.
- “How Claude Code works.” Anthropic, Claude Code docs, accessed October 3, 2026.
- Birgitta Böckeler. “Harness engineering for coding agent users.” martinfowler.com, April 2, 2026.
- “Agent approvals & security.” OpenAI, ChatGPT Learn, accessed October 3, 2026.
- Lee Robinson. “Best practices for coding with agents.” Cursor, January 9, 2026.
- Stefan Heule and Jediah Katz. “Continually improving our agent harness.” Cursor, April 30, 2026.
- Thariq Shihipar. “Building agents with the Claude Agent SDK.” Anthropic, September 29, 2025.
- Mike A. Merrill, Alexander G. Shaw, Nicholas Carlini and 82 others. “Terminal-Bench: Benchmarking Agents on Hard, Realistic Tasks in Command Line Interfaces.” arXiv, January 17, 2026.
- Neil Chowdhury, James Aung, Chan Jun Shern and 13 others. “Introducing SWE-bench Verified.” OpenAI, August 13, 2024.
- Vivek Trivedy. “Improving Deep Agents with harness engineering.” LangChain, February 17, 2026.
- Prithvi Rajasekaran, Ethan Dixon, Carly Ryan and Jeremy Hadfield. “Effective context engineering for AI agents.” Anthropic, September 29, 2025.
- Justin Young. “Effective harnesses for long-running agents.” Anthropic, November 26, 2025.
- “Introducing the Model Context Protocol.” Anthropic, November 25, 2024.
- Barry Zhang, Keith Lazuka and Mahesh Murag. “Equipping agents for the real world with Agent Skills.” Anthropic, October 16, 2025.
- “Configure permissions.” Anthropic, Claude Code docs, accessed October 3, 2026.
- “Automate actions with hooks.” Anthropic, Claude Code docs, accessed October 3, 2026.
- “Monitoring.” Anthropic, Claude Code docs, accessed October 3, 2026.