AI Agent Frameworks: When to Use One and When to Skip It

An AI agent framework is a library that wraps the model loop, tool routing, state, and traces so you do not write them yourself. LangGraph, CrewAI, the OpenAI Agents SDK, the Claude Agent SDK. You do not need one to ship an agent. You need one when a run has to survive a restart, pause for a human, or fan out in parallel. Everything else you can write in an afternoon.

TL;DR

• Start without one. Anthropic's engineering guidance tells developers to use LLM APIs directly because "many patterns can be implemented in a few lines of code," and warns that frameworks "often create extra layers of abstraction that can obscure the underlying prompts and responses."
• The loop is not the hard part. Sending messages, reading tool calls, appending results, repeating: that is about forty lines. Durable state is the hard part.
• Adoption is real and quality is still the wall. LangChain's State of Agent Engineering (1,340 responses, November 18 to December 2, 2025) puts 57.3 percent of respondents with agents in production, with quality named the top blocker by about a third and latency second at 20 percent. Cost has faded as a concern.
• Observability is the layer people actually buy. In that same survey 89 percent had implemented observability and 62 percent had detailed tracing, while only 52.4 percent ran offline evals on test sets.
• Lock-in shrank. MCP moved to the Linux Foundation's Agentic AI Foundation on December 9, 2025, with AWS, Google, Microsoft and OpenAI as platinum members. Tool access is a protocol now, not a framework feature.

What a framework is actually selling you

Strip the marketing off any agent framework and you find five layers stacked on top of the model API. They are not equally valuable, and the top two are the ones people think they are buying.

The loop is a while statement. Tool plumbing used to be a genuine chore and is now a protocol: you write an MCP server once and every client that speaks MCP can call it. What remains is state, concurrency, and traces, which are ordinary distributed systems problems that ordinary distributed systems people have spent decades getting wrong.

That is the honest pitch for a framework. It is a workflow engine with a model-shaped API on the front.

Write the two hundred line version first

Before you evaluate anything, build the smallest agent that does one real job in your product. No framework. Five files.

1. The loop. Send the message list, read the tool calls off the response, execute them, append the results, repeat until the model returns a final answer or you hit a step cap. Set the cap at something low, like 12, and log every time you hit it.
2. The tools. Three to five of them, each with a description written for a model that has never seen your codebase. Return errors as text the model can act on, not exceptions that kill the run.
3. The prompt file. One file, version controlled, with the rules and the examples. Not a string buried in a class.
4. The state row. One database row per run: input, the message list so far, status, step count, last error. This single row is what a framework's checkpointer gives you, and writing it yourself teaches you exactly what your resume semantics need to be.
5. The eval set. Twenty cases with known good outputs. Run them on every prompt change.

That build takes a day or two and it settles arguments no comparison article can. You find out whether your agent is really a fixed pipeline with one model call in the middle, which most of them are. I wrote up the general shape of that in WRITE LOOPS NOT PROMPTS, which is the same pattern applied to any repeated agent job.

The reason to write it yourself is not purity. It is that you cannot evaluate an abstraction until you know what it is abstracting.

The four questions that justify a dependency

Once the raw version runs, score it against four questions. Each one is a real engineering problem with real edge cases, and each one costs you weeks to build properly.

Does the run have to survive a process restart? A support agent that answers in eight seconds does not. A research agent that runs for nine minutes across forty tool calls does, because your deploy will land in the middle of it. Checkpointing means every step boundary writes recoverable state, and getting resume semantics right for partially executed tool calls is genuinely fiddly.

Does it pause for a human and resume later? Approval gates are the single most common reason teams outgrow their own loop. The pause can last hours. The state has to be serialized, the run has to be addressable by an ID a UI can post back to, and the resumed run has to pick up in the right place with the human's decision injected. Frameworks that do this well are worth real money.

Does it fan out in parallel? Three sub-tasks in flight, joined at the end, with cancellation when one fails and a token budget across all of them. You can write this. You will write it badly the first time.

Do you need to replay a past run? Not a log. A replay: the exact messages, tool inputs and outputs, and timings for run a4f9, from Tuesday, so you can find where it went wrong. That LangChain survey found 89 percent with observability in place, and it is the layer teams reach for first because agent bugs are unreproducible without it.

Score zero or one and you should stay on the raw SDK. Score two or more and a framework will save you more than it costs.

The three families, and what each is for

Comparison posts rank these against each other as if they were competing for the same job. They are not.

Graph and state machine frameworks. You define nodes, edges, and a typed state object, and the runtime handles checkpointing, interruption, and resume. LangGraph is the reference example. This shape fits when your agent is a process with named steps and approval gates, and it is deliberately more verbose than the alternatives because the explicitness is the product. Pick it when you need to point at a diagram and say what happens after step four fails.

Role and crew frameworks. You describe agents by role and give them tasks, and the library handles delegation and handoff. CrewAI is the reference example. It reads well, it gets a multi-agent demo running in an afternoon, and it hides more of the control flow. Pick it when the mental model of your problem genuinely is a team of specialists, and be honest that most problems described that way are actually a pipeline with three prompts. I wrote about when the multi-agent shape is real in How to Build a Multi-Agent System.

Vendor SDKs. The OpenAI Agents SDK and the Claude Agent SDK are thin loops with handoffs, tool wiring, and tracing attached, maintained by the people who ship the model. They move fastest on new model features and they are the least abstraction between you and the API. Pick one when you have already committed to a provider and you want the loop and traces without a third-party dependency in the middle.

None of these makes a bad agent good. Quality problems are prompt, tool, and eval problems, which is why quality is still the number one production blocker in a year when every one of these libraries is mature.

Keep the exit cheap

Whatever you adopt, you will want out of it eventually. Five rules make that a week of work instead of a rewrite.

• Own your prompts. Plain files in your repo, loaded at runtime. Never inside a framework class or a hosted prompt registry you cannot diff.
• Own your tools. Write them as MCP servers or plain functions with your own schema, then adapt them at the framework boundary. Post donation, MCP is the closest thing to a neutral standard for tool access, which is exactly what you want from the layer you least want to rewrite. The three worth wiring first are in THE MCP BIG THREE.
• Own your state schema. Your run table, your columns, your migrations. Let the framework checkpoint into it if it can. Do not let its internal representation become your source of truth.
• Own your evals. The eval harness should call your agent through one function signature that has nothing framework-specific in it. Then a framework swap is a change behind that function, and your twenty test cases tell you immediately whether it worked.
• Keep it at the edges. The framework orchestrates. It should not be imported by your business logic, your database layer, or your API handlers.

Teams that skip these rules end up unable to answer a simple question during an incident: what did the model actually get sent. That is the abstraction cost Anthropic's guidance warns about, and it shows up at exactly the wrong moment.

The bottom line

AI agent frameworks solve workflow problems, not intelligence problems. Write the two hundred line version first, because it takes a day and it tells you which of the four hard questions you actually face. If you score zero or one, keep your loop and spend the time on tools and evals instead, which is where quality lives. If you score two or more, pick the family that matches the shape of your problem, keep your prompts, tools, state, and evals outside the framework, and treat it as orchestration at the edge of your system rather than the center of it.

If you want the next one of these when it lands, get it in the newsletter.