Agent Harness Handbook

Appearance

Choosing a Framework or Platform

At a glance Which foundation should you build an agent on? This article lays out writing your own loop, code frameworks, and platforms along a single spectrum, compares LangGraph, CrewAI, AutoGen, OpenAI Agents SDK, Claude Agent SDK, Dify, and Coze on abstraction level, control, and lock-in risk, and closes with a scenario-based decision tree.

Choosing a Framework or Platform ​

If you've read the earlier chapters, you already know what components make up a harness and what trade-offs each one carries. Now for the most practical question of all: when it's your turn to build an agent, which foundation do you pick?

First, this site's position: choosing a foundation isn't about picking "the strongest framework" — it's about deciding which layers of the harness you write yourself and which you outsource. The more you outsource, the faster you get started, but the thicker the black box you hit when debugging. Every pain point you read about in Observability comes back on a platform in the form of "you can't see the inner loop."

A Three-Layer Spectrum ​

As of mid-2026, the foundations on the market line up along a spectrum:

text
        Your control over the loop ─────────────────────────────► High
        Speed from zero to running ◄───────────────────────────── Fast

 ┌─────────────────────┐  ┌───────────────────────────┐  ┌────────────────────────┐
 │  Write your own     │  │      Code frameworks      │  │       Platforms        │
 │  loop               │  │                           │  │                        │
 │                     │  │  LangGraph / CrewAI /     │  │  Dify (self-hostable)  │
 │  Bare while loop    │  │  Microsoft Agent          │  │  Coze (managed SaaS)   │
 │  + model API        │  │  Framework /              │  │                        │
 │                     │  │  OpenAI Agents SDK /      │  │  A complete harness    │
 │  Context, tools,    │  │  Claude Agent SDK         │  │  out of the box; you   │
 │  stop conditions,   │  │                           │  │  only orchestrate      │
 │  all hand-written   │  │  Gives you primitives     │  │  and configure         │
 │                     │  │  and a harness; you       │  │                        │
 │  Example: this      │  │  build the loop           │  │  Example: support      │
 │  site's minimal     │  │  structure yourself       │  │  bots, marketing       │
 │  loop               │  │                           │  │  content pipelines     │
 └─────────────────────┘  └───────────────────────────┘  └────────────────────────┘

Three judgments up front, expanded below:

  • There is no "best" — only "the spot on the spectrum that matches your needs." Articles ranking frameworks mostly compare feature checklists, but feature checklists expire; a position on the spectrum doesn't.
  • The left end isn't "primitive" — it's "transparent." Writing your own loop means every piece of context assembly and every tool execution lives in your code, a decisive advantage for deep customization.
  • The right end isn't "low-end" — it's a "rented harness." Platforms turn architecture decisions into configuration options — the speed is real, and so is the ceiling.

The Seven Contenders at a Glance ​

What follows are facts verified as of mid-2026, focused on positioning and control rather than deep mechanics — LangGraph, Dify, and Coze each have a dedicated article on this site; head to the case-studies chapter for those.

LangGraph: A Controlled Loop in Graph Form ​

Built by the LangChain team and open-sourced under MIT, it shipped v1.0 alongside LangChain in October 2025 with a promise of no breaking changes before 2.0. Its core claim: an agent's control flow should be modeled explicitly as a state graph — nodes, edges, persistence, and breakpoints all declared by the developer. It's the framework that hands over the most control, and under this site's position it's the default answer for "when a framework is the right call." For a teardown of the mechanics, see Case Study: LangGraph.

CrewAI: Role-Playing Multi-Agent ​

Built by the independent company CrewAI ($18 million raised in October 2024), open-sourced under MIT. The abstraction is "Crew (a team of agents with roles) + Flow (event-driven workflows)": you write a persona and task description for each agent and let them collaborate like a small team. It's one of the fastest code frameworks to get started with, but the romantic narrative of role-based collaboration papers over one fact — conversational coordination between multiple agents is very hard to debug in production. A commercial edition, CrewAI Enterprise, provides a control plane.

AutoGen → Microsoft Agent Framework: Replaced — Don't Start New Projects Here ​

This is the easiest trap in the whole selection exercise, so it deserves its own section. AutoGen is the multi-agent conversation framework Microsoft Research open-sourced in late 2023, and for years it was the default choice for multi-agent research. But as of mid-2026: AutoGen is in maintenance mode. In October 2025 Microsoft announced it would merge AutoGen with Semantic Kernel into the Microsoft Agent Framework (MAF), which reached 1.0 GA in April 2026 on both .NET and Python. MAF inherits AutoGen's conversational multi-agent abstraction and Semantic Kernel's enterprise-grade capabilities (session state, middleware, telemetry), and adds graph workflows.

A Note on Selection

Don't start a new project on the stale impression that "AutoGen is popular." Existing AutoGen code can keep being maintained, but new projects should evaluate Microsoft Agent Framework (MIT) or another foundation directly. This is also the best possible illustration of why framework status has to be rechecked every time — a comparison written a year ago can be wholly obsolete today.

OpenAI Agents SDK: Minimal Primitives + an OpenAI Ecosystem Slot ​

Released in March 2025, it is the production successor to the experimental Swarm project — MIT licensed, with implementations in both Python and TypeScript. The design philosophy is radical minimalism: the core primitives number exactly five — Agent, Handoff (transferring conversational control to another agent), Guardrails, Sessions, and Tracing.

Two common misconceptions deserve clearing up:

  • It is not exclusive to OpenAI models. It defaults to the OpenAI Responses API, but adapter layers such as LiteLLM let you connect 100+ model providers — it's just that the engineering polish is concentrated on the OpenAI path.
  • The real lock-in point is Tracing. Built-in tracing ships data to the OpenAI platform by default; using your own observability stack means wiring up a separate processor. The code is MIT; the data pipeline is not.

Claude Agent SDK: A Finished Harness, Exposed ​

Originally the Claude Code SDK, it was renamed Claude Agent SDK in September 2025 — and the rename is itself a positioning statement: this thing's scope reaches beyond writing code. It is the programmatic interface to the same harness that drives Claude Code: built-in file/terminal/search tools, subagent dispatch, permission hooks, and the CLAUDE.md memory mechanism, all forged in a real product with a massive daily active user base.

Its Special Position on the Spectrum

Other frameworks give you "primitives for building a harness"; the Claude Agent SDK gives you "a harness that's already tuned" — your job is to fill in the system prompt, the tools, and the permission policy. That gives it a startup speed no code framework should have, and the price is a double binding: to the Claude models (billed per token) and to Anthropic's judgment of what a good harness looks like. This is not a permissive open-source framework; it's an SDK used under Anthropic's commercial terms.

Dify and Coze: Two Shapes of the Platform End ​

  • Dify: An LLM application development platform open-sourced in April 2023, with more than 150k GitHub stars. The license is Apache 2.0 plus two additional conditions (keep the frontend copyright notice; no multi-tenant SaaS offered to others without written permission) — essentially unrestricted for self-hosted internal use, but read the terms before you build a business on it. It positions itself as "middleware between models and applications," with canvas orchestration + RAG + plugins + LLMOps productized as a complete suite. See Case Study: Dify for details.
  • Coze: ByteDance's all-in-one agent platform. The China edition launched in February 2024, with managed SaaS as the primary form (zero-code orchestration + one-click publishing to Doubao/Feishu/WeChat). On July 26, 2025, its zero-code development platform Coze Studio and its evaluation tool Coze Loop were open-sourced under Apache 2.0 (alongside the previously open-sourced Eino framework), making self-hosting possible — but the ecosystem's center of gravity remains on the managed side. See Case Study: Coze for details.

Deciding by Scenario ​

Translate your requirements into a spot on the spectrum, and the answer often announces itself:

text
Q1. Does anyone on the team write code?
 ├─ No ────────────────────────────────────► Coze (managed SaaS)
 │                                           Zero code, channel publishing built in
 └─ Yes
    └─ Q2. Need self-hosting / data never leaves the intranet?
       ├─ Yes, mostly knowledge-base Q&A ──► Dify (self-hosted)
       │  and fixed flows                    Watch the multi-tenant clause
       └─ Not required, or highly custom flows
          └─ Q3. Shape of the task?
             ├─ Prototype validation, demo ─► Claude Agent SDK
             │  within a week (Claude lock-in    or CrewAI
             │  is acceptable)
             ├─ Production coding agent ────► Claude Agent SDK,
             │                                or write your own loop
             │                                (a framework is mostly a
             │                                liability here)
             ├─ Enterprise process automation ► LangGraph (first choice)
             │  (approvals, state, auditability, or MAF (.NET stack)
             │  long-running jobs over weeks)
             └─ Deep customization / new ────► Write your own loop
                harness research                (see next section)

A Counterintuitive Lesson

"Prototype with a framework, rewrite by hand for production" sounds economical and often costs double: the abstraction habits a framework prototype instills (graphs, roles, handoffs) seep into how you understand the problem, and they are hard to strip out when you rewrite. The sturdier path is to prototype with the simplest version of the final form — for instance, write a 100-line loop directly to validate that the task is feasible, then decide whether a framework is worth introducing.

Head-to-Head Comparison ​

A snapshot as of mid-2026. Licenses and activity levels change; check the official repositories before you decide.

FoundationMaintainer / LicenseAbstraction LevelYour Control over the LoopEcosystem & IntegrationsLock-In Risk
LangGraphLangChain / MITState graph (explicit control flow)High: you draw the loop's topologyLargest: models, tools, LangSmith observabilityLow; the cost of leaving is the graph way of thinking
CrewAICrewAI / MITRoles + tasks + FlowMedium: coordination inside a crew is a black boxLarge: plugins, enterprise control planeLow; but the multi-agent paradigm itself is hard to migrate
MAF (AutoGen's successor)Microsoft / MITConversational multi-agent + graph workflowsMedium-highDeep Azure integration; .NET as a first-class citizenMedium: the pull of the Azure ecosystem
OpenAI Agents SDKOpenAI / MITFive primitives (Agent/Handoff/...)Medium-high: few primitives, many escape hatchesOpenAI-hosted tools; third-party models can be attachedMedium: Tracing phones home to OpenAI by default
Claude Agent SDKAnthropic / commercial termsA finished harnessLow-medium: the loop belongs to Claude CodeThe full Claude Code toolset, MCP, SkillsHigh: double binding to models and harness judgment
DifyDify / Apache 2.0 + additional conditionsVisual orchestrationLow: the loop is built into the platformHundreds of models, plugin marketplace, RAGMedium-low: self-hostable, but leaving means rewriting the orchestration
CozeByteDance / SaaS (Studio open-sourced under Apache 2.0)Zero-code canvasLowByteDance-family channels (Doubao/Feishu/WeChat)High: data and channels deeply bound to the managed side

The right way to read this table: first cross out the rows whose lock-in risk and loop control you cannot accept, then compare ecosystems among what's left — not the other way around.

When to Skip the Framework and Write Your Own Loop ​

Finally we arrive at the judgment this site keeps repeating. The more of these signals you see, the more likely a framework is a net liability:

  • What you're building is precisely harness research or deep customization. Say you want to validate a new context engineering strategy or a new subagent dispatch protocol — a framework's abstraction layers wall you off from the very thing you want to study.
  • The task is one of those shapes — like a coding agent — where the loop itself is the product. The common thread across the Claude Code, SWE-agent, and OpenHands case studies is that their competitiveness lives entirely in the loop, the tools, and the context pipeline; not one of them could have been built on an off-the-shelf framework.
  • The framework's black box starts eating your debugging time. When you catch yourself reverse-engineering "why didn't this handoff fire" or "why was this node's state overwritten," the time the framework saved you has already been handed back.
  • Models are iterating fast. Framework configurations finely tuned to an old model can become dead weight on a new one, while a thin hand-written loop carries the lowest cost across model upgrades.

And the barrier to writing your own loop is badly overestimated — the minimal loop in What Is an Agent Harness is only a few dozen lines, with seven responsibilities laid out plainly. Build Your Own Harness walks you through writing it from zero, and The Harness Tutorial layers on the engineering infrastructure step by step. Once you've written it, you'll look back at frameworks with a new identity: you're no longer a framework "user" but a "peer" who can read the design intent behind every layer. That is probably the most reliable payoff of writing your own loop — even if you end up choosing a framework, the person who knows what the framework is doing for them will always use it better than the one who doesn't.

Further Reading ​

References ​