The most common questions about agent harnesses, explained. October 2026

Six months ago almost nobody said “agent harness” out loud. Now the term shows up in LangChain’s docs, Microsoft’s Agent Framework, OpenAI’s engineering blog, and a steady stream of Reddit and Hacker News threads asking what it means and whether it matters.

The threads tend to circle the same handful of questions. What is a harness, and how is it different from the framework I already use? If the model does the thinking, why would the wrapper around it change the outcome? How do I give an agent real access without handing it my credentials? Where should the thing run? How do I find out what it did after the fact? And should I build one or pick one?

This post answers those six questions in order. The answers draw on the public definitions from LangChain, Microsoft and OpenAI, benchmark results from the community, and our own work at Stacklok on Mecatl, an open source harness built to run as a distributed application rather than a desktop process. Where our experience shapes the answer, we say so.

1. What is an agent harness, and how is it different from a framework?

A harness is the runtime that turns a model into an agent. The model, on its own, maps a context window to an output. The harness runs the loop around it: it assembles the context, describes the available tools, executes the tool calls the model asks for, records what happened, enforces permissions and approval gates, manages session state, and decides when the task is done.

Microsoft’s Agent Framework docs put it plainly: a model can only generate text, and everything that lets it call tools, work through multi-step tasks and keep going until the job is finished is the harness.

The confusion with frameworks is understandable because one product often spans both. LangChain’s own docs draw the line like this: LangChain is a framework (abstractions you compose), LangGraph is a runtime (durable execution, persistence, streaming), and Deep Agents is a harness (a ready-to-run loop with tools, prompts and subagents already wired). Some of the lines between the offerings are blurry.

A short version that holds up well:

Layer	What you get	What you write
Framework (LangChain, CrewAI, Google ADK)	Primitives: agents, tools, state, routing	The control flow
Runtime (LangGraph, Temporal)	Durable execution, persistence, scaling	The graph or workflow
Harness (Claude Code, Deep Agents, Mecatl, Microsoft’s HarnessAgent)	A finished loop with tools, context management, permissions and sessions	Instructions, tool selection, policy

So if you already use a framework, you have not necessarily got a harness. You have the parts to build one. Whether that is a good use of your time is question six.

2. If the model does the thinking, why does the harness change the outcome?

The harness controls what the model sees, what it can touch, and what happens when it fails.

The benchmark data now backs this up. On SWE-bench Pro, swapping the harness moved pass@1 more than many model upgrades do: one analysis cited by AINews found the same model going from 23% to 52% depending on the harness, and harness rankings barely transferred across models. A smaller model in the right harness beat a larger model in the wrong harness.

Anthropic ran a simpler experiment that gets quoted a lot on Reddit: same model, same prompt, build a 2D game editor. Without a harness it burned $9 in 20 minutes and produced something that did not run. With a planner, generator and evaluator wrapped around it, the same model produced a playable game. OpenAI’s harness engineering post describes the same effect from the other direction: in a well-harnessed repository, a model that was unreliable becomes reliable.

A harness does a handful of concrete jobs the raw model cannot do for itself:

• Keeps the context window useful by compacting history and loading only what the current step needs
• Presents tools in a way the model can use well (fewer, more expressive tools beat a long menu of narrow ones)
• Catches a failed tool call and retries, falls back or escalates instead of letting the model drift
• Checks the work against tests, linters or an evaluator before calling it done
• Stops the model from doing things it should not, through permissions and approval gates

Every one of those encodes an assumption about what the model cannot yet do alone. As models improve, the scaffolding does not disappear. It moves up to harder problems, which is why the people shipping agents at scale (OpenAI’s Codex team, Anthropic’s Claude Code team, Cognition) all describe their work as harness engineering now rather than prompt engineering.

3. How do I give an agent tools and access without handing it my credentials?

Most harnesses still do this badly, because they grew up on laptops where the agent inherited whatever the developer could reach.

The desktop pattern looks like this: the agent runs as you, with your shell, your filesystem, your environment variables and your API keys. MCP servers are launched as child processes with the same inheritance. It works, and it is why coding agents got useful so fast. It also means a prompt injection in a README can exfiltrate your AWS keys, and nobody can say afterward which tool the agent called with which identity.

The pattern enterprises are converging on is different, and you can see it in Google’s Agent Mesh blueprints, in TrueFoundry’s managed harness, and in our own designs:

• The agent process holds zero standing credentials. Tool calls go through a gateway that injects the right token, scoped to the current task.
• Tools are a catalog, not a shell. The agent starts from an explicit list of what it may call, each with its own permission and audit boundary.
• MCP servers run in their own isolated containers, not as children of the agent process.
• Identity is explicit. When the agent calls an external system, the receiving side can tell whether the user, the agent, the session or a subagent three levels down is making the request.

That last point is the one we think most about. In a multitenant deployment, “who is calling?” is a real policy question, and Mecatl’s proposed answer is to make the harness its own SPIFFE trust domain and carry the full delegation chain in a JWT, so a downstream service gets a call stack of every identity involved. That is a design draft, not a shipped feature, and we are arguing about it in public.

On the MCP side the pattern is further along. ToolHive wraps every MCP server in an isolated container with a minimal permission profile and no local credentials, proxies the traffic, and emits the audit logs and identity enforcement that security teams ask for. The practical effect is that a developer can connect Claude Code or Cursor to a governed set of servers without shadow MCP sprawl on their laptop, and a platform team can run the same servers on Kubernetes with the same policy.

A harness that gives the agent an unrestricted shell is not wrong for a single developer. It is the wrong starting point for anything a security team has to approve.

4. Where should the harness run: laptop, container, or Kubernetes?

Start on the laptop. That is where every good harness pattern was discovered, and it is still the fastest way to learn what your agent needs. The question is what happens when you want the agent to run without a person sitting in front of it.

The common first move is to put the desktop harness in a container and deploy that. It is tempting because it works for a demo. It does not change how the harness is built. One long-lived process is still the UI, the agent loop, the sandbox, the credential store, the tool host and the session database all at once. When that pod gets evicted mid-task, the conversation is gone. When you want to roll a new version, every running session dies with it. Kubernetes taught the industry that a monolith in a container is still a monolith, and the lesson applies here too.

A cloud-native harness is built as a distributed application from the start. The agent loop is one component, and everything else sits behind an explicit interface:

Concern	Desktop harness	Cloud-native harness
Session state	In-process memory and local files	Durable store (Redis, a database) with a single-writer lease
Workers	One process per user	Disposable replicas; a replacement resumes from the last saved turn
Rollouts	Restart kills sessions	Roll the engine, sessions stay put
Clients	The terminal owns the loop	TUI, API, Slack, web UI attach to the same loop
Execution	The host shell	Assigned workspaces and command runners, isolated per session
Tools	Whatever is on the machine	A governed catalog, each tool with its own boundary

This is the approach we took with our open source, cloud-native harness, Mecatl. The same provider-agnostic loop runs in your terminal, as a service, or on Kubernetes via the mecak8s runtime, which pairs Redis-backed state and event history with Kubernetes leases, drain handling and disposable replicas. A worker dying becomes an inconvenience rather than a lost afternoon. The durability is turn-level, not transactional: work after the last saved turn boundary can be lost, and we say so in the docs.

Why does this matter for an enterprise specifically? Because the people who will use agents next are not developers, and the workloads that matter most are the ones nobody watches. A finance team running a month-end reconciliation agent, or a platform team running hundreds of concurrent coding sessions, needs the same things they already expect from any other service: it survives a node dying, it rolls out safely, it logs to the stack they already have, and it runs on infrastructure they control. A harness built for one person on one machine cannot give them that no matter how good the container is.

If your organization already runs Kubernetes, the strongest argument for a cloud-native harness is that it stops being a special case. It is a deployment, with a Helm chart, an IdP integration and OTel traces, operated by the same team with the same tools as everything else.

5. How do I find out what the agent did, and why?

You need an event history, not a chat transcript. A transcript tells you what the model said. An event history tells you which tool was called, with what arguments, under which identity, what came back, how many tokens it cost, and which turn boundary the session was saved at. Debugging an agent that ran for six hours unattended is impossible without the second kind of record.

Most harnesses now emit something. The useful questions to ask of any of them:

• Can I replay a session from its events, or only read a summary of it?
• Does every tool call carry the identity that made it, so an audit can answer “who did this” without guessing?
• Do traces land in the observability stack I already run (OpenTelemetry into Grafana, Datadog, Honeycomb), or in a vendor console I have to log into separately?
• Is cost attributed per session, per user and per tool, or only per API key?
• Does the audit log live on infrastructure I control, or on a SaaS provider my compliance team has not approved?

That last question is the one that decides deployments in regulated industries. Most MCP and agent platforms are SaaS. If your policy prohibits sensitive data from passing through a third-party processor, a harness whose logs, state and tool traffic stay inside your cluster is the only kind you can run. Stacklok’s Kubernetes operator was built for exactly this: declare policy as a resource, integrate with your IdP, emit OTel traces, and keep everything self-hosted. Mecatl records the full event history in the same durable store that holds session state, so the audit trail and the resume point are the same data.

One practical tip from the field reports: read the model’s outputs regularly, not just the dashboards. OpenAI’s team calls this “seeing like an agent.” Most harness problems show up first as the model doing something slightly odd for a reason you can only understand by reading the trace.

6. Should I build my own harness?

Probably not the loop, but yes you should build the environment around it.

The loop itself (call model, run tool, append result, repeat) is a weekend project, which is why there are hundreds of them on GitHub. The parts that take longer are around the loop: context compaction that does not lose the thread, tool schema validation, bash timeouts, subagent delegation, workspace isolation, crash recovery, and a permission model that holds up under adversarial input. One field report put a production harness at thousands of lines of battle-tested scaffolding, and that matches our experience building Mecatl.

What you should build is the harness-specific layer: the instructions, the tool catalog, the architectural checks, the evaluators, and the repository conventions that make your codebase legible to an agent. OpenAI’s team shipped over a million lines of production code with zero human-written lines using that approach, and their post is explicit that the work was designing environments and feedback loops, not writing the runtime.

When you pick a harness, the questions that matter for an enterprise are mostly infrastructure questions:

• Does it run on infrastructure you control, or only as a vendor’s hosted service?
• Is the loop coupled to one model provider, or can you swap providers and keep the rest?
• Can it run headless, with durable state, so a job survives a restart?
• Does it govern tools through a catalog with identity and audit, or inherit the host shell?
• Can more than one kind of client (terminal, API, Slack, a web app) attach to the same loop?
• Is it open source, so you can read the permission model before you trust it?

Many harnesses on the market fail the first question. The vertically integrated ones work well right up until you need to run them somewhere the vendor did not anticipate. The reason we built Mecatl as open source and provider-agnostic, and the reason our platform runs on your Kubernetes rather than ours, is that the enterprises we talk to want to choose their models, control their costs, and keep their data where their compliance team can see it.

Where to start

If you are evaluating harnesses this quarter, run the same task on your own repository through two or three of them and compare the traces, not the demos. Pay attention to what the agent could reach, what it was denied, and whether you could tell afterward.

If you want to try the cloud-native shape, check out Mecatl; it runs in your terminal first, and deploys to Kubernetes with the mecak8s Helm chart when you are ready. ToolHive handles the MCP side either way. Both are open source, and the identity and tool-grant designs are open drafts we would like torn apart.