Harness Theory Part 01 | What Is a Harness, and Why Do Agents Need One?

Connect a language model to a chat interface and it can answer questions. Give it tools and it can inspect files, run code, retrieve information, and modify a project.

The harder questions arrive once it can act:

How does it know which information to read, which resources it may change, whether a failed step should be retried, when it must stop, and what evidence proves that the task is actually complete?

The model can answer only part of that.

Suppose a coding agent is asked to fix a checkout bug. The model may understand the error and infer a plausible patch. A deliverable system still has to locate the correct repository, create an isolated workspace, load project rules, restrict credentials, run tests, interpret the results, retain progress, produce a diff, wait for approval where necessary, and leave evidence that can be inspected later.

The model supplies reasoning and choice. The system around it supplies the conditions under which those choices can be executed, constrained, observed, and verified. That surrounding system is the subject of this series: the harness.

Figure 1-1 | The model supplies reasoning and choice. The harness supplies the operating environment, constraints, feedback, and verification.

A working definition of a harness

In this series, a harness is the execution and governance system around an LLM or agent runtime.

It is not merely a proxy placed in front of the model. It connects model reasoning to an executable working environment and coordinates context, tools, state, policy, verification, and observability.

A harness commonly has to:

• assemble the context required for the current turn
• expose tools while limiting which tools and arguments are available
• control multi-step execution, retries, stopping, and human approval
• retain task state, checkpoints, and recoverable progress
• manage identity, permissions, time, cost, and data boundaries
• verify outputs and real-world side effects
• record traces that support debugging, replay, and evaluation

The definition is deliberately broad because products draw the boundary in different places.

Some hosts already provide the conversation surface, agent loop, tool execution, and session handling. The product team may only need to add workload-specific controls through APIs, repository rules, CI, and permission systems. In a self-managed backend, the model API is one component among many, and the team owns context, tools, state, verification, and tracing.

OpenAI’s engineering material illustrates this variation. One article uses harness for the core Codex agent loop and execution logic. Another focuses on the tools, repository structure, feedback, and enforceable conventions that make the environment legible to the agent.¹²

Before discussing architecture, establish what the word wraps in that particular system: a bare model, an agent runtime, or a coding agent that already has a tool loop.

The boundary may change. The responsibilities do not disappear.

Model, harness, and agent product

A useful mental model is:

Agent Product Outcome = Model × Harness × Task

This is not a scoring formula. It is a reminder that the result depends on model capability, the environment in which that capability is used, and whether the task is suitable for this form of execution.

The model supplies reasoning and choice

A model can usually:

• interpret natural language and code
• reason and generate from the supplied context
• decompose a problem and propose a next step
• select from candidate tools
• replan after receiving new observations

It can suggest what should happen next. It does not naturally possess database permissions, retrieve the correct file, preserve durable state, or make a deletion reversible.

The harness supplies working conditions

The harness determines:

• which information is visible
• which tools may be invoked
• which arguments and resources are allowed
• which state is retained by the system
• which failures may be retried
• which actions require approval
• which verifier has authority to pass the work
• which events must be recorded

Part of this is feedforward control: rules, structure, and capabilities provided before the model acts. The other part is feedback control: tests, linters, logs, browser checks, review agents, and other sensors that report what happened after the action.

Rules without feedback cannot show whether the rule was satisfied. Feedback without useful structure leaves the agent paying for the same lesson repeatedly.³

A harness cannot manufacture missing intelligence

A harness can improve context, tools, feedback, and constraints. It cannot reliably supply domain reasoning that the model does not possess.

If the model cannot understand the task, adding more if/else branches, prompt clauses, or workflow nodes may only package the failure more elaborately. A harness improves the conditions under which capability is used. It does not create that capability from nothing.

The same applies to self-assessment. A model saying, “I have verified the result,” is a signal, not proof. Tests, policy checks, verifiers, or an explicit human gate must still decide whether the work passes.

The agent product owns the complete outcome

Users normally interact with a product made from a model, a harness, data, and an interface.

The same model can behave differently when another harness gives it different context, tools, permissions, and verification paths. The same harness can produce different results when the model changes its planning quality, tool-use behaviour, or ability to recover from errors.

A model leaderboard measures model performance under specified test conditions. It does not tell a product team whether its context is correct, its tools are reliable, its permissions are safe, or its completion claims can be verified.

Where the harness sits

A harness commonly lives in an application backend, an agent runtime, or the boundary between a host product and the organisation’s own systems.

A simplified self-managed arrangement might look like this:

User
  ↓
Web / App / CLI
  ↓
Backend Harness
  ├── Context / RAG
  ├── Tools / MCP / APIs
  ├── State / Checkpoint
  ├── Policy / Approval
  ├── Verifier
  └── Trace / Eval
  ↓
LLM API or Local Model

This is a conceptual placement diagram, not a canonical deployment architecture.

When a team uses ChatGPT, Claude Code, Codex, or another host, the host already supplies part of the harness. The team’s APIs, repository rules, CI, permission system, and verification tools form another layer for its own workload.

Before comparing architectures, answer three questions:

1. Is the harness wrapping a bare model, an agent runtime, or an agent that already has a tool loop?
2. Which responsibilities belong to the host, and which belong to the product team?
3. Who owns canonical state, final approval, and pass authority?

Without this boundary, an internal harness, a user-owned harness, and a complete agent platform are easily mistaken for the same thing.

Prompts, Modelfiles, and frameworks cover narrower concerns

Figure 1-2 | These concepts answer different engineering questions and should not be treated as interchangeable.

System prompt

A system prompt supplies roles, rules, formats, and behavioural guidance. It can increase the probability of a suitable action, but it should not be the only mechanism enforcing a hard limit.

If “retry no more than three times” exists only in the prompt, it may be misread, diluted by a long context, or unable to constrain an external side effect. A reliable runtime counts attempts and stops, changes recovery path, or escalates after the limit.

Modelfile or model configuration

A Modelfile describes how the model is configured and packaged, including the base model, system prompt, temperature, context window, or adapter.

It may provide configuration to the harness. It does not usually execute tools, preserve durable task state, enforce permissions, manage checkpoints, run verifiers, or retain traces. Tuning the engine does not install steering, brakes, navigation, and instrumentation around it.

Tool calling

Tool calling gives the model a structured way to request an external operation.

The surrounding system still has to decide:

• whether the tool is visible for this task
• whether the arguments are valid
• whether the current identity is authorised
• whether failure should trigger a retry, fallback, or stop
• how the resulting side effect will be verified

Tool calling provides the action interface. The harness still owns execution and governance.

Agent framework

An agent framework may provide an agent loop, graph, memory, tool registry, state store, checkpointing, human-in-the-loop controls, and tracing. It may implement a meaningful part of the runtime.

The product still has to define tenant isolation, cost ceilings, data policy, completion criteria, and incident recovery for the workload at hand. Selecting a framework does not make those decisions automatically.

Anthropic distinguishes workflows from agents in a useful way. A workflow coordinates models and tools through predefined code paths. An agent allows the model to direct its own process and tool use dynamically. Either can operate inside a harness. The architectural question is which decisions remain deterministic and which are delegated to the model.⁴

RAG, workflow, and orchestration

RAG retrieves material for context. A workflow defines a relatively predictable execution path. An orchestrator handles next steps, routing, hand-offs, and stopping.

Each may be part of a harness. None of them alone covers the task’s permissions, state, recovery, verification, and observability.

Concept	Primary engineering question
System prompt	Which guidance should the model follow in this turn?
Modelfile / model config	How is the model configured and packaged?
Tool calling	How can the model request an external operation?
RAG	Which material should be retrieved from which sources?
Workflow / orchestration	What happens next, and where does failure go?
Agent framework	Which abstractions and components are used to build the system?
Harness	How is the whole task executed, constrained, verified, and recovered?

When assessing an agent system, find the owners of state, permission, and pass authority before counting models, tools, or workflow nodes. A system can have many features and still have a weak harness if critical responsibilities have no owner.

Why stronger models still need harnesses

A stronger model can attempt a wider range of tasks. It also creates a larger action space. Once an agent can inspect more data, invoke more tools, and run for longer, the surrounding system inherits more operational complexity.

The following seven dimensions are a working framework for this series, not a universal industry taxonomy.

1. Context budget pressure

A local task may depend on several modules, services, configuration files, historical decisions, and external documents. Too little context omits constraints. Loading everything can bury the task itself.

2. Exploration must converge

An agent may explore repositories, documentation, and tools. Exploration still needs an entry point, useful feedback, and stopping conditions. Otherwise autonomy becomes aimless browsing.

3. Hidden runtime state

A small code change may activate global state, external services, tenant data, and implicit side effects. Reading the source does not mean the model has observed the full runtime state.

4. Knowledge may be unavailable or hard to express

The correct approach may exist only in an engineer’s memory, a Slack thread, an incident review, or stale documentation. For a running agent, inaccessible knowledge is effectively absent.

A related problem is promptability. A team may know how a task should be done without being able to express the requirements, exceptions, and completion criteria as a stable executable contract.

OpenAI’s Codex team addressed part of this problem by making repository knowledge indexed, versioned, and inspectable as a system of record.²

5. Verification is often the expensive part

Producing an answer or patch may be quick. Proving it correct is often slower.

The required tests, logs, and user journeys should not be invented from scratch by the model after it has produced the work.

6. Goals drift during long runs

Long tasks accumulate observations, failures, and local decisions. Without a task contract, progress state, and stopping rules, an agent can remain busy while moving away from the requested outcome.

7. Actions create side effects

A wrong answer and a wrong action have different risk profiles.

When an agent can send mail, alter records, deploy software, or move money, identity, approval, idempotency, rollback, and audit become system responsibilities.

Longer prompts do not enforce these boundaries on their own. Prompts influence decisions. Code, policy, and the execution environment enforce them.

Harnessability: can an agent work with the system?

When an agent fails, the model is an obvious suspect. A second question matters just as much: does the system provide enough structure and feedback for the agent to understand it, make a bounded change, verify the result, and recover from failure?

This property is harnessability.

A highly harnessable system tends to have:

• clear and stable module boundaries with explicit ownership
• reproducible setup, build, test, and runtime procedures
• explicit inputs, outputs, side effects, and completion conditions
• a navigable repository map and an accessible system of record
• local tests, fast sensors, and diagnostic error messages
• change paths that can be isolated, rolled back, replayed, and recovered

Harnessability also depends on whether the task can be packaged into a bounded unit. If context, permissions, and side effects cannot be limited, or if the task lacks clear inputs, outputs, and completion evidence, it is difficult to delegate safely. This property can be described as capsuleability.

Type systems, schemas, linters, standard project structures, and consistent migration tooling can act as ambient affordances. They may not have been introduced for agents, but they narrow the search space and expose mistakes earlier. The Martin Fowler article on harness engineering uses these environmental characteristics to explain why some systems are easier for agents to operate.³

Two practical stress tests are:

1. Can the agent refactor a bounded area without changing observable behaviour?
2. Can it reimplement a core behaviour from the available specification and prove equivalence through external tests?

If both fail, the problem may lie in unclear behavioural boundaries, hidden knowledge, or weak verification rather than model capability alone.

Harnessability should not be compressed into an attractive but unsupported score. A useful assessment identifies high-risk dimensions, supporting evidence, affected task classes, and the sensors, documentation, boundaries, or recovery mechanisms that are missing.

Some projects are not ready for highly autonomous agents. Improving repository navigation, tests, module boundaries, and recoverable execution may create more value than replacing the model.

Human work moves to a steering control plane

Figure 1-3 | Human work moves from operating every step to defining intent, boundaries, evidence, task selection, and system evolution.

More agent execution does not remove the human role. It moves human work from step-by-step operation to a steering control plane.

Control-plane responsibility	Human decision
Intent	Which problem is worth solving, its priority, trade-offs, and acceptable outcome
Boundaries	Which resources are accessible, which actions need approval, and which state transitions remain under deterministic control
Sensors and verification	What should be measured, which checks are trusted, and which failure modes remain invisible
Task portfolio	Which work belongs with humans, agents, or a mixed process, and how much concurrency is manageable
System evolution	Which repeated errors should become documentation, tools, tests, policy, or architectural constraints

The central issue is not whether a human is present somewhere in the loop. It is who holds final authority.

People do not need to inspect every step. They do need to decide which tests carry pass authority, which judgements require sampling or review, and which conditions must stop or escalate the run.

High-risk and irreversible actions still need approval gates. Routine progress can be recorded as durable events and reviewed at natural checkpoints.

Mitchell Hashimoto describes a related operating model in which the human decides when to inspect a background agent instead of allowing notifications to fragment attention.⁵ Anthropic’s study of real agent use found a similar pattern: experienced users allowed Claude Code to operate with auto-approval more often, while also interrupting it more frequently when intervention was needed.⁶

Supervision remains. It shifts from approving every step to setting boundaries, demanding evidence, and handling exceptions.

Five principles for reviewing a harness

The later articles will develop the architecture in detail. Part 01 needs only five principles that will recur throughout the series:

• Constraint-first: define identity, resources, tools, data flow, time, cost, and approval conditions before granting autonomy.
• Verifiability: important actions must leave external evidence. The model may report completion, but tests, verifiers, policy, or an explicit human gate should hold pass authority.
• Progressive trust: scale permissions with task risk and accumulated evidence rather than choosing between full automation and approval at every step.
• Design for failure: models, tools, networks, data, and external services fail. Timeouts, retries, checkpoints, fallbacks, compensation, and escalation should exist before the failure occurs.
• Agent ergonomics: tool schemas, error messages, context, and execution entry points are interfaces for the agent. Convenience matters, but it cannot replace safety or verification.

Walking through the checkout example

Return to the checkout bug from the opening. The responsibility can be split into three layers.

Model

• read the error and relevant code
• infer that coupon state and payment state may be updated in the wrong order
• propose a patch
• revise the patch from test observations

Harness

• locate the correct repository and branch
• create an isolated workspace
• load project rules and relevant modules
• provide only the required test credentials
• prevent access to the production database
• run unit, integration, and browser-journey tests
• retain checkpoints, diffs, logs, and test evidence
• request approval before a high-risk operation

Task contract

• fix the duplicate-charge defect
• keep the current payment provider
• avoid unrelated modules
• pass the relevant tests
• preserve the main checkout journey
• attach replayable verification evidence on completion

A prompt can tell the agent not to access the production database. Hard enforcement means the runtime does not provide the credential, policy rejects the operation before execution, and verification checks that no out-of-bound side effect occurred.

That is the difference between a harness and prompt guidance alone.

Seven questions for assessing an agent system

When examining a new agent product or framework, ask:

1. Who assembles the context for each model turn?
2. Who decides which tools, permissions, and data are available?
3. Who retains canonical state and checkpoints?
4. Who controls retries, timeouts, stopping, and human approval?
5. Who verifies outputs and real side effects?
6. Who records traces, cost, and error evidence?
7. Who restores the task when the model, tool, or session fails?

If the answers are scattered across prompts, front-end state, a few scripts, and human memory, the system does have a harness. It has an invisible, fragmented, and difficult-to-audit one.

---

From theory to implementation: Part 01 checklist

• The team can state the boundary of the harness being discussed in one sentence.
• Hard constraints are enforced by the runtime, policy, or execution environment rather than existing only in prompts.
• Canonical state, pass authority, and recovery responsibility have explicit owners.
• Important tasks produce observable and replayable completion evidence.
• Repeated failures are promoted into guides, sensors, tools, policies, or architectural constraints.

Part 02 will expand these responsibilities into a complete architecture, including the request boundary, policy, canonical state, controller, context, capabilities, verifier, persistence, observability, and client protocol.

Footnotes

1. OpenAI, Unrolling the Codex agent loop, 23 January 2026. ↩

2. OpenAI, Harness engineering: leveraging Codex in an agent-first world, 11 February 2026. ↩ ↩²

3. Birgitta Böckeler, MartinFowler.com, Harness engineering for coding agent users, 2 April 2026. ↩ ↩²

4. Anthropic, Building effective agents, 19 December 2024. ↩

5. Mitchell Hashimoto, My AI Adoption Journey, 5 February 2026. ↩

6. Anthropic, Measuring AI agent autonomy in practice, 18 February 2026. ↩