A walkthrough of Agent Harness: what it is, the core components (filesystem, code execution, sandbox, memory, context, long-horizon), and how its architecture has evolved from a single-container pet to a decoupled three-layer design.
No comments yet.
This article is based on Anthropic - Scaling Managed Agents and LangChain - The Anatomy of an Agent Harness, with my own understanding and examples mixed in.
LangChain gives a concise formula:
Agent = Model + HarnessIn one sentence: if you're not the model, then you're the Harness.
Harness is everything outside the model — the loop that calls the model, tool routing, context management, execution environment, security isolation, memory mechanisms... all the infrastructure that turns a "bare model" into an "Agent that can get work done."
Many early Agent frameworks (typified by early LangChain's Chain/Agent abstractions) tend to: encapsulate model capabilities into predefined tool chains, with developers orchestrating the call sequence.
Harness has a different focus: it presets less about what the model should do, and instead provides general capability primitives (filesystem, code execution, sandbox, network access), letting the model autonomously decide how to combine these primitives to solve problems.
To use an analogy:
Claude Code itself is a typical Harness:
┌───────────────────────────────────────────────┐ │ Claude Code (Harness) │ ├───────────────────────────────────────────────┤ │ • Calls Claude API in a loop │ │ • Routes tool calls (Bash, Read, Write, ...) │ │ • Manages context window │ │ • Provides filesystem access │ │ • Isolates execution environment │ └───────────────────────────────────────────────┘The model is responsible for "thinking" (reasoning, planning, decision-making), and the Harness is responsible for "doing" (executing commands, reading/writing files, managing context, isolating permissions).
The LangChain article summarizes six core components of a Harness. I'll explain each one with Claude Code examples.
The filesystem is the most critical foundational primitive of a Harness, with a role far beyond "reading and writing files":
| Use Case | Description | Claude Code Example |
| Persistent storage | Retain info across conversation runs | CLAUDE.md |
| Context extension | Store info beyond token limits | Large tool outputs persisted to disk; context keeps only summary and file path |
| Multi-Agent collaboration | Shared workspace | Team-shared task list file |
| Version control | Track changes, support rollback | git worktree isolation |
Side note: In the second row of the table, what I call the persisted-output tool output strategy, and in the third row, the "TeamCreate creates a team and binds a shared task list" — these are Claude Code-specific implementation details, not general Harness theory.
The filesystem is essentially the Agent's external memory — the context window is "working memory" (short-term), and the filesystem is "long-term memory."
Rather than giving the model 100 pre-packaged tools, it's better to give it a general code execution capability:
Pre-packaged tool approach:\n Tool: search_files(pattern="*.go", keyword="func main")\n\nCode execution approach:\n Bash: grep -rn "func main" --include="*.go" .\n\nThe latter can combine any shell commands.The latter is more flexible — the model can combine arbitrary shell commands to solve problems, unconstrained by a predefined tool set. Claude Code providing a Bash tool is exactly this design philosophy: giving the model "hands."
The sandbox provides three layers of value:
Agents need to accumulate experience across conversation runs, and also need to access real-time information beyond training data:
run 1: user corrects coding style preference\n ↓ writes to memory\nrun 2: Agent directly codes in the correct styleTwo paths:
Claude Code's memory hierarchy:
In long conversations, the context window will "rot" (context rot): more and more irrelevant information dilutes the effective information. The Harness needs to actively manage context:
In real scenarios, a task may span multiple conversation runs, lasting hours or even days. The Harness needs to support this kind of "long-horizon work":
Long-horizon execution is essentially orchestrating the previous five components (filesystem, code execution, sandbox, memory/search, context management) to give the Agent the ability to "advance one thing across time periods."
This part is the core insight of the Anthropic article — how Harness design evolves with model capability progress.
The original Managed Agents architecture crammed all components into a single container:
┌──────────────────── Container ─────────────────────┐ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Model │ │ Tools │ │ State │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ Everything in one container │ └────────────────────────────────────────────────────┘This is like raising a "pet" — each container is unique, containing irreplaceable state. Problems:
Terminology clarification: Session (capitalized) below specifically refers to the event log component in Anthropic's architecture — an append-only persistent store, distinct from the "conversation session" concept used in earlier sections.
Anthropic's solution is to split the monolithic architecture into three independent interfaces:
┌─────────────────────────────────────────────────────────────┐ │ Managed Agent │ ├──────────────┬──────────────┬──────────────────────────────┤ │ Session │ Harness │ Sandbox │ │ (event log) │ (model call) │ (code execution) │ │ append-only │ stateless │ stateless │ │ persistent │ restartable │ replaceable │ └──────────────┴──────────────┴──────────────────────────────┘(Session = immutable event log; Harness = stateless service that calls the model / routes tools; Sandbox = stateless container that executes code / file operations.)
Session ↔ Harness interaction semantics: the Harness appends event logs to the Session; after restart, the new instance recovers state by replaying the existing event stream.
This design borrows from operating system thinking — just as the OS virtualizes hardware into abstractions like "processes" and "files" that outlive the hardware, Managed Agents virtualize the Agent runtime.
After decoupling, the most core change is that the Brain (Claude + Harness) and Hands (Sandbox and various execution tools) are completely separated:
The Harness is decoupled from the conversation run's state, no longer bound to a specific container (the Harness itself can still run in a container, but it becomes a stateless, restartable service). The container side becomes purely...
Session exists independently of the Harness. If the Harness crashes, no state is lost — a new Harness instance can pick up from the event log with just the sessionId:
// Pseudocode (not official SDK API, just illustrating recovery semantics)\nconst session = await getSession(sessionId);\nconst harness = new Harness({ model: 'claude' });\nawait harness.replay(session.events);\n// Harness is now back to the state before crashDecoupling brought significant performance improvements — the key metric is TTFT (Time-to-First-Token), the time from user sending a message to seeing the first response:
Core reason (based on architectural inference): before decoupling, inference was tied to the container lifecycle, requiring the container to be ready first; after decoupling, the Harness as a stateless service can start inference immediately, no longer blocked by execution environment readiness.
| Metric | Improvement |
| p50 TTFT | ~60% reduction |
| p95 TTFT | >90% reduction |
Decoupling also naturally forms security isolation:
┌──────── Harness ────────┐ ┌──────── Sandbox ────────┐\n│ • User credentials │ │ • Code execution │\n│ • OAuth tokens │ │ • File operations │\n│ • API keys │ ───▶ │ • Tool results │\n│ • Sensitive config │ │ • No credentials visible │\n└──────────────────────────┘ └──────────────────────────┘(The Harness on the left holds user credentials / OAuth tokens / API keys; the sandbox can only see operation results — credentials never enter the sandbox.)
The Anthropic article mentions two approaches to ensure credentials don't enter the sandbox (the specific implementation details below are my inferences based on architectural contracts; the original text doesn't go into this level of detail):
The decoupled architecture leaves room for "many-to-many" expansion (the following structure is an inference based on interface contracts, not an explicit conclusion from the Anthropic article):
Brain A ──┐ ┌── Hand 1 (container)\n ├── Session ────────┤\n Brain B ──┘ └── Hand 2 (container)\n\nMultiple Brains can connect to the same Session;\nMultiple Hands can be used as interchangeable tools.Following Anthropic's "stable interfaces + replaceable implementations" line of thinking one step further, we find a more interesting question: the Harness inevitably encodes assumptions about model capabilities, and these assumptions will expire as the model improves.
Take an easy-to-understand scenario (the following is an illustrative hypothetical example to demonstrate the "assumptions expire" pattern, not a specific case from the original text): suppose early models have "context anxiety" — when conversations get long and approach the context limit, they start forgetting or hallucinating.
Lesson: Harness code written for model limitations is a breeding ground for technical debt.
The Anthropic article's coping strategy is Future-Proofing Through Abstraction — building a set of interfaces that outlive any specific Harness implementation:
Stable interface layer (Session / Sandbox contracts remain unchanged) │ ├── Claude Code Harness (today's implementation) ├── Task-Specific Harness (optimized for specific scenarios) └── Future Harness forms (new shapes we haven't imagined yet)
If you're building an Agent application, here are some points worth considering:
1. Don't encode too many assumptions in the Harness
// Bad: assuming the model is bad at long context\nif (context.length > 4000) {\n context = summarize(context);\n}\n\n// Good: let the model decide\n// (no hardcoded context length limits)2. Consider conversation run persistence from day one
Even for a single-machine application, you should persist conversation history to files/database, not just keep it in memory. Benefits:
3. Security boundary design upfront
Credentials management should be solved at the architecture level, not by "careful coding." Core principle: in environments that model-generated code can reach, there should be no sensitive information.
4. Leave room for model capability growth
Today you may need complex ReAct loops, Chain-of-Thought forcing, multi-step verification. But as model capabilities improve, these may all become redundant. When designing, ask yourself: if the model suddenly gets 10x smarter, which of my code would become unnecessary?
| Dimension | LangChain perspective | Anthropic perspective |
| Focus | What a Harness is (components & responsibilities) | How a Harness evolves (decoupling & architecture) |
| Core idea | Agent = Model + Harness | Decouple Brain from Hands |
| Design approach | Provide general primitives, not predefined tools | Build interfaces that outlive implementations |
| Attitude toward models | Empower models to solve problems autonomously | Don't encode assumptions about models |
| Key innovation | Filesystem as core primitive | Session/Harness/Sandbox three-layer separation |
Both articles point to the same trend: the Harness is getting "thinner." As models get smarter, the Harness's responsibility gradually shifts from "guiding the model to do the right thing" to "giving the model the ability to do things." The best Harness is one that you barely notice.