Sheet W-06 / Writing · AI agents

What is an agent harness, and why does your agent need one?

An agent harness is everything around the model: the loop that runs it, the tools it can call, how its context and memory are managed, the guardrails it runs inside, and the checks on its work. Here is why the afternoon demo breaks in production, and what to build instead.

BastiaanPublished Updated 7 min read, 1,729 words
FIG. 01 The Maison Carrée, Nîmes, photographed as delivered on the left of the section line, and the same building drawn inside its scaffold on the right: the model, and the model with its harness. Photograph Conceptuel, Wikimedia Commons, CC0 (public domain).
In short
  • The model is a function: text in, text out. Everything that makes it an agent, the loop, the tools, the state and the limits, lives in the agent harness.
  • Most production failures are harness failures: context that fills up, tools that fail quietly, nobody checking the work, no memory between runs, nothing that bounds a run.
  • A longer prompt or the next model does not replace a missing harness. A prompt instructs; a harness enforces.
  • Build eight components, weighted to how long the task runs, and keep removing parts as models improve.

I keep having the same conversation. A team shows me an agent that worked in a demo last month: it read a ticket, looked up the customer, drafted the reply. Impressive, in the demo. Then they let it run unattended. It drifted on long tasks, called a tool that failed and carried on as if nothing happened, approved its own output, and afterwards nobody could tell me what it had done or what it had cost.

The model was not the problem. The agent harness was missing. In most of these conversations nobody had heard the term, which is why I wrote this.

01 / Definition

What is an agent harness?

An agent harness is the code, configuration and execution logic that wraps a language model so it can finish work. It is the loop that calls the model, the tools the model can use, the way its context and memory are managed, the guardrails it runs inside, and the checks on its output. The model produces text. The harness turns that text into an agent.

Simon Willison defines an agent as a model that runs tools in a loop to achieve a goal. Strike the model from that sentence and what remains, the loop, the tools and the goal, is all harness. Addy Osmani puts it as an equation he borrowed from Viv Trivedy: agent = model + harness. If you are not the model, you are the harness.

Nobody outside the labs trains the model. Everyone who ships an agent builds a harness, whether they call it that or not. Claude Code, Codex and the agent SDKs are harnesses with a model inside: a loop, a tool set, context compaction, permission gates, hooks. When you wire a model to your CRM with a system prompt and a while loop, that is a harness too. Just a thin one, and in my experience the thin ones are where the trouble starts.

02 / Root cause

Why does the agent break in production?

A demo exercises one happy path, once, with a person watching. Production is a thousand runs with nobody watching. Everything that goes wrong is outside the model:

  1. The context fills up. Long tasks accumulate tool output until the model loses the thread. In Anthropic's experiments with long-running agents, some models also started wrapping up early as they approached what they thought was the end of their context.
  2. Tools fail quietly. A timeout or an empty result comes back as text. Without a contract that makes failure visible, the model narrates around it and keeps going.
  3. Nobody checks the work. Anthropic found that agents reliably skew positive when grading their own output. Ask the model whether the task is done and it says yes.
  4. Nothing is remembered. Each run rediscovers the same facts about your systems, your data and your rules. Sometimes it rediscovers them wrong.
  5. Nothing bounds it. No permission gate before an irreversible action, no budget that stops a run, no trace to read afterwards.

Why it breaks: each of these is a limit of the model that the demo never reached. The harness is where those limits get handled. Without one, they get handled by luck.

03 / The workaround

Why a longer prompt is not a harness

The usual response is to add a paragraph to the prompt for every failure you see. Check the tool result. Do not approve your own work. Stop after ten steps. The prompt grows, behaviour improves for a week, and then the next model version arrives and half the instructions fight it. I have done this myself. It never holds for long.

The second response is to wait for the next model. It will arrive, and it will be better, and the agent will still have no trace, no budget and no gate in front of the delete button.

HumanLayer's framing is blunt: most agent failures are not a model problem but a configuration problem. Prompts are instructions; the harness is enforcement. A line in the prompt asking the agent not to drop a table is a request. A hook that blocks the command is a guarantee.

04 / The fix

The eight components of an agent harness

Eight components. Not every agent needs all eight at full weight, but every production agent needs a decision on each.

  1. The loop and its state. One place that calls the model, executes tool calls, appends the results and decides when to stop. State lives in files or a store, not only in the conversation, so a run can be resumed, inspected or handed over.
  2. Tools with contracts. Typed inputs, explicit errors, idempotent where possible. A failed call returns a failure the loop can see, not a sentence the model can talk past.
  3. Context management. Decide what enters the window. Offload large tool outputs to files, compact history, or reset to a fresh context with a structured handoff. Anthropic found context resets essential for one model generation and unnecessary for the next: keep the mechanism, retest the setting.
  4. Memory. What survives the run: project instructions reloaded each session, a notes file the agent maintains, retrieval over your documents.
  5. Guardrails and permissions. Allow-lists for commands and network, a permission gate before irreversible actions, a sandbox. Enforced in code, not requested in the prompt.
  6. Verification. Tests, type checks and schema validation for what can be checked mechanically. For subjective work, a separate evaluator tuned to be sceptical. Anthropic found the evaluator earns its cost on tasks beyond what the model does reliably alone, and not before.
  7. Observability and cost. Every run leaves a trace: steps, tool calls, tokens, euros. A ceiling that stops the run when it is exceeded.
  8. Human hand-off. A defined point where the agent stops and a person decides, with the state that person needs in front of them.

The effect: the agent becomes a system you can run, inspect and improve, rather than a prompt you hope holds. When a run fails, the trace says where. When a model improves, you remove a component and retest.

05 / Proportion

How much harness does the task need?

Weight the harness to the horizon of the task. A classifier that runs for a second needs a schema check and a retry. An agent that migrates a pipeline over an afternoon needs most of the list.

Task horizon Example Harness weight
Seconds, one call Classify an email, extract fields from a document Loop with schema validation and retries. No memory, no evaluator.
Minutes, a few tools Answer a support question from the knowledge base and the CRM Tools with contracts, a permission gate on writes, a trace per run, a hand-off path.
Hours, many steps Migrate a data pipeline, build and test a feature State in files, context resets or compaction, a separate evaluator, a cost ceiling, hand-off points.

Anthropic's own numbers make the trade-off concrete. In their experiment a solo run took 20 minutes and cost $9, and its central feature did not work. The full harness took 6 hours and $200 and produced a working result. The harness is not free, and it is not always worth it. Match it to the horizon.

06 / Principle

Build the harness for the model you have

Each harness component encodes an assumption about what the model cannot yet do reliably. That is the point of it, and also its expiry date. Anthropic dropped context resets between one model generation and the next, and later removed their sprint construct altogether, because the assumptions behind them stopped being true.

So build the harness for the model you have, run it unattended on real cases, read the traces, and keep removing parts as the model improves. That is most of what harness engineering is: retesting assumptions, not accumulating instructions.

07 / Questions

Frequently asked questions about agent harnesses

Is an agent harness the same as an agent framework?

No. A framework such as LangGraph, the OpenAI Agents SDK or the Claude Agent SDK gives you building blocks for a harness: a loop, tool calling, state. The harness is the specific assembly for your task: which tools, which guardrails, what gets verified, when a person steps in. You can build a harness without a framework, and a framework without the rest is still a demo.

What is harness engineering?

Harness engineering is the work of designing and maintaining that assembly: choosing the components, running the agent unattended, reading the traces and removing what the model no longer needs. The term grew up around coding agents, but the practice applies to any agent that runs without a person watching.

Do I still need a harness if I use Claude Code or a hosted agent product?

You are already using one. Claude Code, Codex and similar products are harnesses with a model inside: a loop, a tool set, context compaction, permission gates and hooks. The question is whether their harness fits your task, and what you add around it: your tools, your guardrails, your checks, your trace.

Is harness engineering the same as prompt engineering?

No. A prompt instructs the model; the harness enforces. A line in the prompt asking the agent not to delete data is a request. A hook that blocks the command is a guarantee. Good agents need both, but only one of them holds when the model changes.

How do I know which harness components my agent needs?

Start from the failures. Run the agent unattended on real cases, read the traces, and add the component that would have caught each failure: a contract for the tool that failed quietly, a verifier for the output that was wrong, a ceiling for the run that did not stop, a hand-off for the decision a person should have made.

What does datalyft build?

We design, build and run AI agents for business workflows and treat the harness as the deliverable: the tools, guardrails, evaluation and traces, built in your environment and handed over to your team with the documentation to run it.

08 / References

References

  1. Anthropic Engineering, Harness design for long-running application development, Prithvi Rajasekaran, 24 March 2026 www.anthropic.com
  2. Addy Osmani, Agent harness engineering, addyosmani.com, 19 April 2026 addyosmani.com
  3. Simon Willison, Designing agentic loops, 30 September 2025 simonwillison.net
  4. HumanLayer, Skill issue: harness engineering for coding agents, 12 March 2026 www.humanlayer.dev
  5. Birgitta Böckeler, Harness engineering for coding agent users, martinfowler.com, 2 April 2026 martinfowler.com
  6. Anthropic Engineering, Building effective agents, December 2024 www.anthropic.com
Sec. 02 / Start

Building an agent, or rebuilding one that stalled?

A 30-minute conversation about your use case: where the harness is thin, what is possible, and what a sensible first step looks like. No obligation.