Heads up: posts on this site are drafted by Claude and fact-checked by Codex. Both can still get things wrong — read with care and verify anything load-bearing before relying on it.
why → how

What is an agent harness?

The loop and scaffolding around a language model that turns 'a thing that emits tokens' into 'a thing that does work in the world.'

AI & ML intro Apr 29, 2026

Why it exists

A raw LLM can’t do anything. It maps a sequence of tokens to a probability distribution over the next token. That’s it. It can’t read your files, run a test, search the web, or remember what it did yesterday. It outputs text into the void.

The first time someone wired a model to a shell — let it propose a command, ran the command, fed the output back into the prompt, and looped — the behavior changed completely. The same model that could only “describe how to debug” could now actually debug. Nothing about the weights changed. What changed was everything around the weights: a loop, a set of tools, some way to keep track of what had happened so far, and rules for when to stop.

That surrounding machinery is the harness. It exists because the gap between “a model that predicts tokens” and “an assistant that ships a pull request” is almost entirely not model capability — it’s plumbing. The harness is the plumbing.

Why it matters now

Every AI product you interact with in 2026 is a harness wrapped around one or two underlying models. Claude Code, Cursor, ChatGPT with tools, Devin, the copilots inside your IDE and your CRM — same handful of frontier models underneath, very different harnesses on top. The harness is where most of the product differentiation now lives: which tools the agent can call, how its context is managed, how it recovers from errors, what it’s allowed to do without asking.

This is also where most agent failures come from. When an agent loops forever, deletes the wrong file, forgets what you told it five minutes ago, or hallucinates an API that doesn’t exist — usually the model knew better and the harness let it down. Understanding the harness is how you reason about why agents fail and how to build ones that don’t.

The short answer

agent = model + harness

A harness is the program that runs around a language model: the loop that calls the model, parses its outputs, executes the tools it asks for, feeds results back in, manages what stays in context, and decides when the task is done. The model is the brain; the harness is the body, the senses, and the short-term memory.

How it works

A minimal harness is a while loop. Pseudocode:

context = [system_prompt, user_request]
while True:
    response = model(context)
    if response.is_final_answer:
        return response.text
    for tool_call in response.tool_calls:
        result = execute(tool_call)        # run the bash, read the file…
        context.append(tool_call, result)

That tiny loop is the whole shape. Real harnesses add five things on top:

1. Tools. A registry of functions the model can call, each with a name, description, and JSON schema for its arguments. The model is shown the list and emits structured calls like {"tool": "read_file", "path": "src/foo.ts"}. The harness validates the call, runs it, and appends the result.

2. Context management. Models have a finite context window. Long tasks overflow it. The harness decides what to keep verbatim, what to summarize, what to drop, and what to fetch back on demand. This is the part most products get wrong first.

3. A system prompt. The persistent instructions that shape how the model behaves: who it is, what tools it has, what it should refuse, how it should format answers. Often thousands of tokens long — the personality and policy of the agent live here.

4. Permissions and safety rails. Before running a destructive tool call (deleting files, sending emails, hitting production), the harness pauses and asks the user — or refuses outright. The model can propose anything; the harness decides what’s actually allowed to execute.

5. A stopping condition. Either the model emits a “I’m done” signal, the user interrupts, a budget (tokens, time, cost) is hit, or a guardrail trips. Without this, agents will happily loop forever.

A worked sketch of one turn:

user: "find the slow test and fix it"

→ model emits: tool_call(run_bash, "pytest --durations=10")
→ harness runs it, captures output
→ model emits: tool_call(read_file, "tests/test_users.py")
→ harness runs it
→ model emits: tool_call(edit_file, ...)
→ harness asks user to approve the edit, applies it
→ model emits: "Fixed. The fixture was rebuilding the DB per test."
→ harness exits the loop, returns the answer

The model never touched the disk. The harness did, on the model’s behalf, under rules the harness enforced.

A subtle and important point: the same weights, in two different harnesses, behave like two different products. A model with a great harness — good tools, careful context handling, sensible permissions — will out-perform a stronger model in a sloppy one on real tasks. This is why “the agent feels smart” and “the underlying model is smart” are not the same claim.

Going deeper