# 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 the content below to `.claude/skills/` or append to your `CLAUDE.md`:

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


## Quick Use

```bash
pip install smolagents
```

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

@tool
def get_weather(city: str) -> str:
    'Get city weather'
    return f"{city}: 22°C, clear"

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

---

## Intro

Smolagents is HuggingFace's minimalist Python agent framework, with 15,000+ GitHub stars. Build a full agent in fewer than 30 lines of code. Its signature Code Agent mode lets the LLM write Python directly to call tools. Ideal for developers who want the shortest path to building an agent.

---

## Source & Thanks

> 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/smolagents-lightweight-agent-framework-huggingface-c3ffefc8
Author: Hugging Face