Use this guide to map the runtime around an agent and decide which controls your team must own when building or selecting one.
What is an AI agent harness?
The industry does not yet have one settled definition of "agent harness." The term appears in current engineering writing to describe the machinery that wraps a model-driven loop: the code that manages state, assembles context, calls tools, enforces permissions, handles hand-offs, applies stopping conditions and records traces.
Anthropic's building effective agents guide distinguishes predefined workflows from agents that dynamically direct their own process. It recommends starting with the simplest workable design and describes patterns such as routing, parallelisation, orchestrator-worker and evaluator-optimizer loops. These are practitioner patterns, not proof that autonomy is needed or that a security boundary is created.
The component map below is an editorial synthesis. It names the responsibilities a team should assign to the harness layer, but it does not come from any single source.
This boundary is easiest to understand in a larger operating model: place the harness inside the wider internal knowledge system to separate organisation-level source approval and maintenance from the runtime controls described here.
Model, workflow, agent, SDK and harness: what changes?
These terms overlap in practice but refer to different layers:
- Model. The language model itself. It generates tokens from supplied context and may emit a structured request to use a tool. The surrounding application validates and executes that request, manages state and enforces permissions; the model does not make those controls effective by proposing a call.
- Workflow. A predefined sequence of steps. The path is fixed; the model fills in content at each step.
- Agent. A system that dynamically directs its own process, choosing which tools to call and when to stop, based on feedback from the environment.
- SDK. A software development kit that provides runtime primitives (loops, sessions, tracing) for building agents. An SDK is a mechanism, not a control.
- Harness. The application layer that uses a model, workflow or agent and adds the surrounding controls: state, context, tools, permissions, hand-offs, stopping, evaluation and observability.
A more autonomous architecture is not inherently better than a deterministic workflow. The task determines the appropriate level of autonomy.
The components of an agent harness
The component map below is an editorial synthesis. Each row names a responsibility, its inputs and outputs, the permission boundary it must respect, a failure signal and the evidence to retain.
| Component | Responsibility | Input | Output | Permission boundary | Failure signal | Evidence to retain |
|---|---|---|---|---|---|---|
| Model interface | Invoke the model with assembled context | Context, instructions | Generated tokens | Model access credentials, rate limits | Timeout, malformed output, refusal | Request and response logs |
| Orchestrator or loop | Direct the execution sequence | Task, state, feedback | Next action or stop | Action scope, tool permissions | Infinite loop, repeated failure | Loop trace, stopping decision |
| Context manager | Select and maintain runtime information | Instructions, tools, retrieved data, history | Assembled context | Context budget, source permissions | Context overflow, stale data | Context snapshot, selection log |
| State or session store | Persist conversation and working state | Previous state, new events | Updated state | Session isolation, data retention | State corruption, cross-session leak | State version, access log |
| Tool gateway | Mediate tool calls and results | Tool request, parameters | Tool result | Tool permissions, rate limits | Tool error, timeout, unauthorised call | Tool call log, permission decision |
| Identity and permissions | Authenticate the subject and authorise actions | Subject identity, requested action | Authorisation decision | Policy, attribute freshness | Permission denied, stale attribute | Decision log, policy version |
| Guardrails | Constrain model output or tool use | Generated content, tool request | Filtered or blocked output | Guardrail policy | Guardrail trigger, false positive | Trigger log, policy version |
| Human intervention | Escalate to a human for review or approval | Escalation trigger, context | Human decision | Approval authority | Timeout, no response | Escalation log, decision |
| Tracing | Record execution for diagnosis and evaluation | All component events | Trace record | Data retention, access control | Missing spans, incomplete trace | Trace ID, retention policy |
| Evaluation | Measure behaviour against criteria | Test cases, outputs | Scores, flags | Evaluation scope | Regression, threshold breach | Test results, baseline |
| Stopping conditions | Determine when the agent should stop | Feedback, budget, error state | Stop or continue | Budget limits, error thresholds | Premature stop, failure to stop | Stop reason, budget consumed |
Execution loops, state and stopping conditions
The execution loop does the central runtime work. It receives a task, assembles context, invokes the model, interprets the output, calls tools if needed, updates state and decides whether to continue or stop.
Give stopping conditions the same attention as the happy path. Without a reliable stop, an agent can loop indefinitely, consume budget or take unintended actions. Set explicit conditions such as maximum iterations, budget exhaustion, an error threshold, a task-completion signal or human override.
State management must handle persistence, isolation and cleanup. A session store that leaks state across users or that retains data beyond its retention policy is a privacy and security risk. The OpenAI Agents SDK documentation describes one concrete implementation of runtime primitives including sessions, hand-offs, guardrails, tracing and human intervention. That SDK is living documentation; features do not establish correct permissions or safe behaviour.
Context, memory and retrieval interfaces
The harness's context manager selects and maintains the information available to the model at inference time. This includes instructions, tool definitions, retrieved knowledge, interaction history and working state.
Anthropic's context engineering guide describes context engineering as selecting and maintaining the information available to a model at inference time, including instructions, tool definitions, retrieved data and interaction history. It argues for a compact, high-signal context and describes just-in-time retrieval, compaction and notes as possible techniques. This is conceptual practitioner guidance, not a universal context design.
At the context layer, design the context supplied to the agent so that the information at inference time is task-relevant, permission-respecting and within budget.
When the harness retrieves knowledge from an external corpus, it connects to a RAG pipeline. The RAG pipeline architecture guide covers the ingestion and runtime stages that supply retrieved context to the harness.
Tools, permissions and constrained actions
The tool gateway is one important enforcement point in this harness design, alongside identity, service and data-layer controls. Before executing a requested tool call, the application should make a current authorisation decision for the subject, action and resource. A tool that can change an external system needs tighter constraints and approval rules than a read-only tool over public information.
The NCSC's secure design guidance supports least privilege, input checks and constraining AI-triggered actions. In a harness, this means:
- Each tool has a defined permission scope.
- The subject's identity and attributes are checked before each tool call.
- Tool parameters are validated and constrained.
- High-impact actions require human approval or additional authorisation.
The Model Context Protocol specification (revision 2026-07-28) defines a host-client-server protocol through which servers can expose resources, prompts and tools. The specification assigns implementers responsibility for consent, authorisation, privacy and access-control decisions. MCP is not a sandbox, vector database, RAG architecture or trust mechanism. Protocol conformance does not make a server, tool, resource or result safe.
When the harness consumes retrieved knowledge, permissions must be preserved during retrieval. The RAG access control guide covers how source permissions survive chunking, indexing and retrieval.
Hand-offs, human intervention and failure handling
Hand-offs transfer control between agents, between an agent and a human, or between an agent and a deterministic workflow. A hand-off should record:
- The reason for the hand-off.
- The state being transferred.
- The permissions that apply to the receiving component.
- The evidence to retain for audit.
Human intervention is a control, not a failure. Design escalation paths for:
- High-impact actions that require approval.
- Ambiguous or low-confidence situations.
- Permission errors or policy conflicts.
- Repeated tool failures.
Make failure handling explicit too. Decide what happens when a tool times out, the model produces malformed output, a permission check fails or the stopping condition is not met within budget.
Tracing, evaluation and observability
Tracing records the execution path for diagnosis and evaluation. A useful trace includes:
- Each model invocation with its context and output.
- Each tool call with its parameters, result and permission decision.
- Each state transition.
- Each stopping decision and its reason.
- Each guardrail trigger.
Evaluation measures behaviour against criteria. The harness should support:
- Representative test cases for the defined task.
- Regression detection when the model, tools or context change.
- Permission and security test cases.
- Budget and latency monitoring.
The RAG security guide covers the system-wide threat model that applies when the harness consumes retrieved knowledge, including prompt injection, poisoning and permission leakage.
Check documents before an agent uses them
An agent harness controls which context and tools an agent can use. Documents deserve their own intake checkpoint before they become part of that context.
.mdSiren is a document security workspace for AI. When it launches, Standard Scan will check the exact document version for supported prompt-injection and document-borne risks, route it to Approved, Needs review or Quarantine, and keep the Approved exact version in your private Library. If the file changes, check the new version. The harness must still enforce identity, permissions, tools and downstream actions.
See how the document checkpoint works.
Build, adopt or combine runtime components
The following table is organised by control ownership, not as a vendor ranking.
| Decision | Build in-house | Adopt an SDK or framework | Combine |
|---|---|---|---|
| When to choose | You need custom permission logic, unusual tool contracts, or strict data-residency constraints | You need standard primitives (loops, sessions, tracing) and can accept the SDK's design | You adopt an SDK for standard primitives but build custom tool gateways, permission checks and evaluation |
| Control ownership | You own all components and their failure modes | The SDK owner maintains primitives; you own configuration, tools and permissions | You own the custom layer; the SDK owner maintains the standard layer |
| Risk | Higher implementation burden; you must test every component | You inherit the SDK's design decisions and update cadence | You must manage the boundary between custom and adopted components |
| Evidence to retain | Full component test results, permission decision logs, trace records | SDK version, configuration, tool definitions, permission policy | Both sets, plus the integration test results at the boundary |
Choose the mix around the task, its risk profile and the team's capabilities. There is no universal answer.
Frequently asked questions
What does an AI agent harness do? It wraps a model-driven loop with the surrounding controls: state, context, tools, permissions, hand-offs, stopping conditions, evaluation and observability. It is the application layer, not the model itself.
Is an agent harness the same as an agent framework? An agent framework is a specific implementation that provides runtime primitives. An agent harness is the broader concept of the control layer around an agent. A framework can be part of a harness, but a harness is not limited to one framework.
Is it the same as an evaluation harness? No. An evaluation harness is a test rig that measures behaviour. An agent harness is the runtime that executes the agent. They are different jobs, though they share some infrastructure.
Does every AI workflow need one? A simple deterministic workflow may not need every component in this map. As a system adds adaptive routing, tools, persistent state or higher-impact actions, the case for assigning explicit harness responsibilities grows. The task and risk determine the required controls; the label itself does not.
Where do RAG and context engineering fit? RAG supplies retrieved knowledge to the context. Context engineering selects and maintains the information at inference time. The harness's context manager is the component that assembles that information. The RAG pipeline and context engineering are input subsystems, not synonyms for the harness.
Does MCP secure an agent's tools? No. MCP is a connection protocol. It defines how a host communicates with servers that expose resources, prompts and tools. It does not provide a sandbox, enforce permissions or guarantee safety. The implementer is responsible for consent, authorisation and access-control decisions.
