A Taxonomy of Agent Frameworks
35 min readreadingThe Framework Landscape
1 of 14Agent Frameworks in Depth
Up next · When No Framework Is the Right Answer
The agent you built from scratch in Agent Architectures: Loops, Planning & Memory has been running in staging for a month. It works. Then the roadmap lands: three more agents by Q3, human approval on anything that touches money, runs that survive deploys, and an on-call rotation that is not just you. Someone in the planning meeting says the word "framework", and by Friday you are eleven browser tabs deep — each repo with a polished README, a Discord badge, and a demo that books a flight in fourteen lines. The demos are all impressive and all useless for your decision, because none of them show the thing you actually need to know: what happens at 2 a.m. when the run dies at step forty-seven.
You are in a better position than most engineers making this choice, because you have already built the thing these frameworks wrap. You know that under every one of them sits the same few hundred lines: a loop that calls a model, a dispatch table for tools, a message list that is the real state, and stop conditions that keep the bill finite. That knowledge changes how you read a framework. You stop asking "what can it do?" — they can all do everything, eventually — and start asking "what does it decide for me, and what does that decision cost when it is wrong?"
This lesson is a map of the 2026 framework landscape organized by philosophy rather than popularity. Each philosophy is a bet about where the complexity of agent engineering lives — and every bet leaks somewhere. By the end you will be able to place any framework you meet, including ones that do not exist yet, into this taxonomy in about five minutes of reading its docs, and you will know which leak you are signing up for.
Ignore feature matrices. Three questions separate frameworks more cleanly than any list of integrations, and they map directly onto what you built by hand in the previous course.
What is the state model? Where does the agent's state live — the message history, the intermediate results, the step counter? Is it a typed object you can inspect, or a dict threaded through closures? Is it serializable, so a run can be saved and resumed, or does it live only in Python object graphs that die with the process? You learned in the checkpointing lesson of Agent Architectures that resumability is a property you design in from the start or retrofit in pain. A framework's state model tells you which of those it chose.
What is the control surface? When you need the agent to do A, then either B or C, then wait for a human — where do you express that? In code you write (a loop, a graph)? In prompts the model interprets ("you are a researcher, hand off to the writer when done")? In conversation dynamics (agents talk until one says TERMINATE)? The further the control surface sits from code, the faster the demo and the harder the guarantee. A routing bug in code is a stack trace; a routing bug in a prompt is a vibe.
What is the failure behavior? Kill the process mid-run: what survives? A tool throws: who catches it, and does the model get a chance to recover, as you built in Tool Use, Code Execution & Sandboxing? The agent loops: whose budget stops it? And when something goes wrong, what do you actually debug — your code, or seven frames of framework internals between your breakpoint and your prompt?
The bet: control flow should be data. LangGraph models an agent as a state machine — typed state flowing through nodes (plain functions) connected by edges (static or conditional). The loop you wrote by hand becomes a literal cycle in a graph you can draw, diff, and test edge by edge. Because all state transits through a declared schema, persistence falls out almost for free: a checkpointer saves state after every node, which is what makes resume-after-crash, time-travel debugging, and human-in-the-loop pauses first-class features rather than heroics. LangGraph 1.0 shipped in late 2025 with a stability guarantee on the core API — notable mostly because so few agent frameworks have ever made one.
Where it leaks: ceremony. A three-step agent that
is one while loop by hand becomes a schema, four node
functions, six add_edge calls, and a compile step.
Reading a graph means hopping between the wiring and the node
bodies — the control flow is visible, but it is visible in a
diagram, not in the top-to-bottom order of a file. Teams adopt
LangGraph for the checkpointing and the interrupts, then discover
that every trivial agent now carries the full apparatus. It is the
control-flow standard-bearer, and it charges you the standard-bearer's
tax. Lessons 3 through 6 of this course go deep on it, precisely
because its concepts — reducers, checkpoints, interrupts, fan-out —
are the ones every other framework eventually re-invents.
The bet: the right abstraction is organizational.
CrewAI asks you to describe agents the way you would describe a
team: each agent gets a role, a goal, and
a backstory; work is divided into tasks;
a crew executes the tasks in a sequential or
hierarchical process. The pitch is speed and legibility — a product
manager can read a crew definition and understand what the system
does, and you can stand up a working multi-agent pipeline in an
afternoon.
Where it leaks: the metaphor is made of prompts. Role, goal, and backstory are not architecture — they are strings concatenated into a system prompt. When the "researcher" hands garbage to the "writer", your debugging surface is prompt text, and your fix is prompt text. Control flow lives partly in the process type and partly in what the model decides to do with its instructions, which means the gap between demo and production is the gap between "usually does the right thing" and "provably routes correctly". CrewAI itself conceded the point by shipping Flows — an event-driven, code-first orchestration layer underneath crews — which is the framework telling you that role abstractions alone do not control production systems. The honest position in 2026: crews for rapid prototyping and demos, flows (or another framework) for the parts that must not be wrong.
The bet: collaboration is a conversation. The AutoGen line — from Microsoft Research's 2023 paper — models multi-agent systems as a group chat: agents post messages, a manager (or a policy) picks the next speaker, and the system runs until someone signals termination. It is the most natural fit for problems that genuinely are conversations — debate, critique-and-revise loops, pair-programming patterns like the classic writer/executor duo — and it has the deepest research pedigree of anything in this lesson.
Where the lineage went. The history matters because you will meet all three descendants in the wild. The original AutoGen went through a ground-up 0.2-to-0.4 rewrite (actor model, async-first); the community forked the older line as AG2; and in 2025-2026 Microsoft merged AutoGen with Semantic Kernel into the Microsoft Agent Framework — conversation patterns from AutoGen, enterprise plumbing (typed workflows, .NET parity, Azure integration, observability) from Semantic Kernel. One research project, three successor codebases in three years: keep that in mind when Section 9 talks about churn.
Where it leaks: emergence is not a control surface. A conversation may not converge. Termination is a prompt-level convention ("reply TERMINATE when done") backed by hard caps, so your cost ceiling is max-turns times context-growth — and context grows quadratically as every message is re-read by every speaker. Testing is harder too: a route in a graph either fires or does not; a conversation has a distribution of trajectories, and you are writing evals over that distribution — the discipline covered in Evaluation & Benchmarking of Agentic Systems. The pattern earns its cost when the problem is genuinely dialogic; Multi-Agent Systems Engineering draws that boundary precisely.
The bet: the framework should barely exist. Two libraries carry this flag in 2026, with very different accents.
smolagents (Hugging Face) keeps its core to
roughly a thousand lines and makes one sharp architectural claim:
the model should act by writing code, not by emitting JSON
tool calls. A CodeAgent writes a Python snippet per
step; the snippet can call tools, loop, branch, and compose results
— collapsing what would be five JSON-tool round-trips into one
generation, which the maintainers report cuts steps by roughly 30%
on benchmark tasks. The price of that power is that you are now
executing model-written code, so the sandbox discipline from
Tool Use, Code Execution & Sandboxing stops being
optional.
Pydantic AI treats an agent as a typed function: dependencies injected in, a Pydantic-validated structured output coming back, with the type checker and validation layer doing the work that other frameworks do with orchestration. It feels like FastAPI for agents, deliberately. Note that even the minimalists churn: Pydantic AI shipped a breaking V2, and code written against V1 needed real migration work — minimal API surface does not mean frozen API surface.
Where it leaks: everything the framework refuses to own, you own. Durable execution, approval gates, multi-agent orchestration, streaming plumbing — with minimalist tools these are your code. For a team that already built them from scratch (you), that can be exactly right. It is a bad fit for a team that wanted the batteries.
The bet: vertical integration wins. Every major model vendor now ships its own agent framework, tuned to its models and welded to its platform:
Where it leaks: the lock-in surface is the whole orchestration layer. These SDKs are genuinely good — the vendor tunes the harness against its own models and ships platform features (tracing, sessions, evals) that third parties bolt on later. But handoffs, guardrails, hooks, and session semantics are not portable concepts with stable meanings across vendors; they are API surfaces. Adopting one prices in a rewrite of your orchestration if you ever move — model-agnostic escape hatches exist in most of them, but they are visibly second-class. Lesson 12 (Framework Evaluation Criteria and Lock-In) makes this cost measurable rather than vibes-based.
The bet: the agent is a product feature, so it should live
in the product's stack. A large fraction of agents ship
inside web products maintained by TypeScript teams. The
Vercel AI SDK owns the UI seam — streaming
primitives, useChat, generative UI — and has grown
loop-control and tool-orchestration APIs that make it a real agent
runtime, not just a fetch wrapper. Mastra (from
the Gatsby founders) is the fuller framework on that side of the
fence: workflows with suspend/resume, agent memory, evals, and
tracing, all TypeScript-native. LangGraph ships a JS port too, but
the center of gravity of these two is the web stack itself.
Where it leaks: gravity and runtimes. The data/ML ecosystem — eval tooling, datasets, research code — still speaks Python first, so TS-first teams sometimes end up maintaining a Python sidecar anyway. And serverless-shaped runtimes, where these stacks are most at home, sit awkwardly with agent runs that want to live for minutes and survive restarts — exactly the durability problem the checkpointing lesson taught you to respect. Mastra's suspend/resume and Vercel's queue-backed patterns are answers, but they are answers to a problem the Python-server world does not have in the same form.
Check: A teammate proposes CrewAI for a payments workflow because "the crew definition is so readable a PM can audit it." Which taxonomy question should you press on first?
One row per philosophy, scored on the axes that predict your operational life. "Lock-in surface" means: how much code do you rewrite to leave?
| Framework | State model | Control flow | HITL primitives | Persistence | Lock-in surface |
|---|---|---|---|---|---|
| LangGraph | Typed graph state + reducers | Explicit graph (nodes, conditional edges) | interrupt(), resume via Command | Checkpointers (SQLite/Postgres), threads | Graph wiring + LangChain message types |
| CrewAI | Task outputs + crew memory | Process semantics + prompts; Flows for code-first | Task-level human input hooks | Flow state persistence (bolt-on) | Role/task/crew definitions, prompt templates |
| AutoGen line / MS Agent Framework | Conversation transcripts; typed workflow state in MAF | Speaker selection + termination conventions; MAF adds typed workflows | Human-proxy agent in the chat; MAF approval steps | MAF: durable workflows (Azure-backed) | Conversation patterns, Azure integration |
| smolagents | Per-step code + execution logs | Model-written code per step | Roll your own | Roll your own | Small — near-library, easy exit |
| Pydantic AI | Typed deps + validated outputs | Your Python code around typed agents | Roll your own (deferred tools help) | Roll your own; durable-exec integrations | Small-to-medium — V2 showed API drift risk |
| OpenAI Agents SDK | Sessions + run state | Handoffs between agents; guardrails | Guardrail halts; approval callbacks | Session storage, platform-side | Large — handoff/guardrail/session semantics |
| Claude Agent SDK | Harness-managed session state | Hardened loop + hooks + subagents | Permission rules, hook-based gating | Session resume, platform-side | Large — hooks/permissions/harness semantics |
| Vercel AI SDK / Mastra | UI-message state / workflow state | Loop control in TS / workflow steps | Mastra suspend-resume; tool-approval patterns | Mastra storage adapters; queue-backed runs | Medium — TS types + streaming protocol |
Read the table by column, not by row. The state-model column tells you who can resume after a crash. The HITL column tells you who treats approval as architecture versus afterthought — recall from Human-in-the-Loop Architecture why bolted-on approval gates fail. The lock-in column tells you the exit price before you pay the entry price.
Every framework in this lesson shipped a breaking change within roughly the last four quarters. AutoGen was rewritten and then merged out of standalone existence. Pydantic AI broke its API at V2. LangChain 1.0 renamed and relocated the prebuilt ReAct constructor that half the internet's tutorials referenced. OpenAI sunset the Assistants API that teams had built products on. This is not an indictment of any one project — it is the climate of a field where the underlying models change capability every six months. Budget for it: pin versions, wrap framework APIs behind your own thin interfaces, and assume any tutorial older than six months is wrong in the details.
The stable ground is the concepts. Typed state with explicit merge semantics. Checkpointing at step boundaries. Interrupts for human approval. Dynamic fan-out for parallel work. Budgets and stop conditions. You built each of these by hand in Agent Architectures; this course now shows you the same five ideas wearing four different API surfaces. Learn the mapping once and framework migrations become tedious rather than terrifying — which, in this field, is the best available deal.
What you can now do: place a framework in the taxonomy from its docs in minutes; name the bet and the leak before adopting; and read the rest of this course as a study of the concepts, with LangGraph (lessons 3-6), the vendor SDKs and CrewAI (lessons 8-11), and the ejection strategy (lessons 12-14) as the concrete terrain. Before any of that, though, the next lesson takes seriously the option every framework vendor would rather you forget: none of the above.