How to Use smolagents

smolagents is Hugging Face’s minimalist agent library that lets a language model write Python code as its primary way of calling tools, in roughly a thousand lines of source.

smolagents is an open-source Python framework from Hugging Face for building LLM-powered agents that reason by writing and executing code. Instead of the usual JSON-tool-call dance, the default agent — CodeAgent — asks the model to emit a Python snippet that calls registered tools, then runs it in a sandbox. Researchers use it to replicate ReAct-style agent papers, startups use it to prototype assistants without pulling in LangChain, and hobbyists use it because the whole library fits in a single afternoon of reading. It’s Apache-2.0 licensed and maintained by the Hugging Face team.

What it is

The library ships two main classes: CodeAgent, which writes Python to orchestrate tools, and ToolCallingAgent, which uses standard JSON function calls. Models plug in through engines like HfApiEngine, LiteLLMModel, or TransformersModel. Tools are ordinary Python functions decorated with @tool, and execution happens in a restricted local interpreter or an E2B remote sandbox.

Install

pip install smolagents
# optional extras for sandboxed execution and web browsing
pip install "smolagents[e2b,litellm]"

First run

Spin up a code-writing agent against a Hugging Face Inference API model and ask it a multi-step question. The agent will decide on tool calls and print its reasoning as it goes.

$ python -c "
from smolagents import CodeAgent, HfApiEngine, DuckDuckGoSearchTool
agent = CodeAgent(tools=[DuckDuckGoSearchTool()], model=HfApiEngine())
agent.run('How tall is the Eiffel Tower in feet?')
"
Thought: I should search the web for the Eiffel Tower’s height.
Code: results = web_search(query="Eiffel Tower height")
Final answer: 1,083 feet (330 m)

Everyday workflows

• Wrap a private API — decorate a function with @tool and pass it in the tools list, done.
• Swap models for cost — use LiteLLMModel to route the same agent at Claude, GPT-4o, or a local Ollama endpoint.
• Safe execution — set executor_type=“e2b” so generated Python runs in a remote sandbox instead of your laptop.

Gotchas and tips

CodeAgent is powerful but dangerous: by default it executes model-generated Python against your environment with a limited allowlist of imports. Treat the local interpreter as “safer than exec” not “safe” — put anything production-facing behind E2B or Docker. Smaller models (<14B) often fail the code-writing format and produce syntax errors; for those, fall back to ToolCallingAgent.

Latency stacks up because each step is a full model turn plus a Python exec. Cap max_steps to 6 or 8 for interactive use, and always log the agent’s logs attribute after a run — it’s the only way to debug why a trajectory went sideways.

Who it’s for

smolagents fits Python developers who want to understand their agent loop end-to-end rather than treat it as a black box. Start by reading smolagents/agents.py — it’s short enough to skim in one sitting, and you’ll save hours of debugging later.