Agent Harness vs Framework: What Is the Difference and When Do You Need Each?
Agent harness vs framework: a framework supplies reusable abstractions, while a harness runs and controls the agent loop. Learn when you need each.
Table of Contents
An agent framework supplies reusable abstractions for constructing an agent, while an agent harness is the configured execution and control layer that runs the model-tool loop. They are not mutually exclusive: a framework can provide part or all of a harness, and many production systems use framework primitives inside an opinionated harness.
What Is the Difference Between an Agent Harness and a Framework?
A framework gives developers reusable components such as agent objects, tool interfaces, state stores, routing primitives, and workflow controls. A harness connects and configures those components for execution: it calls the model, handles actions, carries state, applies policies, records results, and decides when the run stops.
The distinction is about role, not packaging. A library can provide only low-level primitives, or it can include a managed loop and defaults that perform harness responsibilities. An agent product can expose a complete harness while still using one or more frameworks internally.
This is why a binary choice between framework and harness is misleading. Teams need both sets of responsibilities, but they can inherit, configure, or build them in different proportions.
For the foundational definition, see what an agent harness is.
Why Do Framework and Harness Definitions Overlap?
The agent ecosystem has no universally enforced vocabulary. Maintainers use framework, SDK, runtime, scaffold, and harness differently, and individual products often span several layers.
The Hugging Face agent glossary separates scaffolding from the harness. In that model, prompts, tool descriptions, parsing, and context form the scaffold. The harness is the execution layer that calls the model, handles tools, and decides when to stop.
LangChain uses a broader product taxonomy. Its documentation describes Deep Agents as an opinionated, batteries-included framework and an agent harness. That phrasing is not a contradiction. It says the product provides reusable software while also shipping an executable agent pattern with configured defaults.
The safest approach is to inspect responsibilities instead of trusting a label. Ask who owns the loop, tool execution, state, permissions, recovery, observability, and outcome checks.
What Does an Agent Framework Usually Provide?
An agent framework usually provides reusable abstractions that make agent behavior easier to define and compose. Common examples include:
- Agent and tool interfaces
- Model adapters
- State or memory connectors
- Routing and handoff primitives
- Workflow or graph controls
- Hooks and middleware
- Tracing integrations
- Deployment interfaces
These capabilities do not imply that every framework is low level. The OpenAI Agents SDK includes agents, tools, handoffs, guardrails, sessions, tracing, and a built-in agent loop. Developers can use its Runner to manage turns and tool execution or use the Responses API directly when they want to own that loop.
Google ADK similarly includes workflow agents for sequential, parallel, and iterative orchestration. CrewAI provides abstractions for agents, crews, flows, tools, and processes. Their APIs differ, but all reduce the amount of infrastructure a team writes from scratch.
A framework becomes your harness when you configure its primitives into the concrete runtime that operates your agent. You do not need a separate package carrying the harness label.
What Does an Agent Harness Usually Control?
A harness controls execution for a particular agent or class of agents. Its responsibilities commonly include:
- Assemble the instructions, relevant context, state, and available tools.
- Call the selected model.
- Parse the response and validate requested actions.
- Apply permissions, limits, and approval policies.
- Execute approved tools and capture their results.
- Update state and record the trajectory.
- Continue, retry, escalate, or stop.
An opinionated harness may also ship built-in tools, context compression, filesystem access, a sandbox integration, planning, subagents, or persistent memory. Those features are product choices, not requirements that define every harness.
LangChain Deep Agents is a clear example. Its official documentation describes planning, context management, filesystem backends, shell execution with sandbox backends, and subagent spawning. It builds these capabilities on LangChain and LangGraph rather than replacing them.
A small custom harness can be much thinner. For example, an application might expose two tools, keep task state in a database, require approval for writes, and stop after ten turns. It is still a harness even without planning, long-term memory, or a filesystem.
How Do Framework and Harness Responsibilities Compare?
The table below describes common roles rather than universal product rules.
| Responsibility | Typical Framework Role | Typical Harness Role |
|---|---|---|
| Agent and tool abstractions | Defines reusable interfaces | Configures concrete agents and approved tools |
| Model access | Supplies adapters and settings | Selects and calls the model for each run |
| Execution loop | May provide a runner or graph primitives | Configures how the deployed loop behaves |
| Context and state | Supplies stores, reducers, or middleware | Decides what each turn sees and what persists |
| Tool execution | Defines schemas and invocation interfaces | Validates, authorizes, executes, and records calls |
| Safety controls | Supplies guardrail and approval primitives | Applies the chosen policies to real actions |
| Recovery | Supplies hooks, errors, and retry primitives | Sets retry, timeout, fallback, and escalation rules |
| Evaluation | Integrates traces and evaluators | Records trajectories and checks task outcomes |
A framework offers degrees of freedom. A harness turns selected choices into running behavior. The boundary moves depending on how much the framework supplies and how much the application configures.
Where Do Current Agent Products Sit on the Spectrum?
The following labels describe how maintainers present the products and which responsibilities they expose. They are not permanent industry classifications.
| Product | Practical Position | Why |
|---|---|---|
| LangChain | Framework with agent-building primitives | Provides model, tool, middleware, and agent abstractions |
| LangGraph | Low-level orchestration runtime | Lets teams define stateful graphs and execution control |
| Google ADK | Agent development framework | Provides agents, tools, sessions, and workflow agents |
| CrewAI | Multi-agent framework | Provides agents, crews, flows, tools, and process controls |
| LangChain Deep Agents | Opinionated harness built on frameworks | Adds planning, context management, filesystems, and subagents |
| Claude Code | Coding-agent product with a vendor harness | Ships a configured coding loop, tools, permissions, and context behavior |
| OpenAI Agents SDK | SDK/framework with managed runtime behavior | Provides composable primitives plus a Runner-managed agent loop |
OpenAI’s SDK shows why labels alone fail. Its primitives behave like a framework, while its Runner performs harness work by managing turns, tools, guardrails, handoffs, sessions, and stop conditions.
Deep Agents demonstrates composition in the other direction. It is an opinionated harness built on LangChain and LangGraph. The harness packages and configures framework capabilities instead of making frameworks obsolete.
Do Harness Changes Improve Performance Without Changing the Model?
Yes, harness changes can materially affect measured performance while model weights remain fixed. Two vendor case studies illustrate the effect, but neither proves that harness work always matters more than a model upgrade.
LangChain reports that it improved Deep Agents Code from 52.8% to 66.5% on Terminal-Bench 2.0 while keeping GPT-5.2-Codex fixed. The reported changes included prompts and middleware hooks. This isolates a harness-level improvement for that agent, model, benchmark, and experiment setup.
Vercel reports another task-specific result in its text-to-SQL agent case study. The team replaced many specialized tools with filesystem access, Bash, and two tools inside a sandbox.
Across five representative queries, Vercel reported success increasing from four of five to five of five, average token use falling by 37%, and average execution time improving by 3.5 times. The sample was small, and the company says the approach depended on a well-structured semantic layer.
These results support a bounded conclusion: prompts, tools, context, middleware, and execution design can move task metrics without changing model weights. They do not compare those gains with a model upgrade, so they cannot establish that harness changes generally matter more.
For the broader architectural evidence, see agent harness architecture.
How Can You Decide Which Layer Your Team Should Own?
Use the Future AGI Five-Question Ownership Test. It is a decision aid for assigning responsibilities, not a standard industry taxonomy.
- Loop: Do you need to customize how the agent plans, acts, retries, and stops?
- Tools: Do you need custom schemas, execution environments, credentials, or approval policies?
- State: Do you need task-specific persistence, context selection, or recovery after interruption?
- Controls: Do you need precise cost, latency, permission, or compliance boundaries?
- Evidence: Do you need trajectory-level traces and outcome checks tied to release gates?
If most answers are no, an opinionated harness may reduce implementation work. If several answers are yes, choose a framework or runtime that exposes those control points. Most production teams inherit some defaults and customize the parts tied to their failure modes.
The test also prevents category-driven purchasing. A product called a framework may already own the loop, while a product called a harness may require substantial configuration. Evaluate the responsibilities you inherit, not the noun on the homepage.
When Is a Framework the Better Starting Point?
Start from framework or SDK primitives when your workflow needs custom control. This is common when you have deterministic business logic around a few agentic steps, an existing service architecture, or strict requirements for state, credentials, deployment, and observability.
A framework is also useful when the agent loop is not the right shape. A graph or workflow runtime can combine deterministic steps, human approvals, parallel jobs, and model-driven decisions without forcing the whole system into one autonomous loop.
Using a framework does not mean building every component yourself. Many frameworks already provide runnable agents, tool execution, state, guardrails, and tracing. The tradeoff is that your team owns more configuration and integration decisions.
When Is an Opinionated Harness the Better Starting Point?
Choose an opinionated harness when its defaults closely match the task. Coding and research agents often benefit from built-in file operations, context management, planning, subagents, and sandbox integrations because those responsibilities recur across implementations.
The advantage is speed to a useful baseline. The risk is constraint: built-in prompts, tool models, storage assumptions, or permission flows may not match your production environment.
Test the harness on representative tasks before adopting it. Inspect failures at the trajectory level and confirm that the product exposes the controls you will need when a default stops working.
For a deeper runtime comparison, see agent harness vs runtime vs framework.
When Should You Use Both a Framework and a Harness?
Using both is common because the layers compose. A framework supplies abstractions and extensibility. An opinionated harness configures those primitives into a working execution pattern.
Deep Agents is one example: LangChain and LangGraph provide underlying abstractions and runtime capabilities, while Deep Agents adds defaults for planning, filesystems, context management, and delegation. A team can keep those defaults and replace only the parts tied to its use case.
A custom application can follow the same pattern. It might use an SDK’s agent and tool interfaces, then add its own state store, approval service, retry policy, evaluation pipeline, and deployment controls. The result is a team-owned harness built with framework components.
MCP can provide one tool-integration path inside either design. See agent harness vs MCP for that boundary.
How Does This Choice Affect Agent Reliability?
Framework selection affects what is easy to express. Harness design affects how those choices behave during a real run. Neither layer can guarantee reliability by itself.
A framework may expose retries, permissions, memory, and tracing, but the harness configuration determines thresholds, scopes, storage rules, and stop conditions. A capable model can still fail if it receives the wrong context or ambiguous tools. A strong harness cannot recover capability the model does not have.
This is why evaluation belongs beside the execution loop. Teams need to check tool selection, arguments, returned payloads, recovery behavior, policy compliance, and final outcomes across representative trajectories. Evaluating tool-calling agents requires more than scoring the last message.
The practical decision is therefore not framework or harness. It is which responsibilities you will inherit, which you will configure, and which you must validate yourself.
For the engineering discipline behind those decisions, see harness engineering.
Frequently asked questions
What is the difference between an agent harness and an agent framework?
Can I use an agent framework without a separate harness product?
Does an agent harness replace LangChain or another framework?
Is the OpenAI Agents SDK a framework or a harness?
Do harness improvements matter if the model stays the same?
When should I use a framework, an opinionated harness, or both?
An agent harness is the runtime layer around an LLM that manages tools, context, state, execution, and safety. Learn how it shapes reliability.
How agent harness architecture shapes performance across five dimensions, from context and tools to safety and the loop that often outweighs a model upgrade.
Framework, runtime, or harness: what each agent layer actually covers, where reputable sources disagree, and how to tell which one your stack is missing.