# smolagents

> Build agents that think in code, in a few lines of Python

- Category: Agents & Automation / Agent Frameworks & Builders
- Language: Python
- Licence: Apache-2.0
- Repository: https://github.com/huggingface/smolagents
- Website: https://huggingface.co/docs/smolagents
- Canonical page: https://ai-tldr.dev/tools/smolagents/

## In short

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. It sits in the Agent Frameworks & Builders category of the Agents & Automation tools and is open-source, written in Python and licensed Apache-2.0.

## 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.

1. Install

   Install smolagents with the default set of tools.

```bash
pip install "smolagents[toolkit]"
```

2. Create and run an agent

   Define a model, build a CodeAgent with a web search tool, and call run() with your task.

```python
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?")
```

3. Use a different model provider

   smolagents is LLM-agnostic. For example, route to a model through LiteLLM.

```python
from smolagents import LiteLLMModel

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

4. Run from the CLI

   Use the smolagent command to run a multi-step CodeAgent from your terminal.

```bash
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
```

## 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