Getting started with smolagents

Who this is for and what you will be able to do

If you want a language model to search the web, call tools and work through a task in several steps, without writing the scheduling code yourself, smolagents is worth trying. By the end of this guide you should be able to install it, run an agent that searches the web, add a custom tool, and understand the limits on code execution.

What smolagents is and how it differs

smolagents is a lightweight Python library from Hugging Face for building AI agents^[1]. Other open-source frameworks in the same space include LlamaIndex and LangGraph^[1], so the choice between them depends on what your project needs.

The main agent type in smolagents is the CodeAgent. Instead of asking the model to output JSON, it asks the model to generate Python code that performs the actions^[2]. The library also includes ToolCallingAgents, which rely on JSON or text blobs that the system must parse and interpret before anything runs^[1]. The two types differ in how actions are written down.

Writing actions as code has practical advantages. Actions can be combined and reused, complex objects such as images can be handled directly, and code can express any task a computer can perform. High-quality code is also already common in LLM training data^[2]. The framework itself is implemented in about 1,000 lines of code^[2], which makes it small enough to read.

Each step of a CodeAgent works in a loop. The system prompt and the user's task are recorded first. Then the agent turns its logs into chat messages, sends them to the model, extracts the code from the completion, executes it, and records the result in memory^[2]. The agent's run() method follows the ReAct framework, which alternates between reasoning, acting and observing the result^[2].

Preparation

You need a working Python environment. Install the library with the command below. The -U flag upgrades an existing installation to the latest version^[2].

pip install smolagents -U

The default model connection is InferenceClientModel, which reaches models through Hugging Face's Serverless Inference API. Its default model is Qwen/Qwen2.5-Coder-32B-Instruct, and you can choose any compatible model on the Hub instead^[2]. To use the Serverless Inference API, log in to the Hub first^[2]:

from huggingface_hub import login

login()

Step 1: run an agent with web search

An agent needs a list of tools and a model. The example below gives the agent a DuckDuckGo search tool and asks it for music recommendations^[2]:

from smolagents import CodeAgent, DuckDuckGoSearchTool, InferenceClientModel

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

agent.run("Search for the best music recommendations for a party at the Wayne's mansion.")

When the run starts, the output shows a trace of each workflow step being executed, together with the Python code the agent generates for that step^[2]. Read the trace the first time you run an agent, because it shows what the agent actually did.

Step 2: add a custom tool

The @tool decorator turns an ordinary Python function into a tool the agent can call. The docstring matters: its Args section is what tells the model what each argument means. The following example defines a menu tool^[2]:

@tool
def suggest_menu(occasion: str) -> str:
    """
    Suggests a menu based on the occasion.
    Args:
        occasion (str): The type of occasion for the party. Allowed values are:
                        - "casual": Menu for casual party.
                        - "formal": Menu for formal party.
                        - "superhero": Menu for superhero party.
                        - "custom": Custom menu.
    """
    if occasion == "casual":
        return "Pizza, snacks, and drinks."
    elif occasion == "formal":
        return "3-course dinner with wine and dessert."
    elif occasion == "superhero":
        return "Buffet with high-energy and healthy food."
    else:
        return "Custom menu for the butler."

Listing the allowed values in the docstring points the agent toward argument values that actually exist, which limits made-up values^[2]. To use the tool, add it to the tools list and run the agent:

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

agent.run("Prepare a formal menu for the party.")

Step 3: allow an extra import

Code written by the agent runs under restrictions. Imports outside a predefined safe list are blocked by default^[2]. To allow a module, pass its name as a string in the additional_authorized_imports parameter. The example below authorizes datetime^[2]:

agent = CodeAgent(tools=[], model=InferenceClientModel(), additional_authorized_imports=['datetime'])

Authorize only the modules the task needs. Each extra module widens what the generated code can do.

Limits and common questions

smolagents works with both local and API-based language models, so the same agent code can run in different environments^[2]. It also offers sandboxed code execution, which is the main protection when the agent runs code it wrote itself^[2].

To see what happened inside a run, smolagents uses the OpenTelemetry standard for instrumenting agent runs^[2]. With Langfuse and the SmolagentsInstrumentor, each run can be logged and inspected. Install the dependencies first^[2]:

pip install opentelemetry-sdk opentelemetry-exporter-otlp openinference-instrumentation-smolagents langfuse

Then enable the instrumentor before running the agent^[2]:

from openinference.instrumentation.smolagents import SmolagentsInstrumentor

SmolagentsInstrumentor().instrument()

Sharing an agent

agent.push_to_hub() uploads a complete agent to the Hugging Face Hub, and agent.from_hub() downloads it again. The example passes trust_remote_code=True to from_hub()^[2]. That flag allows the loaded agent to run code stored in its repository, so only load agents from sources you trust.