What Is an Agent Harness? Components, Risks, and Design

An agent harness is the software around a language model that turns model output into a controlled sequence of actions. It supplies instructions and tools, decides when a tool call may run, records state, returns results to the model, applies limits, and determines when the task is complete.

The term does not have one universal specification. Teams may call overlapping layers a harness, scaffold, agent runtime, framework, or orchestration system. The useful question is not which label is correct, but which responsibilities exist and who owns them.

A model is not the whole agent

A language model can produce text or a structured request such as “run this test.” It does not independently open a terminal or modify a database. The application receives that request, checks it, executes an allowed tool, captures the result, and sends the result back for the next model turn.

A simplified loop looks like this:

1. The application assembles instructions, user input, and relevant state.
2. The model returns an answer or a structured tool call.
3. The harness validates the tool name and arguments.
4. A permission policy allows, blocks, or pauses the call for approval.
5. The tool runs in an appropriate environment.
6. The harness records and normalizes the result.
7. The model receives the result and decides the next step.
8. The run ends when a completion condition, limit, error, or human decision is reached.

The shorthand agent = model + harness is a helpful mental model, not a formal industry equation. The same model can behave very differently when its tool descriptions, context selection, permissions, execution environment, and verification loop change.

What belongs in an agent harness?

Component	Responsibility	Failure if omitted or weak
Instructions and context	Define the goal, constraints, available evidence, and output contract	Irrelevant, inconsistent, or policy-breaking behavior
Agent loop	Coordinate model turns, tool results, stop conditions, and errors	A chatbot response instead of completed work, or an uncontrolled loop
Tool registry	Expose typed, documented actions	Malformed calls, excessive capability, or ambiguous results
State and memory	Track current progress and, where needed, history across runs	Repeated work, lost decisions, or oversized context
Execution environment	Run code, browse, or access files and services	No real action, or unsafe action on the host
Permissions and approvals	Limit what can be read, changed, sent, or deleted	Unauthorized or irreversible operations
Validation	Check schemas, tests, invariants, and final outputs	Plausible results accepted without evidence
Observability	Record model calls, tools, latency, errors, and outcomes	Failures that cannot be reproduced or improved
Recovery	Handle timeouts, retries, checkpoints, and cancellation	Duplicate side effects or work lost after interruption

Not every system needs every row. A one-turn read-only assistant may need no durable memory, subagents, or sandbox. A long-running coding or operations agent usually needs most of them.

Harness engineering is more than prompt editing

Mitchell Hashimoto described “harness engineering” in a February 2026 account of his AI adoption: when an agent makes a recurring mistake, change the surrounding system so that mistake is less likely or impossible to repeat. His original post presents it as a personal term rather than a settled standard.

That practice turns a failure into a durable control:

Observed failure	Weak response	Harness improvement
Agent edits generated files	Add “please avoid generated files” to every prompt	Mark paths read-only and add a check that rejects generated-file diffs
Agent claims tests passed without running them	Ask for more confidence	Require a test command and attach captured output to completion
Tool receives malformed parameters	Retry the same free-form request	Use a strict schema, validation, and a clear tool error
Agent repeats a non-idempotent action	Tell it to be careful	Add an idempotency key and record committed side effects
Secrets appear in traces	Delete the visible log manually	Redact sensitive fields before storage and restrict trace access

Prompts remain part of the harness, but deterministic constraints are usually stronger than prose for rules that must always hold.

Instructions and progressive context

The harness decides what the model sees. This can include a system instruction, repository rules such as AGENTS.md, tool descriptions, retrieved documents, recent messages, and a summary of earlier work.

Loading everything at once can waste tokens and bury the relevant rule. A progressive approach gives the model a concise index first, then loads detailed procedures or reference material only when the task requires them. LangChain’s Deep Agents context-engineering documentation describes middleware that adds tool-specific instructions for built-in filesystem, subagent, and planning capabilities.

Useful context controls include:

• authoritative-source ranking;
• file and document allowlists;
• version or timestamp metadata;
• retrieval limits and relevance thresholds;
• clear separation of instructions from untrusted content; and
• summaries that link back to the underlying evidence.

Context is not truth. Retrieved text can be obsolete, malicious, or misclassified, so the harness should preserve provenance and avoid treating tool output as trusted instructions.

Tools turn decisions into actions

A tool should expose one bounded capability with a clear name, typed arguments, predictable results, documented errors, and an explicit authority level. “Run anything” is harder to secure and test than “read this approved file” or “create a draft issue in this project.”

For each tool, define:

• who or what may call it;
• which resources and credentials it can access;
• whether it reads, writes, sends, purchases, or deletes;
• argument schema and size limits;
• timeout and cancellation behavior;
• whether repeating the call is safe;
• what evidence the result returns; and
• which calls require human approval.

Model Context Protocol (MCP) can standardize how an application discovers tools and context from external servers. It does not make a server trustworthy. OpenAI’s Agents SDK MCP guide recommends trusting servers before connecting, using least-privilege credentials, filtering tools, and requiring approval for sensitive operations.

State is not one kind of memory

“Memory” often conflates several different stores:

• Run state: current plan, completed steps, tool results, and outstanding approvals
• Conversation history: prior messages needed for a multi-turn interaction
• Artifacts: files, code, reports, and structured outputs created during work
• Durable preferences: approved user or organization settings that apply across runs
• Operational records: idempotency keys, committed side effects, checkpoints, and audit logs

A short agent may need only run state in memory. A long-running workflow needs durable checkpoints. A personalized assistant may need carefully governed cross-session preferences. Do not retain all conversation content indefinitely simply because storage is available.

The OpenAI Agents SDK session documentation describes session memory for conversation history and resumable approvals. Production designs still need retention, access-control, encryption, deletion, and data-residency decisions outside the basic session API.

Execution requires a real security boundary

When an agent can run shell commands or code, a temporary working directory is not automatically a sandbox. A useful isolation boundary restricts filesystem access, process privileges, credentials, network destinations, resource consumption, and lifetime.

Prefer:

• a separate container or virtualized environment per untrusted task;
• non-root execution and a minimal filesystem mount;
• no production secrets by default;
• network disabled or allowlisted;
• CPU, memory, process, disk, and time limits;
• ephemeral credentials scoped to one task; and
• artifact export through a controlled channel.

LangChain’s Deep Agents sandbox documentation similarly treats the sandbox as a boundary between agent execution and host files, credentials, and network access.

Permissions and guardrails need layers

A model-level refusal is not an authorization system. Enforce important boundaries in code and infrastructure:

1. Capability selection: do not expose unnecessary tools.
2. Credential scope: give each tool the least authority it requires.
3. Argument validation: reject invalid paths, recipients, amounts, queries, or payloads.
4. Approval: pause before consequential or ambiguous actions.
5. Postcondition checks: verify what actually changed.
6. Audit and revocation: record the decision and retain a way to stop or undo work.

OpenAI’s guardrail documentation distinguishes checks on initial input, final output, and each custom function-tool call. That distinction matters: an output check cannot prevent a harmful side effect that already occurred during a tool call.

Verification makes an agent more than a generator

For a coding agent, “the code looks right” is not a completion criterion. The harness can require syntax checks, unit tests, type checks, linting, security scans, and a clean diff. Other domains need their own test oracles:

• validate a report against source records;
• recalculate spreadsheet totals independently;
• preview an outbound message and resolve its recipient;
• compare a database change against row-count and authorization limits;
• verify a deployed service with health checks and rollback conditions.

Make the completion contract machine-checkable where possible. When no deterministic test exists, use an explicit human review rather than presenting model confidence as evidence.

Retries and recovery can create new failures

A harness must distinguish safe retry from repeated side effects. Reading a file is usually safe to repeat; charging a card, sending an email, or deleting a record is not.

For consequential tools:

• use idempotency keys or transaction identifiers;
• persist whether the action was committed;
• separate “prepare” from “execute”;
• reconcile uncertain outcomes before retrying;
• cap attempts with backoff; and
• provide cancellation and rollback where the external system permits them.

A checkpoint should include enough structured state to resume safely, not merely a prose summary that says “continue from step four.”

Observability must help without leaking data

Agent traces can record model turns, tool calls, handoffs, approvals, errors, token usage, latency, and cost. The OpenAI Agents SDK, for example, provides built-in tracing for agent runs.

Before enabling full traces in production, decide:

• which prompts, tool inputs, and outputs contain sensitive data;
• which fields must be redacted before storage;
• who can read traces and for how long;
• how a user can request deletion;
• how traces connect to real task outcomes; and
• what alert indicates looping, unusual tool use, or repeated failure.

Observability is not just a debugging feed. It should reveal whether the agent achieved the requested result, how often humans corrected it, and which controls prevented failures.

When do subagents help?

Subagents can isolate context, specialize instructions, or run independent investigations. They also add cost, latency, failure modes, and synthesis work. A supervisor that delegates poorly can produce more noise than one well-scoped agent.

Use a subagent when:

• the workstream is independent;
• its context would distract the main agent;
• it has a distinct tool or permission set;
• its output can be checked through a clear contract; or
• parallel execution materially reduces elapsed time.

Keep the task in one loop when steps share the same files, depend on rapidly changing assumptions, or require continuous integration. LangChain’s subagent guide describes context isolation as a primary benefit.

Harness, framework, SDK, runtime, and orchestrator

Term	Typical emphasis
SDK or framework	APIs and building blocks for defining agents, tools, handoffs, and policies
Runtime	Executing loops, maintaining state, scheduling work, retrying, and resuming
Orchestrator	Routing work across agents, services, queues, or people
Harness	The assembled operating environment around a model for a particular class of work
Product	The user-facing application, which may contain all of the above

The boundaries overlap. LangChain describes Deep Agents as an opinionated harness with filesystem context management, subagents, memory, and optional planning. The OpenAI Agents SDK provides an agent loop, tools, sessions, handoffs, guardrails, sandboxes, and tracing. A team can also build a small custom harness without adopting a full framework.

Start with the smallest system that closes the loop

A practical development sequence is:

1. Define one narrow task and an objective success test.
2. Use a single model call if that solves it reliably.
3. Add one typed tool only when external action or evidence is necessary.
4. Enforce least privilege and a turn, time, and cost budget.
5. Add deterministic validation and a human checkpoint for consequential actions.
6. Trace failures with redaction.
7. Add durable state only if work must resume.
8. Add subagents or orchestration only after measurement shows a benefit.

TipsMake’s list of Python libraries for LLM applications can help map these responsibilities to implementation options. The LLMOps tools guide covers evaluation, tracing, and guardrail categories that become important after a prototype works. For a less code-heavy route, compare no-code agent platforms by their permissions and operating controls, not only their model list.

Evaluate the harness, not only the model

Test the assembled system on representative tasks and failure cases. Measure task success, factual or test accuracy, unsafe-action rate, human corrections, retry behavior, latency, cost, and recovery after interruption. Repeat key evaluations when the model, prompts, tools, permissions, or runtime changes.

The central idea is straightforward: a capable model proposes actions, while the harness decides what context it receives, which actions are possible, how they run, what evidence counts, and when a human must intervene. Agent reliability therefore depends on the surrounding engineering at least as much as on a model benchmark.