smolagents: The Hugging Face Agent Framework That Has Almost Zero Setup

Here's a thought experiment. You want to build an AI agent that can search the web and save the results to a file. How long should that take?

With LangChain: you'll spend 30 minutes understanding runnables, another hour on the tool schema format, 20 minutes debugging a memory class import, and eventually you'll have a working agent wrapped in 150 lines of boilerplate that you only partially understand.

With smolagents: you'll have it working in about 25 lines of code. No boilerplate. No DSL. No documentation spelunking. Just Python.

This is not an exaggeration. It's the actual experience of switching between frameworks — and it's why smolagents has become the entry point that most AI educators now recommend for people learning agent development.

Most agent frameworks work by having the LLM output a JSON object that the framework then parses to figure out what tool to call. This adds complexity and introduces a layer where structured output failures cause the whole thing to break.

smolagents takes a different path. The agent — specifically the CodeAgent — is told: "here are some Python functions available to you. Write Python code to solve the problem." The framework then executes that Python in a sandboxed environment.

This is elegant for several reasons. LLMs are exceptionally good at writing Python — it's one of the most represented languages in their training data. By working in Python instead of JSON schemas, the agent has access to the full expressiveness of the language: variables, loops, conditionals, error handling.

Install smolagents with your choice of model provider:

pip install smolagents[anthropic]  # or [openai], [huggingface]

Build a web research agent:

from smolagents import CodeAgent, DuckDuckGoSearchTool, LiteLLMModel, tool
import os

model = LiteLLMModel(
    model_id="anthropic/claude-sonnet-4-5",
    api_key=os.environ["ANTHROPIC_API_KEY"]
)

@tool
def save_to_file(content: str, filename: str) -> str:
    """Saves text content to a local file.
    Args:
        content: The text content to save
        filename: The output filename (e.g., results.txt)
    """
    with open(filename, 'w') as f:
        f.write(content)
    return f"Saved to {filename}"

agent = CodeAgent(
    tools=[DuckDuckGoSearchTool(), save_to_file],
    model=model
)

agent.run(
    "Search for the top 3 AI agent frameworks released in 2026. "
    "Summarize each one and save the results to ai_frameworks.txt"
)

Run this. In your terminal, you'll see the agent's internal reasoning, the Python it writes, the output of the search tool, and finally the confirmation that the file was saved. Total working code: about 30 lines.

One of smolagents' most powerful features is first-class integration with Hugging Face's model hub. If you want to use a local or hosted open-source model instead of a commercial API, it's a one-line change:

from smolagents import HfApiModel

# Use any model from Hugging Face Hub
model = HfApiModel("Qwen/Qwen2.5-Coder-32B-Instruct")

# Or use a local Ollama model
from smolagents import LiteLLMModel
model = LiteLLMModel(model_id="ollama/qwen2.5-coder:32b")

This flexibility means smolagents works equally well for commercial API use and fully offline local deployments. The agent code doesn't change — only the model definition.

smolagents is the right choice when you need to build something quickly, prototype an agent concept, or build a relatively linear task-automation workflow.

It's the wrong choice when you need: complex multi-agent orchestration with human-in-the-loop checkpoints (use LangGraph), parallel agent workflows with structured role delegation (use CrewAI), or enterprise-grade production infrastructure with observability tooling baked in.

Think of smolagents as the requests library of the agent world — incredibly useful, used constantly, not designed to be your entire infrastructure. The best developers learn smolagents first, then learn LangGraph when they need its power.