An agent harness is the software around an AI model that manages how it performs a task. It assembles context, calls the model, validates proposed actions, executes permitted tools and records what happened. It also decides how the work stops, waits for a person or continues in another session.
The model can propose a next step. The harness determines whether that step can actually run. That distinction becomes important when an agent can edit files, access company information or change an external system.
This article explains the responsibilities of a harness through a software maintenance example. It also separates the execution environment from the shared records a team needs when several people and agents participate in ongoing work.
What does the term include?
There is no single universal harness specification. Frameworks and teams use the term with different boundaries. LangChain's anatomy of a harness uses it broadly for the code, configuration and execution logic outside the model. Microsoft's Agent Framework documentation describes runtime scaffolding for model and tool calls, state, context and approval policies.
In practice, a harness can include an agent loop, tool adapters, permission checks, working storage, context management and recovery logic. It may use an existing framework for much of that behavior. A team does not have to build every part itself.
An instruction file can contribute guidance, but it is not a complete harness. A prompt describing an approval rule does not implement the rule. A tool adapter that checks authority before executing an action is part of the enforcement mechanism.
Similarly, a model SDK helps an application communicate with a provider. A framework can supply useful control structures. The actual configuration, exposed tools, persistence and operating rules still determine the behavior of the resulting agent.
The basic loop is simple; the boundaries are not
At a high level, an agent observes its current state, asks a model for a next step, validates that step and uses an allowed tool. The returned observation becomes input to a later decision. This continues until the task finishes or reaches a condition that requires stopping.
The difficult cases appear between those steps. What if the proposed tool does not exist? What if the user no longer has access to a source? What if the tool times out after it may already have changed something? What if the model says the task is finished without checking the result?
A harness needs explicit behavior for those cases. Retrying everything is unsafe when an action can create duplicates. Continuing indefinitely is unhelpful when the missing input requires a person. Accepting every well formed tool request can turn a structured response into an unauthorized action.
The loop should therefore have a task boundary, an action allowlist, input validation, resource limits and a completion check appropriate to the work. These are application responsibilities even when a framework supplies the implementation.
Example: a maintenance agent resumes after a pause
Imagine a software team asking an agent to prepare a fix for a recurring import problem. The agent can inspect an approved repository snapshot, edit a working copy and run a limited test command. It cannot merge the change or deploy the application.
This is an illustrative design example, not a report of a customer deployment or an executed Swarm Run. The repository, tests and observations are hypothetical. The example describes controls to implement, not capabilities automatically supplied by creating a Space.
The first session examines the supplied failure report and prepares a small change. A test fails because a fixture does not match the documented input. The session stops while the team checks which behavior is correct.
Without a useful checkpoint, the next session may repeat the investigation, treat the proposed change as accepted or rerun a command whose effects are unclear. The harness should preserve enough information to distinguish those states.
A checkpoint might identify the task, working revision, files changed, exact test result, missing decision and proposed next step. It should distinguish observations from the model's interpretation. “The test returned this failure” and “the fixture is wrong” are different claims.
On resume, the harness should check the current state again. The repository may have changed. The human may have rejected the proposed interpretation. The agent's earlier permissions may no longer apply. Loading a saved summary cannot substitute for those checks.
Context management decides what the model can use
Long tasks accumulate more information than should be sent to every model request. A harness may select current instructions, retrieve relevant records, summarize earlier work or keep references to material that can be read when needed.
Each choice can lose something important. A summary might omit that a test was inconclusive. A retrieved note may predate the current implementation. An instruction file may conflict with the user's latest decision.
Preserve stable references and distinguish current state from history. In the maintenance example, the next session needs the current task brief, accepted behavior and relevant test evidence. It may not need the entire earlier conversation. It must still be able to inspect the original failure when the summary is inadequate.
Anthropic's work on agents spanning several context windows describes an initializer and an incremental coding process that leaves records for later sessions. It is one implementation approach to a difficult continuity problem, not a universal guarantee of reliable autonomous work.
The broader principle is to make progress recoverable through inspectable state. Compressing a conversation is useful only if the next session can distinguish what was attempted, what was confirmed and what still requires a decision.
Tool access needs enforcement outside the prompt
Tools define what the agent can affect. Exposing a general shell or unrestricted network client creates a much larger action surface than exposing a small operation with validated arguments.
For the maintenance task, a narrow test operation might accept only the approved test target. A file operation might be confined to the working copy. A merge operation should remain unavailable unless the workflow explicitly authorizes it.
An allowlist is useful, but it is not a complete sandbox. A permitted command can still read sensitive environment data, load untrusted project code or consume excessive resources. Isolation, credential scope, network controls and resource limits need their own design.
Treat repository content and tool output as untrusted input. They can contain instructions that conflict with the task. Reading a file does not grant its author authority to change the agent's permissions.
The harness should validate arguments before execution, return bounded observations and retain the outcome. It should reject an unsupported request with a useful reason, not invent a successful tool result so that the conversation can continue.
Approval is a state transition, not a reassuring sentence
Human review must be connected to a specific proposed action or result. The reviewer needs to know what is being approved, which evidence supports it and whether anything changed while the proposal waited.
In the maintenance example, approval of the intended behavior is different from approval to merge a code change. Approval of a particular change does not automatically authorize later edits. A new revision may require a new decision.
Record the approved scope and check it at the action boundary. Do not accept the model's statement that a person approved something as the approval record itself. An agent cannot fulfill a human approval requirement by agreeing with its own proposal.
Also define what happens when approval is denied or expires. The useful result may be a checkpoint explaining the remaining question, with no external action taken. Waiting is a legitimate operating state when a person owns the next decision.
Recovery needs evidence about external effects
A tool timeout can leave the system uncertain. The action might have failed before starting, completed without a returned response or still be in progress. Blindly retrying can duplicate a message, booking or deployment.
Prefer operations that support safe repeat requests through an appropriate stable identity or an authoritative status check. The exact mechanism depends on the system that owns the action. The harness should preserve the request identity and returned confirmation where available.
For file changes and tests, inspect the actual working state before resuming. For an external operation, read its authoritative status before deciding to repeat it. A saved agent narrative is not enough to establish what changed outside the conversation.
Separate the objective from an attempt. Several attempts may belong to one task, and an interrupted attempt may leave useful partial work. Recovery should make that relationship clear without silently marking the whole task complete.
Put limits on work that can keep going
An agent that can take another step needs rules for when it should not. Useful limits include the number of model calls, elapsed time, tool attempts, output size and the cost or resources allowed for the assignment.
Detect repeated behavior as well as a numerical limit. If the agent reads the same record repeatedly without new evidence, the task may need clarification. If a tool keeps returning a permission error, increasing the attempt count does not solve the access problem.
Cancellation also needs a precise meaning. Stopping future model calls does not undo a message already sent or a file already written. A worker should check for cancellation at sensible boundaries, record partial work and report any action that could not be interrupted.
Limits should produce useful outcomes: completed, waiting for a decision, blocked on a named dependency or stopped with a recoverable checkpoint. A vague failure message makes the next participant repeat the diagnosis.
Evaluate the harness separately from the model
Some harness behavior can be tested without a model at all. Supply scripted decisions and assert that an unknown tool is rejected, an approval boundary is enforced, a repeated action is handled safely and the work stops at its budget.
Those tests establish control behavior, not the quality of model decisions. A live model evaluation needs representative tasks, realistic evidence and explicit acceptance criteria. Keep the two forms of evidence separate.
For the maintenance example, test a fresh attempt, a resume after a changed requirement, a failed test, an inaccessible file and an ambiguous external result. Check whether the next session can identify the current state from the retained records.
When comparing two harness configurations, keep the task and relevant model settings comparable. Record what changed in tool access, context selection, limits and completion rules. A successful demonstration cannot identify which change helped if everything changed at once.
Our guide to AI observability explains how available traces and source records can support that investigation. A trace still describes what was captured; it does not reveal private model reasoning or guarantee complete visibility.
Where Swarm fits alongside a harness
A harness governs an agent's execution. Swarm Spaces provide shared records for people and agents working on a project or program. Context, discussion, outputs, Runs and human decisions can persist beyond one local session.
In the maintenance example, the team could retain the task brief, relevant evidence, proposed fix summary and accepted decision in a Space. An authorized agent in another supported tool could inspect that record before continuing. Only material deliberately saved or connected becomes part of it.
The public guide distinguishes a saved Task from a Run attempt and from the executor that performs it. A connected agent needs an active execution route; saving work or adding a schedule does not keep a closed client working. Available execution controls and billing limits still apply.
Source access and sharing are separate. A link grants no additional permission, and a summary shared with another audience must be safe for that audience. Required human approval stays with humans. A successful Run or client reported trace needs an external confirmation before it proves an external effect.
The public connection guide describes the supported operations. It does not mean that every harness automatically integrates with Swarm or that a Space supplies a sandbox, repository isolation or every recovery rule described here. The integration must enforce its own local and external boundaries.
Choose a harness around the work it must protect
Start with the task and its consequences. Identify the evidence the model needs, the tools it may use, the actions that need approval and the state required for a safe resume.
An existing framework may already supply much of the machinery. Evaluate its behavior against those requirements before adding more abstraction. The important question is whether the complete system can make useful progress, stop for the right reasons and leave a record that another participant can understand.