What is an agent harness?
An agent harness is the runtime code around a language model that turns it into an agent able to finish a task. Microsoft's Agent Framework documentation defines it as "the runtime scaffolding that turns a language model into an agent that can perform work". The harness drives the model and tool calls, manages conversation state and context, applies approval policies and can keep the agent moving through a task with many steps.
LangChain draws the line more sharply in The anatomy of an agent harness. Its definition reads: "A harness is every piece of code, configuration, and execution logic that isn't the model itself." The same article sums it up as Agent = Model + Harness. The model decides what to do next. The loop that runs a tool call and feeds the result back, the file the agent keeps notes in and the rule that stops a dangerous command all belong to the harness.
In plain words
A horse is strong, but on its own it pulls nothing and nobody steers it. The harness hitches it to the cart, and the reins let a driver decide where it goes. A language model is the horse. It brings the ability. The agent harness is the gear that connects that ability to real work (files, tools, a task list) and keeps a person holding the reins.
What a harness does
Harnesses differ in detail, but most of them take care of the same jobs:
- The agent loop. The harness sends the request to the model, runs the tools the model asks for through function calling, returns the results and repeats. Microsoft's harness runs this loop "with a configurable per-request iteration limit".
- Context. It decides what goes into the context window: the system prompt, instruction files such as AGENTS.md, tool descriptions and history. When the history grows, it compacts it, because a full window degrades the answers (context rot).
- Tools and capabilities. A shell, file editing, web search, MCP servers and skills.
- Permissions. It decides which tool calls run on their own and which wait for a person's approval, the core of human-in-the-loop control.
- State and memory. Files, task lists and progress notes that outlive a single context window. See agentic memory.
- Orchestration. Starting subagents, handing work over and choosing a model for each step.
- Deterministic checks. Code that runs at fixed points whatever the model intended, such as Claude Code hooks. LangChain lists "Hooks/Middleware for deterministic execution (compaction, continuation, lint checks)" as part of the harness.
Claude Code and OpenAI's Codex are harnesses in this sense. LangChain notes that both products "are post-trained with models and harnesses in the loop". Anthropic's engineering blog describes the Claude Agent SDK as "a powerful, general-purpose agent harness adept at coding".
Harness, framework or SDK? An agentic AI framework gives you building blocks. A harness is those blocks already assembled into a runtime with defaults you can switch off. Microsoft says of its own Harness that it "composes existing Agent Framework building blocks rather than defining a separate agent runtime". An SDK such as the Claude Agent SDK hands you a ready harness to call from your own code.
Why it matters
- The same model scores differently in different harnesses. LangChain points to the Terminal Bench 2.0 leaderboard. In its words, "Opus 4.6 in Claude Code scores far below Opus 4.6 in other harnesses." A model comparison that does not name the harness compares only half of the system.
- Long tasks are a harness problem. Anthropic's engineers write that "getting agents to make consistent progress across multiple context windows remains an open problem". Their answer in Effective harnesses for long-running agents is a change to the harness. A first session sets up the environment. A
claude-progress.txtfile logs what each session did, and every session commits its progress to git. The next session can then pick up where the last one stopped. - Rules hold only in code. An instruction in a prompt is a request the model may ignore. A permission check or a hook in the harness is a decision it cannot talk its way around.
Our own headless agents work this way. They run Claude Code non-interactively (claude -p). Claude Code is the inner harness. It runs the tool loop, compacts context, starts subagents and fires hooks. Around it we built a second, outer layer for work nobody watches live:
- A scheduler starts each lane (one recurring kind of work, such as the daily standup report) on its own cadence. A lane holds a lock, so a second start of the same lane is skipped while the first one runs.
- Some lanes start with a deterministic precheck script that asks whether there is any work at all. When there is none, the model never starts and the run spends no model tokens.
- Each run has a hard time limit. A comment in our run script puts its purpose in one line: "The timeout is the guard against a stuck run."
- Credentials stay outside the model. The script that starts Claude Code removes secrets such as Slack tokens from its environment, and the scripts that post to Slack read the token themselves.
- After the run, a script commits the agent's state files.
None of these rules lives in a prompt, so none of them depends on the model remembering it.
What to watch out for
- Not every agent needs its own harness. When a developer works with an agent interactively and reads its steps, Claude Code, Codex or Cursor already provide the harness, and a custom layer only adds code to maintain. Build your own layer when runs are unattended, scheduled or must enforce company rules that no off-the-shelf tool knows about.
- A feature of one harness does not travel to another. We hit this while building our MCP Gateway. A client wanted a person to approve certain tool calls. A flag in the tool's metadata made Claude ask for approval, but other harnesses, Cursor among them, let the same call straight through. The approval had to move into the gateway, which every client passes through. The full story is in MCP tool permissions.
- The outer layer can stop the inner one at any moment. A timeout ends the run mid-step, whatever the agent was doing. Treat every run as one that may die halfway, and save progress in small, finished steps, as Anthropic's long-running agents do with git commits. Our content agents commit after each finished phase of an article, so a killed run leaves the last completed phase on a branch.
- A harness is not a security boundary on its own. Permissions and hooks keep the agent on the rails you agreed on, but they check the model's own calls. To limit what a process can reach at all, add an AI agent sandbox and scoped credentials.
Related articles:
- What's an agent? – The concept a harness turns into running software.
- What are agentic AI frameworks? – The building blocks a harness is assembled from.
- What are Claude Code hooks? – The deterministic checks a harness runs at fixed points of a session.
- What are subagents? – How a harness splits work between agents with separate context.
- What is an AI agent sandbox? – The boundary that limits what the commands a harness runs can reach.
- What is context rot? – Why a harness has to manage the context window instead of filling it.
Want to stay one step ahead?
Don't miss our best insights. No spam, just practical analyses, invitations to exclusive events, and podcast summaries delivered straight to your inbox.