# Smolagents: Guia Definitivo — Agentes Minimalistas da HuggingFace

> Domine o smolagents — a biblioteca code-first da HuggingFace com menos de 1000 linhas que transforma LLMs em agentes que escrevem e executam Python....

Source: https://agentify.ia.br/blog/smolagents/

> **TL;DR** — Smolagents é a biblioteca open-source da HuggingFace (Apache 2.0, v1.26) que comprime toda a lógica de agentes IA em ~1000 linhas de código. O diferencial radical: em vez de chamadas de ferramenta via JSON (o padrão da indústria), o agente escreve e executa Python diretamente. Isso reduz steps em ~30%, elimina camadas de abstração e transforma qualquer LLM — local ou cloud — num agente funcional em 5 linhas de código. Suporta CodeAgent (code-first), ToolCallingAgent (JSON clássico), multi-agente hierárquico, MCP, execução sandboxed (E2B/Docker/Blaxel), modelos via Ollama/HF Hub/LiteLLM/OpenAI/Anthropic, e modalidades texto/visão/áudio/vídeo. É o caminho mais rápido para um single-agent loop funcional — mas não tenta ser um orquestrador enterprise. Conhece teu caso de uso, escolhe a ferramenta certa.

---

## Overview

### A filosofia “sub-1000 LOC”

Existe uma tendência incômoda no ecossistema de agentes IA: cada framework novo adiciona mais abstrações, mais classes, mais config. Você olha o LangChain e são centenas de arquivos. Olha o CrewAI e são dezenas de conceitos antes de rodar qualquer coisa. São ótimos frameworks — mas nem todo problema precisa dessa artilharia pesada.

O smolagents nasce de uma premissa oposta: o que é o *mínimo* necessário para transformar um LLM num agente funcional?

A resposta da HuggingFace cabe em ~1000 linhas no arquivo `agents.py`. Sem mágica. Sem metaclasses ocultas. Sem grafo de estados implícito. Você lê o código-fonte inteiro num café da tarde e entende exatamente o que acontece quando seu agente roda. Essa transparência não é acidental — é a proposta de valor central.

Mas “minimalista” não significa “brinquedo”. O smolagents conquistou posição no topo do leaderboard GAIA (benchmark referência para agentes gerais), suporta qualquer LLM que você consiga imaginar, integra com MCP servers, roda multi-agente hierárquico, e te dá sandbox de segurança para execução de código. Tudo isso — em ~1000 linhas de abstração sobre Python puro.

### Code-first: o paradigma que muda tudo

Aqui está a sacada que diferencia o smolagents de praticamente todo o resto do mercado:

**Em vez de chamar ferramentas via JSON, o agente escreve e executa código Python diretamente.**

Parece sutil, mas as consequências são enormes. Quando um agente tradicional quer fazer algo complexo — digamos, buscar dados de uma API, filtrar resultados e calcular uma média — ele precisa fazer três tool calls separadas, cada uma gerando JSON, parseando resposta, e alimentando a próxima. São 3 steps no loop, 3 rodadas de inferência do LLM.

Com o smolagents, o mesmo agente escreve:

```
results = search_api("quarterly revenue 2025")
filtered = [r for r in results if r["region"] == "LATAM"]
average = sum(r["value"] for r in filtered) / len(filtered)
final_answer(f"Média LATAM: {average}")
```

Um step. Uma inferência. O Python faz o resto. É por isso que benchmarks mostram ~30% menos steps comparado com tool-calling tradicional — o código é intrinsecamente composável de um jeito que JSON não é.

Essa composabilidade é o que frameworks maiores tentam resolver com chains, grafos e pipelines. O smolagents resolve com… Python. A linguagem que você já sabe.

### Onde se encaixa no ecossistema

Para ser direto sobre posicionamento:

- **LangGraph** → Controle total, state machines explícitas, grafos complexos. Para quem precisa de cada aresta definida.

- **CrewAI** → Equipes role-based, delegação automática, produção enterprise. Para quem tem múltiplos agentes colaborando.

- **OpenAI Agents SDK** → Handoffs nativos, guardrails built-in, tracing. Para quem vive no ecossistema OpenAI.

- **Smolagents** → Minimalismo radical, code-first, modelo-agnóstico. Para quem quer o caminho mais curto entre “ideia” e “agente rodando”.

Se você quer entender essa paisagem em profundidade, temos um [comparativo completo de frameworks vs coding agents](/blog/agent-frameworks-vs-coding-agents) que detalha cada trade-off.

---

## Tutorial: seu primeiro agente em 5 minutos

### Instalação

```
# Instalação base
pip install smolagents

# Com ferramentas padrão (DuckDuckGo search, code interpreter)
pip install "smolagents[toolkit]"

# All-in-one (MCP, Gradio UI, telemetria, visão, áudio)
pip install "smolagents[all]"
```

Requisitos: Python ≥ 3.10. Só isso. Sem Docker obrigatório, sem serviço background, sem config YAML.

### Hello Agent — 5 linhas

```
from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

model = InferenceClientModel() # usa modelo padrão do HF Hub
agent = CodeAgent(tools=[WebSearchTool()], model=model)

agent.run("Qual a população atual do Brasil?")
```

É isso. Sério. O agente vai:

- Receber a task

- Decidir usar a ferramenta de busca web

- Escrever código Python chamando `web_search(...)`

- Executar o código

- Analisar o resultado

- Chamar `final_answer(...)` com a resposta

Cada step é visível no terminal com logs formatados mostrando o código gerado e o output da execução.

### Usando modelos locais com Ollama

```
from smolagents import CodeAgent, WebSearchTool, LiteLLMModel

model = LiteLLMModel(
 model_id="ollama/llama3.1:8b",
 api_base="http://localhost:11434"
)

agent = CodeAgent(tools=[WebSearchTool()], model=model)
agent.run("Resuma as últimas notícias sobre IA no Brasil")
```

Zero API keys. Zero custo. Tudo local. O smolagents não te prende a nenhum provider — se roda via API compatível com OpenAI, roda no smolagents.

### Usando a CLI

Se você nem quer abrir um editor:

```
smolagent "Planeje uma viagem de 5 dias para Portugal" \
--model-type "InferenceClientModel" \
--model-id "Qwen/Qwen2.5-Coder-32B-Instruct" \
--tools "web_search"
```

Ou no modo interativo (te guia pelos argumentos):

```
smolagent
```

### Interface visual com Gradio

```
from smolagents import CodeAgent, InferenceClientModel, GradioUI

agent = CodeAgent(tools=[], model=InferenceClientModel(), add_base_tools=True)
GradioUI(agent).launch()
```

Abre um chat no browser onde você vê o raciocínio do agente passo a passo — inclusive o código gerado e executado em cada step. Ótimo para demos e debugging.

---

## Deep Dive

### CodeAgent — o coração do framework

O `CodeAgent` é o agente padrão e a razão de existir do smolagents. Ele segue a arquitetura ReAct (Reason + Act):

- **Thought** — o LLM raciocina sobre o próximo passo

- **Code** — gera um snippet Python como ação

- **Observation** — executa o código e observa o resultado

- Repete até chamar `final_answer()`

```
from smolagents import CodeAgent, InferenceClientModel, tool

@tool
def get_weather(city: str) -> str:
 """Retorna a previsão do tempo para uma cidade.
 Args:
 city: Nome da cidade para consultar.
 """
 # Sua lógica aqui
 return f"Ensolarado, 28°C em {city}"

agent = CodeAgent(
 tools=[get_weather],
 model=InferenceClientModel(),
 additional_authorized_imports=["requests", "json"]
)

agent.run("Qual o tempo em São Paulo e Rio? Compare os dois.")
```

O agente vai escrever algo como:

```
sp = get_weather("São Paulo")
rj = get_weather("Rio de Janeiro")
comparison = f"SP: {sp}\nRJ: {rj}"
final_answer(comparison)
```

Percebe a elegância? Composição natural. Sem intermediate steps artificiais.

**Segurança na execução:**

Por padrão, o código roda num interpretador restrito — só funções autorizadas, sem imports perigosos. Para produção, você pode usar sandboxes:

```
# Execução via E2B (sandbox cloud)
agent = CodeAgent(tools=[], model=model, executor_type="e2b")

# Execução via Docker (sandbox local)
agent = CodeAgent(tools=[], model=model, executor_type="docker")

# Execução via Blaxel
agent = CodeAgent(tools=[], model=model, executor_type="blaxel")
```

**Imports controlados:**

```
agent = CodeAgent(
 tools=[],
 model=model,
 additional_authorized_imports=["pandas", "numpy", "matplotlib.pyplot"]
)
```

Você libera só o que o agente precisa. O interpretador bloqueia qualquer outra coisa — inclusive subpacotes não explicitamente autorizados (`numpy.random` precisa ser listado separadamente de `numpy`).

### ToolCallingAgent — o modo compatível

Nem todo caso precisa de code generation. Se você quer o padrão da indústria (JSON tool calls, como OpenAI/Anthropic fazem), o smolagents te cobre:

```
from smolagents import ToolCallingAgent, WebSearchTool, InferenceClientModel

agent = ToolCallingAgent(
 tools=[WebSearchTool()],
 model=InferenceClientModel()
)

agent.run("Quem é o CEO da HuggingFace?")
```

O agente gera JSON estruturado em vez de código:

```
{
 "tool_call": {
 "name": "web_search",
 "arguments": {"query": "CEO HuggingFace 2026"}
 }
}
```

**Quando usar ToolCallingAgent em vez de CodeAgent:**

- Ferramentas atômicas e simples (chama API, retorna dado)

- Alta confiabilidade necessária (JSON é validável por schema)

- Ambientes onde execução de código é inaceitável (compliance, segurança)

- Modelos que performam melhor com tool calling nativo (GPT-4, Claude)

**Quando usar CodeAgent:**

- Tasks que exigem composição, loops, transformação de dados

- Múltiplas ferramentas que se combinam numa mesma ação

- Quando performance (menos steps) importa

- Quando o modelo é bom em gerar código (Qwen Coder, DeepSeek, Codestral)

### Sistema de Tools — criando ferramentas

O smolagents trata ferramentas como funções Python decoradas. Sem classes base complexas, sem JSON schema manual:

```
from smolagents import tool

@tool
def calculate_roi(investment: float, revenue: float) -> str:
 """Calcula o ROI de um investimento.
 Args:
 investment: Valor investido em reais.
 revenue: Receita gerada em reais.
 """
 roi = ((revenue - investment) / investment) *
 return f"ROI: {roi:.1f}%"
```

O decorator extrai automaticamente:

- **Nome** — da função

- **Descrição** — da docstring

- **Tipos de input** — dos type hints

- **Tipo de output** — do return type hint

- **Descrição dos args** — da seção Args: da docstring

Tudo isso vira parte do system prompt do agente — é assim que o LLM “sabe” quais ferramentas existem e como usá-las.

**Ferramentas como classe (para casos complexos):**

```
from smolagents import Tool

class DatabaseQueryTool(Tool):
 name = "query_database"
 description = "Executa uma query SQL no banco de dados da empresa."
 inputs = {
 "query": {"type": "string", "description": "Query SQL a executar"}
 }
 output_type = "string"

 def __init__(self, connection_string: str):
 super().__init__()
 self.conn = connect(connection_string)

 def forward(self, query: str) -> str:
 result = self.conn.execute(query)
 return str(result.fetchall())
```

**Ferramentas do Hub:**

```
from smolagents import load_tool

# Carrega ferramenta publicada por outro dev
image_gen = load_tool("m-ric/text-to-image", trust_remote_code=True)
```

**Ferramentas via MCP:**

Desde a integração com Model Context Protocol, qualquer MCP server vira ferramenta do smolagents:

```
# pip install "smolagents[mcp]"
from smolagents import CodeAgent, InferenceClientModel
from smolagents.mcp import MCPClient

mcp_client = MCPClient("npx", ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"])
tools = mcp_client.get_tools()

agent = CodeAgent(tools=tools, model=InferenceClientModel())
agent.run("Liste os arquivos no diretório e crie um resumo")
```

Com mais de 2000 MCP servers disponíveis na comunidade (bancos de dados, calendários, browsers, file systems, APIs SaaS), o ecossistema de ferramentas é praticamente ilimitado.

### Multi-agent — hierarquia de especialistas

O smolagents suporta sistemas multi-agente hierárquicos onde um agente gerente delega para agentes especializados:

```
from smolagents import CodeAgent, InferenceClientModel, WebSearchTool

model = InferenceClientModel()

# Agente especialista em pesquisa
research_agent = CodeAgent(
 tools=[WebSearchTool()],
 model=model,
 name="research_agent",
 description="Faz pesquisas web detalhadas. Passe sua pergunta como argumento."
)

# Agente especialista em código
code_agent = CodeAgent(
 tools=[],
 model=model,
 name="code_expert",
 description="Resolve problemas de programação e análise de dados.",
 additional_authorized_imports=["pandas", "numpy"]
)

# Agente gerente que orquestra os dois
manager = CodeAgent(
 tools=[],
 model=model,
 managed_agents=[research_agent, code_agent]
)

manager.run(
 "Pesquise as 10 startups brasileiras mais valiosas de 2026 "
 "e crie uma análise estatística do valuation delas"
)
```

O gerente “vê” os agentes especializados como ferramentas disponíveis. Ele decide quando chamar cada um, passa contexto relevante, e combina os resultados. Cada agente mantém sua própria memória e conjunto de ferramentas separados — exatamente como deveria ser.

Isso não é apenas multi-agente por modismo. A separação de memória é crucial: por que poluir o contexto do agente de código com todo o HTML de páginas visitadas pelo agente de pesquisa? Cada agente vê apenas o que precisa.

A HuggingFace usou exatamente essa arquitetura para [conquistar o topo do leaderboard GAIA](https://huggingface.co/blog/beating-gaia) — benchmark de referência para agentes gerais.

### Modelos abertos e locais

O smolagents é genuinamente model-agnostic. Não é marketing — é arquitetura:

```
# HuggingFace Inference Providers (12+ providers, um endpoint)
from smolagents import InferenceClientModel
model = InferenceClientModel(model_id="meta-llama/Llama-3.3-70B-Instruct")

# Ollama (local, gratuito)
from smolagents import LiteLLMModel
model = LiteLLMModel(model_id="ollama/qwen2.5-coder:14b", api_base="http://localhost:11434")

# OpenAI
from smolagents import OpenAIModel
model = OpenAIModel(model_id="gpt-4o")

# Anthropic via LiteLLM
from smolagents import LiteLLMModel
model = LiteLLMModel(model_id="anthropic/claude-4-sonnet-latest")

# Transformers local (GPU)
from smolagents import TransformersModel
model = TransformersModel(model_id="Qwen/Qwen2.5-Coder-7B-Instruct")

# MLX (Apple Silicon)
from smolagents import MLXModel
model = MLXModel(model_id="mlx-community/Qwen2.5-Coder-14B-Instruct-8bit")

# Azure OpenAI
from smolagents import AzureOpenAIModel
model = AzureOpenAIModel(model_id="gpt-4o", azure_endpoint="https://...")

# Amazon Bedrock
from smolagents import AmazonBedrockModel
model = AmazonBedrockModel(model_id="anthropic.claude-4-sonnet")
```

Para CodeAgent especificamente, modelos otimizados para código performam significativamente melhor. Os melhores resultados na prática:

- **Qwen2.5-Coder-32B-Instruct** — melhor custo-benefício open-source

- **DeepSeek-R1** — raciocínio forte, ideal para tasks complexas

- **Claude 4 Sonnet** — consistência em code generation

- **GPT-4o** — polivalente, bom em tool calling e código

Para modelos locais via Ollama, o `qwen2.5-coder:14b` é o sweet spot entre performance e requisitos de hardware (roda em 16GB RAM).

### Funcionalidades avançadas

**Validação de resposta final:**

```
def must_be_json(final_answer: str, agent_memory=None) -> bool:
 """Valida que a resposta final é JSON válido."""
 import json
 try:
 json.loads(final_answer)
 return True
 except ValueError:
 return False

agent = CodeAgent(
 tools=[],
 model=model,
 final_answer_checks=[must_be_json]
)
```

Se a validação falha, o agente continua tentando — autocorreção built-in.

**Compartilhamento via Hub:**

```
# Publicar agente
agent.push_to_hub("seu-usuario/meu-agente-pesquisador")

# Carregar agente publicado
agent = CodeAgent.from_hub("m-ric/my_agent", trust_remote_code=True)
```

**Telemetria e observabilidade:**

```
pip install "smolagents[telemetry]"
```

Integra com OpenTelemetry — conecta com Langfuse, Datadog, ou qualquer backend OTEL para tracing completo de cada step do agente.

**Async:**

```
import asyncio
from smolagents import CodeAgent, InferenceClientModel

agent = CodeAgent(tools=[], model=InferenceClientModel())
result = asyncio.run(agent.arun("Calcule 2^100"))
```

---

## Spider Chart — 8 eixos de avaliação

```
 Facilidade de Setup
 ██████████ 10/10
 │
 Extensibilidade │ Performance (steps)
 ███████ 7/10 ──────┼────── █████████ 9/10
 │
 Ecossistema/ │ Segurança
 Comunidade │ Sandbox
 ██████ 6/10 ─────────────┼─────────── ████████ 8/10
 │
 Multi-agente │ Modelos Suportados
 ██████ 6/10 ────────┼──────── ██████████ 10/10
 │
 Produção/Enterprise
 ████ 4/10
```

 Eixo
 Score
 Justificativa

 Facilidade de Setup
 10/10
 5 linhas. pip install e pronto. Sem YAML, sem Docker obrigatório, sem serviço.

 Performance (steps)
 9/10
 ~30% menos steps que tool-calling. Code é composição nativa.

 Segurança/Sandbox
 8/10
 E2B, Docker, Blaxel, Pyodide. Import whitelist. Bom, mas sandbox é opt-in.

 Modelos Suportados
 10/10
 Qualquer LLM: Ollama, HF Hub (12+ providers), OpenAI, Anthropic, Azure, Bedrock, local.

 Extensibilidade
 7/10
 Tools simples de criar. MCP. Hub sharing. Mas sem plugins/middleware system.

 Multi-agente
 6/10
 Hierárquico funciona bem. Mas sem comunicação lateral, sem workflows complexos.

 Ecossistema/Comunidade
 6/10
 Documentação boa, curso oficial. Mas comunidade menor que LangChain/CrewAI.

 Produção/Enterprise
 4/10
 Sem memória persistente nativa, sem checkpointing, sem retry policies avançadas.

---

## Prós e Contras — sem marketing

### ✅ Prós

- **Curva zero.** Se sabe Python, sabe smolagents. Não tem abstração nova para aprender. A API inteira cabe numa página de docs.

- **Code-first = menos steps = mais rápido.** Benchmarks reais mostram ~30% de redução em steps comparado com tool-calling JSON. Menos inferências = menos latência = menos custo.

- **Transparência total.** São ~1000 linhas. Você consegue ler e entender *todo* o framework numa sessão. Quando algo quebra, você sabe exatamente onde olhar.

- **Verdadeiramente model-agnostic.** Não é lip service. Roda igual com Ollama local, HF Hub, OpenAI, Anthropic, Azure, Bedrock, MLX. Troca uma linha e muda o provider.

- **MCP nativo.** Integração com o ecossistema de 2000+ MCP servers sem wrappers adicionais.

- **Hub integration.** Publica e consome agentes/ferramentas do HuggingFace Hub como packages. Reutilização real de componentes.

- **Segurança pensada.** Múltiplas opções de sandbox para code execution. Import whitelist. Não te deixa rodar `os.system("rm -rf /")` sem que você explicitamente permita.

- **Multimodal.** Texto, visão, vídeo, áudio — depende do modelo, mas o framework não limita.

### ❌ Contras

- **Sem memória persistente.** Cada sessão começa do zero. Para conversas longas ou contexto entre sessões, você precisa integrar algo externo (Mem0, Redis, etc).

- **Multi-agente limitado.** Hierárquico funciona. Mas se você precisa de comunicação lateral, votação entre agentes, ou workflows tipo grafo — não é aqui.

- **Não é enterprise-ready solo.** Sem checkpointing nativo, sem retry policies sofisticadas, sem role-based access, sem audit trail. Para produção séria, vai precisar complementar.

- **Dependência da qualidade do modelo.** Code-first brilha com modelos bons em código. Com modelos fracos, os erros de sintaxe explodem e o agente pode ficar em loop de autocorreção.

- **Comunidade ainda crescendo.** Menos exemplos, menos Stack Overflow, menos blog posts que LangChain. A documentação oficial é boa mas o ecossistema de third-party é menor.

- **API experimental.** O próprio docs declara: “Smolagents is an experimental API which is subject to change at any time.” Upgrades podem quebrar código existente.

- **Segurança é opt-in.** O default roda código localmente sem sandbox. Se você esquece de configurar E2B/Docker, tá rodando code generation não-sandboxed em produção. Isso é perigoso.

---

## Quando usar Smolagents

### Use quando:

- **Prototipagem rápida** — Quer testar uma ideia de agente em minutos, não horas

- **Single-agent tasks** — Um agente resolvendo um problema bem definido

- **Code-heavy workflows** — Análise de dados, transformações, cálculos, parsing

- **Modelo local/open** — Quer rodar tudo no seu hardware sem depender de APIs cloud

- **Pesquisa e experimentação** — Testando diferentes modelos/prompts/ferramentas rapidamente

- **Ferramentas compostas** — Tasks onde chamar 3-4 ferramentas em sequência com lógica entre elas é o padrão

- **Budget limitado** — Menos steps = menos tokens = menos custo em API

### Não use quando:

- **Enterprise em produção** — Precisa de checkpointing, audit trail, compliance, retry policies robustas

- **Multi-agente complexo** — Comunicação lateral, votação, grafos de dependência entre agentes

- **Conversas longas com memória** — Chatbots que precisam lembrar de interações passadas

- **Compliance de segurança** — Ambientes onde code execution (mesmo sandboxed) é inaceitável

- **Time sem experiência Python** — Se o time não entende o código que o agente gera, não consegue debugar

### A regra prática:

> Se seu agente é um **solucionador de problemas individual** que combina ferramentas via código — smolagents é provavelmente o caminho mais curto até a solução. Se seu agente é parte de um **sistema complexo de múltiplos atores** com estado persistente e requisitos enterprise — olhe para LangGraph ou CrewAI.

Para entender como o loop interno de agentes (harness → plan → execute → observe) funciona de verdade independente do framework, vale ler nosso artigo sobre [arquitetura de harness e loops de agentes](/blog/harness-e-loop-arquitetura-agentes).

---

## Referências e recursos

- [Documentação oficial](https://huggingface.co/docs/smolagents)

- [Repositório GitHub](https://github.com/huggingface/smolagents)

- [Curso de Agentes HuggingFace (Unit 2)](https://huggingface.co/learn/agents-course/unit2/smolagents/introduction)

- [PyPI — smolagents](https://pypi.org/project/smolagents/)

- [Guided Tour oficial](https://huggingface.co/docs/smolagents/main/guided_tour)

- [Exemplo: Multi-agent web browser](https://huggingface.co/docs/smolagents/main/en/examples/multiagents)

- [Blog: Beating GAIA leaderboard](https://huggingface.co/blog/beating-gaia)

---

*Quer montar um agente code-first que realmente funciona em produção? Na [ft.ia.br](https://ft.ia.br) ajudamos equipes a implementar agentes IA — da prototipagem com smolagents até arquiteturas multi-agente escaláveis. Bora conversar.*

-->