Agent harnesses — the architecture that wraps the LLM

In short

A standalone LLM responds to a query: it generates text from a context. A harness is the control layer that surrounds it to turn it into an agent capable of executing long, multi-step tasks with tools and persistent memory. Without a harness, the model has no loop, no durable state, no verification mechanism, and no way to delegate work. Agent performance depends as much on the harness as on the model itself — as shown by recent research on the subject (Pan et al., 2026; Anthropic, 2025b).

In short: an LLM is a virtuoso musician. A harness is the orchestra that gives them a score, a conductor, a stage, lighting, sound mixing. Without the harness, the virtuoso plays magnificently… for no one, with no continuity, with no ability to resume after a false start. A concert’s performance depends on the musician AND the staging. For an AI agent, it is the same: doubling the harness quality may yield more gain than doubling the model size.

Why the LLM alone is not enough

A model call is a stateless function: input → output. This property is well-suited to translation, summarization, or one-shot generation tasks. It becomes an obstacle as soon as the task requires multiple steps, external tools, or the coordination of multiple agents.

Three problems appear immediately:

State is ephemeral. Information produced at step 3 is only available at step 7 if it has been explicitly passed in context. As the task extends, the context fills up, information falls out of the window (the phenomenon known as context rot), and the agent loses track of its own work (Liu et al., 2024; Chroma Research, 2025).

Progress is not guaranteed. The model does not know when to stop, when to restart, or how to recover from a failing tool. There are no validation gates, no error taxonomy, no retry logic.

Decomposition is implicit. The model can produce a plan in text, but nothing constrains it to execute it step by step or to delegate sub-tasks to specialized agents.

The harness solves these three problems by externalizing control logic.

What a harness specifies

Pan et al. (2026) formalize a harness as a layer that governs three dimensions for a family of tasks:

Control — how work is decomposed and scheduled. Classic examples: the reason–act loop (ReAct, Yao et al., 2023), a plan → execute → verify → repair pipeline, or a parallel multi-agent topology.

Contracts — which artifacts must be produced, which conditions must be met before moving to the next step, and when the run should stop. A contract defines required inputs and outputs, format constraints, retry rules, and permission boundaries.

State — what must persist between steps, branches, and delegated agents. Without durable state, each step restarts from scratch.

Components of an executable harness

A complete harness exposes at minimum six components (Pan et al., 2026):

• Roles: solver, verifier, researcher, orchestrator — with non-overlapping responsibilities.
• Stage structure: the explicit work topology (plan → execute → verify → repair).
• Adapters and scripts: the deterministic hooks — tests, linters, parsers, checkers — that are not delegated to the LLM.
• State semantics: what persists (artifacts, ledgers, child agent workspaces) and how to retrieve it (paths, manifests).
• Failure taxonomy: the named error modes that trigger recovery (missing artifact, tool error, timeout, verifier failure).
• Execution contracts: the gates that validate outputs before moving to the next step.

In short: these six components are the roles of a film crew. Roles are the screenwriter, the director, the cinematographer — each specialized. Stage structure is the breakdown into shooting days. Adapters are the technicians (sound engineers, editors) who are not artists. State semantics is the production folder reviewed each morning. Failure taxonomy is the protocols for “what to do if the weather turns”. Execution contracts are the rushes validated before tearing down the set.

Common architectural patterns

Research has converged on a set of well-documented patterns:

Reason–Act (ReAct)

The model alternates reasoning and action: it produces a thought, calls a tool, observes the result, produces a new thought. This is the foundational pattern of most current agents (Yao et al., 2023).

Retrieval-augmented generation (RAG)

A retrieval module injects relevant documents into context before each generation. The harness manages source selection, formatting, and coherence between what is retrieved and what is expected (Lewis et al., 2021).

Reflexion / self-critique

After an attempt, a verifier agent inspects the result and generates textual feedback. The solver agent uses this feedback to correct its output without modifying the model weights (Shinn et al., 2023).

Persistent state via files

For long tasks, state is written to path-addressable artifacts rather than maintained in context alone. Three properties are required: externalized (written to disk), path-addressable (exact reopening), and stable under compaction (survives context truncations) (Pan et al., 2026; Anthropic, 2025b).

Multi-agent orchestration

The harness can delegate sub-tasks to child agents (spawn_agent, wait_agent). The parent manages handoff contracts and integration of returned artifacts. On code benchmarks, approximately 90% of tokens and tool calls occur in child agents, not in the parent orchestrator (Pan et al., 2026).

Decision matrix: which harness pattern to choose

Code harness vs. natural-language harness

Historically, the harness is Python or TypeScript code: functions, while loops, conditional calls. This is powerful but opaque — control logic is scattered across the controller code, framework conventions, and verification scripts. Comparing two harnesses or extracting a component from one is difficult.

An alternative approach is emerging: expressing control logic in structured natural language (Natural-Language Agent Harnesses, NLAHs). The harness becomes a readable, portable, and modifiable artifact. A runtime interprets this text at each step (Pan et al., 2026).

Advantages: portability across runtimes, auditability, modular comparison, easier migration.

Limits: natural language is less precise than code. Some mechanisms cannot be faithfully reproduced from text, particularly those that depend on hidden service-side state or training-induced behaviors. The risk of runtime contamination exists: a strong shared charter can absorb part of the behavior one would attribute to the harness [NOT VERIFIED for the exact proportion of this effect].

What architecture does not guarantee

Adding components does not mechanically improve results. Experiments on SWE-bench Verified and OSWorld show:

• More structure can create friction on tasks that benefited from the shortest path.
• A local verifier can diverge from the benchmark’s final gate: a run reports “solved”, the benchmark rejects it anyway.
• Multi-candidate search is token-expensive without proportional gain on aggregated metrics.
• Automatic evolution (self-evolution) is the most effective module — not because it generates more attempts, but because it disciplines the acceptance loop around a clear criterion (Pan et al., 2026).

The correct interpretation: modules help when they tighten the path between intermediate behavior and the final acceptance condition. They hurt when they add validation layers whose notion of success is weakly aligned with the evaluator.

In short: harness complexity does not stack by default. Each module added (local verifier, multi-candidate search, intermediate validation) must prove that it brings you closer to final success as measured. On SWE-bench, local verifiers say “solved” when the benchmark says “not solved” — worse than useless, this is misleading. Pan et al.’s empirical rule: add a module if and only if the intermediate acceptance target is exactly aligned with that of the final deliverable.

Key takeaways

• A harness is the control layer between the LLM and the task: loop, state, tools, roles, contracts, error handling.
• Without a harness, the LLM has no persistent memory, no validation gate, and no recovery mechanism for long tasks.
• The fundamental components are: distinct roles, stage structure, deterministic adapters, externalized state, failure taxonomy.
• More structure is not always better — the alignment between intermediate control gates and the final success condition determines the real value of a module.
• The emerging trend is to express harness logic in natural language to make it portable and auditable, while retaining code for deterministic operations.