Skip to content

smolagents

Hugging Face's compact agent library — agents that act by writing Python code, plus classic tool-calling agents.

GroupLightweight
Current versionv1.26.0
Bonds withPy

Agents that act in code. A CodeAgent writes short Python snippets that call your tools, loop and compute; a ToolCallingAgent uses ordinary JSON tool calls. The core is small enough to read in an afternoon, which makes it a good first framework and an easy one to debug.

Current version: smolagents 1.26.0 (checked 2026-11-19). Python 3.10+.

Install

Terminal window
pip install "smolagents[toolkit]==1.26.0"

Best for

Learning, prototyping, code-first automation, Hugging Face Hub workflows.

  • 1.26.0 — Exa added as a WebSearchTool engine; the experimental WasmExecutor (executor_type="wasm") removed.
  • 1.25.0 — Security hardening of remote executors; allow_pickle defaults to False; documentation now states plainly that LocalPythonExecutor is not a sandbox; huggingface-hub 1.x supported.
  • 1.24.0 — More robust execution timeout for the local executor; FinalAnswerStep passed to step_callbacks; saved agents that reference the old HfApiModel class load as InferenceClientModel (the HfApiModel import itself has not existed since 1.19.0).
from smolagents import CodeAgent, InferenceClientModel, tool
@tool
def add_numbers(a: int, b: int) -> int:
"""Add two numbers together.
Args:
a: The first number.
b: The second number.
"""
return a + b
model = InferenceClientModel(model_id="Qwen/Qwen3.8-27B") # needs HF_TOKEN
agent = CodeAgent(tools=[add_numbers], model=model)
print(agent.run("What is 15 + 27?"))

Pass a model_id: the library’s default model had no live Inference Provider when this was checked on 2026-10-21. See model configuration for how to check which providers serve a model.

Next: Introduction & philosophy, the first step of the learning path.


DateVersionChanges
2026-10-241.26.0Audit against the installed package: corrected the Inference Endpoint example, step-callback registration, GradioUI.launch() sharing default, Docker image rebuilds, the browser-agent recipe and step counting; added sections on memory and steps, planning, MCP, local-executor limits, saving agents and tools, delegation, and scripted tests for tool-calling agents.
2026-10-211.26.0Diagrams page cut to accurate diagrams; tools-in-sandbox, LogLevel and quantisation corrections; served model IDs; recipes for the browser agent, agentic RAG and plan review; streaming endpoint and in-flight autoscaling in the production guide.
2026-10-211.26.0All pages re-verified against the installed package; code rewritten where it used non-existent APIs; release notes corrected; version references now come from the site’s version data.
2026-05-291.26.0Version bump.
2026-04-211.24.0Index redesigned with a learning path and topic grid.
November 20251.23.0Initial documented version.