smolagents - Agentes de IA Orientados a Código

smolagents - Agentes de IA Orientados a Código

smolagents es una librería minimalista orientada a código de Hugging Face. Su idea central: en lugar de hacer que el modelo emita llamadas a herramientas como blobs JSON, un CodeAgent escribe y ejecuta código Python directamente. Expresar acciones como código permite que un paso único llame a múltiples herramientas, use bucles y variables, y encadene lógica — lo cual reduce el número de viajes de ida y vuelta a LLM (aproximadamente ~30% menos) y mejora el rendimiento en tareas complejas. Es agnóstico de modelo, soporta ejecución en sandbox, y deliberadamente se mantiene pequeño y modificable.

Installation

Método	Comando
pip	pip install smolagents
Con extras de herramientas	pip install "smolagents[toolkit]"
Extras de sandbox	pip install "smolagents[e2b]" (o [docker])
Establece una clave de modelo	export HF_TOKEN=... o claves de proveedor
Verificar	python -c "import smolagents; print('ok')"

Core Concepts

Término	Significado
CodeAgent	Agente que escribe acciones Python (el predeterminado)
ToolCallingAgent	Agente que emite llamadas a herramientas JSON clásicas
Herramienta	Una herramienta llamable que el agente puede usar (con un esquema)
Modelo	El backend de LLM (HF, OpenAI, LiteLLM, local)
Sandbox	Dónde se ejecuta código generado (local, E2B, Docker, Modal)

A Minimal CodeAgent

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	Rol
CodeAgent(tools=[...], model=...)	El agente
agent.run("task")	Ejecuta una tarea de extremo a extremo
WebSearchTool()	Una herramienta integrada
InferenceClientModel()	Backend de modelo hospedado en HF

Models

Backend	Clase
HF Inference API	InferenceClientModel
Transformadores locales	TransformersModel
Cualquier proveedor vía LiteLLM	LiteLLMModel(model_id="openai/gpt-4o")
Servidor compatible con OpenAI	OpenAIServerModel(...)
vLLM / puntos finales locales	vía LiteLLM / compatible con OpenAI

Defining Tools

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
Decorador @tool	Convierte una función tipada en una herramienta
Subclase Tool	Más control sobre esquema/comportamiento
Colecciones de herramientas	Importa conjuntos de herramientas (p. ej. desde el Hub)
Herramientas MCP	Conecta servidores Model Context Protocol

Sandboxed Execution (Important)

Porque CodeAgents ejecutan Python generado, aísla en producción.

Sandbox	Cómo
Local (predeterminado)	Ejecuta en proceso — bien solo para desarrollo confiable
E2B	executor_type="e2b" (sandbox remoto)
Docker	executor_type="docker"
Modal	Ejecución sandboxeada remota
Importaciones permitidas	Restringe qué módulos puede importar código generado

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

Multi-Agent & Retrieval

Patrón	Cómo
Agentes gestionados	Dale a un agente otros agentes como herramientas
Recuperación/RAG	Añade una herramienta retriever para respuestas fundamentadas
Planificación	Habilita pasos de planificación periódica para tareas difíciles
Handoffs	Compone especialistas bajo un agente gestor

Common Workflows

# Un agente de investigación que navega y computa en 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 Other Agent Frameworks

Aspecto	smolagents	LangGraph	Pydantic AI
Formato de acción	Código Python	Gráfico/máquina de estados	Llamadas a herramientas tipadas
Tamaño/filosofía	Minimalista, modificable	Orquestación de estado completo	Type-safe, estilo FastAPI
Eficiencia de LLM	Menos llamadas (código)	Depende	Estándar
Mejor para	Bucles de código de agente único	Agentes duraderos con estado	Agentes de producción type-safe

Resources

• GitHub Repository
• Official Documentation
• Guided Tour