Smolagents: Guia Definitivo — Agentes Minimalistas da HuggingFace

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

1. Receber a task
2. Decidir usar a ferramenta de busca web
3. Escrever código Python chamando web_search(...)
4. Executar o código
5. Analisar o resultado
6. 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):

1. Thought — o LLM raciocina sobre o próximo passo
2. Code — gera um snippet Python como ação
3. Observation — executa o código e observa o resultado
4. 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) * 100
    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 — 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:

1. Qwen2.5-Coder-32B-Instruct — melhor custo-benefício open-source
2. DeepSeek-R1 — raciocínio forte, ideal para tasks complexas
3. Claude 4 Sonnet — consistência em code generation
4. 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

Prós e Contras — sem marketing

✅ Prós

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

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

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

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

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

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

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

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

❌ Contras

1. 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).

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

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

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

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

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

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

Referências e recursos

• Documentação oficial
• Repositório GitHub
• Curso de Agentes HuggingFace (Unit 2)
• PyPI — smolagents
• Guided Tour oficial
• Exemplo: Multi-agent web browser
• Blog: Beating GAIA leaderboard

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