A deliberately small framework
On 31 December 2024, HuggingFace announces SmolAgents, a framework for building LLM-based agents with a declaredly minimalist philosophy. The project — led by Aymeric Roucher and his team — responds to the growing complexity of competing agent frameworks by offering a compact abstraction (a few thousand lines of code) fully integrated with the HuggingFace Hub ecosystem. The licence is Apache 2.0.
The stated goal is to provide simple, composable primitives: an agent is defined by a language model, a set of tools and an execution strategy. No state graph, no dedicated DSL, no intermediate abstraction layer.
CodeAgent and ToolCallingAgent
SmolAgents distinguishes two operating modes. The CodeAgent directly generates Python code that invokes tools as functions and executes that code to produce intermediate results. The ToolCallingAgent follows the classic JSON-based paradigm: the model emits structured tool calls and the framework routes them to the corresponding implementation.
The preference for CodeAgent is grounded in the paper “Executable Code Actions Elicit Better LLM Agents” (Wang et al., 2024), which shows that agents expressing actions as executable code outperform JSON-based agents on several benchmarks, thanks to the greater expressiveness of a programming language and the ability to compose multiple calls within a single action.
Tool protocol and sandboxing
The SmolAgents tool protocol is natively integrated with the HuggingFace Hub: tools can be published, versioned and shared as Spaces or dedicated repositories. A tool definition requires a typed docstring — the framework automatically derives the argument schema from the Python signature — and can be loaded remotely without additional registration steps.
For running model-generated code, SmolAgents supports optional integration with E2B, a remote sandbox environment based on Firecracker microVMs. Using E2B isolates code execution from the host environment, mitigating the risk of unintended side effects. Without E2B, the framework ships a local Python executor with a restricted set of allowed modules.
Positioning within the ecosystem
SmolAgents does not position itself as a full replacement for broader frameworks such as LangChain or LlamaIndex, but as an essential tool for use cases where the abstraction surface must remain small. The project fits into the HuggingFace tradition of interoperable components — transformers, datasets, accelerate — and extends that model to the agentic domain.