What Is an Agent Harness? (And When to Build Your Own)

An agent harness is the software around a language model that turns it into an agent. The model produces text. The harness decides what that text is allowed to do.

If you have used Claude Code, Codex or Cursor, you have used a harness. The model underneath is only part of what you were using. The rest was the harness.

A quick note on the name: this has nothing to do with Harness, the CI/CD company. Here, "harness" means the same thing as a test harness or a climbing harness. It is the structure that holds the thing you care about and lets it do useful work safely.

---

The short version

Agent = model + harness.

The model is the reasoning. The harness is the loop, the tool wiring, the instructions, the permissions and the memory that make that reasoning useful on a real task, with real files and real systems.

Two products can use the same model and feel completely different. The difference is almost always the harness.

---

What is inside a harness

Most harnesses, whatever they are called, contain the same handful of parts.

• The run loop. The model proposes an action, the harness runs it, feeds the result back, and repeats until the task is done or it gives up. Deciding when to stop is part of the loop.
• The tool layer. The list of things the agent can do (read a file, run a command, call an API) and the code that actually does them. The model only ever asks. The harness acts.
• The instructions. The system prompt and any rules files. This is where the agent's defaults and personality live: how verbose it is, what it assumes about you, what it should never do.
• Context management. Deciding what the model sees on each turn. Files, earlier messages and tool results all compete for a limited window, and something has to choose.
• Permissions and guardrails. What the agent can do on its own, what needs a human to approve, and what is blocked outright.
• Memory and session state. What carries over between turns, and between sessions.

None of these is exotic. Together they are most of what determines whether an agent is pleasant or painful to work with.

---

Harness, framework, SDK: what is the difference?

The terms blur, so here is how I use them.

A harness is a working agent setup you can run: a loop, tools, instructions and permissions, assembled for some purpose. Claude Code is a harness. So is whatever you build for yourself.

An SDK or framework is the toolkit you build a harness from. It gives you the loop and the plumbing so you do not start from nothing. My own harness is built on the PI SDK.

The model is a third thing again. You can usually swap it without changing the harness, and you can run different harnesses on the same model.

---

Why the harness matters

When an agent does something annoying, the model is usually not the cause. Look at the usual complaints:

• It asks permission for things you would happily delegate.
• It reaches for a tool you never wanted used.
• It forgets a rule you gave it twenty minutes ago.
• It is far too wordy when you only wanted the change.

Every one of those is a harness decision: the permission layer, the tool list, the context handling, the instructions. A better model does not fix them. Changing the harness does.

It is also where safety lives. If an agent reads untrusted text, such as an email, a PDF or a web page, the harness is what decides whether anything in that text can trigger an action. That is a design problem in the layer around the model, not something you can solve with a better-worded prompt.

---

Generic harness or your own?

Start with a generic one. Claude Code, Codex and Cursor are good, they improve constantly, and they cost you no build time. For most people, most of the time, that is the right answer.

Building your own starts to make sense when the friction compounds. Signs that you are there:

• You keep re-explaining the same context. The same codebase shape, the same house rules, every session.
• You use agents across several different jobs. Code, writing, deployment and operations each want different defaults, and one harness cannot hold all of them well.
• You need specific permission boundaries. Some actions must always be approved. Others must never be possible.
• The agent needs to act inside your own systems. Your tools are your own APIs and data, and you want the agent shaped around them.
• You need to see what it did. Logs, audit trails and replays that the generic tool does not give you.

If none of those sound familiar, you probably do not need to build one.

---

If you do build one

It is smaller than it sounds. A first version needs four things:

1. A run loop.
2. A way to load instructions.
3. A tool registry.
4. A session store.

The interesting work is not the framework. It is the profiles: bundles of instructions, tools and defaults that turn the same loop into a different agent for a different job. Keep the number small. A handful of focused profiles beats a directory of half-maintained ones.

I wrote up my own attempt, including the two profiles I built first, in Building My Own Agent Harness.

---

Deciding for a team

For a team the question changes. It is less "what do I prefer" and more "where is our agent setup holding us back, and is it worth owning?" That depends on what you want agents to do, what they can safely touch, and who maintains the result.

If you are weighing that up, the AI Readiness Checklist is a quick way to see where you stand. If you would rather talk it through, that is what my services are for.