smolagents

// Overview

smolagents is a small agent library from Hugging Face. Instead of having a model emit structured tool calls, its main agent type writes its actions as Python code and runs them. The whole agent logic is kept to around 1,000 lines, so the abstractions stay close to the raw code you would write yourself.

It is aimed at developers who want to wire an LLM up to tools without adopting a large framework. You give a CodeAgent a list of tools and a model, then call run() with a task. Because it is model-agnostic, you can point it at a local transformers or Ollama model, a Hugging Face Inference provider, or OpenAI, Anthropic, and others through LiteLLM.

As a general agent framework, smolagents focuses on the act-by-writing-code pattern and on sharing. You can pull tools and agents from the Hugging Face Hub, use tools from any MCP server or from LangChain, and run generated code inside sandboxed environments (Blaxel, E2B, Modal, or Docker) when you need isolation.

// What it does

• CodeAgent writes its actions as Python code rather than predefined tool-call payloads
• Model-agnostic: local transformers/Ollama, Hugging Face inference providers, or OpenAI/Anthropic/others via LiteLLM
• Tool-agnostic: use tools from MCP servers, LangChain, or a Hugging Face Hub Space
• Sandboxed code execution via Blaxel, E2B, Modal, or Docker
• Share and load tools and agents through the Hugging Face Hub
• Two CLI commands, smolagent and webagent, to run agents from the terminal

// Getting started

Install the package with its default toolkit, then create a CodeAgent, give it tools and a model, and run a task.

pip install "smolagents[toolkit]"

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

model = InferenceClientModel()
agent = CodeAgent(tools=[WebSearchTool()], model=model, stream_outputs=True)

agent.run("How many seconds would it take for a leopard at full speed to run through Pont des Arts?")

from smolagents import LiteLLMModel

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

smolagent "Plan a trip to Tokyo, Kyoto and Osaka between Mar 28 and Apr 7." --model-type "InferenceClientModel" --model-id "Qwen/Qwen3-Next-80B-A3B-Thinking" --imports pandas numpy

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Build a research assistant that searches the web and reasons over results step by step
• Add tool-calling agents to an app without committing to a large framework
• Run agents against different LLM providers (local, Hugging Face, OpenAI, Anthropic) behind one interface
• Connect an agent to existing MCP servers or LangChain tools and share it via the Hugging Face Hub

// How smolagents compares

smolagents alongside other open-source agent frameworks & builders tools AI/TLDR tracks, ranked by GitHub stars.