smolagents

smolagents is a Python library for building autonomous AI agents, released by Hugging Face on December 31, 2024. The library's central premise is that agents should write and execute Python code to take actions, rather than generating JSON tool-call dictionaries as most other frameworks do. The core agent logic fits in approximately 1,000 lines of code, which is a deliberate choice: the entire framework is readable, auditable, and hackable in an afternoon. Licensed under Apache 2.0, smolagents has grown to 27,000 GitHub stars by May 2026, making it one of the fastest-adopted agent frameworks since LangChain.

The library ships two agent types: CodeAgent, which generates Python snippets as actions and executes them in a sandboxed interpreter (producing 30% fewer LLM calls than JSON-based tool usage), and ToolCallingAgent, which follows the standard JSON tool-calling format for compatibility with OpenAI-style APIs. It supports 100-plus model backends through LiteLLM, including local inference via Ollama and Hugging Face Transformers, plus OpenAI, Anthropic, and any provider with an OpenAI-compatible endpoint. Agents and tools can be shared and pulled from the Hugging Face Hub. Multimodal inputs (text, vision, video, audio) are supported. Sandbox execution options include E2B, Modal, Docker, Blaxel, and WebAssembly environments for teams running untrusted code in production.

What smolagents actually does in April 2026

smolagents runs a multi-step reasoning loop: the agent receives a task, asks the LLM what to do next, executes the resulting action (as Python code or a tool call), observes the output, and repeats until the task is complete or the step limit is reached. The CodeAgent variant converts this into executable Python at each step rather than a JSON action object. A minimal working agent takes three lines of Python: import the library, instantiate a CodeAgent with a list of tools and a model, then call agent.run("your task").

Version 1.24.0 (January 2026) expanded the multi-agent architecture, where a manager CodeAgent can delegate subtasks to specialized sub-agents. The Hub integration means any tool or agent configuration published to the Hugging Face Hub is importable in one line. MCP server compatibility was added in early 2025, so smolagents can consume tools exposed through the Model Context Protocol alongside native Python tools and LangChain-compatible tools.

The GAIA benchmark result from the library's launch period established its credibility: a CodeAgent built with the smolagents architecture scored 44.2% on the GAIA validation set (ranked first at launch), beating Microsoft's AutoGen at 40% and far above the baseline GPT-4-Turbo score of under 7% on the same benchmark without an agent framework. GAIA tests high-level planning, multimodal reasoning, and multi-step information gathering across complex tasks like identifying artworks, matching historical documents, and processing structured data. By late 2025, further optimization pushed smolagents-based systems to 55% on GAIA, reinforcing the code-first approach's advantage on tasks requiring composable, stateful computation.

Where smolagents sits versus LangChain and PydanticAI

The three most-cited comparisons for smolagents are LangChain/LangGraph (the dominant incumbent), PydanticAI (the type-safety-first newcomer), and to a lesser degree LlamaIndex. Each represents a different philosophy about what an agent framework should be.

LangChain and LangGraph have 90,000-plus GitHub stars and five years of production history. LangGraph extends LangChain with a directed acyclic graph (DAG) architecture where agent steps are explicit graph nodes, giving developers precise control over branching logic, state machines, retries, and error propagation. That control comes with ceremony: defining a LangGraph workflow requires explicit node definitions, edges, and state schemas before a single action runs. smolagents handles the ReAct loop automatically in its 1,000-line core; you supply tools and a model, and the loop is managed for you. LangGraph is the right choice for complex stateful orchestration with human-in-the-loop checkpoints and fine-grained error handling. smolagents is faster to prototype but less controllable at scale.

PydanticAI, released in September 2024 and reaching v1.0 in September 2025, brings FastAPI-style structured validation to agent development. Every tool call and agent output is validated against Pydantic schemas before processing, with built-in OpenTelemetry instrumentation and async-first design. PydanticAI's mechanical difference from smolagents is output enforcement: where smolagents produces whatever Python the LLM writes and trusts the code to be valid, PydanticAI enforces schema contracts at every boundary. For healthcare records, financial data pipelines, or any application requiring auditable, predictable structured responses, PydanticAI's validation guarantees matter. smolagents offers no equivalent mechanism. The tradeoff is that PydanticAI's strict typing adds setup overhead that smolagents deliberately avoids.

For teams already invested in the Hugging Face ecosystem, using Transformers or open-source models via Ollama, or building research prototypes, smolagents has a clear home-field advantage. For teams running production applications that process sensitive structured data, LangGraph's control or PydanticAI's validation are worth the added complexity. Users often pair smolagents with Hugging Face Hub for model access and tool sharing, or with LangChain tools through smolagents' LangChain compatibility layer.

"If JSON snippets were a better expression, JSON would be the top programming language and programming would be hell on earth." - Aymeric Roucher, Merve Noyan, and Thomas Wolf, Hugging Face engineering team, smolagents launch blog, December 2024

What the agent loop reality looks like

Running a CodeAgent in smolagents means the LLM is generating Python on every step. That works well when the model has strong code generation ability. When it does not, the loop degrades quickly: the agent writes syntactically broken Python, the interpreter throws an exception, the error gets appended to the context, and the LLM is asked to fix it. On capable models (GPT-4o, Claude Sonnet, DeepSeek-R1, Qwen2.5-Coder), this self-correction loop is robust. On general-purpose smaller models, it produces a frustrating spiral of failing code that burns tokens without making progress.

Memory management is the most frequently cited frustration in GitHub issues. The agent maintains a full history of every action and observation. On long tasks, this history grows past the model's context window. Unlike Claude Code's summarization approach (which compresses older context on a rolling basis), smolagents as of early 2026 has no built-in memory consolidation. GitHub issue #694 describes the problem directly: "basic truncation and message removal, but NO built-in summarization to manage long-term memory growth." Issue #901, filed March 2025, confirms that "memory-related tooling is not yet exposed in smolagents, which is a limitation for more advanced agent applications." Issue #1121 (April 2025) is a feature request for a persistent long-term memory bank. These are known gaps on the public roadmap.

Sandboxed code execution is documented but layered. Running the CodeAgent locally uses a restricted Python interpreter (AST-based, with import controls and operation count caps). For stricter isolation, E2B, Modal, Docker, and WebAssembly sandboxes are available, but the multi-agent architecture does not currently support sandboxed executors, meaning the manager agent and its sub-agents run in the same execution context. Production deployments handling untrusted inputs need to architect around this limitation explicitly.

"There's a big step from what smolagents currently does to everything you need for an agent framework running a production-level application." - agentsdecoded.com framework review, 2025

Users building research and data science workflows report the smoothest experience. A typical pattern: define 5-10 tools (DuckDuckGo search, a Python REPL, a file reader, an API client), instantiate a CodeAgent, and hand it an open-ended research task. The agent composes Python that chains tool calls, processes intermediate results in variables, and returns structured output without the developer writing any orchestration logic. Users frequently pair smolagents with DSPy for prompt optimization or PydanticAI for output validation in hybrid pipelines.

Who smolagents is built for

smolagents suits ML researchers, data scientists, and backend developers who already think in Python and want minimal framework overhead. The HuggingFace ecosystem integration (Hub models, Hub tools, Transformers, Datasets) makes it the natural first choice for teams already inside that stack. If your model deployment is Ollama running Llama or Qwen locally, or a fine-tuned model on HuggingFace Inference Endpoints, smolagents is the obvious starting point: the integration is native, the license is compatible, and the codebase is small enough to read and patch.

Open-source model users benefit specifically because smolagents treats all models equally through LiteLLM compatibility. There is no premium tier for gated models or proprietary optimizations. The same CodeAgent that runs against GPT-4o can run against a local Qwen2.5-Coder model with one config change. Teams exploring agent architectures without vendor lock-in will appreciate this flexibility. For exploring multi-agent coordination, the managed agents pattern (where a top-level agent orchestrates sub-agents) works out of the box without additional configuration. The library complements LlamaIndex in pipelines where retrieval-augmented generation feeds into an agent that processes the retrieved context with code.

What smolagents is not

smolagents is not a production-grade enterprise agent platform. It has no built-in observability, structured logging, or retry policies beyond what the developer adds manually. There are no schema-enforced outputs, no native audit trail, and no compliance certifications. Teams in regulated industries (healthcare, finance, legal) evaluating agent frameworks for production deployments will find PydanticAI's validation contracts or LangGraph's explicit state management better matches for their governance requirements.

It is also not forgiving of weak models. The code-first approach requires an LLM that writes clean, functional Python under prompt pressure. Attempting to run smolagents against smaller general-purpose models (below roughly 7B parameters, or models not specifically trained on code) produces unreliable results. This is a real hardware and cost constraint for teams wanting to self-host everything on consumer-grade GPUs.

Finally, smolagents is not a workflow orchestration tool in the LangGraph sense. If your use case requires explicit branching logic (route task A to sub-agent X, task B to sub-agent Y based on a classifier), conditional retries with state persistence, or human-in-the-loop approval steps, LangGraph gives you those primitives. smolagents abstracts them away, which is its strength for simple cases and its ceiling for complex ones. Teams that have outgrown the automatic ReAct loop and need precise orchestration control should treat smolagents as a prototyping phase before migrating to a more explicit framework like LangGraph or CrewAI.