Agent Harness

Why This Matters

AI-017 taught the agent loop as a concept: observe, plan, act, repeat. That loop has to run somewhere, on something, with something keeping track of what happened three turns ago and what tools are even available to call. That "somewhere" is the harness. Teams that skip thinking about the harness end up rebuilding memory management, tool sandboxing, and state persistence from scratch inside every agent project, badly, and usually insecurely. Understanding the harness as its own layer of infrastructure, separate from prompt design and separate from the model itself, is what separates a demo agent from a production one.

Everyday Analogy

A brilliant new employee (the model) shows up on day one with excellent judgment and can answer questions, but has no desk, no laptop, no access badge, no notebook to write down what happened yesterday, and no list of which tools they're allowed to use. The harness is everything the company gives that employee to actually function: the laptop (execution environment), the badge (permissions and sandboxing), the notebook (memory), the tool cabinet key (tool registry), and the onboarding checklist (planner). The employee's raw intelligence does not change; what they can accomplish changes enormously once the harness exists.

What a Harness Actually Provides

A harness is the runtime layer between "I have an LLM API key" and "I have a working agent." Its core components:

• Planner. Breaks a high-level goal into steps, decides what to do next given the current state, and decides when the task is complete. This is where the AI-017 agent loop actually executes.
• Tool registry and execution. A catalog of available tools (search, code execution, file access, external APIs) with schemas the model can call via function calling (see AI-018), plus the runtime that actually executes the call and returns results.
• Memory. Short-term memory (the current conversation and recent tool results) and long-term memory (facts, prior decisions, and user preferences persisted across sessions), built on the memory system patterns from AI-035.
• State management. Tracking where the agent is in a multi-step task across turns, including partial progress, so a five-step task doesn't restart from step one if the connection drops or a human interrupts to ask a question.
• Sandboxing. Running generated code or risky tool calls in an isolated environment (a container, a restricted filesystem, a network-limited VM) so a hallucinated rm -rf or an injected malicious instruction cannot damage the host system.
• Output verification. Checking tool results and final outputs against expectations before trusting them, closing the loop rather than blindly acting on whatever the model produced.

Harness versus loop versus multi-agent: three different layers

It is easy to blur these together, so keep the boundaries explicit:

A multi-agent system is not a bigger harness; it is multiple harness instances plus a coordination layer on top. Confusing "harness" with "loop" is the most common conceptual error: the loop is the algorithm, the harness is the infrastructure that runs the algorithm reliably.

Real Agent Harnesses

A Worked Example: A Multi-Turn Task Through a Harness

Consider a user asking an agent: "Find last quarter's revenue numbers in our reports folder, and draft a one-paragraph summary."

1. Planner breaks this into steps: locate files, extract numbers, verify totals, draft summary.
2. Tool registry exposes a file-search tool and a file-read tool; the model calls search_files(query="Q3 revenue") via function calling.
3. Sandbox executes the search inside a restricted filesystem scope (only the reports folder is visible, not the whole disk).
4. Memory stores the extracted numbers in short-term working memory for this task, and, if the user has done this before, long-term memory might recall "this user always wants totals rounded to the nearest thousand."
5. State management tracks that steps 1 and 2 are complete before the model moves to drafting, so if the user interrupts with a clarifying question mid-task, the harness can resume from step 3 rather than restarting.
6. Output verification checks that the drafted numbers in the summary actually match the numbers extracted from the files before returning the final answer, catching a case where the model might otherwise paraphrase a number incorrectly.

Notice that the model itself only ever does one thing well: predict the next useful token or tool call given context. Everything about persisting that context, isolating the risky parts, and verifying the output is the harness's job, not the model's.

Real-World Showcase

• Anthropic's own engineering blog describes Claude Code's effectiveness as coming substantially from harness decisions (which tools are exposed, how permissions gate risky actions, how context is compacted across a long session) rather than from prompting alone.
• LangGraph's adoption in production agent systems is frequently cited specifically for making long-running, branching agent state debuggable, a problem that becomes unmanageable with an implicit, unstructured loop.
• Early AutoGPT-style projects in 2023 became widely used case studies in why loose harnesses (minimal state tracking, no sandboxing, no verification step) lead to expensive, looping failures, directly motivating the more disciplined harness designs that followed.

Try It Yourself

1. List the five harness components covered above (planner, tool registry, memory, state management, sandbox) and, for a task like "book a flight and email me the confirmation," write one sentence describing what each component would actually need to do.
2. Compare the Claude Agent SDK and OpenAI Assistants API rows in the table: which one manages state on the client versus the server, and what tradeoff does that create for building a multi-device agent experience?
3. Design a sandboxing policy in plain English for an agent that can execute code: what should it be allowed to touch (files, network, environment variables) and what should always be blocked?

Common Mistakes

• Treating the harness as an afterthought and hard-coding memory and tool logic inside prompt text instead of building it as real infrastructure.
• Running agent-generated code without sandboxing, assuming the model "probably won't" do anything destructive.
• Confusing the agent loop (AI-017) with the harness: better prompting cannot fix a harness that loses state between turns.
• Building a custom harness from scratch when an existing one (Claude Agent SDK, LangGraph, Assistants API) already solves the problem, duplicating effort and missing hardening the existing tools already have.
• Skipping output verification and trusting tool results or final answers without any check, letting a single bad tool call cascade through the rest of a multi-step task.

Key Takeaways

• An agent harness is the runtime infrastructure, planner, tool registry, memory, state management, and sandboxing, that wraps a model into a working agent.
• It is a distinct layer from the agent loop (AI-017) and from multi-agent coordination (AI-032); confusing the layers is the most common conceptual mistake.
• Real harnesses range from managed (OpenAI Assistants API) to graph-based and inspectable (LangGraph) to embedded in a product (Claude Code).
• Sandboxing and output verification are what make a harness safe to run autonomously, not just capable.
• "The vendor ships the model, you own the loop" means the harness, not the model choice, is usually where most of an agent product's engineering effort actually goes.