Harness Engineering for Agents
Foundations & The Minimal Loop
Type a request into a coding agent and watch it open six files, run the tests, and fix a failure it found along the way. It feels like a mind at work. The machinery underneath is far smaller than the feeling suggests, and that gap is where most of the engineering lives. This article answers one question: what is the smallest program that turns a language model into something that acts? Once you can build that program yourself, you can also see exactly where it breaks, and every later layer of this discipline exists to contain one of those breaks.
Agent Equals Model Plus Harness
A language model, on its own, is a function from text to text. You give it a sequence of tokens, and it predicts the next token, then the next, until it stops. It has no hands, no clock, and no memory that survives the call. If you ask it to rename a function across a repository, it can only describe what it would do.
The program that gives the model hands is called the harness. The harness builds the input text for each call, sends it to the model, reads what comes back, carries out any actions the model asks for, records what happened, and decides when to stop. The model supplies judgement about the next step. The harness supplies the world the model can touch, plus the rules that keep that touching bounded. So the working equation is: agent = model + harness. Remove the model and you have a deterministic program with no judgement. Remove the harness and you have a text generator with no effect.
This framing also sorts three terms people often blur. Prompt engineering is about the words you write for the model. Context engineering is about everything in the window at each call, which includes the prompt, the history, tool outputs, and retrieved material. Harness engineering is about the program that decides what enters that window, what happens to each output, and what the system does when something fails. Each term covers more control than the one before it. The rest of this course lives mostly at the harness level, because that is where decisions about persistence, permissions, and recovery are made.
It may surprise you how much of a production coding agent is harness. The model call is a single line in a large program. The rest handles process isolation, permission checks, streaming progress to the user, retries after rate limits, and saving state so a crash does not erase an hour of work. Consider a concrete case: the process dies after a tool has deleted a file but before the result is recorded. The model never learns what happened, because the only place that knows is the harness, and the harness is gone. Whoever writes the harness owns that failure.
$$\text{agent} = \text{model} + \text{harness}$$
Static diagram: layered architecture of an agent. An outer rounded box labelled "Harness" contains four labelled blocks: "ReAct loop (call, parse, execute, append)", "Message history", "Tool registry with JSON schemas", and "Budgets and stop rules". Inside the harness box, a smaller box labelled "Model (predicts next tokens)" sits in the centre. Arrows show: messages flow from history into the model; the model returns text or tool-call requests back to the loop; the loop executes tools against two outer targets labelled "Filesystem" and "Shell" drawn outside the harness box, with results returning to message history.
The Core ReAct Loop
The unit of agent behaviour is one round trip: the model decides on an action, the harness performs it, and the result is shown to the model before it decides again. The name ReAct, from a 2022 paper by Yao and colleagues, joins the two halves: reasoning (text the model produces about what to do) and acting (a structured request to call a tool). Each round trip is a step. A turn is one user request, which may contain many steps.
The loop's only memory is its message history: an ordered list of messages covering the user's request, the model's replies, and the results of every tool call. Each iteration sends the full history plus the tool schemas to the model. The reply is either plain text, which ends the loop, or one or more tool-call requests, which the harness executes. Each result is appended to the history tied to the call that produced it, and the loop repeats. Nothing else carries over between steps, so the history must contain everything the model needs.
Providers disagree on the exact wire format, and the disagreement matters because a mismatch is a hard error. In one common style, the model's reply contains a block of type tool_use with an id, a name, and an input object, and you answer with a block of type tool_result that refers to the same id. In another style, the reply carries a tool_calls list whose arguments field is a JSON-encoded string, and you answer with a message whose role is tool and which names the call it answers. The rule underneath both is identical: every tool request must receive exactly one answer, carrying its identifier, before the next model call. Break that rule and the provider rejects the request.
Tool schemas are the contract between model and harness. Each tool has a name, a natural-language description, and a JSON Schema describing its parameters. The model is not executing code; it is emitting text that is supposed to match the schema. That text is therefore untrusted input, and the harness must parse it, validate it, and handle the failure when it does not parse. The key design decision is what to do on failure. A malformed argument should not crash the process. It should come back to the model as a tool result that says, briefly and specifically, what was wrong, such as "edit_file: old was not found in src/app.ts", so the model can correct itself on the next step.
Termination is a guarantee you must build, because the model will not reliably stop on its own. The loop exits in one of three ways: the model replies with text and no tool call, a hard step cap is reached, or a retry budget runs out. A fourth safeguard, stop-loss detection, watches for progress that is not happening, such as the same tool called with identical arguments several times in a row. Bounding the steps bounds the cost. If each step costs at most $c$ and the cap is $K$, the whole turn costs at most $K \cdot c$, which is the only upper bound you can rely on when a model gets stuck.
Static diagram: the ReAct loop as a cycle. Boxes in order, with arrows connecting them clockwise: "Send messages + tool schemas to model", then "Model returns: text (exit) or tool_use request(s)", then "Harness parses JSON args (on error, return error as tool result)", then "Execute tool (read_file, edit_file, bash)", then "Append tool_result with matching call id to history", with an arrow returning to the first box. A side exit labelled "Stop: no tool call, step cap reached, or retry budget spent" leaves from the decision box.
Failure Modes You Must Experience Firsthand
The minimal loop works on a demo. It fails in predictable ways once you give it real work, and those failures are not bugs you can patch once. They are properties of the design. You cannot contain a failure you have never watched happen, so the point of building the loop yourself is to make these failures happen on purpose.
The first family is context degradation. The message history grows with every step, and the window the model reads has a fixed size. A single oversized tool output can consume a large share of that window. Ask the agent to inspect a build log of 3,000 lines, and the harness will happily append all of it. The useful sentence is buried in the middle, and as the history grows, the model attends less reliably to earlier content. This is often called context rot: quality declines as the context fills with material that was once relevant and no longer is. Nothing in the loop as described so far notices it.
The second family is the partial-write hazard. Suppose edit_file rewrites a file by truncating it and then writing the new content. If the process is killed between those two steps, the file on disk is now shorter than it was, and the history may not record the edit at all. Now the world and the transcript disagree. A related case is the mid-turn crash: the tool finishes, but the process dies before the harness records the result. On restart, the transcript says the call never happened, so the agent may run it again. For a read, that is harmless. For a write or a deletion, running it twice can destroy work.
Static diagram: timeline of a half-applied edit, drawn as a horizontal sequence of five labelled stages from left to right. Stage 1 "t0: src/app.ts has 120 lines; history has no pending call". Stage 2 "t1: edit_file opens src/app.ts for writing (file truncated to 0 lines)". Stage 3 "t2: first 60 lines written". Stage 4 "t3: process killed by kill -9 (red marker)". Stage 5 "t4 on restart: file has 60 lines; transcript has an assistant tool_use with no tool_result". Beneath stage 5, a note reads "disk and history disagree".
These failures share a shape. The model cannot see them, because the model only sees text, and the harness that would notice has either been flooded or has died. That is why they are hard to reason about from the outside, and why you should watch them in a terminal. Read the failing transcript, then look at the file on disk, and notice that the two describe different realities.
Capstone: 150-Line CLI Agent
The capstone is a command-line agent of roughly 150 lines, in one file, built on nothing but a model API client and the standard library. It has three tools. read_file returns a file's contents. edit_file takes a path, an exact old string, and a new string, replaces the single occurrence of old, and fails loudly if old is missing or appears more than once. bash runs a shell command with a timeout and returns its output. The choice of exact-match editing is deliberate: it makes the model's mistakes visible as error messages instead of silent corruption.
Around those tools you write the loop. It keeps a message history, converts the tool schemas into the provider's format, parses each tool call's JSON arguments, and returns parse errors and tool failures to the model as tool results. It enforces a step cap of about twenty and a simple stop-loss rule that halts when the same call repeats three times in a row. The loop ends when the model replies with text alone. Keep it that small on purpose. A loop you can read in one sitting makes it obvious where the model's judgement ends and the harness's responsibility begins.
Then break it on purpose. Point the agent at a directory containing a 3,000-line log and ask a question the answer to which sits in the middle of that log; notice how the response degrades and how much of the window the output consumed. Next, ask for a multi-step edit across two files, and send kill -9 to the process partway through a write. Inspect the file on disk, restart the agent, and read the transcript it rebuilds. Those two experiments, done by hand, are the foundation the rest of the course builds on.
AI-generated study article from SophistAI. Sign up free to study it with an AI tutor.