Agent frameworks are having a moment, and most of the noise is selling you something you do not need. So before comparing any of them, the more useful question is the one the category avoids: do you need an agent framework at all? Most of the time, the honest answer is no. For a business thinking about an agent for routine paperwork, such as pulling fields out of supplier invoices, that answer decides how much code someone has to maintain.
This piece is about when that answer flips to yes, and about the one framework we actually reach for when it does: smolagents. We keep an eye on alternatives like OpenJarvis, but we will not stack a tool we have not run in real work against one we have. One solid side beats two shaky ones.
What is an agent framework, and do you need one?
Agent frameworks are not end-user products. They are libraries you use to build your own agents, which is the line that separates them from coding agents like Aider or Cline that you simply use. A framework is for when you are constructing a multi-step workflow of your own: research a topic, weigh options, take an action, report back.
If what you want is a coding agent to use rather than build, the choice is between tools, and our OpenCode vs Pi vs Cursor comparison rests on one question: whether your code leaves your machine.
Most of the time, you do not need a framework. A well-prompted model in a loop with a couple of function tools beats a framework-based solution for typical work. The honest take is that this category is hype-heavy and substance-light for most of our use. Reach for a framework only when a plain loop genuinely breaks down: many tools, branching logic, code-execution-driven steps.
What makes an AI agentic?
“Agentic” is one of those words that gets stretched until it stops meaning anything, so it helps to pin it to one plain distinction. A model that answers takes your text and gives you text back. You ask, it responds, the exchange ends. An agent works in a loop. It reads files, edits them, runs commands, looks at the result, and decides what to do next, repeating until the goal is met or it gets stuck. The model is no longer the whole product. It is the decision-maker inside a loop that can touch the real world.
It is easier to see in a real tool. OpenCode ships as a native desktop app: you point it at a folder and type a prompt, and it reads files, proposes edits, runs commands and shows you the work. Ask it to “add a function to utils.py that takes a list and returns the sum, add a test for it,” and the agent reads the relevant files, proposes the edit, asks permission, and applies it. That is the loop: read, decide, act, check, repeat. smolagents, below, has the same engine with a different shape.
For local AI that shift changed what the category is for. Before agents, a local model was a chat partner. It could draft and summarise and answer, but opening the file, making the edit and running the test still landed on you. Wire OpenCode to a local Ollama model and a capable open model, and the agent reads your files, edits your code and runs your commands with none of it leaving the laptop. The privacy story used to come with a tax, which was that you did everything by hand. Now the loop runs locally too. The category went from “private chat” to “private worker.”
A research agent is that loop at its most useful. Our fully private local deep research engine wires Local Deep Research to Ollama and a self-hosted SearXNG, so the question never reaches a third party and no report costs an API fee.
What is smolagents?
smolagents is HuggingFace’s minimalist, code-execution-based framework: you define a function, mark it as a tool, give the agent a goal, and watch it write Python to call your tools. It is the framework you reach for when you want an agent without a framework headache.
It is small on purpose. The framework is roughly a thousand lines of Python, which means you can read the source rather than trust a black box. Its defining choice is the execution model: instead of picking from a menu of rigid tool-call schemas, the agent writes actual Python code to call your tools. You define a tool as a plain function with a docstring, the agent reads that docstring to understand it, and it composes code to get the job done. The agent writes code, executes it, sees the result as a variable it can use, and decides the next step.
That code-first approach is more flexible than menu-style tool calling, and it is the reason smolagents feels less like a framework and more like a thin, honest layer over the model. It runs against local models through the LiteLLM integration, so you can point it at Ollama and keep everything on your machine. That makes it possible to stand up a custom agent, such as a research helper or a workflow runner, that takes real actions on your machine with nothing going to a third party.
A concrete example makes it click. Say you want an agent that takes a topic, searches a few sources, and writes a short brief. You write three small Python functions, search, fetch, and summarize, each with a clear docstring, hand the agent the goal, and it writes the glue code that calls them in order, inspects the results, and decides whether it needs to search again. You did not configure a graph or learn a domain-specific language. You wrote functions and described the job.
What are the risks of a code-writing agent?
The trade-offs are real. Code execution is powerful and dangerous in equal measure: the agent writes Python that runs on your machine, so sandboxing with something like E2B or Docker is essential for anything untrusted. An agent that can run code is an agent that can run the wrong code, and the boundary you put around it is your responsibility.
When a tool can edit files and run commands, “approve each step” stops being a nicety and becomes the safety model. OpenCode’s flow is built around exactly this: the agent proposes an action and you approve it before it happens. Treat that approval step as load-bearing, not as a speed bump to click through.
And because the agent writes code, a weaker model fails more visibly, producing broken Python rather than quietly malformed tool calls. The fix is the same as everywhere in local AI: use a strong model. A code-based agent makes model weakness obvious, which is uncomfortable but honest; a schema-based one can hide the same weakness behind a valid-looking call. The same holds for OpenCode, where model quality is still the ceiling and a weak model is still a weak agent. A chat model can hedge a thin answer. An agent that acts on a thin decision breaks something.
Those risks multiply when several agents run at once, and that is now a funded research question. In June 2026, Google DeepMind, Schmidt Sciences, the Cooperative AI Foundation, ARIA and Google.org opened a $10 million call for research into how large groups of AI agents behave when they interact. One agent writing Python on your machine is a sandboxing problem. Fifty of them is a field of study.
When should you actually reach for smolagents?
Reach for smolagents if you write Python, you have outgrown a plain LLM-in-a-loop, and you want a code-first agent without ceremony. It is the right step up when direct calls with structured outputs stop being enough: multiple tools, branching logic, code-driven workflows. It is also the framework to reach for first precisely because it is the easiest to abandon when you discover you did not need a framework after all.
Reach for nothing if a simple model call and a Python loop would do the job. If the task is one call and one answer, such as summarise this or classify that, a direct model call does it without tools or a loop. That is genuinely the right answer more often than the category’s marketing admits. Do not adopt a framework to solve a problem a loop already solves.
The progression is worth internalising: one prompt, then a prompt plus a tool, then a small loop, and only then a framework. Each step is cheap to try and cheap to undo. Skipping straight to a framework is how a one-afternoon problem quietly becomes a one-week dependency.
smolagents vs a plain loop for invoice extraction: what should a business test?
Invoice field extraction is a good test of the framework question, because the job is narrow. Each invoice needs the same handful of fields: supplier, invoice number, date, total, tax. A plain loop sends the invoice text to a model with a fixed list of fields, asks for structured output, checks it, and retries once if a field is missing. smolagents turns the same job into an agent that writes Python to call your tools, which this article argues earns its keep only when the path through an invoice is not fixed: a scanned page that needs a separate reading tool first, a supplier that must be looked up in a ledger before the total is accepted, or a credit note that changes which fields count.
We have not run one fixed batch of real invoices through field extraction both ways on Gemma 4 31B on our test machine, so there are no fields-correct counts, no count of invoices needing a person, no seconds per invoice and no lines-of-code comparison here. That run is on our list. What we can give is the cost of each extra step on our own hardware. On our test machine, an M4 Pro with 48 GB of unified memory, Gemma 4 31B generates at a median 11.0 tokens a second, measured in our local LLM benchmarks on the M4 Pro. At that rate, every extra model call that writes 300 tokens of code or reasoning adds about 27 seconds per invoice (300 divided by 11). A code-writing agent that takes three steps where a loop takes one pays that cost three times on every document.
A business deciding between the two should run the same batch of invoices both ways and record four things: fields correct per invoice, invoices that needed a person, seconds per invoice, and how many lines of code each version needs. Where the agent runs code against financial documents, the sandboxing described above stops being optional.
What to decide before an agent pilot
If the test says an agent is worth it, write down four answers before any agent touches real files.
First, confirm the job needs an agent at all: tools, branching and several steps, not one call and one answer.
Second, decide who approves actions. OpenCode asks before it reads, edits or runs anything. In a pilot, the approver is the person who owns that code or data, and approvals stay on for the whole pilot rather than being switched off once people grow used to them.
Third, decide where the agent runs. Anything that writes and executes code, as smolagents does, belongs in a sandbox such as E2B or Docker. Point a pilot at a copy of a repository or a test folder, never at the live one.
Fourth, decide what data may leave the machine. A local model keeps every file the agent reads on your own hardware. If the pilot uses a cloud model for some steps, list which folders it may see.
Judge the pilot on whether the agent completed the task inside those limits and how often a person had to step in. We have not run a scoped agent pilot on a test repository on our test machine with tasks completed, approvals given and interventions logged, so we publish no figures for what such a pilot produces. That run is on our list.
What do we run, and why?
Most teams will need a framework rarely, and when they do, smolagents is our pick. For most work, a direct model call with structured outputs and a small hand-written loop is enough, and it is easier to reason about than anything a framework gives you. smolagents earns its place only when that approach breaks down, and its minimalism is why it can be trusted there: if you outgrow it, the problem has usually been overengineered and the framework tells you so.
For coding work such as refactors and repo edits, a framework is the wrong tool. End-user products do the job: Aider and Cline, and OpenCode pointed at a local model, which runs the agentic loop fully on the machine. smolagents is for building a custom agent that does something specific, not for general coding. Alternatives like OpenJarvis stay on the bench until we have run them in real work; when that is done, we will say so here rather than guess now.
The takeaway is smaller and more useful than a framework shootout. “Agentic” is a model in a loop with the ability to act, and for local AI that moved the ceiling from answering questions to completing tasks while the data stays on your machine. Start with a loop. Add smolagents only when the loop visibly breaks. And treat any framework that cannot survive you reading its source in an afternoon with suspicion. You watch the work, you decide.
