Anatomy of a harness

Most agent demos share a skeleton: a prompt, a list of tools, and a while-loop that feeds model output back in until the model says it is done. It fits in eighty lines and it works, in the sense that a rope bridge works — right up until something heavy walks across it.

The gap between that demo and a production agent is not a better prompt or a bigger model. It is a harness: the structured runtime that sits between the model and everything the model can touch. This post is about what actually lives in that layer, because “agent harness” gets used loosely and the details are where systems live or die.

The model proposes; the harness disposes

The central design principle is a separation of powers. The model is a reasoning engine: it reads context and proposes actions. The harness is the execution authority: it decides whether, how, and with what supervision those proposals touch the world.

This matters because a model’s failure modes are statistical. It will occasionally call a tool that does not exist, pass arguments of the wrong shape, retry a destructive operation because it lost track of state, or pursue a subtly wrong goal with impressive persistence. None of these are bugs you can patch in the model. They are properties of the component, and the architecture has to absorb them — the same way networked systems absorb packet loss rather than legislating against it.

A prompt and a loop absorbs none of this. It grants a probabilistic component unmediated access to real systems and hopes for the best. That is not an architecture; it is an incident report with a delay on it.

Tool mediation

Every tool call should pass through a mediation layer, and that layer earns its keep several times over:

• Validation. Schemas checked before execution, not after the stack trace. Malformed calls are returned to the model as structured errors it can correct, rather than crashing the run or — worse — half-executing.
• Authorisation. The model’s tool list is not the model’s permission set. The harness enforces which tools this agent, on behalf of this user, in this environment, may invoke, with what argument constraints. A read-only agent should be unable to write even if it hallucinates a perfectly formed write call.
• Consequence classification. Reading a record and issuing a refund are different categories of action. The harness knows which calls are reversible, which are idempotent, and which need confirmation, a dry run, or a human before they execute.
• Recording. Every proposed call, every decision, every result, in a trace. When something goes wrong — and something will — the trace is the difference between a post-mortem and a shrug.

Context management

The model’s entire worldview is its context window, and the harness is what constructs it. This is a genuine engineering discipline that the demo skeleton skips entirely.

Long-running tasks exceed any window, so the harness must compact: summarising earlier turns, pinning what is load-bearing (the original goal, hard constraints, decisions already taken), and dropping what is not. Done carelessly, compaction is how agents forget their instructions halfway through a task — a failure that presents as the model being stupid but is really the runtime being sloppy.

Tool results need shaping, too. A tool that returns forty thousand tokens of JSON has handed the model a haystack and billed you for it. The harness truncates, extracts, and formats. And anything entering the window from outside — documents, web pages, other tools’ output — is untrusted input. The harness is where prompt-injection defence lives, keeping fetched content clearly separated from instructions and treating “the document told me to do it” as a threat model rather than an excuse.

Retries, fallbacks, and knowing the difference

Failure handling in agent systems has a property that generic retry libraries miss: you must distinguish operational failures from behavioural ones.

A timeout or a rate limit is operational. Retry it with backoff, and make sure the operation is idempotent first — retrying a non-idempotent write because the acknowledgement was lost is a classic self-inflicted wound.

A model producing an unparseable plan, or heading off-goal, is behavioural. Retrying the same context and hoping is not a strategy; the harness should re-prompt with the error made explicit, and count. Which raises the piece almost every homegrown loop forgets: budgets. Bounded iterations, bounded cost, bounded wall-clock time, and loop detection for the agent that keeps trying the same failing call with minor variations. An agent without budgets is a bill without a ceiling.

Fallbacks are the coarser mechanism: an alternate model when the primary degrades, a simpler deterministic path when the clever one fails, graceful refusal when nothing is safe. The harness holds the ladder and decides when to step down it.

Human escalation

The most under-engineered part of most agent systems is the exit. Autonomy should be a spectrum with explicit rungs, not a binary between “fully automatic” and “someone reads the logs on Friday”.

A well-built harness escalates when confidence is low, when an action crosses a consequence threshold, when budgets are exhausted, or when policy simply says this class of decision belongs to a person. And escalation is a designed workflow, not an exception: the human sees what the agent was doing, what it proposes, and why it stopped — with enough context to decide in a minute, not twenty. The agent pauses cleanly, resumes cleanly, and treats the human’s decision as an instruction, not a suggestion.

Get this right and escalation stops being a failure mode. It is the mechanism that lets you deploy agents on consequential work before you would trust them unattended — which, in practice, is how all consequential automation has ever earned trust.

Why this is a layer, not a library

Everything above is model-agnostic. Mediation, context discipline, budgets, escalation — none of it depends on which model is reasoning inside the loop, and all of it embodies your organisation’s policies rather than the model vendor’s defaults. That is the argument for treating the harness as durable infrastructure: models will be swapped many times over the life of a production agent; the runtime around them is what persists and compounds.

It is also, not coincidentally, what Hyperpriors builds. The while-loop is the easy part. The harness is the part that lets you sleep.