What is an AI agent harness? The body around the brain

Two developers sit down with the same task: fix a gnarly bug in a mid-sized codebase. One opens Claude Code in a terminal. The other opens Cursor. Under the hood, both are talking to the same Claude model — same weights, same training, same raw intelligence, rented from the same API.

An hour later they compare notes, and the experiences were completely different. One tool explored the repository on its own, ran the failing test, read the stack trace, fixed the bug, re-ran the test, and stopped when it passed. The other needed more hand-holding — but drew beautiful inline diffs and never touched a file without showing the change first.

Developers argue endlessly about which product “has the smarter AI.” It is the wrong argument. The brain was identical. What differed was everything wrapped around the brain — which files it was shown, what it was allowed to do, how many times it could try, when it had to stop and ask.

That wrapping has a name, and it is quietly becoming the most important word in AI engineering: the harness — the same word English uses for the straps that turn a horse’s raw power into a straight furrow. The horse supplies every unit of force; the harness decides where the force goes.

The plain definition, before we get to the anatomy: an AI agent harness is the software wrapped around a language model — the orchestration loop, tools, context, memory, and guardrails that turn the model’s raw text output into useful, safe, finished work. The rest of this essay unpacks that one sentence.

A model is a brain in a jar

Strip away the mystique and a large language model is a surprisingly small thing: billions of numbers, frozen the day training ended, sitting behind an API. You send it text; it predicts the text that should follow, one token at a time; it sends that back. One call, one reply. That is the entire interface.

Everything else you may have heard lives outside this object. The model has no eyes — it cannot read your codebase, because nobody showed it the files. It has no hands — it can describe the fix but cannot run it, so it cannot know whether the fix works. It has no memory — every API call starts from zero; yesterday’s conversation is gone unless someone pastes it back in. It cannot try, fail, and try again, because there is no second attempt inside a single reply. It cannot even stop — a model has no notion of a task being done, only of a reply being finished.

And it is stateless in a deeper sense too: the same frozen weights serve you, me, and a million other people simultaneously. Nothing you tell it changes it. “Training” happened once, in a datacenter, months ago; what you are talking to is a snapshot.

A model is a brain in a jar. Astonishing reasoning, zero reach.

The harness is the rest of the body

The harness is everything wrapped around that jar to give the brain a body — ordinary software, written by ordinary engineering teams, that decides what the model perceives, what it can touch, how it iterates, and where it must stop. When people say “AI can now ship features end to end,” the capability they are marveling at lives mostly in the body, not the jar.

The mapping is almost one-to-one, so let’s walk the body part by part.

The senses: context

Context is everything the model is allowed to perceive on this call: the task, the relevant files, the documentation, the error message it just caused. The model cannot look around — it sees exactly what the harness shows it, nothing more.

This is where harnesses most visibly beat each other. Send the whole repository and the model drowns in noise; send too little and it hallucinates file names. Good harnesses search, rank, and trim — they aim the eyes.

The hands: tools

Tools are how thinking touches the world: edit a file, run a command, query an API, open a browser. Mechanically it’s simple — the model replies “I want to run the test suite,” and the harness actually executes that in a real shell and reports back what happened.

The hands define the agent’s reach. A harness with read-only tools can advise; one with a shell and a git branch can build. Choosing which hands to give it — and which to withhold — is a design decision, not a technical limit.

The spine: the orchestration loop

The spine is what turns one reply into a session of work. Watch it in slow motion on “fix the failing test”:

1. Think. The harness packages task + context + available tools, calls the model. The model replies with an intention: run the tests.
2. Act. The harness executes it.
3. Observe. The output — FAIL: expected 200, got 404 — is fed back into context. The brain now perceives the consequence of its own action.
4. Repeat. Think again, with new information: open the router file. Act. Observe. Edit line 41. Act. Observe. Re-run. PASS.
5. Exit. The stopping condition is met — tests green — and the loop ends.

Every step is ordinary software — a while-loop, some parsing, some plumbing — and none of it is intelligent. But stack it around a model and something qualitative changes: a text generator becomes a worker. One model call is a reply. A loop with an exit condition is an agent.

The reflexes: guardrails

An agent that can execute commands can execute rm -rf. An agent that can call APIs can call them 40,000 times. The same loop that fixes your test can, with equal enthusiasm, walk off a cliff — and a model is always confident, especially when wrong.

Guardrails assume failure will happen and make it survivable, the way reflexes fire before conscious thought:

• Permission gates. The agent proposes; a human disposes. Nothing consequential happens without a sign-off.
• Sandboxes. Actions run inside a container or a git branch, where the blast radius is a workspace, not production.
• Hard limits. Maximum iterations, maximum tokens, maximum spend — enforced unconditionally, before thought.
• Audit trails. Every action logged, so “why did it do that?” always has an answer.

The counterintuitive part, learned the expensive way: guardrails are not the tax you pay to deploy AI — they are what lets you deploy it. An agent that is 95% right and 100% autonomous is unshippable, because the 5% lands in production with nobody’s name on it. Add the reflexes and the failure mode changes from “silent wrong action” to “wrong draft in a review queue.” A safety harness doesn’t make the climber cautious; it makes him bold, safely. (The reflex, it turns out, can even be a product: I decoded TypeSafe’s Jev, a model that returns only typed decisions — essentially this organ, sold as a service.)

The long-term memory: what survives the session

The model forgets everything between calls, so remembering is the harness’s job: project conventions, past decisions, the gotcha that burned you last month — written down, stored, and re-fed into context when relevant. It is the difference between a brilliant contractor on day one, every day, and a colleague on year two.

Model, harness, agent — three words, constantly blurred

The vocabulary in AI is a mess, and “harness” gets mixed into it. The cleanest separation I know:

	Model	Harness	Agent
What it is	A neural network behind an API	Software wrapped around model calls	The two combined, running
Analogy	Brain	Body	The complete human, at work
Can it act alone?	No — text in, text out	No — machinery with nothing to think	Yes — that’s the definition
Who builds it	A handful of labs	Any engineering team	You, by combining the two
How it improves	Retraining, billions of dollars	Ordinary iteration, one commit at a time	Either side improving
Your relationship	Rented by the token	Owned — your IP	Operated

The punchline sits in the middle column: an agent is not a smarter model. Agent = model + harness, running. When a product feels magically capable, instinct says “they must have a better model.” Usually they don’t. They have the same three or four frontier models everyone else rents — and a better body around them.

A few neighboring terms, since they cause most of the confusion:

• Wrapper. A thin UI over one model call — question in, answer out. No loop, no tools, no state. The insult “GPT wrapper” exists precisely because a wrapper has no harness engineering in it.
• Framework. LangChain, LangGraph, the OpenAI Agents SDK, the Claude Agent SDK — these are not harnesses; they are kits for building harnesses. Buying a toolbox is not owning a house.
• Orchestrator. Legitimate term, but it usually names one organ — the loop and scheduling logic — not the whole body of tools, context, memory, and guardrails.
• Scaffolding. Research-paper synonym for harness (“agent scaffolding”). Same idea; “harness” is winning in industry usage.
• Prompt engineering. Wordsmithing the instruction inside one model call. A harness decides which prompts get sent, what context rides along, and what happens with the reply. Prompt engineering is a sentence; harness engineering is the conversation.

Inside a real one: our agentic OS at Anatta

Theory is cheap, so let me open up the machinery I know from the inside. At Anatta, client delivery runs on the agentic OS I wrote about earlier — and the first thing to understand about it is that it is not one harness. It is a cluster of harnesses that interact with one another. Microservices, but of harnesses: each has its own senses, hands, spine, and reflexes, and the handoffs between them are the joints of the system.

Take one member of the cluster — the team chat harness. It lives inside each client team’s chat and behaves like the team’s best employee: always present, always briefed, and able to go from a conversation to finished work. Walk through its anatomy:

Senses. Who is talking changes everything it perceives. Every client team has an environment — everything that belongs to that team: its repositories, its documents, its past decisions, its running work. When a message arrives, the harness senses that team’s environment and no other. Same brain for every team; different eyes depending on who speaks. That is context doing its job.

Hands. It doesn’t just answer. It can turn the conversation into a PRD — a proper project requirement document, not a summary. And it can reach into the team’s repositories and write the code itself, on the team’s actual codebase.

Spine. Its loop is conversational. A message arrives; the harness interprets it, decides what it amounts to, does the work — drafts the PRD, makes the change — reports back into the chat, and exits: back to waiting for the next message. The stopping condition isn’t a test going green; it’s the conversation being served.

Reflexes. Underneath sits what we call our skill infra — pre-encoded action patterns. When a message matches a shape the harness has a skill for, it doesn’t reason from first principles about what to do; it recognizes and jumps straight into action, the way a trained hand moves before conscious thought. Reflexes come in two kinds, and the harness has both: trained ones that fire into action (the skills) and protective ones that fire against it — because the house rule still stands above everything: no approval, no action.

And the brain is rented — even swapped mid-flight. The chat harness owns no model; it borrows whichever frontier brain fits. The swap happens in two ways. The slow way: when a better model ships, we change the default, and the whole cluster inherits the upgrade without surgery. The fast way: the harness picks the brain itself, per conversation — based on who it is talking to, what the request demands, and a few other signals, it will quietly reach for a different model. The body doesn’t just tolerate brain swaps; it performs them.

That last point is the observation that motivated this whole essay: the models kept changing underneath us and the system barely noticed. What makes it better every single week is harness work — sharper skills, richer team environments, cleaner handoffs between the harnesses. Ordinary commits, compounding.

You don’t always have to build one

Building a harness makes sense when the workflow is your business, as delivery is ours. For everything else, use a ready-made one — it is also the fastest way to make this essay concrete, because you can watch the anatomy work:

• Claude Code — Anthropic’s terminal harness, and the one I live in daily. Context management, tools, permission gates, memory files: the full body, visible in action.
• Codex CLI — OpenAI’s equivalent, same species.
• OpenCode, Aider, OpenHands, Goose, Cline — open-source harnesses, and the fastest education available: read their source and you are reading harness anatomy in code.

And between using and building sits a middle path: harness SDKs, where a vendor ships the skeleton — loop, tool plumbing, state — and you bolt on your own senses, hands, and reflexes. Anthropic’s Claude Agent SDK is literally Claude Code’s machinery offered as a library. OpenAI has its Agents SDK. Cloudflare’s Agents SDK runs stateful, long-lived agents on Workers at the edge — the harness as infrastructure, with persistence and scheduling handled for you. Vercel’s AI SDK and LangGraph play the same role. A rule of thumb: use a ready harness for general work, reach for an SDK when your domain demands custom organs, and build from scratch only when the harness itself is the product.

Harness engineering is the new software engineering

For fifteen years my job was building static software. You gathered requirements, encoded the logic by hand, and shipped a thing that does exactly — and only — what it was told: a website, a checkout flow, a dashboard. All the intelligence lived in the engineer; the software was just the frozen record of it.

That era is closing. Software engineers don’t really build websites anymore — we build the thing that is itself the application of AI: the body around a rented brain. The deliverable is no longer the logic; the deliverable is the harness that lets a mind produce the logic, safely, on demand, forever.

The investor in me adds the economic reason this is where the profession moves. Frontier models leapfrog each other every quarter; whatever model advantage a product has today evaporates by the next release. The harness doesn’t evaporate. It accumulates your domain’s edge cases, your failure playbooks, your taste — one commit at a time, in software you own outright. Models are rented, harnesses are owned. Rented things get better without you; owned things get better because of you — and when the next benchmark-topping brain arrives, a real harness swaps it in over a weekend and inherits the upgrade for free. The body doesn’t care whose brain is in the jar.

The future of software engineering is not writing what the machine should do. It is building the body that lets a mind do it.

The AI gold rush keeps staring at the horses. Watch the harness makers.