What Is a Harness in AI Agents?
A harness is the software layer that turns a language model into an agent. The model only produces text. The harness runs the tool the model asks for, hands the result back, decides what gets remembered, and sets when to stop. Short formula: agent = model + harness. The word itself means the straps on a draft animal, which is a fair picture: the horse supplies the power, the harness is what lets it pull the cart.
Coding tools such as Claude Code, Codex CLI and Cursor are harnesses. Run the same model inside a different harness and the agent behaves noticeably differently. That is the usual answer to “why does one agent finish the job and the other stop halfway on the same model?”
What a harness does
- It runs the loop. The model answers and asks for a tool; the harness runs the tool, returns the result, and the model thinks again. The harness also decides when the loop ends and when work is handed to a sub-agent.
- It connects and limits tools. File reads, shell commands, web search, database queries. Which tool is open at which moment, and with what permission, is the harness’s call. Asking a human to approve a risky step belongs here too.
- It manages context. On a long task the output of every step accumulates and the context window fills. The harness decides what is kept, summarised, or dropped.
- It catches errors. A model can invent a tool name or return the wrong format. The harness catches that and gives the model a chance to correct it.
Harness vs prompt vs framework
| Term | What it does |
|---|---|
| Prompt | Tells the model what to do. |
| Harness | Determines what the model can reach, what happens on failure, and when the work ends. |
| Framework | Gives you building blocks for agents (tool definitions, memory patterns); you still assemble the running system. |
A harness is often built on top of a framework, and the terms blur. The practical difference: in a ready-made harness, decisions such as planning, file access and context handling come already made.
What a harness changes: Anthropic’s example
In March 2026 Anthropic’s engineering team published a harness design for long-running application development (Harness design for long-running application development). It names these problems for a single agent on a long task:
- Losing coherence: as the context fills, the model drifts on a long task.
- Context anxiety: some models start wrapping up early when they think they are near their context limit.
- Praising its own work: a model grading its own output tends to be generous, especially on subjective work like design.
- Superficial QA: a model acting as QA finds real problems, then talks itself out of them and approves anyway.
The remedy is not a different model but a different apparatus: split planning, building and evaluation across separate agents; make the evaluator actually test the running application; and, where needed, reset the context and continue with a fresh agent from a structured hand-off note. According to the same post, context resets were essential with one model and largely unnecessary with a newer one. So which parts of a harness you need also depends on the model you use.
Who supplies the harness
The difference is who writes the apparatus and where the code runs:
| Approach | Who writes the harness | Where it runs |
|---|---|---|
| Hand-written loop | You | Your infrastructure |
| The SDK’s tool runner | The library | Your infrastructure |
| Claude Agent SDK | The library (with built-in tools) | Your infrastructure |
| Managed agents | The provider | The provider’s infrastructure |
A library supplying a harness does not mean it also hosts it; in the first three, the servers are still yours.
When to write your own harness
In its simplest form a harness is the loop “call the model, run the tool it asks for, return the result”. The hard part is everything around it: context overflow, resuming interrupted work, permissions, error logs.
- Don’t write one if the job is a single model call, or a fixed workflow whose steps are known in advance. A harness is overkill there.
- Use a ready-made one if the agent needs to read files, run commands, or sustain a long task. That covers most jobs.
- Write your own if you need custom approval steps, sub-agents running in a particular order, or a constraint such as data not leaving your own servers.
When an agent project isn’t delivering, the first instinct is a stronger model. Check this first: is the task too long for one context, are the tools broader than needed, is there a separate step that reviews the output? Multi-agent systems exist for exactly this reason. I described the setup I use in my agentic stack.
What to ask when you receive an agent proposal
If someone proposes to “build you an AI agent”, these questions expose the harness:
- Who reviews the output: the same model or a separate step?
- Which tools does the agent reach, and at which step is human approval required?
- When does it stop? What happens if it gets stuck or hits an error?
- How is context managed on a long task?
A proposal that answers none of these and only names the model is incomplete.
Frequently Asked Questions
Is the harness the same as the model?
No. The model reasons; the harness turns that reasoning into action: it runs tools, stores state, and enforces rules.
What is the difference between a harness and a prompt?
A prompt tells the model what to do. A harness governs what it can do, what happens on failure, and when the work ends. A good prompt won’t rescue a poor harness.
Is a harness the same as a framework?
Close, but not the same. A framework gives you components for building agents; a harness is the running apparatus with most decisions already made. In practice they overlap.
Does the model know it is inside a harness?
Not explicitly; it only sees what is in its context. That is why, when an agent behaves unexpectedly, you often look for the cause in the harness rather than the model.
How does it relate to RAG?
Different layers. RAG is about getting the right information to the model; the harness is about managing what the model does with it.