Smolagents — AI Native Crash Course

TL;DR — Smolagents is Hugging Face's agent library — radically minimal. An agent is ~1000 lines of code total. The key idea: the model writes Python code as its action (not JSON tool calls), which the framework executes in a sandboxed interpreter. Tools are plain Python functions. The whole thing fits in your head.

What it is

Smolagents provides two agent types: CodeAgent (model writes Python snippets that call tools — the default and recommended) and ToolCallingAgent (classic JSON tool-calling). Both run a ReAct loop: think → act → observe → repeat. The library is deliberately small — no chains, no graphs, no middleware. Just the loop and the tools.

Why it exists

Most frameworks over-abstract. Smolagents bets that code generation is a better action format than JSON — it's more expressive (loops, conditionals, variables), lets the model compose tools naturally, and eliminates the "translate intent to tool call schema" failure mode. The small surface area means you can read the entire source in an afternoon.

Install & setup

pip install smolagents
export OPENAI_API_KEY=sk-...

Basic agent

from smolagents import CodeAgent, tool, OpenAIServerModel

@tool
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"Sunny, 22°C in {city}"

model = OpenAIServerModel(model_id="gpt-4o")
agent = CodeAgent(tools=[get_weather], model=model)

result = agent.run("What's the weather in Paris?")
print(result)

The model generates something like:

# Agent's generated code:
weather = get_weather("Paris")
print(weather)

Hub tools

Load community tools from the Hugging Face Hub:

from smolagents import load_tool

image_gen = load_tool("m-ric/text-to-image", trust_remote_code=True)
agent = CodeAgent(tools=[image_gen], model=model)

Multi-agent

Wrap one agent as a tool for another — the managed agent pattern:

web_agent = CodeAgent(tools=[search_tool], model=model, name="web_searcher")

manager = CodeAgent(
    tools=[],
    model=model,
    managed_agents=[web_agent],
)
result = manager.run("Research vLLM and summarize findings")

When to use, when to skip

Use it when you want the simplest possible agent with code-based actions, especially with Hugging Face models and Hub tools. Great for learning, prototyping, and research.

Skip it for production systems that need persistence, middleware, or complex orchestration — LangChain or LangGraph are better there. Code execution in production requires careful sandboxing.

vs the alternatives

Tool	Best for	Trade-off
Smolagents	Minimal agents, code actions, HF ecosystem	No persistence, small ecosystem
LangChain	Full-featured agents, middleware, integrations	Large surface area
Pydantic AI	Type-safe, minimal but JSON tool calls	No code-action mode
Agno	Fast, lightweight agents	Different philosophy

Verified against Smolagents docs (huggingface.co/docs/smolagents), May 2026.

Smolagents — Hugging Face's minimal code-first agent library.