Harness Engineering for Agents
Prompt Context and Harness Engineering Compared
You've likely heard that building an agent means "just prompt the model." That view collapses three distinct layers of control into one, and it's the reason most agent projects fail to graduate from demo to production. Each layer owns a different set of decisions, interacts with the others through clean interfaces, and requires different engineering techniques. Understanding the separation is the difference between a prompt that sometimes works and a system that reliably produces correct behavior.
The three layers form a stack. Prompt engineering chooses what to say to the model on a single turn. Context engineering decides what information to include across the history of a conversation. Harness engineering builds the runtime infrastructure that executes the loop, enforces safety, and makes both prompt and context decisions actually matter. A change at any layer can break or fix the others; knowing which layer owns a given problem tells you where to invest your engineering effort.
Prompt Engineering Is Local, Context Engineering Is Global
Prompt engineering operates on a single model call. You choose the system instruction, the user message, and the tool definitions for one round trip. The goal is to maximize the probability that the model produces a correct action on that specific step. This is what most people mean when they say "prompting"—trying different phrasings, adding examples, adjusting the tone. It is fundamentally local: you optimize one input at a time, and the effect of a good prompt is immediate on the next model response.
Context engineering operates across the entire conversation. You decide what historical information to preserve, what to compress, what to discard, and what to inject dynamically on each turn. The goal is to keep the model's effective working memory focused on what matters without overflowing its context window. A perfect prompt on turn 50 is useless if the model has forgotten the file it was editing on turn 10 because you kept five full file reads in the history. Context engineering owns the tension between completeness and window limits.
The interaction is subtle. A context change can break a carefully tuned prompt: injecting a large diagnostic log changes the distribution of attention in the model's internal representations, shifting the probability of correct tool selection even if the prompt text is identical. Conversely, a prompt change can demand context changes: if you rewrite the system prompt to ask for more structured reasoning, you might need to keep more intermediate steps in the history for the pattern to work. The two layers must be co-designed, but they are not the same job.
The Harness Owns the Execution Contract
Harness engineering is everything that runs before, between, and after model calls. It manages the loop: calling the model, receiving the response, parsing tool calls, executing tools, formatting results, checking stop conditions, and deciding whether to call the model again. It enforces the limits that protect both cost and reliability: step caps, retry budgets, token budgets, timeouts. It handles failures that the model cannot recover from: a malformed tool response, a crash during execution, a context window overflow.
Prompt and context engineering determine what goes into the model. Harness engineering determines whether the model's output produces a safe, correct, and durable effect in the world. A harness that retries silently after a crash can hide a bug that the prompt never needs to handle. A harness that truncates tool output without warning can starve the context of information the prompt expected to be there. The harness does not decide what to say, but it decides whether what was said actually gets executed and whether the loop continues or stops.
The key insight: the harness is the only layer that can enforce constraints the model is not capable of respecting. A model cannot cap its own step count—it will keep calling tools indefinitely if the harness lets it. A model cannot distinguish between a harmless prompt injection attempt and a legitimate instruction—the harness must provide the safety boundary. The harness is where engineering rigor lives; the prompts are where intelligence lives, but intelligence without rigor is dangerous.
Failure Modes Reveal Layer Ownership
When an agent fails, the layer that caused the failure is often not the layer where the fix belongs. Consider a model that repeatedly calls a search tool with the same query because it didn't remember the previous results. The failure looks like a context problem (history missing the previous response), but the fix might be harness engineering: inject a memoization layer that deduplicates identical tool calls before they reach the model, or rewrite the tool interface to return a "you already asked this" response without consuming context tokens. The prompt didn't change, the context didn't change, but the harness absorbed the failure mode.
Consider the opposite: the model produces a valid tool call with incorrect arguments. The harness executed it correctly, the context was complete, but the output was wrong. That is a prompt engineering problem: the prompt failed to guide the model to the right choice. Fixing it demands changing the instruction, adding examples, or restructuring the tool schema. No amount of harness engineering can make a bad prompt good.
Consider a crash mid-turn: the sandbox running a bash command died, and the agent is left with a half-applied file edit and no record of what succeeded. Prompt and context are irrelevant—the harness must own crash recovery. It must log the partial state, replay from a safe checkpoint, or fail cleanly without corrupting data. This is pure infrastructure design, and no prompt can fix it.
These three failure archetypes—repetition, bad arguments, partial execution—map cleanly to context, prompt, and harness ownership. When you debug an agent failure, the first question is not what to change but which layer owns the problem.
The Layers Interact Through the Context Window
The context window is the physical shared resource that ties all three layers together. Prompt engineering consumes it (every token you write reduces space for history). Context engineering manages it (compression, truncation, injection). Harness engineering is constrained by it (you cannot execute more steps than fit in the window, and you must protect against overflow).
spec: static diagram of three horizontal bars stacked vertically. Top bar labelled "Prompt Engineering" contains a block "Current Turn: System + User + Tools". Middle bar labelled "Context Engineering" contains a chain of blocks "Turn 1", "Turn 2", ... "Turn N" with arrows between them, and a downward arrow feeding into the top bar's current turn block. Bottom bar labelled "Harness Engineering" contains blocks "Loop Control", "Tool Exec", "Safety Check" connected by arrows, with an upward arrow feeding into the context engineering bar. All three bars sit inside a bounding box labelled "Context Window Limit". The diagram shows that harness feeds context, context feeds prompt, and all three share the finite token budget.
The constraint creates design trade-offs that cross layer boundaries. A harness that executes many small tool calls produces a long history, forcing context engineering to compress more aggressively, which then changes what the prompt sees on the next turn. A prompt that asks for verbose reasoning consumes tokens that could otherwise keep historical tool outputs intact. There is no free lunch: every decision at one layer changes the available budget for the others.
Each Layer Has Its Own Testing and Debugging Methodology
Prompt engineering is tested offline: you collect a set of input-output pairs, vary the prompt, measure accuracy on held-out examples. The test is cheap, fast, and deterministic given the model. Context engineering is tested in simulation: you replay recorded conversations with different compression and injection strategies, measuring how much information is lost and whether the model still produces correct actions. The test is more expensive because it requires running the full loop, but the conditions are controlled.
Harness engineering is tested with fault injection: you crash the process mid-step, corrupt the tool output, overflow the context window, send invalid JSON from the model, and verify the harness handles each case without data loss or infinite loops. These tests are the most expensive because they require running the agent in production-like conditions with deliberate chaos. They are also the most important: a harness that survives chaos can protect the other two layers from the consequences of their own mistakes.
The three testing methodologies are complementary. Passing prompt tests does not guarantee the context stays healthy over 50 turns. Passing context simulations does not guarantee the harness survives a sandbox crash. You need all three, and you need to know which layer's tests failed when a production incident occurs.
AI-generated study article from SophistAI. Sign up free to study it with an AI tutor.