Agent harness or agent framework?

In July I wrote Prompt, Context, Harness, Loop, which split an agent into four parts and argued that the harness — the thing that owns the loop and decides what the model sees — was the part nobody talked about.

I checked this week. Two of the largest projects in the space now use the word in their own one-line description. LangChain's deepagents calls itself "the batteries-included agent harness." Y Combinator's qm calls itself "multiplayer agent harness for work."

So the word arrived. What hasn't arrived is the distinction, and every comparison article I can find still files harnesses and frameworks under one heading called "AI agent tools." Those are different products that fail in different ways, and picking the wrong one costs you a rewrite.

An agent framework is a library you build an agent with — you own the loop. An agent harness is a runtime that owns the loop and calls your model. Frameworks give you control and hand you the hard problems; harnesses solve the hard problems and take the control. Most teams reach for a framework when they wanted a harness.

What actually separates a harness from a framework?

Take the four parts from the original post and ask, for each one, who owns it — you or the tool?

The row that decides everything is Loop. In a framework you call the library from inside your own loop. In a harness, the harness is the program and your code is a plugin.

That inversion is why "we'll start with a framework and swap it later" so often fails. You're not swapping a dependency; you're inverting control flow.

The landscape, with real numbers

Pulled from the GitHub API on 2026-08-12. Every one of these was pushed to the same day, so activity isn't a differentiator — they're all alive.

Read the right-hand column as a taxonomy and it sorts itself. "Framework" and "platform" mean you own the loop. "Agent" and "harness" mean they do. The projects are telling you which one they are; the comparison articles just aren't reading it.

Note also that three of the eight are written in Rust or shipped as terminal binaries. That's not a language preference, it's a symptom: if your product is the loop, you are shipping a program, and programs care about startup time and single-binary distribution in a way libraries never do.

Which one do you actually want?

The honest test is a single question, and it isn't about features.

Does an agent run inside your application, or does your application run inside an agent?

If your product is a web service that occasionally needs to reason, you want a framework. The agent is a subroutine. You own the request lifecycle, your observability already exists, and you cannot hand control of the process to something else.

If your product is the agent — a coding assistant, a research tool, an autonomous worker — you want a harness. The loop, context management, tool dispatch and compaction are the hard parts, and they are also solved parts. Rebuilding them on top of a framework is the most common expensive mistake in this space, and it looks like progress for about six weeks.

The trap is that frameworks demo better. A framework demo is fifteen lines and a tidy diagram. A harness demo is a terminal, which looks like less work but is the finished product.

What does an agent harness actually solve for you?

Having built a small one, these are the parts that ate the time — and they're all invisible in a demo:

Context compaction. Not the summarisation call itself; deciding when, choosing what survives, and keeping the result stable enough not to destroy your prompt cache. I wrote about what a compaction does to your cache bill — it resets it entirely, which is correct behaviour and still expensive.

Tool result truncation. A tool returns 400KB of JSON. You cannot put that in the context and you cannot drop it. Every harness has a strategy here and they differ a lot.

Interruption and resumption. The user hits Ctrl-C mid-tool-call. What's the state? Frameworks mostly don't answer this because they assume you own the process.

Permission boundaries. Which tools can run without asking. qm's pitch is isolated workspaces per person, which is this problem at team scale.

Recovery from malformed output. The model emits a tool call with a missing required field. Retry, repair, or surface it? This one decides whether small models are usable at all — which is the subject of the benchmark I'm running next.

Each is a week of work and none of them is interesting. That's precisely the argument for not writing them yourself.

Where does the distinction break down?

Two honest complications, because a taxonomy that admits no exceptions is usually wrong.

deepagents is a harness shipped as a library. It calls itself a harness, and it is one, but it's a Python package you import rather than a binary you run. So it inverts control inside your process. That's a genuine third position and probably where the category is heading — harness semantics, library packaging.

LangChain calls itself a platform now, not a framework. With 144,078 stars and a decade of scope creep it contains both: primitives you build with, and higher-level runners that own the loop. The taxonomy applies to which part you use, not to the repo.

So the test isn't "which project is this?" It's "for the piece I'm about to depend on, who runs the loop?" Ask it per component and the answer stays useful.

What I'd tell someone starting today

Start with a harness and escape downward if you must. The reverse — start with a framework, grow into a harness — means rebuilding the five things above while shipping features, and everyone who does it says the same thing afterwards.

Read the one-line description literally. These projects are precise about what they are. "Platform," "framework," "harness," "agent" are load-bearing words chosen by people who know the difference.

Check who owns compaction before you commit. It's the single highest-leverage behaviour and the hardest to replace. If a tool won't tell you its compaction strategy, that's your answer.

Ignore star counts for this decision. opencode has 14× qm's stars and they're not solving the same problem. Popularity is a proxy for maturity, not fit — and every project here is actively maintained anyway.

TL;DR

• The distinction is control flow, not features. In a framework you call the loop; in a harness the loop calls you. Swapping between them isn't a dependency change, it's an inversion.

• The projects self-identify accurately. "Framework" and "platform" mean you own the loop (LangChain, CrewAI, Mastra); "agent" and "harness" mean they do (opencode, Codex, goose, qm, deepagents).

• The test is one question: does an agent run inside your application, or your application inside an agent?

• Harnesses solve five boring, expensive problems — compaction, tool-result truncation, interruption, permissions, malformed-output recovery. Each is a week you won't enjoy.

• deepagents is the interesting edge case: harness semantics in library packaging, which may be where the whole category lands.

Data

GitHub API, 2026-08-12. Star counts and languages as reported.
All eight repositories had commits pushed on the day of collection.

Star counts move; the taxonomy doesn't. If you're reading this much later, the numbers are stale and the four-part test still works.

References

• Prompt, Context, Harness, Loop: An Agent's Anatomy — the four-part split this post applies. Worth reading first if the terms above felt slippery.

• yc-software/qm — the clearest example of harness-as-product, and the one that takes multi-user permission boundaries seriously.

• langchain-ai/deepagents — a harness distributed as a library, from the project best known for the framework half of this distinction.

Next: I'm benchmarking whether small models can survive the malformed-output problem above — the one that decides if local agents are viable at all.

👉 Follow me: LinkedIn | GitHub