What Is an Agent Harness? The Software Around the Model, Explained (2026)

An agent harness is the software around a language model that turns it into an agent: the loop that calls the model, runs the tools it asks for, manages what it remembers, enforces what it may touch, and decides when the work is finished. The model supplies the judgment; the harness supplies everything else. When people say "agent = model + harness", this is the half of the sentence they mean.

The term borrows from engineering, where a harness is the rigging that connects a powerful thing to the work it is meant to do (a wiring harness, a horse's harness, a test harness). A model on its own can only return text. A harness gives that text consequences: a tool call becomes a file write, a shell command, a search, or an API request, and the result goes back into the next turn.

If you searched "harness" and landed here by accident, three other meanings are common. Harness is also a DevOps company (Harness.io) that sells CI/CD and testing software. A test harness is the scaffolding that runs a test suite against code. An evaluation harness, such as EleutherAI's lm-evaluation-harness, runs a model through a set of benchmarks; that belongs with LLM evals, not with agents.

What an agent harness actually does

Every harness, from a 200-line script to Claude Code, runs a version of the same loop: send the instructions and the context to the model, read the response, execute any tool calls it contains, append the results, and go again until the model says it is done or the harness stops it. The interesting decisions are in the layers around that loop.

• Loop and stop conditions. When to call the model again and when to stop: a done signal, a step limit, a token or cost budget. Without it: agents that loop forever, or quit early and report success.
• Tools. Which actions exist, how they are described to the model, and how results and errors come back. Without it: the model guessing at actions, or never seeing that a command failed.
• Context management. What goes into the window each turn, how long tool output is trimmed, and when to compact. Without it: constraints from turn 3 forgotten by turn 40.
• Instructions. The standing rules loaded every session (CLAUDE.md, AGENTS.md, a system prompt). Without them: project conventions re-explained in every chat.
• Permissions and sandbox. Which files, commands, and networks the agent can reach, and what needs a human yes. Without them: an agent that edits production or signs something on your behalf.
• Hooks and guardrails. Deterministic checks that fire on specific actions, outside the model. Without them: safety rules that depend on the model choosing to follow them.
• Memory. What is written somewhere durable and read back next time (agent memory). Without it: every session starts from zero.
• Observability. A trace of every model call, tool call, and result. Without it: failures you cannot reconstruct after the fact.

The list is also a reasonable way to compare harnesses. Two tools that look identical in a demo can differ completely in how they trim a 40,000-line log before the model sees it, or in whether a failed command is reported as an error or silently swallowed.

Why the harness matters as much as the model

For most production work in 2026, model capability is no longer the only variable that decides the outcome, and often not the biggest. Research on coding agents made this concrete early: the SWE-agent project showed that redesigning the interface between the agent and its environment (how files are viewed, how edits are applied, how errors are shown) moved results substantially with the same underlying model. Public leaderboards for terminal and coding tasks now list the agent and the model as a pair for the same reason.

Our own coverage keeps landing on the same point. When a builder pointed 11 autonomous agents at their own product and only 3 finished, the failures were not about intelligence but about harness problems: context bloat, redundant turns, and loops with no clean exit. The three that finished had tight, verifiable stop conditions. When Claude Code was run against the Claude app's own codebase, it handled contained changes and fell apart on ones that needed the whole system in view, which is a context-management limit as much as a model one.

Cost is the other reason. A long agentic session can make dozens of model calls, and the harness decides how expensive each one is. Grist routes coding tasks across four model tiers so that only hard tasks reach a frontier model, and Writer shipped a token-cost harness alongside its model rather than leaving budgeting to the customer. Both are harness decisions, not model ones.

The main kinds of agent harness

The market has split into three rough groups, a pattern we described in what builders are actually choosing among agent harnesses:

• Managed coding harnesses. Claude Code, OpenAI's Codex CLI, Gemini CLI, and the agent modes inside editors such as Cursor. They come with tools, permissions, compaction, and instruction files already designed, and they are tuned for one vendor's models. The trade-off is less control over the loop and, often, a higher token bill.
• Framework-built harnesses. Teams assemble their own loop with LangGraph, the OpenAI Agents SDK, or the Claude Agent SDK. More setup, explicit control over topology, routing, and state.
• Lightweight open-source runners. OpenCode, Aider, and smaller projects that prioritise local control, model choice, and cost, and are easy to fork when the loop needs to change.

None of these is better in general. The useful question is which layer from the list above is failing on your tasks, and which group lets you change that layer.

Harness engineering

"Harness engineering" is the name that has stuck for the work of improving an agent without changing its model: writing better tool descriptions, deciding what the agent sees after an error, adding hooks, tightening permissions, and setting stop conditions. It is to agents what prompt engineering is to single calls, and most of it is unglamorous.

A few practices have become standard:

1. Put durable rules in instruction files, not chat. A rule in CLAUDE.md or AGENTS.md is loaded every session and does not depend on surviving a summary. Even the Linux kernel community has discussed adding an Agents.md file for contributors that are agents.
2. Enforce safety in the wrapper. Hooks that block a command or require approval run deterministically, whatever the model decides. Our piece on the stack for reliable agents covers hooks, typed structured calls, and decision tracing as three separate layers.
3. Check output with tools, not with the model's own opinion. Tests, type checks, and structural linters such as RepoGuard, which checks AI-generated code against architecture rules, turn "the agent says it is done" into "the build says it is done".
4. Trace before you tune. You cannot fix a harness you cannot see. Log every model call and tool result first; most fixes come from reading a handful of failed traces, the method in our silent agent failures guide.
5. Measure changes with a fixed task set. A harness change is a product change. Run the same 20 to 50 real tasks before and after, the same way you would run LLM evals on a prompt.

A prompt for auditing your agent harness

Paste a description of your setup, or a failed trace, into a capable model and use this to find the weakest layer:

You are reviewing the harness around an AI agent, not the model.
<setup>[describe the harness: tools available, how errors are returned, context limits and compaction, instruction files, permissions, hooks, stop conditions]</setup>
<trace>[optional: paste one failed or suspicious run]</trace>
For each layer (loop and stop conditions, tools, context management, instructions, permissions, hooks, memory, observability):
1. Say what the current setup does, in one line.
2. Name the most likely failure it allows, with evidence from the trace if there is one.
3. Propose one change, and say whether it is configuration or code.
Rank the three changes that would most reduce wrong-but-confident results. Do not suggest switching models.

The last line is deliberate. "Use a smarter model" is the answer people reach for first, and it is usually the most expensive way to fix a problem that lives in the loop.