smolagents - Cheatsheet de Agentes de IA Code-First

smolagents - Cheatsheet de Agentes de IA Code-First

smolagents é uma biblioteca minimalista de agentes code-first do Hugging Face. Sua ideia central: em vez de o modelo emitir chamadas de ferramenta como blobs JSON, um CodeAgent escreve e executa código Python diretamente. Expressar ações como código permite que um único passo chame múltiplas ferramentas, use loops e variáveis, e encadeie lógica — o que reduz o número de round-trips LLM (aproximadamente ~30% menos) e melhora o desempenho em tarefas complexas. É agnóstico ao modelo, suporta execução em sandbox e permanece deliberadamente pequeno e hackeável.

Instalação

Method	Command
pip	pip install smolagents
Com tools extras	pip install "smolagents[toolkit]"
Sandbox extras	pip install "smolagents[e2b]" (ou [docker])
Defina uma chave de modelo	export HF_TOKEN=... ou chaves do provider
Verificar	python -c "import smolagents; print('ok')"

Conceitos Principais

Termo	Significado
CodeAgent	Agente que escreve ações em Python (o padrão)
ToolCallingAgent	Agente que emite chamadas de ferramenta JSON clássicas
Tool	Uma callable que o agente pode usar (com um schema)
Model	O backend LLM (HF, OpenAI, LiteLLM, local)
Sandbox	Onde o código gerado é executado (local, E2B, Docker, Modal)

Um CodeAgent Minimalista

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

agent = CodeAgent(
    tools=[WebSearchTool()],
    model=InferenceClientModel(),   # HF Inference API
)

agent.run("How many seconds would it take a cheetah to cross the Golden Gate Bridge?")

Objeto	Papel
CodeAgent(tools=[...], model=...)	O agente
agent.run("task")	Execute uma tarefa de ponta a ponta
WebSearchTool()	Uma ferramenta built-in
InferenceClientModel()	Backend de modelo hospedado em HF

Modelos

Backend	Class
HF Inference API	InferenceClientModel
Local transformers	TransformersModel
Qualquer provider via LiteLLM	LiteLLMModel(model_id="openai/gpt-4o")
Servidor compatível com OpenAI	OpenAIServerModel(...)
vLLM / endpoints locais	via LiteLLM / compatível com OpenAI

Definindo Ferramentas

from smolagents import tool

@tool
def get_weather(city: str) -> str:
    """Return the weather for a city.

    Args:
        city: The city to look up.
    """
    return f"Sunny in {city}"

agent = CodeAgent(tools=[get_weather], model=InferenceClientModel())

Mecanismo	Uso
@tool decorator	Transforme uma função tipada em uma ferramenta
Tool subclass	Mais controle sobre schema/comportamento
Tool Collections	Importe conjuntos de ferramentas (ex. do Hub)
MCP tools	Conecte servidores Model Context Protocol

Execução em Sandbox (Importante)

Como CodeAgents executam Python gerado, isole-o em produção.

Sandbox	Como
Local (padrão)	Executa in-process — bom apenas para dev confiável
E2B	executor_type="e2b" (sandbox remoto)
Docker	executor_type="docker"
Modal	Execução remota em sandbox
Allowed imports	Restrinja quais módulos o código gerado pode importar

agent = CodeAgent(tools=[...], model=..., executor_type="e2b")

Multi-Agent & Retrieval

Padrão	Como
Managed agents	Dê a um agente outros agentes como ferramentas
Retrieval/RAG	Adicione uma ferramenta retriever para respostas fundamentadas
Planning	Ative passos de planejamento periódicos para tarefas difíceis
Handoffs	Componha especialistas sob um agente gerenciador

Fluxos de Trabalho Comuns

# Um agente de pesquisa que navega e computa em código
from smolagents import CodeAgent, WebSearchTool, InferenceClientModel
agent = CodeAgent(tools=[WebSearchTool()], model=InferenceClientModel(),
                  executor_type="docker")
agent.run("Compare the population growth of Tokyo and Delhi since 2000.")

smolagents vs Outros Frameworks de Agente

Aspecto	smolagents	LangGraph	Pydantic AI
Action format	Código Python	Graph/state machine	Chamadas de ferramenta tipadas
Size/philosophy	Minimalista, hackeável	Orquestração completa de estado	Type-safe, estilo FastAPI
LLM efficiency	Menos chamadas (código)	Depende	Padrão
Melhor para	Loops de código de agente único	Agentes com estado durável	Agentes de produção type-safe

Recursos

• GitHub Repository
• Official Documentation
• Guided Tour