An agent harnesscontrols what surroundseach model call.
Agent harnesses:the system around the model.
The harness is the runtime wrapped around a model: it assembles context, runs the tool loop, enforces permissions, remembers the thread, and decides when the work is actually done.A harness is the software around the AI. It provides useful information and tools, saves progress, enforces permissions, and decides when the job is finished.
- MODELchooses the next movesuggests what to do next
- HARNESSvalidates and executes actionschecks and runs suggested actions
- CODING AGENTuses a harness for repository workuses that system for a coding job
text in → text out
WITH THE HARNESSintent → bounded work → evidence
The harness is the part that turns suggestions into a controlled process.The surrounding system turns an AI suggestion into a controlled job.
People often call the whole product “the agent.” Useful shorthand can obscure which component owns a behavior. Separating the model, harness, and job-specific workflow makes failures easier to locate.People often call the whole product “the agent,” but it has separate parts. Knowing which part thought, controlled, or acted makes problems easier to find.
Model
Interprets the prompt and proposes text or tool calls. It does not, by itself, own a filesystem, persist a thread, or enforce your approval rules.Reads the request and suggests words or actions. On its own, it cannot open files, remember a job, or enforce approval rules.
probabilisticsuggestsHarness
Builds each model input, routes tool calls, returns observations, manages context and session state, and applies runtime policy.Gives the AI its instructions and tools, saves progress, returns tool results, and enforces the rules around the task.
softwarecontrolsCoding agent
A model operating through a software-shaped harness with repository tools, instructions, tests, and a user experience for engineering work.The complete product: an AI working through this workspace with project files, instructions, checks, and a user interface.
systemdeliversModel quality affects judgment. Harness quality affects context, execution, permissions, state, and observability.The AI affects which step is suggested. The surrounding software affects what it can see, do, remember, and report.
Longer tasks require more runtime support.
Choose a task. The model stays the same while the required context, controls, persistence, and observability change.
Move token parsing to the boundary without changing behavior.
- 01maptrace callers + invariantsexecute
- 02patchedit multiple modulesapproval
- 03testobserve failureexecute
- 04recoverrevise the patchexecute
- 05handoffdiff + checks + caveatspersist
The loop is only half the story. Policy, context, recovery, and evidence keep the refactor bounded.
7 modules enabledA harness is runtime infrastructure inside an agent system.
During debugging, determine whether a mistake came from the model’s choice, the harness’s execution, or the coding workflow’s definition of success.
Runtime and orchestration software around one or more model calls.
A system or product that performs software-engineering tasks.
Loop, context assembly, sessions, tool routing, permissions, events, stop conditions.
The job: inspect the repo, plan, edit, test, recover, and report.
Not necessarily. A research, support, or browser agent also needs a harness.
Yes. Its tools, instructions, feedback, and success criteria are shaped around code.
Often. A good boundary lets the runtime evolve separately from the model.
Yes, but behavior still changes because the model is one major component of the full system.
Six responsibilities commonly handled by an agent harness.Six jobs handled by the software around the AI.
Implementations divide these responsibilities differently. All six are software behavior around the model.Products divide these jobs differently. They all come from software around the AI.
Input builderReading-pack builder
Combines system instructions, repository guidance, user intent, available tools, prior events, and relevant environment facts.Combines the main instructions, project rules, person’s request, available tools, earlier results, and useful facts about the current situation.
Context is selected, not dumped.Choose the useful material; do not dump everything.Loop controllerStep controller
Calls the model, distinguishes a final answer from a tool request, executes allowed actions, appends observations, and repeats.Calls the AI, recognizes an answer or tool request, runs allowed actions, saves what happened, and decides whether to continue.
A loop needs a budget and an exit.Every repeated job needs limits and a finish line.Tool routerTool router
Validates arguments, maps a requested tool to real infrastructure, normalizes results, and returns errors the model can act on.Checks the requested details, connects a known tool to the real service, cleans up the result, and returns useful errors.
A schema is not authorization.A well-shaped request still needs permission.Policy boundarySafety boundary
Applies sandbox scope, network rules, approvals, credential handling, and other constraints before side effects occur.Applies workspace limits, network rules, approvals, and careful handling of credentials before an action can have consequences.
Enforce outside the prompt.Use hard controls outside the AI instructions.State carrierProgress keeper
Persists threads and artifacts, compacts context, restores work, and keeps long tasks from depending on one model window.Saves conversations and files, summarizes older material, restores work, and keeps long jobs from depending on one short reading window.
The transcript is not the whole state.The chat transcript is not the whole job.Event recorderActivity recorder
Emits typed progress, tool calls, approvals, diffs, errors, usage, and traces so clients and operators can inspect the run.Records progress, actions, approvals, changes, errors, and usage so people can inspect what the job did.
If you cannot see it, you cannot tune it.If you cannot see it, you cannot improve it.Five rules for observable, controllable agent runtimes.
Harness assumptions age. Re-test which orchestration remains useful as models and tools improve.
- 01
Make the environment legible.
Put durable facts in inspectable files, schemas, commands, logs, and tests. Invisible tribal knowledge cannot steer a run.
- 02
Keep policy out of the model’s imagination.
Prompts explain. Sandboxes, validators, approval gates, and credential scopes enforce.
- 03
Preserve truth outside the context window.
For long work, persist plans, checkpoints, test state, and handoff notes where a fresh session can recover them.
- 04
Expose one clean action surface.
Tools should have sharp names, typed arguments, bounded outputs, actionable errors, and the least authority required.
- 05
Design the stop as carefully as the loop.
Define success, budgets, retry limits, escalation conditions, cancellation, and what evidence a final handoff must contain.
Four recurring harness failures.
Many apparent model failures come from stale context, permissive tools, hidden state, or weak stopping logic in the harness.
Over-constrained workflows
Fifty rigid steps make a capable model behave like a brittle macro.
Encode invariants and interfaces; leave local judgment to the model.
Prompt-only safety rules
The model is politely asked not to do something the runtime still allows.
Move hard boundaries into executable policy, sandboxing, and approvals.
State stored only in the transcript
A compacted or resumed run forgets what was changed, tested, or still broken.
Persist task truth in artifacts that survive the conversation window.
Missing completion criteria
The loop keeps finding plausible work because “done” was never operationalized.
Add budgets, explicit success checks, escalation, and a final evidence contract.
The harness validates and executes each model request.
This provider-neutral pseudocode shows the main boundaries: tool filtering, argument validation, authorization, sandboxed execution, event recording, state checkpoints, and external completion checks.
while (budget.remaining()) {
const input = context.build({
thread,
instructions,
tools: policy.allowedTools(),
workspace: await inspectEnvironment(),
});
const move = await model.respond(input);
events.record(move);
if (move.type === "final") {
return verifyHandoff(move, workspace);
}
const call = validate(move.toolCall);
await policy.authorize(call);
const observation = await sandbox.execute(call);
thread.append(observation);
if (context.needsCompaction()) {
await checkpoint.persist(thread, workspace);
thread = await context.compact(thread);
}
}
return escalate("Budget exhausted with unfinished work");Improve each layer separately. Evaluate the behavior of the whole system together.