# Smolagents — Lightweight Agent Framework by HuggingFace

> Minimalist Python agent framework by HuggingFace. Build agents with tool use in under 30 lines of code. Supports code-based agents that write and execute Python instead of JSON tool calls. 15,000+ stars.

## Install

Save as a script file and run:

## Quick Use

```bash
pip install smolagents
```

```python
from smolagents import CodeAgent, tool, LiteLLMModel

@tool
def get_weather(city: str) -> str:
    \"\"\"Get current weather for a city.\"\"\"
    return f"Weather in {city}: 22C, sunny"

model = LiteLLMModel(model_id="anthropic/claude-sonnet-4-20250514")
agent = CodeAgent(tools=[get_weather], model=model)
agent.run("What is the weather in Tokyo?")
```

That is it — a working agent in 10 lines.

---

## Intro

Smolagents is a minimalist Python agent framework by HuggingFace with 15,000+ GitHub stars. Instead of complex chains and verbose configurations, build agents with tool use in under 30 lines of code. Its unique Code Agent mode lets the LLM write and execute Python code directly — no JSON tool calling overhead, just natural code generation. Best for developers who want the simplest possible path to a working agent. Works with: Claude, GPT-4, any model via LiteLLM, HuggingFace models. Setup time: under 1 minute.

---

## Two Agent Modes

### Code Agent (Recommended)
The LLM writes Python code to use tools:

```python
from smolagents import CodeAgent, tool, LiteLLMModel

@tool
def search_web(query: str) -> str:
    'Search the web and return results.'
    import requests
    return requests.get(f"https://api.tavily.com/search?q={query}").text

agent = CodeAgent(tools=[search_web], model=LiteLLMModel("anthropic/claude-sonnet-4-20250514"))
result = agent.run("Find the latest news about AI agents")
```

The agent generates Python like:
```python
results = search_web("latest AI agent news 2026")
print(results)
```

### Tool Calling Agent
Traditional JSON-based tool calls:

```python
from smolagents import ToolCallingAgent

agent = ToolCallingAgent(tools=[search_web], model=model)
```

### Why Code Agent is Better

| Aspect | Code Agent | Tool Calling |
|--------|-----------|-------------|
| Flexibility | Write any Python logic | Limited to tool schemas |
| Composability | Chain tools with code | Sequential only |
| Data processing | Manipulate results directly | Need extra tools |
| Debugging | Read the generated code | Parse JSON traces |

### Custom Tools

```python
from smolagents import tool

@tool
def calculate_roi(investment: float, returns: float) -> str:
    'Calculate return on investment percentage.'
    roi = ((returns - investment) / investment) * 100
    return f"ROI: {roi:.1f}%"

@tool
def query_database(sql: str) -> str:
    'Execute SQL query and return results.'
    import sqlite3
    conn = sqlite3.connect("data.db")
    result = conn.execute(sql).fetchall()
    return str(result)
```

### Multi-Step Agents

```python
from smolagents import CodeAgent, ManagedAgent

# Create specialist agents
researcher = CodeAgent(tools=[search_web], model=model)
writer = CodeAgent(tools=[], model=model)

# Orchestrate with a manager
managed_researcher = ManagedAgent(agent=researcher, name="researcher")
manager = CodeAgent(tools=[], model=model, managed_agents=[managed_researcher])
manager.run("Research AI trends and write a summary")
```

### HuggingFace Hub Integration

```python
from smolagents import load_tool

# Load tools from HuggingFace Hub
image_gen = load_tool("image-generation", model="black-forest-labs/FLUX.1-schnell")
speech = load_tool("text-to-speech")

agent = CodeAgent(tools=[image_gen, speech], model=model)
```

### Key Stats
- 15,000+ GitHub stars
- By HuggingFace
- 10-line agent setup
- Code Agent mode (unique)
- HuggingFace Hub integration

### FAQ

**Q: What is Smolagents?**
A: A minimalist Python agent framework by HuggingFace where you build agents with tool use in under 30 lines of code, featuring a unique Code Agent mode.

**Q: Is Smolagents free?**
A: Yes, open-source under Apache 2.0 license.

**Q: How is Smolagents different from LangChain?**
A: Smolagents is deliberately minimal — 10 lines to a working agent vs 50+ in LangChain. Its Code Agent mode writes Python directly instead of using JSON tool calls.

---

## Source & Thanks

> Created by [HuggingFace](https://github.com/huggingface). Licensed under Apache 2.0.
>
> [smolagents](https://github.com/huggingface/smolagents) — ⭐ 15,000+

Thanks to HuggingFace for proving agents do not need to be complicated.

---

<!-- ZH -->

## 快速使用

```bash
pip install smolagents
```

```python
from smolagents import CodeAgent, tool, LiteLLMModel

@tool
def get_weather(city: str) -> str:
    '获取城市天气'
    return f"{city}: 22°C, 晴"

agent = CodeAgent(tools=[get_weather], model=LiteLLMModel("anthropic/claude-sonnet-4-20250514"))
agent.run("东京天气怎么样?")
```

---

## 简介

Smolagents 是 HuggingFace 推出的极简 Python Agent 框架，GitHub 15,000+ stars。不到 30 行代码构建完整 Agent。独特的 Code Agent 模式让 LLM 直接写 Python 代码调用工具。适合需要最简路径构建 Agent 的开发者。

---

## 来源与感谢

> Created by [HuggingFace](https://github.com/huggingface). Licensed under Apache 2.0.
>
> [smolagents](https://github.com/huggingface/smolagents) — ⭐ 15,000+

---
Source: https://tokrepo.com/en/workflows/c3ffefc8-dda1-4723-896e-d5c1b8422b41
Author: Agent Toolkit