An agent harness is the software that wraps a large language model so it can act, not just chat. The model reasons about the next step; the harness runs tools, manages context and memory, enforces permissions, and decides when to stop. In short: agent = model + harness. That formula shows up in LangChain's agent docs, Databricks' harness guide, and the Wikipedia entry on agent harnesses.
This guide explains what a harness actually includes, how it differs from an agent framework, which products people mean when they say "harness" in 2026, and how teams design harnesses for long running work.
Free from Ahzy Capital (our own product): The AI Agent Cheat Sheet has 24 copy and paste AI agent setups for 8 types of small business, each with the prompt and the workflow. It's free; Stan asks for your email to send it.
What an agent harness does
A raw LLM maps tokens to tokens. It has no filesystem, no shell, no durable memory across sessions, and no way to refuse a dangerous action on its own. The harness is everything around that loop:
| Piece | Role |
|---|---|
| Tool dispatch | Expose APIs, shell, editors, browsers, MCP servers; run the call the model requested |
| Context management | Build each prompt, compact or summarize history, load skills and instruction files |
| Memory and state | Persist threads, checkpoints, progress files, or external memory stores |
| Execution environment | Sandboxes, workspaces, and code runners so actions stay isolated |
| Guardrails | Permissions, approval gates, hooks, budgets, and observability |
| Loop control | Stop conditions, retries, handoffs to subagents, human in the loop pauses |
Databricks frames the same split as brain versus body: the model decides; the harness acts and observes. The common reason, act and observe cycle (often called ReAct) sits inside that loop. Without the harness half, you only get answers. With it, you get an agent that can edit a repo, call MCP tools, or run code in something like E2B. To write that loop yourself, see how to build an AI agent from scratch.
Agent harness vs framework vs scaffolding
People mix three terms. They overlap, but they are not the same:
- Framework: libraries you assemble an agent from (prompt templates, tool abstractions, graph runtimes). LangGraph, CrewAI, and Mastra are frameworks. You choose the pieces and wire the loop. Our agent frameworks directory lists the main options side by side.
- Harness: the running system around a model on a given task: which tools are live, what context is injected, what the sandbox allows, when a human must approve. You build with a framework; you run inside a harness.
- Scaffolding: an older synonym for the same runtime layer. The UK AI Security Institute and early safety writing used "scaffolding"; "harness" is the word most vendors use in 2026.
LangChain says it plainly: a harness is everything around the model and tools loop (prompt, tools, middleware), and create_agent is a configurable harness. Deep Agents is their prebuilt harness on top of that stack for long jobs. A framework without a solid harness is a kit of parts. A harness without a clear framework is still an agent. Claude Code and Codex ship as product harnesses first.
For picking a Python framework rather than designing a harness, see Best AI agent framework for Python. If your stack is Node, Mastra and its peers are compared in best TypeScript AI agent frameworks.
Concrete harnesses you will meet in 2026
Coding agent harnesses
Terminal coding agents are the most visible harnesses. Claude Code, OpenAI Codex, Gemini CLI / Antigravity, Cursor's agent mode, and open CLIs such as Pi all wrap a model with repo tools, permissions, instruction files (AGENTS.md / CLAUDE.md), skills, and often MCP. Anthropic's Agent SDK exposes the same Claude Code loop as a Python or TypeScript library (hooks, sessions, permissions, and MCP included) and Anthropic also documents a hosted "Managed Agents" option as a hosted agent harness. Skills can turn these harnesses into specialists, as the Cloudflare security audit skill does for code review.
If you are choosing among the big CLIs, start with Claude Code vs Codex vs Gemini CLI.
Framework harnesses (LangChain, Deep Agents, AI SDK)
LangChain's create_agent is intentionally described as a harness you configure with middleware: filesystem backends, summarization, memory, skills, subagents, retries, PII filters, and human in the loop. Deep Agents ships that stack preassembled for coding and research tasks.
On the TypeScript side, the Vercel AI SDK gives you ToolLoopAgent for a custom tool loop and HarnessAgent when you want to drive an established coding harness (Claude Code, Codex, or Pi) behind the same streaming interface. See the AI SDK agents overview, or our Vercel AI SDK guide for a tested agent with tool approvals.
Orchestrators that delegate to a coding harness
Docker Agent has a literal harness: block: an agent can hand coding work to Claude Code, Codex, opencode, or Pi on your PATH while Docker Agent keeps orchestration, hooks, permissions, and distribution. The Docker Agent harness docs call this out as combining CLI strengths with multiagent control. Our Docker Agent guide walks through the rest of that runtime.
Harness engineering for long running agents
"Harness engineering" is the craft of making that runtime reliable: context strategy, tool surface, verification, approvals, and recovery. Prompt and context engineering sit inside it; they are not replacements for it.
Anthropic's November 2025 engineering post Effective harnesses for long running agents is the clearest worked example. The problem: each new context window starts with no memory of the last shift. Compaction helps but is not enough. Their pattern:
- Initializer agent: first session writes
init.sh, a feature list (JSON withpasses: false), a progress log, and an initial git commit. - Coding agent: every later session reads git + progress, picks one unfinished feature, implements it, tests (including browser automation where needed), commits, and updates the progress file.
That is harness design in practice: durable artifacts outside the context window, incremental goals, and verification before marking work done. Weak harnesses show up as context rot, tool overload, brittle schemas, slow multistep latency, and agents that declare victory early: failure modes Databricks also catalogs in its harness writeup.
Sandboxes are part of the same story. If the harness can run model written code or shell commands, isolate them. Compare options in E2B vs Daytona vs Modal.
Who should care which harness
| You are… | Start here |
|---|---|
| Building a product agent in Python | Configurable harness: LangChain create_agent or LangGraph; Deep Agents if you want the prebuilt stack |
| Embedding Claude Code's loop in your app | Anthropic Agent SDK (or Claude Managed Agents if you want Anthropic to host the harness) |
| Shipping a TS/Next.js agent UI | Vercel AI SDK ToolLoopAgent; HarnessAgent to wrap an existing coding CLI |
| Orchestrating specialists + a coding CLI | Docker Agent with harness: agents |
| Day to day coding in a terminal | Claude Code, Codex, or another coding agent harness. Pick the product, not a framework |
Treat the harness as a product surface: measure tokens, tool errors, approval friction, and end to end task success. Swapping the model with a weak harness often underperforms upgrading the harness around a mid tier model.
From Ahzy Capital (our own products, labeled as such): Get the free AI Agent Cheat Sheet: 24 copy and paste AI agent setups for 8 types of small business, with prompts and workflows. Building agents for clients? The AI Agency Playbook ($47) is our 6 module course with client scripts and pricing guidance. We make and sell these, so they aren't independent picks.
FAQ
What is an agent harness in simple words?
It is the runtime around an LLM that lets the model use tools, keep state, stay inside permissions, and finish multistep jobs. The model thinks; the harness does the work and feeds results back.
Is an agent harness the same as an agent framework?
No. A framework is how you build the agent (libraries and abstractions). A harness is how the agent runs (tools live, context injected, sandbox, stop rules). Many frameworks ship a default harness; coding products ship a harness without asking you to assemble a framework.
What is harness engineering?
Designing and improving that runtime so agents stay reliable: context management, tool orchestration, verification loops, guardrails, and recovery across sessions. Prompt wording is one input; the harness is the system.
What is a coding agent harness?
A harness specialized for software work: repo tools, shell, diffs, tests, instruction files, and often MCP. Claude Code, Codex, Cursor's agent, and Pi are examples. Some orchestrators (Docker Agent, AI SDK HarnessAgent) can delegate to those CLIs as subagents.
Agent harness vs agent scaffolding, which term should I use?
They mean the same layer. "Scaffolding" appears in older safety and research writing; "harness" is the term LangChain, Anthropic, Databricks, and most 2026 product docs use. Prefer "harness" unless you are citing a source that says scaffolding.
Do I need a custom harness or is a framework enough?
If you are prototyping, a framework's default loop is enough. If agents run for hours, touch production systems, or must survive many context windows, invest in harness pieces: durable progress artifacts, sandboxes, approvals, and verification. The Anthropic long running pattern is a good template.
