smolagents: Hugging Face's Code-First Python Agent Library

June 14, 2026·AI Newsroom·4 min read·9 sources
huggingfacesmolagentsagentcode-agentopen-sourcemcp+4high-risk claims
smolagents open-source repository social preview card
Image: GitHub / huggingface/smolagents repository (Apache 2.0)

As of 2026-06-14, the public repository huggingface/smolagents — Hugging Face’s Python library for building LLM agents — counts 27,843 stars, 2,687 forks, 595 open issues, ships under Apache 2.0, with last push on 2026-06-09 and latest release v1.26.0 on 2026-05-29 (GitHub Releases, 2026-06-14). The README positions it as “a barebones library for agents that think in code” — the LLM writes Python snippets that execute, instead of a JSON dictionary of tool name + arguments (HF blog, 2024-12-31).

What it is

Two agent classes (smolagents docs):

Installation: pip install 'smolagents[toolkit]' with optional extras ([docker], [e2b], [modal], [litellm], [mcp], [telemetry]). Quickstart:

from smolagents import CodeAgent, InferenceClientModel, DuckDuckGoSearchTool
model = InferenceClientModel()
agent = CodeAgent(tools=[DuckDuckGoSearchTool()], model=model)
result = agent.run("What is the current weather in Paris?")

Integrations (as of 2026-06-14):

Release cadence: 17 releases between v1.23.0 (2025-11-17) and v1.26.0 (2026-05-29) — about one every 12-15 days. v1.25.0 (2026-05-14) hardened remote executors: removed allow_origin from Docker/Modal, added token auth in Docker/Wasm, isolated Deno caches, and reinforced “LocalPythonExecutor is not a security tool.”

Why it matters

1. The “Code Agent” paradigm is a research choice, not a tagline. The CodeAct paper (Wang et al., 2024, ICML 2024) evaluates 17 LLMs on API-Bank and M3ToolEval (82 multi-tool tasks). CodeAct posts a higher success rate on 12 of 17 models versus JSON or text — up to 20% absolute gain on gpt-4-1106-preview, with up to 30% fewer interactions (§2.3). The reasons: composability (nested calls, loops, conditionals in one action), object handling (output becomes a variable for the next action), generality (Python is Turing-complete), and training-data fit (LLMs already see lots of Python). The transformers.agents → smolagents transition was the move to align HF’s reference library with this paper.

2. Sandboxing is explicit, not optional. The Secure code execution page opens with: “By default, the CodeAgent runs LLM-generated code in your environment. This is inherently risky.” The mitigation is a remote sandbox — DockerExecutor (recommended Dockerfile: USER nobody, cap_drop=ALL, mem_limit=512m, no-new-privileges), E2BExecutor, ModalExecutor, BlaxelExecutor. The default LocalPythonExecutor is a custom AST-walking interpreter that blocks unauthorized imports and limits operations — a first filter, not a security boundary.

3. It’s an HF library, not a community fork. Owner is the huggingface org; most releases are signed by HF staff. Distribution is native HF Hub: push_to_hub() publishes a tool as a Space, Tool.from_space() consumes one, InferenceClientModel calls the HF Inference API. For teams already on HF Hub, this is the lowest-friction option in the Python agent landscape.

4. The entry barrier is intentionally low. Core logic fits in ~1,000 lines (agents.py). The ReAct loop, planning, memory, and logging are all readable. Heavier libraries (LangGraph, crewAI) offer production multi-agent, persistence, and tracing — smolagents offers a readable Code Agent.

5. Adoption is strong, read honestly. 27.8k stars is high for a six-month-old library, but crewAI is at 53.5k, langchain above 100k, autogen around 50k. Smolagents competes on positioning (Code Agents + simplicity), not absolute volume. 595 open issues signal an active user base and a real backlog.

Practical implications

Risks and caveats

  1. “Code Agents” ≠ “secure by default.” LocalPythonExecutor runs model code in your environment; the docs say so explicitly.
  2. CodeAct numbers are research-grade. The 20%/30% figures are on M3ToolEval (82 tasks) and gpt-4-1106-preview. Open-source models score far lower (CodeActAgent-Mistral at 12.2% vs gpt-4-1106-preview at 74.4% on the same benchmark).
  3. Not the only Code Agent implementation. TaskWeaver is concurrent work; autogen and langgraph also support code execution.
  4. Supply-chain risk via Tool.from_space. Third-party HF Space code runs in your agent. Verify the author and revisions.
  5. 595 open issues is a real backlog. Active maintenance, not abandoned.
  6. Stars are a snapshot. 27,843 on 2026-06-14, not a permanent number.

What to watch

Verdict

huggingface/smolagents is a well-maintained, Apache 2.0, HF-native Python agent library that puts executable code at the center of agent actions. The bet — higher execution risk in exchange for expressiveness and training-data fit — is supported by the CodeAct paper on a synthetic benchmark, not by exhaustive comparison. For an AI engineer in 2026: read the docs, install it, and try it. Configure remote sandboxing from the first commit. For multi-agent production with tracing and flow control, prefer LangGraph or crewAI. For a simple, readable, Code-First agent that integrates with the HF ecosystem, smolagents is the natural pick.

Sources