Frameworks landscape

LangGraph, CrewAI, AutoGen, the OpenAI and Claude Agent SDKs, LlamaIndex, Pydantic AI, smolagents, Google ADK - a dozen frameworks that look wildly different. They are not. Strip each one down and you find the same loop underneath. What differs is which abstraction each makes first-class on top of it - and once you can name that, choosing (or skipping) a framework becomes a five-minute decision.

One loop lives under all of them

Simon Willison's now-canonical definition: "An LLM agent runs tools in a loop to achieve a goal," and "the skill is in the design of both the tools and the loop."^[1] That loop is the entire substrate. Every framework in this lesson is a lens on it.

Before you compare frameworks, absorb the distinction every one of them is built to serve. Anthropic's Building Effective Agents splits agentic systems into two kinds.^[2]

The single most useful teaching point in the whole module: most production "AI systems" should be workflows, not agents. Add agency only when the flexibility is worth the tradeoff. Both are built from one primitive - the augmented LLM.^[2]

The "no framework" option, often the right default

Because the loop is the substrate, the loop is also about twenty lines of Python. You do not need permission from a framework to write it.

# The whole thing. No dependencies beyond the provider SDK.
messages = [system_prompt, user_question]
while True:
    resp = client.messages.create(model=..., tools=TOOLS, messages=messages)
    if resp.stop_reason != "tool_use":
        break                      # model emitted a final answer -> done
    for call in tool_calls(resp):
        messages.append(run_tool(call))  # ground truth from the environment
# You own routing, retries, guardrails, logging - and you can see every prompt.

This is a legitimate, sometimes-recommended baseline, and the labs endorse it. Anthropic reports the most successful implementations they saw used "simple, composable patterns," not frameworks, and warns that frameworks "create extra layers of abstraction that can obscure the underlying prompts and responses, making them harder to debug."^[2] Willison argues cross-model differences (cache control, tool-prompt format, provider-side tools) are large enough that many teams end up building their own thin abstraction anyway.^[1] And Hamel Husain's evals-first stance: "great products are mostly harness plus product plus evals, not the model."^[17]

Four shapes: the positioning map

Sort the field by which abstraction each framework makes first-class. Four dominant shapes emerge - graph/state, role/crew, conversation, and code-as-action - plus cross-cutting styles: handoffs (model-decided delegation within one run), typed/DI (validated structured I/O with dependencies injected), and the programmable harness (the production loop plus built-in tools, packaged for reuse).^[18] The horizontal axis is how much the framework decides for you: left is raw loop and low abstraction (a hand-rolled loop, OpenAI's few primitives, smolagents' hackable core); right is opinionated and high abstraction (LangChain's prebuilt agent, CrewAI's org-chart).

What each framework makes first-class

Learn the primitives once - they are convergent - and the API surface is the only variable. The distinctive mechanic of each:

Graph, state, and data

LangGraph - graph / state. Model the agent as a StateGraph: nodes are functions that read and write a shared State; edges (including conditional ones) route control and can cycle back, which is what lets retries and iterative reasoning exist. Checkpointers persist state after every step, giving durable execution, human-in-the-loop via interrupt, and time-travel. As of v1.0, LangChain agents run on LangGraph - one runtime, two layers.^[6]

LlamaIndex - data / RAG-centric. The go-to for retrieval-heavy agents: indexes, retrievers, and query engines, orchestrated by event-driven Workflows where @steps consume and emit Events, so loops, branches, and parallelism fall out. AgentWorkflow handles multi-agent handoff systems.^[15]

Google ADK - agent tree. Code-first and model-agnostic. Compose LlmAgents with deterministic workflow agents (Sequential/Parallel/LoopAgent) into a tree via sub_agents. First-class A2A and Vertex AI deployment; spans Python and Java.^[11]

Roles and conversation

CrewAI - roles / crew. Each Agent carries a role, goal, and backstory; Tasks bind work to agents; a Crew runs them under a Process - sequential or hierarchical (a manager delegates). You reason about it like an org chart. Correction for students: CrewAI is rebuilt from scratch, with no LangChain dependency (it can use LangChain tools, but is not a wrapper).^[7]

AutoGen to MS Agent Framework - conversation. AutoGen modeled multi-agent systems as a dialogue between agents and humans (assistant and user-proxy, group chats). That lineage now lives in the Microsoft Agent Framework, which merges AutoGen's simple agents with Semantic Kernel's enterprise plumbing and adds typed graph workflows. Runs on .NET and Python; AutoGen and SK are now maintenance-mode.^[8]

Minimal, typed, harness, and code-as-action

OpenAI Agents SDK - handoffs plus guardrails. Few primitives, Python-first. A handoff lets one agent delegate to another within one run, implemented as exposing the target agent as a tool, so routing is model-decided.^[4] Guardrails run in parallel and trip a "tripwire" to halt; input guardrails cover only the first agent, output only the final one.^[5] The Runner owns the loop.^[3]

Claude Agent SDK - the harness. Not a new abstraction - it hands you the same production harness that runs Claude Code: a tuned loop, built-in tools (file/bash/code/web), subagents (parallel work in isolated context), hooks, the Skills system, MCP, and automatic context compaction. Verification is first-class - the SDK names the loop gather context, take action, verify work, repeat.^[9] "Give the model a computer." Contrast the raw Messages API, where you write the loop yourself.^[10]

Pydantic AI - typed plus DI. The Agent[DepsType, OutputType] is generic, so your type-checker verifies dependencies and outputs. output_type=SomeModel forces a validated object (parse failures become retryable errors, not silent string bugs); deps_type injects DB/API clients into tools. Goal: "bring the FastAPI developer experience to GenAI."^[12]

smolagents - code as action. Instead of a JSON tool call, the model writes a Python snippet that calls tools (as functions) and is executed each step. CodeAgent gets loops, conditionals, and intermediate-object handling for free - the CodeAct paper measured up to about 20% higher success across 17 LLMs versus JSON tool-calling.^[14] The catch: model-written code must run in a sandbox (E2B/Docker/Modal).^[13]

No framework - raw loop. The provider SDK plus your own while loop (above). Maximum control, minimal deps, every prompt visible. The right call for a single autonomous agent until you need durability, HITL, or checkpointing, then graduate to a shape that gives those for free.^[2]

The comparison table

The same field, one row per option. The last column is the decision heuristic in miniature.

How to choose

Do not start from the framework. Start from the task and climb only as high as it forces you - every rung adds latency, cost, and failure surface.^[2]

1. Can a plain function / SQL query / regex do it? Do that. Microsoft's blunt heuristic: "If you can write a function to handle the task, do that instead of using an AI agent."^[8]
2. Is one LLM call (maybe with tools) enough? A single augmented LLM. No framework needed.
3. Predictable multi-step? Build a workflow (prompt chaining / routing / parallelization). Reach for LangGraph, ADK, or LlamaIndex Workflows only if you want durability, HITL, or tracing for free.
4. Open-ended, unpredictable steps? Now it is an agent. Pick by shape from the table: graph plus durability, LangGraph; typed service, Pydantic AI; RAG, LlamaIndex; code-as-action, smolagents; harness, Claude Agent SDK.
5. Multiple specialists must coordinate? Multi-agent - handoffs (OpenAI), crews (CrewAI), sub-agents (ADK), or graph edges (LangGraph).

Traps to sidestep

Check yourself