Agent framework or hand-rolled loop: what each buys you, and what changes your mind

01The loop is not the hard part

Call the model with the tools, execute any calls, append the results, repeat until it stops. With a step cap, error handling and a deduplication check, that is still under a hundred lines in any language, and it has no dependencies beyond the provider's SDK. Nobody adopts a framework to avoid writing it.

What is hard is the rest: keeping state across a process restart, pausing for a human and resuming a day later, running six workers in parallel and joining their results, handing a conversation from one specialised agent to another, tracing why a run cost what it cost. Those are infrastructure problems, and they are what a framework is selling. So the decision is not "write the loop or import it"; it is "which of these infrastructure problems do I have, and do I want to own the solution".

02What a framework actually provides

Being specific about this makes the decision concrete. A mature agent framework typically gives you:

• A graph or state-machine model for control flow: nodes, edges, conditional branches, parallel fan-out and join, instead of nested conditionals.
• Durable execution: checkpointing the state after each node, so a run survives a crash and can be resumed, replayed or inspected.
• Human-in-the-loop primitives: pause a run at a node, wait for approval or input, continue, with the state persisted while waiting.
• Multi-agent patterns: supervisors, handoffs, shared state between agents, worker pools.
• Integrations: adapters for tool protocols, vector stores, memory backends, and the model providers themselves.
• Observability hooks: a trace of nodes, calls and tokens, usually tied to the vendor's tracing product.
• Streaming and sessions wired through all of the above.

If you read that list and need two or fewer of the items, you probably do not need the framework. If you need four or more and would otherwise be building them, you probably do.

03When to hand-roll

• One agent, a few tools, a clear loop. Three to eight tools, reason-act-observe until done. This is most agent products, and a framework adds abstraction to something that did not need any.
• You need to see the context. Latency, cost and quality all come down to what is in the messages sent to the model. With your own loop, you assemble them and nothing is appended that you did not put there. That matters for prompt caching, which needs a stable prefix, and for debugging, where the first question is always "what did the model actually see".
• Every call must pass custom checks. Regulated domains, finance, health, anything with an audit requirement: each tool call, retry and state transition has to go through your validation and your logging, in your format. Threading that through a framework's execution path is harder than writing the path.
• You want to understand the system. A team that writes its own loop knows exactly what the agent does. A team that configures a framework knows what it asked for.

04When to use a framework

• Durable, long-running work. Runs that take hours, must survive restarts, and must be resumable from where they stopped. Checkpointing done properly is real work, and a framework has done it.
• Pause for a person, resume later. Approval gates where the state waits in storage for a human who may answer tomorrow. Building this well is a workflow engine, and that is what the durable-execution frameworks are.
• Graph-shaped control flow. Branches, loops within loops, parallel workers with a join, retries scoped to a sub-graph. Once the flow is a graph, a graph library is the right tool, the same way you would not hand-write a parser for a grammar of any size.
• Several agents with handoffs and shared state. A supervisor dispatching to specialists, each with its own tools and context, passing work between them. The coordination logic is where a framework earns its keep.
• A prototype by Friday. Integrations out of the box let you prove the idea before deciding what to own. The risk is forgetting to decide later.

05The middle option

The usual comparison presents two choices. There is a third, and it covers a lot of ground.

• Thin loop helpers in the provider's SDK. Most providers now ship a tool-runner: you define the tools, it runs the call-execute-append loop, and it exposes hooks per turn for approval, logging and result modification. You get the loop without writing it and without any abstraction over the messages, which stay the provider's own types. This is the right default for a single-agent product that does not need durable execution.
• Managed agent runtimes. The provider hosts the loop, the state and often a sandbox for tool execution; you supply configuration and your own tools and receive events. This is the choice when you want durability and sessions without running the infrastructure, at the cost of running inside the provider's model of an agent.

Neither is a framework in the sense of the question, and neither is hand-rolled. They exist because the common case, one agent with tools, turned out not to need a graph library, and because the hard case, durability, turned out to be better hosted than imported.

06Side by side

The "zero dependencies" claim sometimes made for hand-rolled loops is not quite true; you depend on the provider's SDK and API, which also change. The difference is one dependency with a stable contract versus a framework plus everything it wraps.

07What pushes a team from a framework to a loop

• Not being able to answer "why did it do that". An agent loops, or passes a corrupted state, or ignores a tool, and the cause is three abstraction layers down. Every debugging session starts by reconstructing what the framework sent to the model. At some point the team writes a direct loop just to see, and then keeps it.
• Context you did not put there. Frameworks append wrappers, state summaries and verbose schema renderings. The token bill is higher than the messages justify, the cache misses because the prefix shifts, and the fix means fighting the framework's assembly logic.
• Upstream churn. Agent libraries move fast. A minor version renames an abstraction, an integration breaks, and a week goes to migration rather than product. Pinning versions delays the cost without removing it.
• The graph turned out to be a line. The multi-agent architecture the prototype planned for never materialised, and the production system is one agent with six tools, carrying the machinery for twelve.

08What pushes a team from a loop to a framework

• Persistence became a project. The loop needed to survive restarts, then to pause for approval, then to resume sessions days later. Each was a small change until together they were a workflow engine, written by people whose job was the product.
• Orchestration spaghetti. The loop grew branches, then sub-loops, then parallel workers with a join, then delegation to specialised agents. The control logic is now a hand-written state machine with no diagram, and every change breaks a path nobody remembered.
• Observability had to be built twice. Tracing, cost attribution and replay were added ad hoc and then needed to be rebuilt properly, and a framework's tracing already does what the rebuild was going to.

09A way to decide

one agent, a handful of tools, no need to survive restarts
   → provider loop helper, or a hand-rolled loop if you need every message under your control

one agent, must survive restarts, pause for people, keep sessions
   → managed runtime if you can run inside the provider's model
   → durable-execution framework if you must own the infrastructure

branching graph, parallel workers, several agents handing off
   → graph framework, and keep each agent's inner loop simple

regulated, every call audited in your format
   → hand-rolled, whatever the shape; wrap a framework only if it lets your checks sit on the execution path

Two honest observations to go with the chart. The often-quoted path, prototype on a framework and rewrite the hot paths by hand, is real, but so is the reverse, and in practice the move from framework to loop has been the more common one, because single-agent systems are the more common system. And whichever you choose, keep the agent's inner loop small and visible: the fifty lines are the part you will need to read when something goes wrong, and no framework should be allowed to hide them.

10Takeaways

1. The loop is fifty lines. A framework sells the infrastructure around it, not the loop.
2. List what a framework provides and count what you need. Two or fewer, hand-roll; four or more, consider it.
3. Hand-roll for one agent, visible context, and custom checks on every call.
4. Use a framework for durability, pause-and-resume, graphs and multi-agent handoffs.
5. Do not forget the middle: provider loop helpers for the common case, managed runtimes for durability without infrastructure.
6. Frameworks lose teams over visibility, context and churn; loops lose teams over persistence and spaghetti. Watch for both.
7. Whatever you pick, keep the inner loop readable. It is what you will read when it breaks.