What is an AI agent harness? A plain explanation

You've seen the word all week. Someone says a new model is great "in the right harness." Someone else says the harness matters more than the model. And a lot of people are quietly nodding along without being sure what it means.

You're in good company. One developer posted that either Theo was being obnoxious or they didn't actually know what a harness is. Theo then wrote a whole post explaining it, and a few hours later asked if he could finally stop explaining this.

Here's the plain version, the one you could explain to a friend over lunch.

A model only writes text

Start with what an AI model actually does. You give it text. It gives you text back. That's all.

It can't open a file. It can't send an email. It can't check whether the code it wrote runs. It doesn't remember what you told it yesterday. As one builder put it, a model on its own is a one-shot text generator: prompt in, tokens out, stop.

So how does Claude Code fix a bug across ten files? How does an agent update your CRM? Something else is doing the work. That something is the harness.

The harness is everything around the model

The cleanest definition we've seen comes from Anthropic itself. In its engineering post on Managed Agents, it splits an agent into three parts:

• The harness: the loop that calls the model and routes its tool calls to the right place.
• The sandbox: where code actually runs and files get edited.
• The session: a log of everything that happened.

Think of a race car. The model is the engine. It's where the power comes from. The harness is the rest of the car: the wheels, the steering, the brakes, the dashboard. A great engine bolted to a shopping cart doesn't win races.

Here's the loop a harness runs, over and over, until the job is done:

The model never touches your files. It writes "read the Meeting notes table." The harness reads the table, hands the result back, and the model decides what to do next. Every real action happens in the harness.

What a good harness actually does

Greg Isenberg listed the basics well: a harness runs the model in a loop so it keeps working step after step, and gives it hands to read files, call tools and run code. In practice a good one does three jobs.

It gives the model hands. Tools to read and write files, search the web, call other apps.

It sets limits. What the agent may touch, how much a run may cost, how long it may take. The model can't enforce any of that on itself. Only the harness can.

It remembers. It decides what context the model sees on each step, keeps a log of every step, and records what the run changed so you can check it later.

Why the same model scores differently

This is why the argument got heated. People compare models as if the model were the whole thing. It isn't.

Y Combinator pointed out that harnesses get dismissed as just scaffolding, and gathered researchers to argue the opposite. Another builder found that their harness alone made a 13x cost difference on the same task with the same model, almost all of it from prompt caching. And when a new coding leaderboard came out this week, one reply reminded everyone that its scores are the model and the harness together, not the model anywhere.

So when someone says "model X is better," ask: better inside which harness?

Where the harness sits in Team Brain

You don't have to build a harness to use one. When you make an agent in Team Brain, the harness is the agent itself. You describe the job, and Team Brain runs the loop, gives the agent its tools, and keeps the record.

Each part of that page is a piece of the harness:

• When it runs is how the loop starts: on a schedule, when a row changes, or when an email lands.
• Connections are the hands: the apps and accounts it uses, listed where you can see them.
• Settings are the limits: a cost cap per run, a time limit, and who can change it.
• Recent runs and Versions are the memory: what each run did, and every version of the agent.

And because the model is just one setting, you can swap it without rebuilding anything. Pick Claude, GPT, Gemini or Grok, or let Auto pick per task. The harness stays the same.

That's the practical upshot of this whole debate. Pick a harness you trust, with real limits and a real record, then try models inside it. A cheaper model in a good harness often beats a better model in a bad one.

Common questions

Is a harness the same as an agent framework? Close. A framework is a kit for building a harness. The harness is the running thing: the loop, the tools, the limits.

Is Claude Code a harness? Yes. Anthropic calls the Claude Agent SDK the agent harness that powers Claude Code, offered so you can build other agents on it.

Do I need to build my own? Only if you're building a product around agents. If you want agents doing work on your docs and tables, use one that already has limits and a record built in.

Does a better harness make a bad model good? It can make a decent model much more useful. It can't make a model know things it doesn't.