huggingface-smolagents-2

name	huggingface-smolagents-2
description	smolagents v2: lightweight Hugging Face agent framework for building LLMs with tool use, code execution, and multi-agent workflows.
version	1.0.0
author	Hugging Face
license	Apache 2.0
dependencies	["smolagents","transformers","torch"]
platforms	["linux","macos","windows"]
metadata	{"hermes":{"tags":["smolagents","HuggingFace","Agents","ToolUse","CodeAgents","MultiAgent","LLMs","AI","Reasoning"]}}

smolagents v2 — Hugging Face Agent Framework

Overview

smolagents is a lightweight agent framework from Hugging Face (27K+ GitHub stars, Apache 2.0). It enables building AI agents that can:

• Use tools (function calling / tool use)
• Execute code (Python or JavaScript code agents)
• Chain multiple agents for complex workflows

smol = small + simple + smooth — designed to be minimal, fast, and easy to extend.

---

Quick Start

Installation

pip install smolagents

Basic Agent with Tool Use

from smolagents import HfApiModel, ReactAgent

# Use Hugging Face Inference API
model = HfApiModel(model_id="meta-llama/Llama-3-8B-Instruct")

# Initialize agent with tools
agent = ReactAgent(
    model=model,
    tools=[calculator, search_tool]  # Add your tools
)

# Run agent
result = agent.run("What is 42 squared plus 7?")

Code Agent Example

from smolagents import CodeAgent, HfApiModel

agent = CodeAgent(
    model=HfApiModel(model_id="meta-llama/Llama-3-8B-Instruct"),
    additional_authorized_imports=["requests", "json"]
)

agent.run("Fetch the current weather for Tokyo using a free API")

---

Core Concepts

1. Models

smolagents supports multiple model backends:

from smolagents import HfApiModel, LocalModel, LiteLLMModel

# Hugging Face Inference API
model = HfApiModel(model_id="Qwen/Qwen2.5-72B-Instruct")

# Local model (transformers)
model = LocalModel(model_id="meta-llama/Llama-3-8B-Instruct")

# LiteLLM (unified API for 100+ LLMs)
model = LiteLLMModel(model_id="anthropic/claude-3-5-sonnet")

2. Agents

Agent Type	Use Case
ReactAgent	Reasoning + tool use (ReAct pattern)
CodeAgent	Python code generation + execution
JsonAgent	Structured JSON output
MultiAgent	Hierarchical agent orchestration

from smolagents import ReactAgent, CodeAgent, MultiAgent

# React Agent (tool use)
agent = ReactAgent(model=model, tools=[...])

# Code Agent (write + run Python)
agent = CodeAgent(model=model, tools=[...], additional_authorized_imports=["math", "json"])

# Multi-Agent (hierarchical)
sub_agent = ReactAgent(model=model, tools=[research_tool])
orchestrator = MultiAgent(agents=[sub_agent])

3. Tools

smolagents provides built-in tools and supports custom tools:

from smolagents import tool, DuckDuckGoSearchTool, CalculatorTool

# Built-in tools
search = DuckDuckGoSearchTool()
calculator = CalculatorTool()

# Custom tool
@tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    # Your implementation
    return f"Weather in {city}: 72°F, sunny"

# Use in agent
agent = ReactAgent(model=model, tools=[search, calculator, get_weather])

4. Tool Router

The ToolRouter automatically selects appropriate tools for each task:

from smolagents import ToolRouter

router = ToolRouter(tools=[search, calculator, file_reader])
selected = router.get_tools_for_task("Calculate the square root of 144")

---

Common Workflows

Workflow 1: Research Assistant

User Query → ReactAgent → [Web Search] → [Calculator] → Final Answer

agent = ReactAgent(
    model=model,
    tools=[DuckDuckGoSearchTool(), CalculatorTool()]
)
agent.run("Research the population density of Tokyo and compare it to New York City")

Workflow 2: Data Analysis Pipeline

from smolagents import CodeAgent

agent = CodeAgent(
    model=model,
    tools=[FileReader(), FileWriter()],
    additional_authorized_imports=["pandas", "matplotlib", "json"]
)

agent.run("""
1. Read the CSV file at 'sales_data.csv'
2. Calculate monthly totals
3. Create a line chart showing the trend
4. Save the chart as 'monthly_sales.png'
""")

Workflow 3: Multi-Agent Research System

from smolagents import MultiAgent, ReactAgent, HfApiModel

# Sub-agents
web_searcher = ReactAgent(
    model=model,
    tools=[DuckDuckGoSearchTool()],
    name="web_searcher"
)

data_analyzer = CodeAgent(
    model=model,
    tools=[],
    additional_authorized_imports=["pandas", "numpy"]
)

# Orchestrator
orchestrator = MultiAgent(
    agents=[web_searcher, data_analyzer]
)

orchestrator.run("""
1. Search for the latest developments in AI research
2. Analyze the trends and create a summary report
""")

---

Tool Development

Creating a Custom Tool

from smolagents import tool

@tool
def query_database(query: str) -> str:
    """
    Execute a read-only SQL query against the analytics database.
    
    Args:
        query: A SELECT statement (no INSERT/UPDATE/DELETE)
    
    Returns:
        JSON string with query results
    """
    import json
    # Your database logic here
    results = [{"column": "value"}]
    return json.dumps(results)

Tool Best Practices

1. Clear docstrings — Describe inputs, outputs, and edge cases
2. Type hints — Help the agent understand expected types
3. Error handling — Return meaningful error messages
4. Idempotency — Safe to retry

---

Production Deployment

Serving with Hugging Face Spaces

# Create app.py
from smolagents import ReactAgent, HfApiModel
import gradio as gr

agent = ReactAgent(model=HfApiModel(model_id="meta-llama/Llama-3-8B-Instruct"))

demo = gr.ChatInterface(
    fn=lambda msg: agent.run(msg),
    title="Research Assistant"
)
demo.launch()

Integration with HF Ecosystem

from smolagents import ReactAgent
from huggingface_hub import list_models

# Use HF Hub directly in tools
@tool
def find_models(task: str) -> str:
    """Find models on Hugging Face Hub for a specific task."""
    models = list_models(filter=task, sort="downloads", direction=-1, limit=5)
    return "\n".join([f"- {m.id}: {m.downloads} downloads" for m in models])

agent = ReactAgent(model=model, tools=[find_models])

---

Key Differences: smolagents v1 vs v2

Feature	v1	v2
Code Agent	❌	✅ Native
Multi-Agent	Basic	✅ Hierarchical
Tool Router	Manual	✅ Auto
Streaming	Limited	✅ Full
MCP Integration	❌	✅

---

Troubleshooting

"Model not found"

# Use correct model ID
model = HfApiModel(model_id="meta-llama/Llama-3-8B-Instruct")  # Not just "llama-3"

"Import not authorized"

# Add to allowed imports for CodeAgent
CodeAgent(
    model=model,
    additional_authorized_imports=["requests", "beautifulsoup4"]
)

"Tool execution failed"

• Check tool docstrings match expected input format
• Verify API keys are set for external services
• Enable debug mode: agent = ReactAgent(model=model, tools=[...], debug=True)

---

Resources

• GitHub: https://github.com/huggingface/smolagents
• Documentation: https://huggingface.co/docs/smolagents
• Spaces: https://huggingface.co/spaces/smolagents/ml-intern
• License: Apache 2.0