What Are Agent Frameworks and Do You Need One?

An agent framework is a library that handles the repetitive parts of building an LLM agent: running the tool-calling loop, tracking conversation state, validating tool arguments, streaming output and tracing what happened. You do not need one to build an agent, because an agent is just a loop around a model API. You need one when that loop starts to grow features you would rather not maintain yourself.

What a framework actually gives you

Every agent, however fancy, does the same basic thing. It sends messages and tool definitions to a model, reads the reply, runs any tools the model asked for, appends the results and calls the model again. It stops when the model replies without a tool call. If you want to see that loop written by hand, the Tool Use & Agent Loops topic covers it. Frameworks wrap this loop and add surrounding features.

The common features are:

• A tool abstraction. You write a normal function, and the framework builds the JSON schema from its signature and docstring.
• A run loop. One call such as Runner.run_sync() or agent.invoke() drives the model and tools until a final answer exists.
• State and memory. Message history, checkpoints and sessions so that a conversation can continue later.
• Structured output. The final answer is parsed into a typed object instead of free text.
• Streaming and tracing. Token streams, event streams and spans that show each model call and tool call.
• Orchestration. Handoffs between agents, graphs with branches, human approval steps and retries.

What it costs you

Frameworks are not free. Each one brings its own vocabulary, its own abstractions and its own release cadence. Agent libraries change quickly, and code written against one version can need edits after an upgrade. A framework also sits between you and the model API, so when something goes wrong you debug two layers instead of one. Some frameworks make it hard to see the exact prompt that reached the model, which makes prompt problems slower to fix.

There is also the learning cost. A beginner who needs one tool and one model call can be served by twenty lines of plain SDK code. Adding a framework in that case means learning concepts that the project does not need.

A concrete comparison

Here is a tiny agent written with the Pydantic AI framework. It defines one tool and lets the framework run the loop.

from pydantic_ai import Agent

agent = Agent(
    'anthropic:claude-sonnet-5-5',
    instructions='You are a helpful assistant. Use tools when needed.',
)

@agent.tool_plain
def word_count(text: str) -> int:
    """Count the words in a piece of text."""
    return len(text.split())

result = agent.run_sync('How many words are in "the quick brown fox"?')
print(result.output)

Run this with ANTHROPIC_API_KEY set and it prints a sentence saying the text has four words. The tool schema, the loop and the message handling are all done for you. With a plain SDK you would write roughly thirty lines to get the same result: a schema dictionary, a while loop, a check for tool-use blocks and a dispatch table.

How to decide

Use this short list as a first pass.

• One model call, no tools: use the provider SDK directly.
• A few tools and a simple loop: a plain SDK or a light framework such as the OpenAI Agents SDK or Pydantic AI works well.
• Branching, retries, pauses for human approval, long-running state: a graph or workflow framework such as LangGraph earns its weight.
• Several role-based agents collaborating: CrewAI, AutoGen or the handoff features of the OpenAI Agents SDK fit.
• A coding or file-based agent that edits files and runs commands: the Claude Agent SDK gives you the tools and loop used by Claude Code.
• A TypeScript web app: the Vercel AI SDK or Mastra fit naturally.

Common mistakes

• Picking a framework because it is popular, before you know what your agent must do.
• Using a multi-agent framework for a task one agent with three tools could handle.
• Hiding every prompt behind framework defaults, then being unable to explain a bad answer.
• Not pinning versions, so an upgrade silently changes behavior.

The rest of this course walks through the real frameworks one at a time, then compares them side by side so the choice becomes easy. Start with the map of the landscape in the next post.