Agent Frameworks Compared

No framework wins every time. A heavy framework on a one-tool job is just extra work. A very light one on a system that needs approval steps and clear error routes means you rebuild those features by hand, and badly. This lesson is a way to decide, not a ranking.

LangGraph: clear control over complex flow

LangGraph treats an agent as boxes joined by arrows. You decide exactly how control moves between steps, where errors go and when a person must approve before it continues. That clarity is the point. For flows with loops, parallel branches and approval steps, it gives you a place in code for each decision, instead of hoping the model does the right thing.

const graph = new StateGraph(AgentState)
  .addNode("plan", planStep)
  .addNode("execute", executeStep)
  .addNode("humanApproval", waitForApproval)
  .addConditionalEdges("execute", (state) =>
    state.needsApproval ? "humanApproval" : "plan"
  )
  .addEdge("plan", "execute")
  .setEntryPoint("plan");

CrewAI: least setup for teams of roles

CrewAI works with a crew of agents that each have a role, such as researcher, writer and reviewer. Each has its own goal and tools. The framework coordinates them, so you do not draw the arrows yourself. It is the fastest way to a working team of agents when your problem already splits into clear roles.

const researcher = new Agent({ role: "Researcher", goal: "Find accurate sources", tools: [webSearch] });
const writer      = new Agent({ role: "Writer", goal: "Draft from research", tools: [] });
const crew = new Crew({ agents: [researcher, writer], tasks: [researchTask, writeTask] });
await crew.kickoff();

Smolagents and the Claude Agent SDK: small by design

Smolagents is a quick way to a working single-agent loop when you do not need heavy orchestration. It is close to the hand-built loop from the tool-calling lesson, with the repeated parts done for you. The Claude Agent SDK is built for coding agents. It comes with the kind of built-in tools Claude Code uses, such as reading and writing files, running commands and searching. So you do not have to build a file and shell layer yourself.

A way to decide

• One agent, simple tools, no approval steps: Smolagents, or the plain loop from the tool-calling lesson.
• A coding agent: the Claude Agent SDK, for its built-in tools alone.
• Several agents with clearly different roles: CrewAI.
• Complex control flow with loops, branches and approval steps: LangGraph.
• Deep use of one provider's hosted tools, and you accept the lock-in: that provider's own SDK.

Going deeper: keep your core free of any framework

Frameworks change faster than your business logic. The most robust teams keep the valuable parts in plain code: prompts, tool functions, schemas and tests. They treat the framework as a thin layer around them. Then swapping or upgrading a framework is a small job and not a rewrite.

# core/ (no framework imports)
class Tool(Protocol):
    name: str
    schema: dict
    def __call__(self, **kwargs) -> dict: ...

def refund_tool() -> Tool: ...       # plain functions with typed inputs/outputs
SYSTEM_PROMPT = load("prompts/support_system.v14.md")
EVALS = load_cases("evals/support.jsonl")

# adapters/langgraph_adapter.py   -> wraps core tools as graph nodes
# adapters/claude_sdk_adapter.py  -> wraps core tools for that SDK
# adapters/plain_loop.py          -> the 40-line loop from the tool-calling module

# Same tools, prompts and evals run under any adapter. Compare frameworks by running
# YOUR eval set through each adapter, not by reading feature tables.

A checklist for judging any framework

• State: how is a run saved, checkpointed and resumed? Can you inspect it and rewind it?
• Control flow: can you build loops, branches, parallel steps and human approval without fighting the framework?
• Visibility: does it record a trace of every model and tool call, with prompt and version details?
• Testing: can you run an agent in tests with fake models and fake tools?
• Streaming, retries, timeouts and cancelling: are they built in, or yours to write?
• Escape hatches: can you drop down to plain API calls when the framework gets in the way?
• Deployment: how does it run as a service, in a queue worker or serverless?
• Project health: how often it releases, how often it breaks things, who maintains it, its licence, and how much of it you would really use.
• Lock-in: how many lines would a move touch? Keep that number small.