Agent HarnessAI Agent

What is an agent harness? How it works, its parts and use cases

Learn what an agent harness is, how its loop runs a task and what its parts are: context, tools and permissions, what is kept between sessions, and hooks. Tests by OpenAI and Anthropic show how much a harness changed a model's results, and both companies describe harnesses for particular kinds of work.

By Rahmatullah Musawi · · 8 min read · sources checked 30 October 2026

Key points

  • The Claude Code documentation uses the term agentic harness for the layer around an AI model that gives the model its tools and manages the context the model sees.[1]
  • OpenAI publishes the harness of Codex as open source and writes that model access is kept separate from the open-source harness. Google's terminal program Antigravity CLI and its desktop app Antigravity 2.0 share one agent harness.[2] [3] [4]
  • The Claude Agent SDK, a library that runs Claude Code, works in a loop: the model asks to use tools, and the SDK checks each request, runs the tools and returns the results. The loop ends when the model answers without asking for a tool.[5] [6] [7]
  • OpenAI reports that retained reasoning and context compaction raised one model's benchmark score from 13.3% to 38.3%. In a test by Anthropic, one agent alone built a game maker whose central feature did not work; with a harness of three agents, the same model built a game maker in which a game could be played.[2] [8]
  • Anthropic describes harnesses for work across many sessions, for building an application over hours, and for long, parallel or highly structured tasks. OpenAI describes how it built a code base written only by agents and calls this work "harness engineering".[9] [8] [10] [11]

Arize, a company that makes tools for observing and evaluating AI agents, counts four coding agents as harnesses: "Cursor, Claude Code, Windsurf, and Codex are all harnesses."12

What is an agent harness?

The Claude Code documentation describes Claude Code as "the layer around the model that provides the tools and manages the context the model sees" and calls this layer an agentic harness; the model is Claude.1 Other sources, and this article, use the term agent harness.3 4

The documentation also says that "tools are what make Claude Code agentic". Without tools, Claude can only respond with text. With tools, it can read code, edit files, run commands and search the web.1

OpenAI, which makes Codex, writes that "a capable agent is more than a prompt and a model response". According to OpenAI, such an agent also needs, among other things, ways to understand a task, keep context over time, call tools, handle failures, ask a person for approval when necessary and return a useful result. OpenAI calls the "surrounding execution system" that provides these abilities the harness.2

The table collects what three vendors write about their own harnesses.

VendorWhat it says about its harness
OpenAIThe Codex harness is open source. It powers the Codex app, the command-line program and the extension for code editors. OpenAI writes that the open-source part is the harness and integration surface, while "model access and managed services remain separate".2
AnthropicAn Anthropic engineering article calls the Claude Agent SDK "a powerful, general-purpose agent harness".9 The SDK is "a library that runs the Claude Code binary". It gives developers "the same tools, agent loop, and context management that power Claude Code".5
GoogleGoogle's terminal program Antigravity CLI and Google's desktop app Antigravity 2.0 use the same agent harness.3 4 Google describes this harness as "co-optimized with Gemini models".4

LangChain, a company that makes open-source libraries for building agents, describes its three products as three layers; one of them, like the company, is called LangChain: "LangGraph is an agent runtime, LangChain is an agent framework, and Deep Agents is an agent harness. The runtime offers the most control and the least abstraction; the harness offers the inverse."13

LangChain's termProductHow LangChain describes it
Agent runtimeLangGraph13LangChain calls it "a graph-based framework for custom agent workflows" and writes that it "powers the agent abstractions" of the other two products.13
Agent frameworkThe LangChain framework13LangChain calls it "the abstraction and integrations layer". It comes with "a super minimal agent harness", whose core agent is "an LLM, running in a loop, calling tools". An LLM is a large language model.13
Agent harnessDeep Agents13LangChain calls it "an off-the-shelf agent harness". It comes with a filesystem, subagents, skills and memory. LangChain writes that the job of an agent harness is "to get the right context to the model at the right time".13

For Arize, a harness is a finished agent: "You don't configure a harness into existence. It ships as a working agent with a fixed architecture: the iteration loop, the context management, the tool registry, and the permission layer." Arize does not count the LangChain framework or LangGraph as harnesses: "LangChain is not a harness. LangGraph is not a harness. These are frameworks designed for humans to build agents."12

How a harness runs a task

Anthropic writes that agents "are typically just LLMs using tools based on environmental feedback in a loop".14 Arize writes that "the core architectural foundation of a modern harness is the while loop": the model decides which tools to call and keeps calling tools until it is finished.12 The Claude Agent SDK runs the same loop as Claude Code, and its documentation describes the loop in five steps.6 Before a tool runs, the SDK also checks whether the call is allowed.7 The figure "The loop of the Claude Agent SDK" shows the five steps and adds this check as step 3.

The loop of the Claude Agent SDK
Follow the arrows from top to bottom. Blue is the model, navy is the harness's code. A dashed line is the model's choice: to ask for tools or to answer. The numbers match the notes.
LOOPYOUR PROMPTReceive the prompttools, conversation1Evaluate and respondtext or tool calls2tool callsCheck the callhooks, permissions3Execute the toolsfiles, commands, web4resultsgo backno tool callsReturn the resulttext, cost, session ID6RESULT5
  1. Receive the promptClaude receives the prompt together with the system prompt, the definitions of the tools and the conversation so far.6 According to Arize, the system prompt is how a harness tells the model who it is, what it can do and what it is working on.12
  2. Evaluate and respondClaude may respond with text, ask for one or more tool calls, or both.6
  3. Check the callHooks, permission rules, the permission mode and an approval function decide whether each tool call may run.7
  4. Execute the toolsThe SDK runs each requested tool and collects the results. Tools that only read can run at the same time. Tools that modify state, such as Edit, Write and Bash, run one after another.6
  5. RepeatThe results go back to Claude for the next decision. One pass through the loop is a turn. The turns continue until Claude produces a response with no tool calls.6
  6. Return the resultThe SDK returns the final text together with the token usage, the cost and the session ID. With the session ID, the session can be resumed later.6 A developer can limit the loop to a maximum number of turns or to a budget in dollars. Without limits, the loop runs until Claude finishes on its own.6

The SDK documentation walks through the loop for one example prompt, "Fix the failing tests in auth.ts". The task takes four turns and uses three tools: Bash runs shell commands, Read reads files and Edit modifies files.6

What Claude asks forWhat comes back
Turn 1Bash: run the tests with npm test6The test output: three tests fail6
Turn 2Read: auth.ts and auth.test.ts6The contents of both files6
Turn 3Edit: fix auth.ts; then Bash: run npm test again6All three tests pass6
Final turnNo tool. Claude answers in text: "Fixed the auth bug, all three tests pass now."6The SDK returns this text with the cost and the usage, and the loop ends6

Hermes Agent, which Arize calls an open-source agent harness,15 also runs a loop. It runs the tool calls the model returns and goes round again until the model returns text; then it saves the session and returns the answer.16 By default, it allows at most 500 iterations; at that limit, it stops and returns a summary of the work done.16

TopicWhat is Hermes Agent? How it works, its structure and use cases describes the loop, the memory and the skills of Hermes Agent.

The parts of a harness

Arize lists nine components; in its words, they are "what every successful harness converged on independently". They are the loop, context management, skills and tools, subagents, built-in skills, session persistence, the system prompt, lifecycle hooks and the permission layer.12 This section explains four parts: context, tools and permissions, what is kept between sessions, and hooks.

Context: what the model sees

The SDK documentation defines the context window as "the total amount of information available to Claude during a session". The context window does not reset between turns: the system prompt, the tool definitions, the conversation, and every tool input and output pile up in it.6

Anthropic cites studies showing that the more tokens the context window holds, the less accurately the model recalls information from it. It calls context "a finite resource with diminishing marginal returns".17 The Claude Code documentation describes compaction when the context nears its limit, subagents with their own context window, and skills and MCP tools that load on demand.1 The figure "Managing the context window" shows these three.

Managing the context window
Each drawing shows one way to manage the context window. In Compaction, the older turns become a summary. In Subagents, the dashed line is the hand-over the model chooses. In Loading on demand, the dashed arrow points to the full text, which is loaded when it is used.
Beforeolder turnsrecent turnsAftersummary of older turnsrecent turnsCompactionWhen the context window approaches its limit, the SDK summarizes the older history and keeps the most recent exchanges and key decisions.6 When the conversation grows beyond half of the model's context window, Hermes Agent compresses it before the next call to the model: it summarizes the middle turns and keeps the last messages intact.16
Main agentits own contextSubagentfresh contextsubtaskits final responseSubagentsThe main agent hands a subtask to a subagent. The subagent works in its own context window and starts fresh, unless it is a fork: a subagent that starts with a copy of the conversation so far.1 The subagent returns only its final response; in the documentation's words, the main agent's context "grows by a summary, not by the subtask's transcript".6
In the contextskill descriptionsMCP tool namesFull textread when neededLoading on demandIn Claude Code, skills extend what Claude knows. Claude sees the descriptions of skills at the start of a session; the full content of a skill loads only when it is used.1 MCP, the Model Context Protocol, connects an agent to external tools and data sources.5 Tools from MCP servers are deferred by default: until Claude uses one, only the tool names and the servers' instructions take up space in the context window.1
TopicAI workflows and agent skills: what they are and how to use them describes what a skill is and how an agent loads it in stages.

Tools and permissions

Claude decides which tools to call, but the SDK documentation tells developers: "you control whether those calls are allowed to execute".6 When Claude asks for a tool, the SDK checks the call in a fixed order of six steps.7

The six checks before a tool call runs
Follow the arrows from top to bottom. A call that no step decides goes on to the next step. Green means the call runs, red means it is blocked, and amber means it goes straight to step 6. The numbers match the notes.
TOOL CALLHookscan deny it1Deny rulesa rule matches2Ask rulesa rule matches3Permission modebypassPermissions4Allow rulesa rule matches5ApprovalcanUseTool decides6BlockedBlockedRunsRunsyesnoRunsBlocked
  1. HooksA hook (see "Hooks") can deny the call outright or pass it on.7
  2. Deny rulesIf the call matches a deny rule, it is blocked, even in bypassPermissions mode (step 4).7
  3. Ask rulesIf the call matches an ask rule, it goes straight to step 6 for confirmation.7
  4. Permission modeThe permission mode controls whether the agent asks for approval before using tools.6 In bypassPermissions mode, nearly every call that reaches this step is approved. In acceptEdits mode, file operations are approved. In plan mode, file edits go to step 6. Every call that this step does not decide goes on to step 5.7
  5. Allow rulesIf the call matches an allow rule, it runs. A rule can cover only part of a tool: Bash(npm *) approves only the Bash commands that match the pattern npm *, and other Bash calls that need approval go on to step 6.6 7
  6. ApprovalA call that no step has decided goes to the developer's approval function, canUseTool, which can ask a person while the agent runs.7

A blocked call does not run; Claude receives a rejection message as the tool result and typically tries a different approach or reports that it couldn't proceed.6 The SDK documentation says to use bypassPermissions only in isolated environments, such as CI (continuous integration) systems or containers.6

Claude Code itself also has permission modes. In Manual mode, Claude asks before file edits and shell commands; in Auto mode, a classifier reviews most actions in the background and blocks the risky ones instead of asking.1

TopicWhat is MCP (Model Context Protocol)? How it works and its use cases describes how an agent calls a tool on an MCP server and what comes back.

What is kept between sessions

Each new session of Claude Code starts with a fresh context window, without the conversation of earlier sessions. Claude can carry learnings across sessions with auto memory, and you can add lasting instructions in CLAUDE.md. Claude Code also saves each session to a file, so that the session can be resumed later.1 The figure "What Claude Code keeps after a session" shows the three: the session file, auto memory and CLAUDE.md.

What Claude Code keeps after a session
The upper arrows show what is written during a session. The lower arrows show how these files are used later.
This sessionworks on a taskSessionsaved fileAuto memorylearningsCLAUDE.mdyou write itRESUME LATERNext sessionloads both files
  • SessionClaude Code writes each message, tool use and result to a plain-text file. Resuming reopens the session and adds new messages to it. Forking a session copies its history into a new session and leaves the original unchanged.1 Hermes Agent saves its messages to a SQLite database.16
  • Auto memoryAs you work, Claude saves what it learns, such as your preferences, to auto memory, in a file named MEMORY.md. At the start of each session, Claude Code loads the first 200 lines or the first 25 KB of this file, whichever limit is reached first.1 Hermes Agent keeps two memory files: its own notes and a profile of the user. The agent writes them with a memory tool, and they are put into the system prompt at the start of every session.18
  • CLAUDE.mdCLAUDE.md is a file in which you write the instructions, conventions and context Claude should know in every session.1 Because the SDK adds the content of CLAUDE.md to every request, the rules in the file survive a compaction. The compaction also reads CLAUDE.md, so the file can say what the summary must keep.6

Hooks

Hooks are pieces of code that run at specific points in the loop.6 For example, the PreToolUse hook runs before a tool runs, PostToolUse after the tool returns, UserPromptSubmit when a prompt is sent, Stop when the agent finishes and PreCompact before a compaction. Hooks run in the developer's application, outside the agent's context window, so they use none of it.6

Arize writes that hooks let organizations "inject custom logic before or after tool execution without forking the harness itself", that is, without making their own copy of the harness.12 Hindsight, a memory system that is not part of Claude Code, gives Claude Code memory across sessions through hooks.19 The figure "Example: how Hindsight adds memory to Claude Code through hooks" shows two of these hooks: one recalls memories, the other retains them.

Example: how Hindsight adds memory to Claude Code through hooks
The figure follows one request from top to bottom. The numbers match the notes.
YOUR REQUESTUserPromptSubmithook: recall1Model and toolsthe loop runs2Stophook: retain3Hindsightmemoryrecallmemoriesnew content
  1. Recall when a request is sentThe UserPromptSubmit hook adds memories recalled from Hindsight to the context. They do not appear in the chat.19
  2. The loop runsThe model and the tools work as in the figure "The loop of the Claude Agent SDK".
  3. Retain after the answerThe Stop hook sends the new content of the conversation to Hindsight, which keeps it.19

Hermes Agent can also use Hindsight as its memory provider: by default, Hindsight puts relevant memories into the system prompt before the model sees a message and retains the conversation after each response.20

TopicWhat is Hindsight? Agent memory, knowledge graph and use cases describes what Hindsight stores and how it retrieves it.

Why the harness matters

OpenAI writes that "harness design can materially change results".2 OpenAI and Anthropic each report a test that runs one model in two setups.2 8

TestFirst setupSecond setup
OpenAI: the model GPT-5.6 Sol on the benchmark ARC-AGI-3Before retained reasoning and context compaction were added: score 13.3%2With retained reasoning and context compaction: score 38.3%, with one sixth as many output tokens2
Anthropic: the model Claude Opus 4.5 builds "a 2D retro game maker" from a one-sentence promptOne agent alone: 20 minutes and $9. The central feature of the application "simply didn't work"8Three agents: 6 hours and $200. The application had more polish, and a game made with it could be played8

The figure "Example: Anthropic's harness for building an application over hours" shows the three agents of the second setup.

Example: Anthropic's harness for building an application over hours
The figure shows the three agents and what each hands to the next, in the version of the harness that used Opus 4.5. The numbers match the notes.
A SHORT PROMPTPlannerwrites the product spec1Generatorbuilds in sprints2Evaluatortests the app3specappfeedbackAPPLICATION
  1. PlannerThe planner expands a prompt of one to four sentences into a full product specification; in the game-maker test, the prompt was one sentence. The specification focuses on the product and its high-level technical design rather than on details of the code.8
  2. GeneratorThe generator builds the application in sprints, one feature at a time. At the end of each sprint, it checks its own work and then hands the sprint's work to the evaluator.8
  3. EvaluatorThe evaluator clicks through the running application the way a user would. It uses the Playwright MCP to test the interface, the API endpoints and the database states. The evaluator grades each sprint against criteria and, when a sprint fails, gives the generator detailed feedback.8 Anthropic made the evaluator a separate agent because agents asked to evaluate their own work "tend to respond by confidently praising the work".8

The three-agent harness ran as one continuous session. Anthropic's earlier harness for work that spans many sessions had used context resets instead: the harness cleared the context window and started a fresh agent, which received a handoff of the previous agent's state.8 Anthropic did this because the model it used, Sonnet 4.5, showed "context anxiety": as the model approached what it believed was its context limit, it began wrapping up work early.8

With Opus 4.5, this behavior had largely disappeared. So the three-agent harness did without context resets; the Agent SDK's automatic compaction handled the growing context instead.8

Anthropic writes that "every component in a harness encodes an assumption about what the model can't do on its own" and that these assumptions "can quickly go stale as models improve". It recommends re-examining the harness whenever a new model arrives: removing the pieces that no longer help performance and adding new ones.8

Use cases

Two Anthropic staff members who work on Claude Code write that the default Claude Code harness is built for coding but "is also useful for many other types of tasks because, as it turns out, many tasks resemble coding tasks".10 They name the kinds of task for which the default harness can break down: long-running, massively parallel, highly structured or adversarial tasks.10 The table lists harnesses that Anthropic and OpenAI describe in detail.

Use caseWhat the harness doesDocumented by
Work that spans many sessionsIn the first session, an agent sets up the environment: a list of features, a script that starts the app, a progress file and a first git commit. In every later session, an agent reads the progress file and the git log, works on one feature, tests it end to end as a human user would, and ends with a git commit and a progress update.9 The harness used the model Sonnet 4.5.8Anthropic9
Building an application over hoursThree agents (a planner, a generator and an evaluator) run as one continuous session.8 The figure "Example: Anthropic's harness for building an application over hours" shows them.Anthropic8
Long, parallel or highly structured tasksClaude Code writes its own multi-agent harness on the fly: a JavaScript file whose special functions start and coordinate subagents, each with its own context window. Anthropic calls such harnesses dynamic workflows.10Anthropic10
A code base written only by agentsAGENTS.md is a file for coding agents; Claude Code can read it in place of a CLAUDE.md.1 In OpenAI's project, a short AGENTS.md serves as a map with pointers to deeper sources.11 The project's knowledge base lives in a docs/ folder. The error messages of custom code checks tell the agent how to fix the error, and agents can query logs and metrics. About 1,500 pull requests were opened and merged by a team of three engineers driving Codex; the team has since grown to seven. No code was written by hand.11OpenAI, under the name "harness engineering"11

Sources

  1. How Claude Code works Claude Code docs
  2. Codex as a platform: build on the open agent harness OpenAI Developers
  3. An important update: Transitioning Gemini CLI to Antigravity CLI Google Developers Blog
  4. Google Antigravity CLI Google Antigravity blog
  5. Agent SDK overview Claude Code docs
  6. How the agent loop works Claude Code docs
  7. Configure permissions Claude Code docs
  8. Harness design for long-running application development Anthropic
  9. Effective harnesses for long-running agents Anthropic
  10. A harness for every task: dynamic workflows in Claude Code Claude blog
  11. Harness engineering: leveraging Codex in an agent-first world OpenAI
  12. What is an agent harness? Arize AI
  13. Deep Agents vs LangChain vs LangGraph LangChain
  14. Building effective agents Anthropic
  15. How the Hermes agent harness implements an open source architecture Arize AI
  16. Agent Loop Internals Hermes Agent docs
  17. Effective context engineering for AI agents Anthropic
  18. Persistent Memory Hermes Agent docs
  19. Guide: Add Claude Code Persistent Memory with Hindsight Hindsight docs
  20. Hindsight Is Now a Native Memory Provider in Hermes Agent Hindsight blog

Written by Rahmatullah Musawi with the help of an AI assistant.