smolagents - HuggingFace's NEW Agent Framework

Hugging Face’s new “smolagents” framework pushes agent building toward “code agents”: instead of forcing an LLM to emit JSON-style plans, it can write and run Python in a sandbox to decide what to do next. The practical payoff is a simpler path from prompt to action—often just “model + tools”—while still keeping guardrails through restricted, sandboxed imports and tool access.

The framework’s first big differentiator is how it defines “agency.” It positions agents on a spectrum: from tightly constrained tool-calling loops (safer, more predictable) to higher-agency setups that let models take multi-step actions. smolagents leans into the middle ground by supporting both tool-calling agents and code agents, with code agents designed to let the model “think in code” and execute it step-by-step. This direction draws on prior research showing benefits from letting models execute code (e.g., via Python) and feed back structured results, rather than relying purely on text or JSON.

On the model side, smolagents is built to work with Hugging Face Hub models, with an out-of-the-box default using “Qwen 2.5 Coder 32B Instruct.” Access depends on Hugging Face account tier, but the framework also supports proprietary models through “light llm,” enabling use of OpenAI and Anthropic-style backends. In practice, the setup is framed as minimal: import a code agent, provide a model wrapper, and register tools. A built-in example computes the cube root of 27 by running Python directly—no external search tool needed.

Where the framework becomes most revealing is in real tasks that require external data and reasoning. For a route-time question (“drive from Melbourne to Sydney”), the agent switches to web search, extracts distance/time candidates from results, and produces an estimated range. For a more complex finance scenario (“buy Bitcoin with $11,000 to reach $1 million”), the agent attempts to fetch historical prices and write code to compute the answer, but it fails repeatedly due to sandbox restrictions—certain Python libraries (like requests) and even JSON handling are not authorized by default. The agent then falls back to less reliable strategies (web queries and printed outputs) and hits a maximum iteration limit, consuming substantial token budgets along the way.

The transcript also highlights how to tune the sandbox: authorized imports can be expanded (e.g., adding requests, bs4, or math), and system prompts can be overridden to change agent behavior. Even with tuning, the agent may still struggle with errors when assembling tables or performing multi-step data work, suggesting that reliability depends heavily on allowed libraries, iteration limits, and prompt/model fit.

Finally, smolagents supports traditional tool-calling patterns (React-like loops) and custom tools defined by developers, including specifying input/output schemas and pushing tools to the Hugging Face Hub for reuse. The overall message is that smolagents makes agent experimentation faster and more flexible, but code-agent reliability still hinges on sandbox permissions and error-handling—especially for data-heavy tasks.