smolagents - Code-First AI Agents Cheatsheet

smolagents - Code-First AI Agents Cheatsheet

smolagents is a minimal, code-first agent library from Hugging Face. Its central idea: instead of having the model emit tool calls as JSON blobs, a CodeAgent writes and executes Python code directly. Expressing actions as code lets a single step call multiple tools, use loops and variables, and chain logic — which reduces the number of LLM round-trips (roughly ~30% fewer) and improves performance on complex tasks. It is model-agnostic, supports sandboxed execution, and stays deliberately small and hackable.

Installation

Method	Command
pip	pip install smolagents
With tools extras	pip install "smolagents[toolkit]"
Sandbox extras	pip install "smolagents[e2b]" (or [docker])
Set a model key	export HF_TOKEN=... or provider keys
Verify	python -c "import smolagents; print('ok')"

Core Concepts

Term	Meaning
CodeAgent	Agent that writes Python actions (the default)
ToolCallingAgent	Agent that emits classic JSON tool calls
Tool	A callable the agent can use (with a schema)
Model	The LLM backend (HF, OpenAI, LiteLLM, local)
Sandbox	Where generated code runs (local, E2B, Docker, Modal)

A Minimal CodeAgent

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

agent = CodeAgent(
    tools=[WebSearchTool()],
    model=InferenceClientModel(),   # HF Inference API
)

agent.run("How many seconds would it take a cheetah to cross the Golden Gate Bridge?")

Object	Role
CodeAgent(tools=[...], model=...)	The agent
agent.run("task")	Execute a task end to end
WebSearchTool()	A built-in tool
InferenceClientModel()	HF-hosted model backend

Models

Backend	Class
HF Inference API	InferenceClientModel
Local transformers	TransformersModel
Any provider via LiteLLM	LiteLLMModel(model_id="openai/gpt-4o")
OpenAI-compatible server	OpenAIServerModel(...)
vLLM / local endpoints	via LiteLLM / OpenAI-compatible

Defining Tools

from smolagents import tool

@tool
def get_weather(city: str) -> str:
    """Return the weather for a city.

    Args:
        city: The city to look up.
    """
    return f"Sunny in {city}"

agent = CodeAgent(tools=[get_weather], model=InferenceClientModel())

Mechanism	Use
@tool decorator	Turn a typed function into a tool
Tool subclass	More control over schema/behavior
Tool Collections	Import sets of tools (e.g. from the Hub)
MCP tools	Connect Model Context Protocol servers

Sandboxed Execution (Important)

Because CodeAgents run generated Python, isolate it in production.

Sandbox	How
Local (default)	Runs in-process — fine for trusted dev only
E2B	executor_type="e2b" (remote sandbox)
Docker	executor_type="docker"
Modal	Remote sandboxed execution
Allowed imports	Restrict which modules generated code may import

agent = CodeAgent(tools=[...], model=..., executor_type="e2b")

Multi-Agent & Retrieval

Pattern	How
Managed agents	Give one agent other agents as tools
Retrieval/RAG	Add a retriever tool for grounded answers
Planning	Enable periodic planning steps for hard tasks
Handoffs	Compose specialists under a manager agent

Common Workflows

# A research agent that browses and computes in code
from smolagents import CodeAgent, WebSearchTool, InferenceClientModel
agent = CodeAgent(tools=[WebSearchTool()], model=InferenceClientModel(),
                  executor_type="docker")
agent.run("Compare the population growth of Tokyo and Delhi since 2000.")

smolagents vs Other Agent Frameworks

Aspect	smolagents	LangGraph	Pydantic AI
Action format	Python code	Graph/state machine	Typed tool calls
Size/philosophy	Minimal, hackable	Full state orchestration	Type-safe, FastAPI-style
LLM efficiency	Fewer calls (code)	Depends	Standard
Best for	Single-agent code loops	Durable stateful agents	Type-safe production agents

Resources

• GitHub Repository
• Official Documentation
• Guided Tour