smolagents - a smol library to build great agents!

smolagents is a library that enables you to run powerful agents in a few lines of code. It offers:

✨ Simplicity: the logic for agents fits in 1,000 lines of code (see agents.py). We kept abstractions to their minimal shape above raw code!

🧑‍💻 First-class support for Code Agents. Our CodeAgent writes its actions in code (as opposed to "agents being used to write code"). To make it secure, we support executing in sandboxed environments via E2B.

🤗 Hub integrations: you can share/pull tools to/from the Hub, and more is to come!

🌐 Model-agnostic: smolagents supports any LLM. It can be a local transformers or ollama model, one of many providers on the Hub, or any model from OpenAI, Anthropic and many others via our LiteLLM integration.

👁️ Modality-agnostic: Agents support text, vision, video, even audio inputs! Cf this tutorial for vision.

🛠️ Tool-agnostic: you can use tools from LangChain, Anthropic's MCP, you can even use a Hub Space as a tool.

Full documentation can be found here.

Note

Check the our launch blog post to learn more about smolagents!

Table of Contents

• Introduction
• Quick Demo
• Command Line Interface
• Code Agents
• How smol is this library?
• How Strong are Open Models for Agentic Workflows?
• Contributing
• Citing smolagents

Quick demo

First install the package.

pip install smolagents

Then define your agent, give it the tools it needs and run it!

from smolagents import CodeAgent, DuckDuckGoSearchTool, HfApiModel

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

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

smolagents.mp4

Our library is LLM-agnostic: you could switch the example above to any inference provider.

HfApiModel, gateway for 4 inference providers

from smolagents import HfApiModel

model = HfApiModel(
    model_id="deepseek-ai/DeepSeek-R1",
    provider="together",
)

LiteLLM to access 100+ LLMs

from smolagents import LiteLLMModel

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

OpenAI-compatible servers

import os
from smolagents import OpenAIServerModel

model = OpenAIServerModel(
    model_id="deepseek-ai/DeepSeek-R1",
    api_base="https://api.together.xyz/v1/", # Leave this blank to query OpenAI servers.
    api_key=os.environ["TOGETHER_API_KEY"], # Switch to the API key for the server you're targeting.
)

Local `transformers` model

from smolagents import TransformersModel

model = TransformersModel(
    model_id="Qwen/Qwen2.5-Coder-32B-Instruct",
    max_new_tokens=4096,
    device_map="auto"
)

Azure models

import os
from smolagents import AzureOpenAIServerModel

model = AzureOpenAIServerModel(
    model_id = os.environ.get("AZURE_OPENAI_MODEL"),
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
    api_version=os.environ.get("OPENAI_API_VERSION")    
)

Command Line Interface

You can run agents from CLI using two commands: smolagent and webagent. smolagent is a generalist command to run a multi-step CodeAgent that can be equipped with various tools, meanwhile webagent is a specific web-browsing agent using helium.

Web Browser Agent in CLI

webagent allows users to automate web browsing tasks. It uses the helium library to interact with web pages and uses defined tools to browse the web. Read more about this agent here.

Run the following command to get started:

webagent {YOUR_PROMPT_HERE} --model "LiteLLMModel" --model-id "gpt-4o"

For instance:

webagent --prompt "go to xyz.com/women, get to sale section, click the first clothing item you see. Get the product details, and the price, return them. note that I'm shopping from France"

We redacted the website here, modify it with the website of your choice.

CodeAgent in CLI

Use smolagent to run a multi-step agent with tools. It uses web search tool by default. You can easily get started with $ smolagent {YOUR_PROMPT_HERE}. You can customize this as follows (more details here).

smolagent {YOUR_PROMPT_HERE} --model-type "HfApiModel" --model-id "Qwen/Qwen2.5-Coder-32B-Instruct" --imports "pandas numpy" --tools "web_search translation"

For instance:

smolagent "Plan a trip to Tokyo, Kyoto and Osaka between Mar 28 and Apr 7. Allocate time according to number of public attraction in each, and optimize for distance and travel time. Bring all the public transportation options."

Code agents?

In our CodeAgent, the LLM engine writes its actions in code. This approach is demonstrated to work better than the current industry practice of letting the LLM output a dictionary of the tools it wants to calls: uses 30% fewer steps (thus 30% fewer LLM calls) and reaches higher performance on difficult benchmarks. Head to our high-level intro to agents to learn more on that.

Especially, since code execution can be a security concern (arbitrary code execution!), we provide options at runtime:

• a secure python interpreter to run code more safely in your environment (more secure than raw code execution but still risky)
• a sandboxed environment using E2B (removes the risk to your own system).

On top of this CodeAgent class, we still support the standard ToolCallingAgent that writes actions as JSON/text blobs. But we recommend always using CodeAgent.

How smol is this library?

We strived to keep abstractions to a strict minimum: the main code in agents.py has <1,000 lines of code. Still, we implement several types of agents: CodeAgent writes its actions as Python code snippets, and the more classic ToolCallingAgent leverages built-in tool calling methods. We also have multi-agent hierarchies, import from tool collections, remote code execution, vision models...

By the way, why use a framework at all? Well, because a big part of this stuff is non-trivial. For instance, the code agent has to keep a consistent format for code throughout its system prompt, its parser, the execution. So our framework handles this complexity for you. But of course we still encourage you to hack into the source code and use only the bits that you need, to the exclusion of everything else!

How strong are open models for agentic workflows?

We've created CodeAgent instances with some leading models, and compared them on this benchmark that gathers questions from a few different benchmarks to propose a varied blend of challenges.

Find the benchmarking code here for more detail on the agentic setup used, and see a comparison of using LLMs code agents compared to vanilla (spoilers: code agents works better).

This comparison shows that open-source models can now take on the best closed models!

Contribute

To contribute, follow our contribution guide.

At any moment, feel welcome to open an issue, citing your exact error traces and package versions if it's a bug. It's often even better to open a PR with your proposed fixes/changes!

To install dev dependencies, run:

pip install -e ".[dev]"

When making changes to the codebase, please check that it follows the repo's code quality requirements by running: To check code quality of the source code:

make quality

If the checks fail, you can run the formatter with:

make style

And commit the changes.

To run tests locally, run this command:

make test

Cite smolagents

If you use smolagents in your publication, please cite it by using the following BibTeX entry.

@Misc{smolagents,
  title =        {`smolagents`: a smol library to build great agentic systems.},
  author =       {Aymeric Roucher and Albert Villanova del Moral and Thomas Wolf and Leandro von Werra and Erik Kaunismäki},
  howpublished = {\url{https://github.com/huggingface/smolagents}},
  year =         {2025}
}