Skip to content
Recent Articles
3/5 - The Agent's Operating System: Harness Engineering Without the Hype
8 min · readRECENT ARTICLES

3/5 - The Agent's Operating System: Harness Engineering Without the Hype

#Harness Engineering #AI Agents #MCP #Agent Security
Abhishek Kumar
Abhishek Kumar

The model is not the agent. The agent is the model plus a runtime that assembles context, exposes tools, executes side effects, persists state, handles failure, verifies work, and leaves evidence for the next person or process. That runtime is the harness.

Calling the harness a wrapper understates the engineering. A wrapper forwards a request. A harness decides whether a tool call is authorized, whether its arguments satisfy a schema, how credentials are scoped, whether a retry can repeat a side effect, what state survives a restart, and what counts as a successful run. The model supplies suggestions; the harness supplies the boundary between suggestions and consequences.

The mental model: an operating system around inference

The harness should make the model useful without making it sovereign. It can offer tools as typed capabilities, route a model call, maintain a state machine, ask for approval, and verify outputs. It should not allow an untrusted string from a document or tool result to grant itself a credential or widen its authority.

The harness is the agent's operating systemHarness engineering covers the runtime responsibilities that make model-driven actions operable and safe.
The harness is the agent's operating system
The model sits inside a runtime that manages capabilities, state, policy, execution, and evidence.
1 · External contractAuthenticate the caller, bind tenant and deadline, and define the request and response contract.
2 · Context and planningAssemble the working set, expose typed capabilities, and preserve a stable run and trace identity.
3 · Policy and executionValidate tool arguments, broker credentials, enforce approvals, execute in a sandbox, and bound retries.
4 · Verification and evidenceCheck results, persist receipts and checkpoints, emit telemetry, and make resume behavior deterministic.
A harness turns a model suggestion into a controlled action. Every boundary needs identity, limits, failure semantics, and evidence.
Harness engineering covers the runtime responsibilities that make model-driven actions operable and safe.

Description: The layers are responsibilities, not necessarily separate services. A small application may implement them in one process. A larger platform may split policy, tool mediation, and durable state across services. The contract remains the same: the model can propose; the harness decides and records.

Tools are typed capabilities, not a bag of functions

A tool definition should include a stable name, version, argument schema, description, risk class, timeout, retry policy, and required permissions. Validate arguments before execution and validate results after execution. The tool service should receive a server-generated identity and scoped credential reference, not a raw secret copied from model output or client input.

Model Context Protocol, or MCP, standardizes a way for clients and servers to discover and invoke tools, resources, and prompts. It does not decide whether a caller is allowed to delete a record. That decision belongs to the harness and the system owning the resource. Treat the protocol as an interoperability boundary, then apply your own authentication, authorization, rate, and audit policy at that boundary.

A run is a state machine, not a log file

Represent the run explicitly: accepted, planning, awaiting approval, executing, verifying, paused, completed, failed, or cancelled. Persist transitions with an idempotency key and a monotonic revision. This avoids a familiar recovery bug where a worker restarts after the side effect but before the success record, then repeats the action because the log appears incomplete.

The harness around one model turnA robust harness keeps the model in a propose-and-observe cycle while it owns authority, state, and recovery.
The harness around one model turn
Every action crosses a policy boundary, and every observation becomes durable state before the next turn.
Goal and identityCaller, tenant, deadline, and requested outcome
Assemble contextTask state, evidence, policy, and available tools
Model decisionA typed suggestion, a response, or a tool request
AuthorizeCheck risk, scope, schema, approval, and idempotency
ExecuteRun with scoped credentials and bounded resources
Verify and recordCheck the result, emit a receipt, and checkpoint the run
The next model turn consumes the observation only after the harness has classified and recorded it.
The model can request an action; only the harness can turn that request into a side effect.
A robust harness keeps the model in a propose-and-observe cycle while it owns authority, state, and recovery.

Reliability details that matter

Timeouts need a budget hierarchy. The request deadline should bound the run; each model and tool call should receive a smaller remaining budget; retries should include backoff and jitter and must never extend the original deadline. A retry is safe only when the operation is idempotent or the harness has a deduplication key and a way to determine whether the first attempt took effect.

Idempotency is more than a UUID in a header. The resource owner must use it to recognize a repeated intent. For a payment, deployment, or database mutation, record the key with the result and make the key scope explicit. For a read-only lookup, a repeat may be harmless. For a tool that sends an email, “try again” must not mean “send twice.”

Keep credentials server-side. The model can receive a description of a capability and a reference to its result, but it should not receive a long-lived cloud key. Use short-lived, least-privilege credentials and log the credential reference, not its value. Redact secrets and personal data from traces while keeping enough metadata to investigate the action.

Where harnesses fail

The most dangerous failure is a confused deputy: the agent is authorized to call the harness, and the harness accidentally uses that authority for a different user, tenant, or document. Bind identity to every tool call and verify scope at the final resource boundary. The second is a partial side effect: the tool succeeds, the worker crashes before recording it, and a retry duplicates it. Idempotency and reconciliation belong in the design, not only in incident response.

Harness failure is authority failureThe harness owns the consequences of a tool call, so it must own the safety and recovery contract too.
Harness failure is authority failure
A model error is usually recoverable; an uncontrolled side effect can become a security and data-integrity incident.
A tool request crosses the boundary without complete policy stateIdentity, arguments, approval, or idempotency is missing or stale
CorrectnessWrong tenant or resourceInvalid result accepted as success
ReliabilityTimeout hides a completed side effectRetry creates a duplicate action
SecurityCredential scope is too broadUntrusted content becomes authority
Containment and recoveryDeny by default, reconcile the resource, bind approval to an argument digest, and resume only from a durable checkpoint.
A complete receipt should answer who requested what, under which policy, with which credential scope, and what the resource reported.
The harness owns the consequences of a tool call, so it must own the safety and recovery contract too.

Verification is not the model asking itself whether it is done

Verification should be as independent as the task allows. A code agent can run tests. A data agent can validate a schema and check row counts. A deployment agent can query health, version, and rollout state. A second model can help judge quality, but deterministic checks should own hard invariants. The harness should distinguish “the model produced a plausible answer” from “the requested state is true.”

Observability needs a single trace identity across model calls, tool calls, approvals, retries, and state transitions. Capture duration, queue time, input and output token counts, tool latency, error class, policy decision, and cost. Do not record raw secrets or unrestricted sensitive content merely because it is convenient. A trace that cannot be safely retained is not a reason to disable all evidence; redact and retain the operational shape.

A production recipe

Start with one read-only tool and one deterministic verifier. Define the run state machine and a durable receipt before adding autonomy. Add a write tool only after you can simulate denial, timeout after side effect, duplicate request, worker restart, expired credential, malformed arguments, and partial dependency failure. Test the recovery path with fault injection. The happy path is the least interesting harness test.

Use a capability registry so tools can be disabled or versioned without rebuilding every agent. Add policy decisions as data with a reason and snapshot ID. Keep approvals bound to exact intent, resource, argument digest, expiry, and actor. If any of those change, require a new decision. This makes resume safe and makes an audit explainable.

Primary references

The takeaway

Harness engineering is the operating-system work around model inference. It turns suggestions into bounded capabilities, actions into audited state transitions, and failures into recoverable outcomes. If a system has real side effects, the harness is not an accessory. It is the part that makes the agent trustworthy enough to run.

2/5 - The Working Set, Not the Window: Context Engineering for Agents4/5 - When Done Actually Means Done: Loop Engineering for Long-Running Agents