What Is Harness Engineering? The System Around an AI Agent
Harness engineering is designing everything around an AI model so an agent works reliably: instructions, tools, memory, checks and permissions.
Give two coding agents the same AI model and the same task, and one may finish cleanly while the other loops, forgets what it was doing or declares victory with half the work missing. The model is identical. What differs is everything around it.
That surrounding layer is called the harness, and designing it on purpose has a name: harness engineering. In 2026 it became one of the most discussed ideas in building AI agents, largely because the teams shipping the most capable agents said the harness, not the model, was where their reliability came from.
The model is the engine. The harness is the rest of the car: steering, brakes, dashboard and fuel gauge. Harness engineering is building that car so the engine can actually get you somewhere safely.
This guide explains what a harness is, what goes inside one, how two of the largest AI labs describe their own harnesses, and what to look for when you build or choose an agent.
What is an agent harness?
A language model on its own does one thing: it reads text and writes text. It can't run a command, open a file, remember yesterday's session or check whether its code works. An agent needs all of those, and the code that provides them is the harness.
LangChain's engineering team put it in one line: "If you're not the model, you're the harness." In their framing, an agent is simply model + harness.
A useful way to see it: when you use a coding agent such as Claude Code, Codex or Cursor's agent mode, you're not talking to a bare model. You're using a harness that decides what the model sees, which tools it can call, when to stop it and how to check its work.
Harness is also the name of a software delivery platform. "Agent harness" and "harness engineering" in this article have nothing to do with it.
What goes inside a harness?
Harnesses differ, but most of them handle the same jobs:
| Part | What it does | Example |
|---|---|---|
| Instructions | Tells the model its role, rules and project conventions | A system prompt, an AGENTS.md file read at the start of every session |
| Tools | Lets the model act, not just talk | Running shell commands, editing files, searching the web, tool calling through MCP |
| Context management | Keeps the context window useful | Summarising old turns, saving long outputs to files instead of the conversation |
| State and memory | Carries work across sessions | Progress notes, task lists, git history (agent memory) |
| Execution environment | Gives the agent somewhere safe to work | A sandbox, a container, a browser it can drive |
| Feedback loops | Tells the agent when it's wrong | Tests, type checks, linters, screenshots of the running app |
| Guardrails and approvals | Limits what it may do | Blocked commands, permission prompts, human sign-off for risky actions (guardrails) |
| Orchestration | Splits large jobs up | Sub-agents, hand-offs, choosing a model per task (orchestration) |
None of these parts is new on its own. Harness engineering is the practice of treating them as one system, designed together, and improving it every time the agent fails.
From prompt engineering to harness engineering
The term grew out of two earlier ideas, and it helps to see them side by side.
| Prompt engineering | Context engineering | Harness engineering | |
|---|---|---|---|
| Question | How do I word the request? | What should the model see right now? | What system does the agent run in? |
| Scope | One message | One model call | Every session, tool, check and permission |
| Typical fix | Rewrite the instruction | Add or remove documents and history | Add a test, a rule, a tool or a progress file |
| Who does it | Anyone using AI | Developers building AI features | Teams running agents on real work |
Prompt engineering still matters inside a harness: the instructions are a prompt. But for agents that work for hours across many steps, wording alone can't stop an agent from losing track of a half-finished feature. A progress file and a test can.
How AI labs describe their harnesses
Two widely read engineering posts gave the idea its shape.
Anthropic: agents that work across many sessions
In November 2025, Anthropic described the harness it used to have Claude build a full web application over many separate sessions. Each new session starts with no memory of the last one, and the team saw two failures: the agent tried to do too much at once and ran out of context mid-feature, or it later decided the job was finished when it wasn't.
Their fix was structural, not a better prompt:
- A first "initializer" session turns the request into a detailed feature list (over 200 items in their example, all marked as failing), writes a script to start the app, creates a progress log and makes the first git commit.
- Every later session reads the progress log and git history, starts the app, runs a quick end-to-end check, then works on one feature only, commits it and updates the log.
- The feature list is JSON, not prose, because the model was less likely to rewrite it, and agents may only flip a feature's status to passing after testing it.
- Testing like a user. Unit tests alone missed broken features; giving the agent a browser it could drive found bugs that weren't visible in the code.
OpenAI: a product written entirely by agents
In February 2026, OpenAI published "Harness engineering", describing an internal project in which a small team built a beta product of around a million lines of code over five months without writing the source code by hand. Codex agents wrote it; the engineers built the environment the agents worked in. According to InfoQ's summary (opens in a new tab), that environment included:
- Documentation as the source of truth: maps, plans and design specs kept in the repository, cross-linked and checked in CI.
- Rules a machine can enforce: a fixed order of code layers, with structural tests and linters that fail when an agent breaks it.
- Observability for the agents: logs, metrics and traces the agents could read to reproduce and fix bugs themselves.
The common thread: when the agent made a mistake, the team didn't just correct the output. They changed the environment so that kind of mistake would be caught, or couldn't happen, next time.
The harness engineering loop
Practitioners describe the same cycle again and again:
- Run the agent on real tasks, not demos.
- Watch where it fails: lost context, wrong tool, skipped test, unsafe command, claimed success without checking.
- Name the cause. Was information missing? Was there no way to verify? Was an action allowed that shouldn't be?
- Fix the harness, not just the answer: add a rule to the instructions file, a test, a tool, a hook that blocks a command, or a progress file.
- Repeat. Each line in a good
AGENTS.mdusually traces back to a real failure.
A few clear tools work better than many overlapping ones, and short rules that each prevent a known failure work better than long style guides. Keep successful checks quiet and failures loud, so the agent's attention goes where it's needed.
A starter checklist
If you're setting up an agent for your own team, these are the pieces most harnesses add first:
- An instructions file in the project (
AGENTS.mdor similar): how to build, test and run, and the rules that matter. - A way to verify: tests, type checks or a linter the agent must run before it says it's done.
- Durable progress: a progress note or task list plus version control, so a new session can pick up where the last stopped.
- A sandbox with sensible defaults, so mistakes stay contained.
- Permissions: which commands and files are off limits, and which actions need a person to approve.
- Readable output: logs and errors the agent can see, not just you.
- One task at a time for long jobs, with a clean, committed state at the end of each.
What to look for when choosing an AI agent
You don't need to build a harness to benefit from the idea. When comparing coding agents, browser agents or workflow tools, ask about the harness as much as the model:
- Can it check its own work? Does it run tests or look at the result, or does it just say it's finished?
- What can it touch? Are there permission settings, approvals for risky actions and a sandbox?
- Does it remember the project? Can it read project instructions and carry progress across sessions?
- Can you see what it did? Look for a clear log of commands, edits and decisions.
- Can you extend it? Support for MCP servers, custom tools and hooks lets the harness grow with your needs.
Two tools built on the same model can differ more on these points than two tools built on different models.
Limits and common misunderstandings
- It's not a replacement for a capable model. A harness makes a good model reliable; it can't make a weak model good at reasoning.
- More scaffolding isn't always better. Every rule and tool takes space in the context window. Harnesses tuned for older models can hold newer ones back, so teams prune as well as add.
- Agents grade themselves generously. An agent asked whether its own work is good will often say yes. Separate checks (tests, a second reviewer agent or a person) catch what self-review misses.
- Security still applies. Tools and browsing open the door to prompt injection. Permissions and approvals are part of the harness for a reason.
- Benchmarks measure the pair. An agent's score on a coding benchmark reflects the model and its harness, so compare like with like.
Frequently asked questions
What is harness engineering in simple terms?
It's designing the system around an AI model (its instructions, tools, memory, checks and permissions) so that an AI agent does real work reliably, and improving that system each time the agent fails.
What is an agent harness?
An agent harness is all the software around a model that turns it into an agent: it runs tools, manages context, stores progress, checks results and enforces limits.
Is harness engineering the same as prompt engineering?
No. Prompt engineering is about wording a request. Harness engineering covers the whole environment the agent runs in, including tests, tools and state across sessions. Prompts are one part of a harness.
Is Claude Code a harness?
Coding agents such as Claude Code and Codex are commonly described as harnesses: products that wrap a model with tools, context handling, permissions and project instructions.
Who uses harness engineering?
Mostly teams running AI agents on software development and other long, multi-step work. The ideas also apply to anyone setting up an agent for their own projects.
Does harness engineering have anything to do with Harness.io?
No. Harness is a software delivery company; harness engineering is a general term from AI agent development.
Summary
- An agent is a model plus a harness: everything that isn't the model.
- The harness handles instructions, tools, context, memory, sandboxing, checks and permissions.
- Harness engineering means designing those parts as one system and fixing the system, not just the output, whenever the agent fails.
- Anthropic and OpenAI both credit their harnesses (progress files, one task at a time, enforced rules, real testing) for making long-running agents work.
- When choosing an agent, judge the harness as well as the model.
Sources
- Anthropic Engineering, Effective harnesses for long-running agents (opens in a new tab) (November 2025)
- OpenAI, Harness engineering: leveraging Codex in an agent-first world (opens in a new tab) (February 2026)
- InfoQ, OpenAI introduces harness engineering (opens in a new tab) (February 2026)
- LangChain, The anatomy of an agent harness (opens in a new tab) (March 2026)
Compare AI agents on Ploba
Browse coding agents, browser agents and agent builders, and compare how they work.
Stephen Gbolagade
Software Engineer and Technical Writer at Ploba
Writes Ploba's guides to AI tools, agents and protocols, explaining how they work in plain language.
Keep learning
Plain-language explanations, technical guides and practical comparisons.
