Agent Harness Design for Production

What An Agent Harness Actually Is

Anthropic's own framing: "An agent harness is everything between the language model and the real world. The model generates text. The harness decides what that text can touch." Microsoft describes the same layer as "where model reasoning meets real execution." OpenAI's Codex team runs every surface — CLI, web, VS Code, macOS — through one shared harness for exactly this reason: the harness, not the product surface, is what actually determines behavior.

A harness has, at minimum:

• An execution loop that alternates model calls and tool execution until a stop condition is met
• A tool layer — built-in tools plus external connections, typically via MCP
• A permission system controlling which tool calls run automatically vs. require approval
• Context and session management, including what persists across turns and how it gets compacted
• A stop and failure path — turn limits, budget limits, or an explicit, verified "done"

It does not include the model's training, multi-agent orchestration patterns like routing or orchestrator-worker (those run on top of a harness, not as part of it), or the tool-to-external-system protocols a harness consumes, like MCP.

The Tool-Execution Loop

The loop itself is simple: the model evaluates the current state, calls tools, receives results, and repeats until it produces output with no further tool calls. Anthropic's own SDK documentation is explicit that this can run long on open-ended prompts, and recommends an explicit turn cap and cost budget as "a good default for production agents" rather than leaving the loop unbounded. A quick lookup might take one or two turns; a real refactor can chain dozens of tool calls across many turns, with the model adjusting its approach based on each result.

The engineering decision that matters here isn't the loop shape — every major harness implements essentially the same alternation — it's where the bounds sit. No limit means a well-scoped task finishes fine and an ambiguous one burns budget silently. A limit set too low means real multi-step work gets cut off mid-task with no path to resume cleanly.

Permission Gating And Sandboxing

Every tool call needs an explicit allow, ask, or deny decision, evaluated in a fixed precedence order with deny always winning. Read tools — search, list, fetch — default to auto-approved; write and side-effecting tools — edit, run a command, call an external API — default to requiring approval. Auto-approval modes exist precisely because asking for permission on every call doesn't scale, but they trade human friction for a smaller, still-real attack surface.

The pattern behind both: a permission boundary that looks complete against the documented command set but wasn't tested against everything adjacent to it — a pre-trust network call, an unlisted shell built-in. Sandboxing the execution environment (container or VM isolation for anything running arbitrary commands) is the backstop for exactly this class of gap, which is why every harness reviewed for this guide — Claude Agent SDK, Codex, Microsoft Agent Framework, OpenHands — treats isolated tool execution as a first-class component, not an afterthought. For the full mechanics of both CVEs and an adversarial audit checklist, see Permission & Sandboxing Design for Coding Agents.

Context Compaction And Multi-Session Continuity

Context accumulates within a session and doesn't reset between turns. When it approaches the window limit, a harness automatically compacts: it summarizes older history and keeps recent exchanges intact. This is explicitly lossy — specific instructions from early in a session may not survive — which is why persistent rules belong in a re-injected instructions file (an AGENTS.md or CLAUDE.md) rather than the initial prompt: that content reloads every request instead of surviving only until the next compaction.

Anthropic names the failure mode this causes directly: goal drift, a gradual loss of fidelity to the original objective across many turns, especially after compaction — alongside "agentic laziness" (stopping early on multi-part tasks) and "self-preferential bias" (an agent trusting its own unverified prior output). For a long-running task that spans multiple sessions, Anthropic's own engineering research adds a second layer: a dedicated first session should set up durable infrastructure — an init script, a structured progress log, an initial commit — so every later session onboards from persisted state instead of re-deriving project context from scratch, because "each new session begins with no memory of what came before."

Verification Before Completion

The single most concrete failure mode in Anthropic's own harness-engineering research is a model marking a feature complete without actually testing it. The fix wasn't a better prompt — it was giving the agent browser automation tools and explicitly requiring end-to-end testing "as a human user would" before a completion claim gets accepted. The general rule generalizes past coding agents: a harness needs an explicit, tool-backed verification step wired into the loop, not an assumption that the model will self-report accurately.

Reference Architecture

A production-hardened harness, layered by concern:

• Instructions. AGENTS.md/CLAUDE.md at the project root, re-injected every request so it survives compaction.
• Loop. Explicit turn and budget caps; reasoning effort tuned to task complexity rather than maxed out by default.
• Tools. Read tools auto-approved; write and side-effecting tools require approval by default; tool schemas loaded on demand where the harness supports it, to control context cost.
• Permissions. Allow/ask/deny precedence with deny always winning; sandboxed execution for anything running arbitrary commands; adversarial tests against allowlist-bypass patterns, not just documented-command coverage.
• Context. Automatic compaction with an explicit "preserve on summarize" instruction set; sub-agents used for both task decomposition and context isolation on noisy sub-tasks.
• Continuity. Session store/resume from persisted state; a structured progress file and commit history as the durable state a new session onboards from.
• Verification. A tool-backed check gating every "done" claim — never a model self-report.
• Deployment. A regression benchmark run before any model or harness-version change reaches production — not a one-time build, given how much the "same model, different harness" effect moves scores on its own.

Benchmarking A Harness, Not Just A Model

Public benchmarks are starting to separate the two explicitly. Terminal-Bench reports results per agent-harness combination (its own Harbor framework paired with a named agent, such as "Terminus 2 agent harness in an e2b sandbox") rather than by model alone. METR's time-horizon work measures the related but distinct question of how long a task an agent can complete autonomously at 50% reliability — frontier models reached roughly an hour as of METR's March 2025 measurement, a horizon that has been doubling roughly every seven months.

For a client-specific eval, isolate the harness variable directly: run the identical task set against the same model under at least two harness configurations before attributing a performance change to a model upgrade, include a forced-compaction case to check task fidelity survives, and include an adversarial permission-boundary case modeled on the CVE pattern above.

For the underlying context-management primitives in more depth, see Context Engineering for Production AI Agents. For the protocol a harness's tool layer typically speaks to reach external systems, see MCP Security in Production. The core term is defined in the glossary as Agent Harness.