What is an agent harness? Inside a real one

Agent = model + harness. Everyone benchmarks the first half. Here is the anatomy of the second half, drawn from an open-source system over 3,700 developers starred.

Aug 06, 2026

Hand-drawn sketchnote title card reading What is an agent harness. A terminal window labeled MODEL sits inside a larger frame labeled HARNESS, with tools, memory, and gates attached by arrows.

TL;DR

An agent harness is everything around the model: instructions, tools, memory, feedback loops, and guardrails.
Same model, different harness, different agent. The harness now explains more of the result than model choice does.
Every part below is a general pattern first. My open-source second brain is the worked example, running in public.

Ask a builder which model runs their agent and you get a fast, confident answer. Ask what harness it runs in and you often get a pause.

That pause is closing fast. Anthropic’s own docs describe Claude Code as an agentic harness. OpenAI published a post titled “Harness engineering.” One line from the discourse stuck with me: 2025 was the year of agents, 2026 is the year of agent harnesses.

So the term is everywhere. What is missing is a real one you can open and read. Definitions are cheap. Working harnesses are not.

I have been doing harness engineering for six months without calling it that. This post is the definition, the five parts every working harness has, and the one I run in public so you can check every claim.

What an agent harness actually is

An agent harness is the execution layer wrapped around a language model. It decides what the model sees, which tools it can call, what it remembers between sessions, and what it may do without asking a human.

The formula that makes it click: agent = model + harness. The model provides reasoning. The harness provides everything else. Remove the harness and you do not have an agent, you have a chat window.

Sketchnote of a visual equation: a chip labeled MODEL, plus a frame labeled HARNESS with tags for tools, memory, and rules, equals a terminal window labeled AGENT.

A harness is not a framework. A framework is where you write agent logic. A harness is the envelope your agent runs inside: state, permissions, tool access, recovery. Claude Code is a harness. Codex CLI is a harness. The layer you build on top of them is also a harness, yours.

One more boundary, because the term gets overloaded. Benchmark scaffolds like the ones behind SWE-bench are evaluation harnesses. This post is about runtime harnesses, the kind that do real work every day.

The five parts of a working harness

Strip any serious harness down and you find the same five parts. Here they are, each with the general pattern first and my public implementation second.

Sketchnote with a terminal window labeled AGENT in the center, surrounded by a scroll labeled INSTRUCTIONS, a wrench labeled TOOLS, a filing box labeled MEMORY, a circular arrow labeled FEEDBACK LOOPS, and a fence labeled GUARDRAILS.

1. Instructions. The standing orders the model loads before any task: conventions, boundaries, definitions of done. In practice this is a CLAUDE.md or AGENTS.md file. Mine is public, and I wrote up what belongs in a CLAUDE.md after watching 3,000 developers run one.

2. Tools. The actions the model can take: scripts, commands, APIs. The pattern that holds up is a small, purposeful surface. A model with 400 tools picks badly. A model with 12 sharp ones picks well.

3. Memory. What survives the session. The general pattern: durable state in plain files the agent both reads and writes, not a black-box store. In my system that is an Obsidian vault, and the retrieval side is a recall budget, not a database: four notes per prompt, abstain when unsure, fail closed.

4. Feedback loops. Deterministic checks the model must pass before its output counts: linters, tests, structure gates. The model drafts, the gate rejects, the model fixes. This is where output quality actually comes from.

5. Guardrails. What the agent may never do without a human. Permission prompts, content firewalls, hard rules like “never publish, only draft.”

None of these parts is glamorous. Together they are the difference between a demo and a system.

What harness engineering looks like in practice

Harness engineering is the discipline of building and tuning that envelope. The core principle, now showing up in research papers: code owns the control flow, the model gets called at the reasoning steps.

The post you are reading came out of a harness. A research script pulled live sources and keyword volumes. A voice linter rejected every AI-tell phrase. A structure script checked the title length, the word count, and every section against a locked checklist before the draft counted as done.

Sketchnote of a flow: a page labeled DRAFT moves through an arrow labeled check to a rubber stamp labeled GATE. A rejected page with a red X loops back with an arrow labeled fix. A passed page with a check mark exits right under an arrow labeled ships.

Notice what the model did in that pipeline: it wrote prose. Everything else was code, written once, enforced every run. When the output misses, I do not tweak a prompt and hope. I tighten a gate, and the fix holds forever.

The same principle runs my vault. Search respects supersedes chains, so an agent asking for the current decision never retrieves a confidently stale one. Scheduled agents reconcile contradictions overnight. Six months of running it taught me what to keep and what to skip from the patterns everyone quotes.

That is harness engineering: fewer heroic prompts, more boring gates that compound.

But the model is all that matters, right

The strongest counter-argument deserves a fair hearing: models improve so fast that harness work is a wrapper, obsolete by the next release.

Three things break that argument in practice.

Sketchnote comparing two identical chips labeled MODEL. The left sits in a thin cracked frame labeled BARE above a falling result-quality chart labeled demo. The right sits in a solid frame labeled HARNESS with tags for memory and gates, above a rising chart labeled system.

First, the benchmark evidence points the other way. The same model scores differently depending on the scaffold around it. If harnesses were neutral wrappers, that variance would not exist.

Second, model upgrades raise the ceiling. The harness decides how much of the ceiling you reach. A stronger model in a harness with no memory and no gates just produces confident mistakes faster.

Third, and this is the part the wrapper argument misses completely: the harness is where your context lives. Your conventions, your history, your definitions of done. No lab will ever ship that, because it is yours.

To be fair to the other side: a weak model in a great harness is still a weak agent. The harness multiplies the model, it does not replace it. But you rent the model. The harness you own.

How to start building yours

You do not need a platform or a framework migration. You need five unglamorous moves, in this order.

Write the instructions file. One page: conventions, boundaries, what done means. This alone changes agent behavior more than any prompt trick.
Give it memory in plain files. A folder of markdown the agent reads and writes beats a vector store you cannot inspect.
Add one deterministic gate. A linter, a test suite, a checklist script. Make the agent pass it before output counts.
Set the guardrails. List what the agent must never do unattended, and enforce it in code or permissions, not in hopes.
Only then automate loops. Scheduled runs, background agents, self-checks. Loops amplify whatever exists, including the flaws.

And the boundary, so this stays honest: do not build a harness for a task you run twice. A good prompt in a bare CLI is the right tool for one-off work. The harness pays off on the tasks you repeat every week, because every gate you add keeps paying.

The model in my harness will be replaced many times. The harness is the part that compounds.

Frequently asked questions

What is an agent harness?
The execution layer around a language model that turns it into an agent: instructions, tools, memory, feedback loops, and guardrails. The model reasons; the harness decides what it sees, what it can do, and what persists.

What is the difference between an agent harness and an agent framework?
A framework is where you write agent logic, like LangGraph or the OpenAI Agents SDK. A harness is the runtime envelope the agent operates inside: state, permissions, tool access, recovery. You often use both, and the harness is the layer that touches production.

Is Claude Code an agent harness?
Yes. Anthropic’s own documentation describes Claude Code as an agentic harness: the tools, context management, and execution environment that turn the model into a coding agent. Codex CLI and similar tools sit in the same category.

What is harness engineering?
The discipline of designing that envelope: choosing tools, structuring context and memory, writing deterministic gates, and setting stop conditions. Code owns the control flow; the model is called at the reasoning steps.

Do I need to build my own agent harness?
If you use an agentic CLI, you already have one, and every CLAUDE.md rule or hook you add is you engineering it. Building your own layer on top pays off once you repeat the same class of work weekly and need memory and gates the stock harness does not ship.

What is the difference between a runtime harness and an evaluation harness?
A runtime harness runs real work every day, like Claude Code or the system in this post. An evaluation harness, like a benchmark scaffold, exists to measure a model on a fixed task set. Same anatomy, different purpose.

Key takeaways

An agent is a model plus a harness. The model reasons; the harness supplies instructions, tools, memory, feedback loops, and guardrails.
A framework is where you write agent logic. A harness is the envelope the agent runs inside. Claude Code itself is a harness, and you can build yours on top.
Feedback loops are where quality comes from: deterministic gates the model must pass, written once, enforced on every run.
The “just a wrapper” argument fails because the same model performs differently in different harnesses, and because your context lives in the harness, not the model.
Build order matters: instructions file, plain-file memory, one gate, guardrails, and only then automated loops.
You rent the model. You own the harness. Only one of them compounds.

About the author

Eugeniu Ghelbur writes The AI Operator, a publication about practical AI systems. He maintains Obsidian Second Brain, an open-source system starred by over 4,000 developers on GitHub. The writing here comes from building and maintaining that public system.

Discussion about this post

Ready for more?