An Agent harness is the software around an AI agent that makes it usable in a real system. The model may decide what to do next, but the harness decides what it can see, which actions it may request, where those actions run, how long work survives, and what happens when something fails.

That distinction is becoming harder to ignore. On September 3, Cursor Cloud Agents gained an option to run in Vercel Sandbox rather than Cursor-hosted machines. In the announced design, Vercel Functions and Workflow handle queued work, provisioning, monitoring, and cleanup, while Vercel Sandbox supplies an isolated Firecracker microVM for each agent request. Vercel’s announcement is a useful concrete example of a broader architectural point: an agent in production is not a model call with a few tools attached. It is a control system plus one or more execution environments.

The model is not the system

A model is the component that turns supplied input into generated output: prose, a proposed plan, a tool call, or code. In an agent loop, it receives Context, suggests an action, observes the result, and repeats. It is good at choosing among possibilities, but it is not a reliable place to implement security boundaries, retry semantics, secret handling, or operational policy.

The harness is the trusted layer around that loop. It accepts a task, assembles the relevant Context, calls the model, validates and routes requested actions, records the outcome, and decides whether another step is allowed. It also connects the agent to Tools: bounded interfaces for actions such as reading a repository, opening a ticket, running tests, or querying a service.

Vercel describes a harness as orchestration software that contains tools and connections to external services, distinct from the model-driven agent itself. Its architecture guidance also recommends keeping the harness and its secrets in a different security context from generated-code execution. This is less a branding distinction than a useful line of responsibility.

Plain English: The model can suggest an action. The harness decides whether that action is possible, permitted, recorded, and safely carried out.

“Agent” makes this confusing because it can mean either the model-driven behavior or the full assembled application. Treating an agent harness as a named architectural component removes ambiguity. In a design review, you can ask: what is agent policy, what belongs to the harness, and what runs outside both in an isolated environment?

Why this boundary matters now

Early agent prototypes often run everything in one process: prompt, model call, shell access, credentials, working directory, and retry logic. That is fast to build. It is also a poor fit for an agent that can handle untrusted repository content, execute generated code, call third-party services, or work long enough to encounter a transient failure.

The Cursor–Vercel integration makes the separation visible. The durable control-plane work—queueing requests, creating workers, monitoring them, and cleaning them up—does not have to occur inside the same machine that runs code the agent generated. Each request can receive an isolated microVM. The announcement also describes scale-to-zero workers, short-lived user-scoped credentials, and durable retries. Those are properties of the surrounding architecture, not qualities that emerge from the model.

A control plane is the part of a system that directs and observes work: it schedules, configures, authorizes, monitors, and terminates execution. The code that actually runs tests or scripts is the data plane in this simplified framing. A harness commonly sits at this boundary. It translates an agent’s evolving plan into controlled work requests and turns results back into Context for the next model call.

This matters especially for coding agents. A generated test command might consume a large amount of CPU, alter a database, leak an environment variable through logs, or hang indefinitely. The agent may be acting in good faith and still make a bad choice. Giving it a constrained interface and a disposable runtime reduces the blast radius. It does not make the output correct, but it means a flawed output has fewer places to cause damage.

How an agent harness works

The exact implementation differs by product and team, and the word “harness” is not fully standardized. Still, the operating sequence is fairly stable.

First, the harness receives a task and establishes a session. It selects the model and builds Context from the task, repository state, relevant prior work, and any policy messages. Context Engineering is the deliberate work of choosing, structuring, and limiting that information so the model has what it needs without being flooded by irrelevant or unsafe material.

Second, the harness exposes a small set of Tools. A Tool should have a defined input, expected output, authorization rule, timeout, and audit trail. “Run arbitrary shell command on production” is not a well-bounded Tool. “Run this test target in an isolated workspace with a fixed time limit” is much closer.

Third, when the model asks for an action, the harness applies policy before execution. It can reject the request, require approval, narrow parameters, or issue short-lived Credentials scoped to that single action. The model should not receive durable infrastructure secrets merely because it needs to use a service once.

Fourth, the harness sends risky or failure-prone work to a Sandbox. A Sandbox is an isolated execution environment intended to limit what code can access. In the Cursor–Vercel design, that role is played by a Firecracker microVM per request. Vercel describes the microVM isolation here. The harness remains outside the Sandbox, keeps its secrets separate, and passes in only the files, network access, and credentials required for the task.

Fifth, the harness collects results, records Telemetry, and either stops or continues the loop. Telemetry means operational signals such as tool inputs and outputs, timing, errors, resource use, approval decisions, and model-call metadata. It is how an engineering team can reconstruct why an agent changed a file, retried a task, or failed at a boundary.

Finally, long-running work needs durable orchestration. A Workflow is a managed sequence of steps that can keep track of progress across interruptions and retries. A workflow engine can provide the durable state transitions; the harness adds agent-specific responsibilities such as model interaction, Context assembly, Tool policy, and approvals. Vercel’s coding-agent guidance identifies durable orchestration, isolated execution, and model-access infrastructure as separate responsibilities. That decomposition is worth preserving even if you do not use Vercel.

Plain English: Put the agent’s decisions, the authority to act, and the risky execution in separate places. Then a failure in one place is less likely to become a failure everywhere.

What a harness is not

A harness is not the model. Switching models should ideally change an adapter or configuration, not force a rewrite of authorization and execution policy. It is not a Sandbox, either: the Sandbox confines execution; the harness provisions it, limits it, communicates with it, and disposes of it.

It is also not merely a workflow orchestrator. A workflow system is excellent at steps, state, waiting, and retries. It does not automatically know how to select model Context, interpret a Tool request, or distinguish a harmless file read from a destructive deployment. Conversely, a tool gateway alone can expose services through a controlled endpoint, but it does not supply the agent loop, session lifecycle, or broader operating model.

Vercel’s AI SDK 7 uses HarnessAgent for a common interface around established harnesses including Claude Code, Codex, and Pi, with configurable sandboxes, tools, and Skills. That abstraction is useful, but it also illustrates a portability trap. A shared interface can normalize how software invokes agents without making their permission models, tool semantics, Context behavior, or runtime guarantees identical.

A practical example: an internal pull-request repair agent

Imagine a hypothetical service that receives a failing CI job and asks an agent to propose a repair. The unsafe version gives the agent a repository checkout, a broad CI token, shell access, and permission to push a branch. It might work until a prompt injection in an issue, a malicious dependency script, or a mistaken command crosses a boundary.

A harness-oriented version separates the concerns.

The harness creates a task record and provides the model with the failing test output, selected files, and repository conventions. It offers tightly scoped Tools: inspect permitted paths, create a patch, run a named test target, and request a human review. The model can propose a fix, but it cannot directly choose a host machine, browse unrelated secrets, or push code.

For test execution, the harness creates an ephemeral Sandbox with a read-only source snapshot, a writable temporary workspace, a restrictive network policy, resource limits, and a credential that can access only the required package registry if one is necessary. The test result and patch return to the harness. If the agent wants to retry, the Workflow resumes from recorded state rather than reconstructing the task from scratch.

A human approval gate sits before any irreversible action, such as opening a pull request or applying a production configuration change. The harness records the proposed diff, Tool calls, test results, and approval. This does not establish that the patch is good. It establishes who or what did what, under which authority, and in which environment.

That is the real benefit: not autonomous code generation, but an inspectable path from suggestion to constrained action.

Where the design breaks

A harness is containment, not proof of safety. The model can still misunderstand a task, be manipulated by hostile text, select an unsuitable Tool, or produce subtly wrong code. Tool output can itself be untrusted; a malicious web page, log line, or repository file can try to steer later model decisions. Treating every Tool result as trustworthy Context is an avoidable mistake.

Sandboxing also has limits. Isolation depends on the actual configuration of mounts, networking, egress rules, inter-process channels, and credentials. A microVM that receives a powerful production token or unrestricted network access may be isolated from the host while still able to do unacceptable work elsewhere.

Reliability creates a separate class of bug. Retrying a failed “read file” action is normally harmless; retrying “create invoice” or “deploy change” may repeat a side effect. Design externally visible Tools for idempotency, meaning that repeating the same request has the intended effect once rather than many times, or provide a compensating action when that is impossible. Durable retries are valuable, but they must be paired with durable semantics.

Finally, separation adds moving parts: session state, queues, trace correlation, timeouts, cleanup, and debugging across security contexts. A harness can become an opaque platform if its policies and traces are not legible. The right response is not to collapse the layers again. It is to make their contracts explicit and test them.

Plain English: A harness reduces risk and makes failures easier to investigate. It cannot turn an error-prone model into a perfectly safe operator.

What you can do this week

Start by drawing your current agent path. Mark where model calls occur; where Context comes from; which Tools exist; where secrets live; where generated code runs; and who can approve consequential actions. If all of those marks land in one process or one long-lived machine, you have found a design assumption worth challenging.

Next, define Tool contracts before improving prompts. Give every Tool a narrow purpose, explicit input validation, timeout, authorization policy, and observable outcome. Separate read-only discovery from state-changing actions. Require confirmation or review for actions that publish, spend money, alter production, or expose data.

Then move generated-code execution into an ephemeral, least-privilege environment. Start with one risky step—tests, dependency installation, or repository analysis—rather than redesigning the whole system. Verify the details: mounted paths, outbound networking, credential scope, cleanup, and resource limits.

Finally, make failure a first-class test case. Interrupt a task halfway through. Cause a Tool timeout. Replay a retry. Feed the agent misleading text in a fixture. Confirm that the harness records enough Telemetry to explain the outcome and that no repeated side effect occurs. The Vercel material frames tool loops, tool design, Context management, Sandbox lifecycle, human controls, planning, and verification as separate engineering concerns. That is a strong checklist for your own architecture.

The important question is not whether your product “has an agent.” It is whether the system around that agent can safely grant, constrain, observe, and revoke its ability to act.