An agent harness is everything in an AI agent that is not the model: the loop that calls it, the tools and how they are described, the code that assembles and trims the context, memory, permissions, sandboxing, sub-agents and logging. The model supplies the reasoning. The harness decides what the model sees, what it may do and what happens when a step fails, which is why two products built on the same model can behave so differently.
What is an agent harness?
A language model takes text in and gives text out. It cannot read a file, call an API or remember yesterday. An agent can do those things because software around the model does them on its behalf, and that software is the harness.
The term has settled over the past year. Anthropic’s documentation for Claude Code describes the product as the layer around the model that provides the tools and manages the context, and says that this surrounding layer is what the term agentic harness refers to. LangChain presents its Deep Agents library as an agent harness too. Engineers will recognise the word from testing, where a test harness is the rig that holds a component, feeds it inputs and records what it does. The meaning carries over.
Two clarifications. A harness is not a framework. A framework is a kit of parts for building agents, and a harness is the running system, with its decisions made. We compare the kits in LangChain and the alternatives. And the word is used at two levels. Products such as coding agents contain a harness built by their makers. Teams then add an outer layer of their own: rules files, tests and checks that the agent’s work must pass. This article is mostly about the first, though the same reasoning applies to both.
What does a harness contain?
| Part | What it does | What goes wrong without it |
|---|---|---|
| The loop | Calls the model, runs the tools it requests, returns results, decides when to stop | Runs that never end, or that give up at the first error |
| Tools and descriptions | Define what the agent can do and how each action is explained to the model | The wrong tool is chosen, or the right one is called badly |
| Context assembly and compaction | Builds each request and shrinks history when it grows | Important details crowded out or summarised away |
| Memory | Keeps notes and facts beyond one context window | Every session starts from nothing |
| Permissions and approval | Decide which actions run freely, which need a person and which are refused | An agent that can do anything its tools allow |
| Sandbox | Confines where code runs and what it can reach | One bad command touches real systems |
| Sub-agents | Give a piece of work to a separate model call with a clean context | One context polluted by every side task |
| Logging and tracing | Record every call, tool result and decision | Failures that nobody can explain |
Some of these deserve a paragraph.
The loop
The loop is short to write and holds more policy than it appears to. It decides how many steps a run may take, what to do when a tool fails, whether tool calls run in parallel, and when the task counts as finished. The last point matters most. Models tend to declare success early, and a loop that accepts the model’s word produces confident, incomplete work.
Tools and how they are described
The model never sees your API. It sees a name, a description and a parameter schema, and chooses from those. Two harnesses can wrap the same system and get different behaviour because one describes a tool in a line and the other explains when to use it, what it returns and what its errors mean. Many tools now arrive through the Model Context Protocol, and the harness still decides which are loaded and how results are trimmed.
Context and memory
Before every call the harness builds the request: instructions, tool definitions, history, retrieved material and memory. When history grows too long it compacts it, and what the summary keeps or drops shapes everything after. This is context engineering carried out by code. Memory is the part that outlives the window, and we explain it in AI agent memory explained.
Permissions, approval and the sandbox
A prompt can ask the model to be careful. Only the harness can stop it. Permission rules decide which tool calls run without asking, which wait for a person and which are refused. The sandbox limits what a permitted command can reach on the filesystem and the network. Because these are enforced in code, they hold even when the model has been misled by something it read, which is the subject of guardrails for AI agents.
Sub-agents and tracing
Sub-agents keep side work out of the main context, at the price of more tokens. When they help is covered in multi-agent systems. Tracing is what lets you answer why a run did what it did, and it belongs with the rest of your monitoring and LLMOps.
Why do two products with the same model behave so differently?
Imagine an operations team that tries one model in two harnesses on the same job: reconcile 200 supplier invoices against purchase orders and list the mismatches.
The first harness is a bare loop with a database tool. It works well for the first thirty invoices. Around the sixtieth, the context is full of earlier query results, the harness truncates the oldest messages, and the instruction to flag currency differences goes with them. The run finishes and reports success. Some of the mismatches are missing, and nothing in the output says so.
The second harness keeps a task file listing every invoice and its status. It clears old tool results once they have been used and re-reads the task file after each compaction. It runs each batch in a sub-agent that returns only its findings, and it will not accept ‘done’ until every row in the file has a status. Same model, same data, a different outcome.
Published evidence points the same way. Anthropic’s engineers wrote up an attempt to have a model build a web application across many sessions. A capable model in a loop with compaction was not enough. What changed the result was the harness: a first session that set up a feature list and a progress file, and later sessions that each completed one feature and left notes for the next. Their account, effective harnesses for long-running agents, is worth reading in full.
A second study from the same company shows how sensitive results are to the surroundings. Holding the model and the harness fixed, and changing only the resources given to the container, moved a coding benchmark score by six percentage points. In our experience the loop, the tools and the compaction policy matter at least as much. It is one reason to distrust a claim that one product beats another ‘because of the model’.
What do the SDKs and open-source projects provide?
You rarely need to write all of this. The position at the time of writing, from each project’s documentation:
- The Claude Agent SDK packages the loop, tools and context management behind Claude Code as a Python and TypeScript library, with built-in file, shell and web tools, hooks, sub-agents, MCP, permissions and sessions. Anthropic also offers a hosted version, Managed Agents, in beta.
- The OpenAI Agents SDK provides agents, handoffs, guardrails, sessions, human-in-the-loop controls, MCP support, sandboxed agents and built-in tracing.
- Google’s Agent Development Kit covers Python, TypeScript, Go, Java and Kotlin, with sessions, state and memory, context compaction, evaluation tools and graph workflows.
- Among open-source projects, Deep Agents bundles a virtual filesystem, sub-agents, summarisation and approval pauses on chosen tools. Several agents publish their code under open licences, including OpenAI’s Codex CLI, Google’s Gemini CLI, OpenCode and goose, so you can read how a production harness is put together.
They differ in how much is decided for you. A provider’s SDK gives you a harness tuned for that provider’s models, with opinions built in. An open-source project gives you the same and lets you read and change it. A framework gives you parts and leaves the opinions to you.
Our view: adopt a packaged harness when the work looks like what it was built for, which today mostly means agents that read files, run commands and write code or documents. For a narrow business agent with five tools and strict rules, a small harness of your own is often easier to reason about and to audit. How to build one is the subject of designing an agent harness.
How do you judge a harness?
Whether you are choosing a product, picking an SDK or reviewing your own code, the same questions apply.
- Can you see the exact request sent to the model at every step, with nothing hidden?
- What happens when the context fills up, and what is guaranteed to survive?
- How many tools are loaded, how are they described, and how large are their results?
- Which actions run without approval, and is that enforced in code or requested in a prompt?
- Where does code execute, and what can it reach on the filesystem and the network?
- What stops a run: limits on steps, tokens, time and spend?
- If a tool fails or the process dies halfway, can the run resume without repeating actions?
- Does it check its own work before reporting success, and against what?
- Can you replay a failed run from its trace?
- What breaks if you change the model?
The last question is underrated. Harnesses are tuned to particular models: prompts, tool formats and compaction thresholds are all adjusted against one model’s habits. A harness that claims to work equally well with any model has usually been tuned for none.
Then test it on your own work. Twenty real tasks, run several times each and scored on outcomes, will tell you more than a public leaderboard, for the reasons in how to evaluate AI agents. Agent leaderboards such as Terminal-Bench report a model and an agent together, on someone else’s tasks.
How to start
If you already run an agent, you already have a harness, even if it is eighty lines in one file. In the first week, write down what it does under each of the eight headings in the table above, and mark the ones where the answer is ‘nothing’. Permissions, stop limits and tracing are the usual gaps.
Then capture one complete run and read it from start to finish: every request, every tool result, every decision. It is the fastest way to find out what your harness is really doing.
The first decision is whether to adopt or to build, and it should follow from the work, not from the model you happen to prefer. What it takes to run the result reliably is in AI agents in production. If you want a harness reviewed, or built around your own tools, that is the core of the AI agent work we do at WeStack AI.