What is the difference between a harness and a model?

How can two AI agents get the same instructions, produce almost the same plan, and still hand you different results?

Say you ask two coding agents, one running Claude and one running Gemini, to write a small piece of code. You give them identical instructions, and before they start you ask each for a plan. The plans look nearly the same, so you would expect the final code to look the same too.

Then you run it. One works and one fails. Your first thought is that one model is simply better at writing code.

That is usually the wrong conclusion. Even when two models receive the same instructions and produce the same plan, the software around them differs. One agent might have better access to your files, different tools for running the code, or a better way of seeing an error and trying again.

That software around the model is the harness.

What is the difference between a harness and a model?

A model is the AI component that reasons over information and generates a response or proposes an action. A harness is the software layer around that model that runs an agent session, connects the model to context and tools, coordinates tool calls, manages approvals and state, and feeds results back into the next turn.

VS Code describes an agent harness in close to these terms, and Anthropic similarly describes the harness as the system that lets a model act as an agent.

A useful shorthand is agent = model + harness, although the boundary varies between products. The model does not, on its own, read your files, run commands, or change code. It can request those actions. The harness coordinates the system that carries them out.

So when an agent fails at a task, your first question should be which layer actually failed.

How do a model and harness work together?

Through a repeated cycle called the agent loop: request, reason, act, observe, repeat.

Say you ask a coding agent to fix a failing test. Your request does not go straight to a model and come back as a finished answer.

OpenAI describes its Codex harness in similar terms, with the core harness providing the agent loop and execution logic alongside thread persistence, configuration, authentication, tool execution, and extensions.

What are the main differences between a model and a harness?

They differ in role, input, output, and the kind of failure each one produces. Separating their jobs is what makes an agent debuggable.

VS Code treats the language model and the harness as separate choices, noting that one harness can offer multiple models.

The layers still depend on each other, though. A better model cannot repair a missing terminal tool, and a sophisticated harness cannot make a model capable of reasoning it cannot do. Anthropic therefore evaluates the model and harness together when assessing an agent.

Why does the distinction matter when you are using an AI agent?

Because it gives you somewhere sensible to look when an agent misbehaves, instead of immediately switching models.

Say you ask your agent to fix a test and it produces a convincing explanation, but the code is still wrong. If it had the relevant files, instructions, and tools, you are probably looking at a model capability or reasoning problem.

Now imagine it identifies the correct fix but cannot run the test, because the terminal tool is unavailable. Or it can run the command but lacks permission. Or it keeps losing information it discovered earlier in the task. Those failures point at the harness, context management, permissions, or execution environment instead.

The same model behaves differently in different harnesses, because the surrounding system determines what information and actions are available to it.

When should you change the model, and when should you change the harness?

Diagnose the missing capability first. If the answer is reasoning, investigate the model. If the answer is tools, context, permissions, state, or execution, investigate the surrounding system.

Consider changing the model when the task consistently exceeds its reasoning or coding capability, when it misunderstands a well-specified instruction even with the right context, or when you need a capability the current model does not have.

Consider changing or improving the harness when the agent cannot reach the tools it needs, receives poor or incomplete context, loses useful state between steps, has an unsuitable permission setup, or cannot execute and verify the work it proposes.

For example, if your coding agent writes code but never runs the tests, you can change its harness so it can use a terminal, run the suite, read the result, and send that result back to the model. The model then decides what to change and tries again. You have not changed the model, but you have changed what the agent can do with it.

One harness may support several models while another is tightly coupled to a single provider, so changing the harness does not always mean keeping the same model. VS Code's documentation makes the separation explicit, and OpenAI describes its Codex harness as a reusable layer across several Codex experiences.

Ask one question before replacing anything: what capability is actually missing?

What is the difference between a harness, an agent, and an execution environment?

A model provides reasoning and generation. A harness coordinates the model, tools, context, state, and agent loop. An agent is the working system that uses those pieces to pursue a goal. The execution environment is where the tools actually run.

That last distinction is worth keeping straight. Your local machine, a remote machine, or cloud infrastructure can be where an agent's tools operate, but that environment is not automatically the harness. The harness coordinates the work. The environment is where the work happens.

What are the common misconceptions about models and harnesses?

Four of them come up repeatedly, and each one sends people looking in the wrong place when an agent fails.

The first is that the model is the whole agent. A model can generate text and request an action. An agent system adds the machinery needed to gather context, use tools, maintain state, and repeat the work.

The second is that a better model fixes every agent problem. It cannot. If your agent cannot reach the right file or run the required command, changing the model leaves the actual failure untouched.

The third is that a harness is just a prompt wrapper. Modern harnesses include tool execution, permissions, session persistence, context management, and the logic deciding what happens after each model response. OpenAI's description of the Codex harness covers the agent loop, thread persistence, configuration, authentication, and tool execution.

The fourth is that the word has a fixed meaning. It does not. Some teams use "harness" broadly for most of the software around a model, while others distinguish it from scaffolding or other surrounding components. Hugging Face's terminology guide makes that variation explicit.

What else do people ask about harnesses and models?