A Deep "Dissection" of the AI Agent Harness
Akshay Pachaar May 25, 2026, 07:00
“If you’re not the model itself, then you’re the Harness.” — Vivek Trivedy
Prologue
On this OceanBase community WeChat account, Zlatan has never made a habit of simply translating a foreign-language article into Chinese and publishing it as-is. We want every article to be something we’ve actually read ourselves first, distilling our own understanding before sharing it with everyone. But today’s piece is an exception.
A while back, Akshay Pachaar posted a long article on Twitter, “The Anatomy of an Agent Harness,” that systematically dissects the Agent Harness architecture designs of companies like Anthropic, OpenAI, and LangChain. It is, to date, the clearest and most comprehensive treatment of the Harness that Zlatan has ever read. And the article has already racked up 1.39 million views.
You’re also welcome to follow the OceanBase community WeChat account “Lao Ji’s Tech Talk.”
The Main Text
This article is about what Anthropic, OpenAI, and LangChain are really building. Let’s take a look together — the orchestration loop, tools, memory, context management, and the underlying mechanisms that turn a “stateless” large language model into a fully capable agent.
You’ve probably already built a chatbot, maybe even hacked together a ReAct loop with a few tools. The demo runs and everything looks great, but the moment it hits production it falls apart: the model forgets what it did three steps ago, tool calls fail silently, and the context window fills up with useless junk.
The problem isn’t the model. It’s the layer of infrastructure wrapped around it.
LangChain let the facts speak: same model, same parameters — they changed nothing but the architecture around it, and on TerminalBench 2.0 they shot up from outside the top 30 all the way to 5th place. Another study let an LLM optimize this architecture itself, and the pass rate hit 76.4% — beating systems carefully designed by humans. Now this infrastructure has an official name: the AI Agent Harness.
What Is an Agent Harness?
Although the term “Harness” only became standard at the start of 2026, the idea behind it has been around for a while. The Harness is the entire software architecture wrapped around the large model: the orchestration loop, tools, memory, context management, state persistence, error handling, guardrails — all of it.
Anthropic put it plainly in the Claude Code docs: the SDK is the “Agent Harness that drives Claude Code.” OpenAI’s Codex team means the same thing. LangChain’s Vivek Trivedy offers this definition: “If you’re not the model itself, then you’re the Harness.” Blunt and to the point.
A lot of people conflate two concepts: the “AI Agent” is the behavior you see; the “Harness” is the machine behind the curtain. When someone says “I built an agent,” what they really mean is “I built a Harness and plugged a model into it.”
Beren Millidge offered a particularly apt analogy: a bare large model is like a CPU with no memory, no disk, and no I/O. The context window is the memory, the external database is the disk, and tool integrations are the device drivers. And the Harness is the operating system. “We’ve reinvented the von Neumann architecture.”
The Three Levels of Engineering
- Prompt Engineering: writing good instructions to feed the model.
- Context Engineering: managing what the model can see and when.
- Harness Engineering: encompasses both of the above, plus the entire application architecture — tool orchestration, state persistence, error recovery, verification loops, secure execution, and lifecycle management.
A Harness is not some prompt-wrapping shell (an AI Wrapper); it’s the complete system that lets an agent truly act on its own.
The 12 Core Components of a Production-Grade Harness
Synthesizing the experience of Anthropic, OpenAI, LangChain, and frontline practitioners, a production-grade Harness consists of 12 core components.
1. The Orchestration Loop
The “Think-Act-Observe” (TAO) loop: assemble the prompt → call the large model → parse the output → execute tool calls → feed the results back → repeat, until the task is done. At the code level it’s just a while loop. Anthropic calls its own runtime the “dumb loop.”
2. Tools
Tools are the agent’s “hands.” Claude Code provides six categories of tools: file operations, search, execution, web access, code analysis, and subagent creation. OpenAI’s Agents SDK supports function tools, hosted tools, and MCP server tools.
3. Memory
Short-term memory is the conversation history within a single session. Long-term memory persists across sessions: Anthropic uses MEMORY.md, LangGraph uses JSON storage, and OpenAI uses SQLite or Redis. Claude Code built a three-tier memory architecture. An important principle: the agent treats its own memory as a “hint,” and must verify against actual state before acting.
4. Context Management
This is the area where many agents quietly derail. Context rot: once key information lands in the middle of the window, the model’s performance drops by 30% or more — Stanford calls this “lost in the middle.”
Production strategies: Compaction, Observation Masking, Just-in-time Retrieval, and subagent delegation.
5. Prompt Construction
Layered: system prompt, tool definitions, memory files, conversation history, and finally the current user message.
6. Output Parsing
Modern Harnesses use native tool calling: the model directly returns a structured tool_calls object.
7. State Management
LangGraph models state as a typed dictionary, automatically checkpointing at key steps. Claude Code uses Git commits as checkpoints.
8. Error Handling
Ten steps, each with a 99% success rate, leaves the whole pipeline at only a 90.4% success rate. LangGraph handles errors in four categories.
9. Guardrails and Safety
OpenAI builds three lines of defense. Anthropic separates “permission to execute” from “model reasoning” — the model decides what it wants to do, the Harness decides whether to allow it.
10. Verification Loops
The dividing line between “demoable” and “shippable.” Boris Cherny, the creator of Claude Code, has said that letting the model verify its own work can multiply output quality by 2–3x.
11. Subagent Orchestration
Claude Code supports three approaches: Fork, Teammate, and Worktree.
How the Loop Works: A Step-by-Step Walkthrough
Now that we know all the parts, let’s see how they work together within a single loop.
The seven-step loop: prompt assembly → model inference → output classification → tool execution → result packaging → context update → loop.
Exit conditions: the model returns a response with no tool calls, the maximum number of turns is reached, the token budget is exhausted, a guardrail fires, or the user interrupts. Anthropic also developed a two-phase “Ralph loop” approach for long tasks that span multiple windows.
How the Frameworks Actually Land in Practice
- Anthropic (Claude Agent SDK): the
query()function exposes the Harness; the runtime is the “dumb loop” - OpenAI (Agents SDK): a code-first approach; the Codex Harness has three layers
- LangGraph: an explicit state graph, two nodes with a conditional edge
- CrewAI: role-based multi-agent collaboration
- AutoGen: from Microsoft, with five orchestration patterns
The Scaffolding Metaphor
The co-evolution principle: today’s models are already trained with the Harness in mind. The litmus test: swap in a stronger model, and performance should improve without needing to increase Harness complexity.
The 7 Key Decisions That Define a Harness
- Single-agent vs. multi-agent: squeeze out the single-agent potential first
- ReAct vs. plan-then-execute: LLMCompiler is 3.6x faster than sequential ReAct
- Context management strategy: prioritize preserving the reasoning trace, cutting token consumption by 26–54%
- Verification loop design: guidance (feedforward) + sensors (feedback)
- Permission and security architecture: lax or strict depending on the scenario
- Tool scope management: Vercel cut 80% of its tools and ended up better off
- Harness thickness: how much logic is hardcoded, and how much is left to the model
The Harness Is the Product
Two agents on the same model can perform wildly differently — and the difference is the Harness. TerminalBench proves that swapping the Harness alone can move you up more than 20 places in the rankings. The Harness will never disappear. Even the strongest model still needs a Harness to manage its window, run code, store state, and verify results.
Editor’s Note
Because the Agent era will generate massive amounts of high-frequency, semi-structured, context-laden process data that needs to be replayed and compared.
There’s now a glaring problem: general-purpose agents dump their runtime data into peripheral files like JSONL / Markdown / SQLite. Many companies are being driven crazy by the operational cost of running Postgres + pgvector + Redis + ClickHouse + LangSmith + JSONL.
LangChain built its own SmithDB for LangSmith. For details, see: LangChain “Goes Off-Script” — They Actually Built a Database from Scratch?
An agent’s context, execution history, tasks, observability, and footprint should all settle directly into the database.
What’s more?
On May 30, AgentSeek will be unveiled with great fanfare at the OceanBase × LangChain Meetup.
AgentSeek packs OB4AI + SeekVFS + SeekContext, and can take on context / trace / tool I/O / footprint as database-native objects.
Click the image below to view event details:
Time: May 30; Location: 35F, T1 (Moli·Source), Zhangjiang Gate of Science, Pudong New Area, Shanghai
Original article: “The Anatomy of an Agent Harness”: https://x.com/akshay_pachaar/status/2041146899319971922