Frameworks: What They Abstract and What It Costs

Strip the marketing and every agent framework is a bundle of six things you would otherwise write yourself. Knowing the list lets you evaluate a framework by asking, for each item, whether its version is better than the fifty lines you would write and whether you need it at all.

Frameworks sit at three levels, and the level matters more than the brand. Low-level libraries (typed model clients, schema helpers, the Vercel AI SDK, Pydantic AI) give you primitives and leave the loop to you; you see every prompt. Mid-level graph runtimes (LangGraph, Google ADK, Microsoft Agent Framework) give you an explicit state machine with persistence; the control flow is yours, the plumbing is theirs. High-level agent frameworks (CrewAI, LangChain agents, OpenAI Agents SDK in its default mode) give you roles, tasks and an autonomous loop; you write descriptions and the framework writes the prompts.

The higher the level, the faster the demo and the harder the production incident. Each level is the right choice for some team; the failure is picking a high-level framework for a system that needs low-level control, or writing a graph runtime from scratch when one exists. The Framework Explorer at /agentic/frameworks compares the individual frameworks along these axes with code samples.

Hidden prompts. High-level frameworks inject their own system prompt text: role descriptions, formatting instructions, tool-use scaffolding. You did not write it, you cannot easily see it, and it changes between versions. When the agent misbehaves, the cause may be a sentence you have never read. When you tune your prompt, you are tuning a fraction of what the model sees.

Hard-to-debug loops. A framework’s loop has its own retry logic, its own termination condition and its own error handling. When it loops or stops early, the trace shows framework internals, and the fix may require monkey-patching. The bounded loop from Budgets, Limits and Termination is trivial to write and to reason about; a framework’s equivalent is a configuration flag whose semantics you must look up.

Version churn. The field moves fast and frameworks move with it: renamed modules, deprecated agent classes, breaking changes in minor versions. A system built on a high-level abstraction inherits an upgrade treadmill; pinning versions inherits a security and model-support freeze. Low-level libraries churn less because they wrap fewer opinions.

Lock-in of concepts, not just code. Once the team thinks in “crews” and “tasks”, redesigning as a plain workflow feels like a rewrite even when it is a simplification. Choose abstractions you could remove.

Start from the architecture, not the framework (Choosing the Right Abstraction). If the design is a single LLM call, structured output or a short tool loop, Option 0: No Framework applies and a framework adds only cost. If the design is a persistent, resumable state graph with human approval steps and parallel branches, a mid-level runtime saves real engineering. If you need a demo tomorrow and will throw it away, a high-level framework is fine, as long as everyone agrees it will be thrown away.

Whatever you pick, insist on three properties: you can print every prompt the model receives, you can set hard step and cost limits, and traces show your own tool names rather than framework internals. A framework that fails any of these will fail you in production.