How to choose an AI agent framework: archetypes, not leaderboards

The core decision: do you need a framework at all?

Start with the question the framework landscape would rather you skip. An agent, mechanically, is a loop: call the model, execute the tool it picked, append the result, repeat until done. Modern model APIs handle tool calling natively, and the provider SDKs — the OpenAI Agents SDK, Anthropic’s SDKs (not in our index; they’re the standard external options) — make that loop maybe a hundred lines of code you fully understand. For a single agent with a handful of tools, that is a legitimate, often superior, answer: no dependency churn, no abstraction between you and the prompt, nothing to fight when behavior gets weird.

A framework earns its keep when the loop stops being the hard part. Multi-agent coordination, durable state that survives restarts, streaming through several layers, retries and human-in-the-loop checkpoints, a team that needs shared conventions instead of five bespoke loops — that’s the workload frameworks exist for. The honest test: write the plain loop first, even as a throwaway. If it’s straining, you’ll know exactly which missing piece you’re shopping for, and you’ll evaluate frameworks on that piece instead of on their quickstarts.

If you do need one, the market sorts into five archetypes. Identify yours first; only then compare names within it — cross-archetype comparisons are how teams end up benchmarking a visual canvas against a typed library and learning nothing.

The five archetypes

For each: what it optimizes for, the in-index options, and the one thing that quietly costs you.

The criteria that actually separate them

Within an archetype, the candidates’ feature lists converge fast. These five criteria are what still differ — and they’re roughly in order of how much pain they cause when you get them wrong.

• Abstraction cost. Every abstraction that saves boilerplate in week one charges interest in month three, when you need to know exactly what was sent to the model and the framework is between you and the answer. The test is simple: open the source of the core agent loop and see whether you can follow it. If you can’t, you’re not adopting a tool, you’re adopting a belief system.
• Debuggability. Agents fail probabilistically, so your real interface with a framework is its failure view: can you see the exact prompts, tool calls, and intermediate state of a bad run, and replay it? A framework with first-class tracing beats a “more powerful” one without it, because you’ll spend far more hours diagnosing runs than writing them.
• Ecosystem and momentum. In a field moving this fast, maintainer activity and release cadence matter more than the current feature list — a stalled framework is a liability regardless of stars. But weigh the part of the ecosystem you’ll use: a thousand integrations you don’t need are marketing, and the three you do need are the requirement.
• Migration path. Ask what leaves with you before you commit. Prompts and typed tool definitions port to any framework; orchestration graphs, crew configs, and framework-specific state do not. The frameworks that let your business logic live in plain functions are quietly the safest bet, whatever else differs.
• Language. Framework choice is downstream of language choice, and language choice belongs to your team, not to the agent ecosystem. The debugging-and-iteration loop is where agent projects live or die, and it runs fastest in the language your team ships every day.

The mistakes that sink framework choices

• Choosing by GitHub stars. Stars measure age and marketing reach, not fit. The most-starred framework was optimized for a different builder with a different problem — and the count tells you nothing about what it’s like to debug at 2 a.m.
• Starting with multi-agent. Most jobs are one agent with good tools. Roles, crews, and handoffs multiply failure modes and token spend before they add capability — earn your way to a second agent by proving one agent can’t do it.
• Skipping the no-framework baseline. If you’ve never written the hundred-line loop yourself, you can’t tell which of a framework’s abstractions pay rent and which just add distance between you and the model.
• Ignoring the debugging story. Decide how you’ll inspect a failed run — traces, replays, the exact prompt that was sent — before you commit. A framework without a real observability story turns every production bug into archaeology.
• Confusing frameworks with platforms. A code library and a hosted visual canvas are different commitments with different exits. Comparing Dify to Pydantic AI is comparing a product decision to an architecture decision — settle which one you’re making first.
• Bending your architecture to the framework. The moment you restructure your domain logic to satisfy a framework’s worldview, the dependency has inverted. Keep tools and business logic in plain functions the framework calls — not the other way around.

Which should you pick?

• Single agent, a few tools, engineers on the code → no framework, or Pydantic AI for typed structure without the weight.
• Sprawling app, many integrations → LangChain — its ecosystem is the moat — with Agno as the performance-minded alternative.
• Work that decomposes into roles (research → draft → review) → CrewAI first for approachability; hive if production multi-agent operation is the emphasis.
• Microsoft / .NET / Azure shop → Agent Framework for new builds; keep an existing AutoGen system where it is.
• TypeScript product and team → eliza for persona-driven, long-running agents, or ruflo for orchestration.
• Non-engineers must own the flows → Dify or n8n — and treat it as the platform decision it is, not a framework pick.

Frequently asked

Do I need an agent framework at all?

For a single agent with a handful of tools: honestly, no. Modern model APIs do tool calling natively, and the core loop — call the model, execute the tool it picked, append the result, repeat — is on the order of a hundred lines. Provider SDKs like the OpenAI Agents SDK and Anthropic’s SDKs (not in our index; they’re the standard external options) cover this well. Frameworks earn their keep when you hit multi-agent coordination, durable state across sessions, human-in-the-loop checkpoints, or a team that needs shared conventions. Write the plain loop once even if you then adopt a framework — it’s the baseline that tells you what you’re paying for.

LangChain vs CrewAI — which should I use?

They answer different questions. LangChain is general-purpose orchestration with the largest ecosystem of integrations — the safe pick when your app touches many providers, retrievers, and services, at the cost of heavier abstraction. CrewAI is an opinionated multi-agent framework: you define agents with roles, goals, and tasks, and it runs the collaboration. If your mental model of the problem is “a team with roles,” CrewAI gets you there faster; if it’s “a pipeline or graph of steps,” LangChain’s way of thinking fits better. Prototype your hardest flow in both — the one that fights you less is your answer, and no comparison table can make that call for you.

Python or TypeScript for AI agents?

Python still has the deeper agent ecosystem — more frameworks, more eval and retrieval tooling, and most reference implementations land there first. But TypeScript is where product and web teams live, it now has credible native frameworks (eliza, ruflo), and the major provider SDKs ship first-class TypeScript. The honest tiebreaker: choose the language your team ships every day. A familiar language with a decent framework beats an unfamiliar language with the “best” one, because the hard part of agents is debugging and iteration speed, not library features.

Will my framework choice lock me in?

Less than you fear at the model layer, more than you’d like at the orchestration layer. Nearly every serious framework is model-agnostic, so swapping providers is cheap. What doesn’t port is the orchestration itself: graph definitions, crew configurations, state management, and framework-specific callbacks are rewrites. The insurance is architectural — keep prompts as data, tools as plain functions with typed signatures, and business logic outside the framework’s classes. Do that and a migration is weeks of mechanical work instead of a quarter of untangling.

What about Microsoft AutoGen and Agent Framework?

AutoGen is Microsoft’s research-born multi-agent framework and popularized conversation-driven agent collaboration. In late 2025 Microsoft folded AutoGen and Semantic Kernel (not separately in our index) into a production successor, Agent Framework, with first-class Python and .NET support. The practical read: an existing AutoGen system keeps working and doesn’t need a panic migration, but new builds on the Microsoft stack should start on Agent Framework — that’s where the engineering gravity is going. Outside the Microsoft ecosystem, neither is an obvious default over the alternatives.

Primary sources

The official documentation for the frameworks this guide discusses most:

• LangChain — official Python documentation.
• CrewAI — official docs for the role-based-crews framework.
• AutoGen — official docs for Microsoft’s multi-agent framework.
• Pydantic AI — official docs for the type-safe framework.

More stack guides