How it works
A harness sits between the model and the world. The model proposes; the harness decides what actually runs. In practice it drives a loop:
- Assemble context. Gather the task, relevant memory, tool descriptions, and prior steps into the prompt.
- Sample an action. The model returns text, a tool call, or a final answer.
- Mediate the action. Validate the call against a schema, check permissions, and apply guardrails before anything executes.
- Execute in a bounded environment. Run the tool or code in a sandbox with scoped credentials and limits.
- Observe and record. Feed the result back, log the step, and update state.
- Repeat or stop. Continue until a stop condition, budget, or approval gate ends the run.
The model supplies judgment inside that loop; the harness supplies everything that makes the judgment safe to act on. Tools are the hands, memory and context management are the working set, the execution environment is where effects land, and guardrails plus permissions are the walls. None of this lives in the weights. A capable model with no harness can only emit text. The same model inside a well-built harness can edit a repository, call an API, or run a multi-step job—and can be stopped, inspected, and undone when it goes wrong.
Why it matters in an agent harness
The harness is where every property you care about in production is actually enforced. Model quality sets the ceiling on what an agent might do; the harness sets the floor on what it can do to your systems.
Control lives here: iteration budgets and approval gates decide how far a run proceeds before a human sees it. Reversibility lives here: checkpoints and rollback let you undo a bad trajectory instead of cleaning up after it. Observability lives here: the harness is the only component that sees every step, tool call, and result, so it is the only place you can log a full trace. Permissions live here: least-privilege scoping and sandboxing bound the blast radius when the model is wrong or gets prompt-injected.
Evaluation depends on it too. You cannot score an agent without capturing its trajectory, and the harness is what produces that record. When a run misbehaves, the fix is almost never "a smarter model"—it is a tighter tool surface, a missing guardrail, a stricter budget, or a checkpoint you forgot to write. Treat the harness as the primary engineering surface and most agent reliability problems become ordinary systems problems.
Agent harness vs agent framework
The two are easy to conflate but they answer different questions. A framework is a reusable library for building agents; a harness is the fitted control surface around one specific agent in one specific environment.
| Agent harness | Agent framework | |
|---|---|---|
| What it is | The runtime control layer around your agent | A library/toolkit for building agents |
| Scope | This agent, these tools, this environment | Many agents, general patterns |
| Owns | Permissions, budgets, checkpoints, logs | Abstractions, loop primitives, adapters |
| Optimized for | Control and reversibility in production | Reuse and developer velocity |
A framework can help you build a harness, but adopting one does not give you a harness for free. The permission boundaries, rollback strategy, and stop conditions specific to your systems are yours to fit. This distinction changes a decision: reach for a framework to move fast on structure, but never assume it has drawn the safety boundaries your environment needs.
The Rifty take
We optimize the harness for control and reversibility before speed or autonomy. A run you can stop, inspect, and undo is worth more than a faster one you cannot. We accept the tradeoff that mediation—schema checks, scoped credentials, budgets, checkpoints—adds latency and code, because that cost buys a system that holds together when the model is wrong. The boundary we enforce is simple: the model proposes, the harness disposes, and no effect reaches production without passing through the harness.
Implementation checks
- Every tool call is mediated. Nothing executes without schema validation, a permission check, and a log entry.
- Credentials are scoped per run. The harness holds least-privilege tokens; the model never sees raw secrets.
- Effects are bounded. Sandboxed execution and a clear blast-radius limit contain a wrong or injected action.
- State is checkpointed. You can roll a run back to a known-good point rather than repairing side effects by hand.
- Budgets and stop conditions exist. Iteration and tool budgets, plus approval gates, cap how far an unattended run proceeds.
- Trajectories are captured. Full step-level traces exist for every run so you can evaluate, debug, and replay.
- Failure is observable, not silent. A blocked action surfaces a clear reason instead of degrading into a confident wrong answer.
Frequently asked questions
What is the difference between an agent harness and a language model?
The model is a text predictor; the harness is the infrastructure that lets it act. The model supplies judgment—what to do next—while the harness supplies tools, memory, a bounded execution environment, permissions, and guardrails. Without a harness, a model can only emit text, not take real actions.
Does a better model reduce the need for a harness?
No. A stronger model raises capability but not control. Permissions, reversibility, budgets, and observability are enforced by the harness, not the weights. Better models often act on more systems, which makes tight tool surfaces, sandboxing, and checkpoints more important, not less. Reliability lives in the harness.
What belongs in the harness versus the prompt?
The prompt shapes intent and reasoning; the harness enforces boundaries. Anything that must hold even when the model is wrong—permission checks, credential scoping, schema validation, budgets, rollback—belongs in the harness. Relying on prompt instructions alone to prevent dangerous actions is a common and unsafe mistake.
How does an agent harness support reversibility?
By checkpointing state before consequential steps and mediating every effect through a single control point. Because the harness is the only component that sees each action, it can record a trajectory, snapshot state, and roll a run back to a known-good point—so you undo a bad path instead of repairing side effects manually.
Is an agent framework the same as an agent harness?
No. A framework is a reusable library for building agents; a harness is the fitted control surface around one specific agent and environment. A framework can help you build a harness, but it does not draw your permission boundaries, budgets, or rollback strategy—those are specific to your systems and remain yours to fit.