Understanding the Agent Harness, From Scratch
Let me start with a fact that surprises most people learning about AI: a language model, on its own, cannot actually do anything.
It can’t open a file. It can’t run your code. It can’t search the web, check a result, or click a button. A raw model does exactly one thing, and only one thing: you give it text, and it gives you text back. That’s the whole of it. It’s astonishingly good at that one thing, good enough to write essays, explain ideas, and reason through problems, but it is still just text in, text out.
So here’s the puzzle. If a model can only read and write text, how do “AI agents” fix bugs, book flights, run commands, and get real work done? Something else must be doing the actual doing. That something has a name, and it’s the piece almost nobody explains clearly: the harness.
This post is a from-scratch walkthrough of exactly what a harness is and how it works. You only need basic AI knowledge to follow along. By the end, the whole thing will feel obvious, and you’ll understand the machine that turns a text-predictor into an agent that acts.
The one thing a model can do
First, let’s really sit with the limitation, because the harness exists entirely to work around it.
The brain-in-a-jar picture
Here’s the mental image that makes everything click. Picture the model as a brain in a jar: brilliant, full of knowledge, able to think and reason, but with no eyes, no hands, no way to touch the world. It can decide “I should open that door,” but it has no arm to reach out and turn the handle.
The harness is the body you build around that brain. It’s the eyes that show the brain what’s happening, and the hands that carry out what the brain decides. The brain thinks; the body acts. Neither is useful alone. Together, they get things done.
The model (the brain)
Thinks, reasons, decides what should happen next. But it can only express that decision as text. It has no way to actually carry it out.
The harness (the body)
Reads the brain's decision, actually performs it in the real world, a file gets read, code gets run, then reports back what happened.
So what is a harness, in one line?
A harness is a loop of software that runs around the model, letting it take actions and see the results, over and over, until a task is done.
That word loop is the heart of it. The harness doesn’t call the model just once. It calls it, does what the model asked, shows the model the result, and calls it again with that new information. Round and round. Let me show you exactly what happens in one trip around that loop.
The loop, step by step
Here is the entire machine, in six steps. Read it once and you’ll understand more about agents than most people do.
The key decision: is it an answer, or an action?
Step 3 is the clever pivot of the whole loop, so let’s zoom into it. Every time the model replies, the harness has to decide one thing: did the model just give a final answer, or is it asking to use a tool?
Watch it work: fixing a broken test
Abstract steps are easier to believe once you see them play out. Say you ask an agent: “my Python test is failing, fix it.” Here’s the actual back-and-forth between the model and the harness, one loop at a time.
This is the sentence worth remembering: the intelligence is in the loop, not in the tools. The tools are simple (read a file, run a command). The magic is that the model gets to see each result and decide the next move, again and again.
The parts that make up a real harness
The loop is the skeleton. A real, working harness adds a few more parts, each one solving a specific limitation of the bare model. Here they are in plain terms.
When do you even need one?
Not every use of AI needs a harness, and it’s worth knowing the line. If you just want the model to write something once, a summary, an email, an explanation, you don’t need a harness at all. You ask, it answers, done.
You need a harness the moment the task requires the model to act and react over time:
| You DON'T need a harness | You DO need a harness |
|---|---|
| Write me an email | Read my inbox and reply to the urgent ones |
| Explain how sorting works | Fix the failing test in my project |
| Summarize this text | Research a topic across many web pages |
| One question, one answer | A goal that takes many steps and real feedback |
The takeaway
Here’s the whole idea, tied up. A language model is a brilliant brain in a jar: it can think, but it can’t touch the world. The harness is the body you build around it, a loop of software that takes the model’s decisions, actually carries them out, shows the model what happened, and asks it again, over and over until the job is done. The model supplies the thinking. The harness supplies the doing.
So the next time you watch an AI agent fix a bug, book a trip, or work through a task step by step, you’ll know the real shape of what’s happening underneath. It isn’t one magic super-brain. It’s a plain, understandable loop, patiently letting a text-predictor act, look, and act again. That loop is the quiet engine behind every AI agent you’ll ever meet, and now you understand it exactly.