smolagents es la biblioteca de agentes de Hugging Face, y su idea central es sencilla: un agente razona mejor cuando escribe sus acciones como código Python en lugar de rellenar objetos JSON. Con menos de mil líneas de lógica y compatibilidad con casi cualquier modelo, es de las formas más rápidas de montar un agente que de verdad hace cosas. Esta guía explica qué es, cómo funciona su CodeAgent y cuándo elegirla frente a un framework más grande. La misma explicación está disponible en inglés.

Puntos clave

  • smolagents es una biblioteca de código abierto (licencia Apache-2.0) cuya lógica de agente cabe en menos de mil líneas; su versión 1.26.0 se publicó el 29 de mayo de 2026.
  • Su CodeAgent escribe las acciones como código Python ejecutable, lo que según Hugging Face reduce alrededor de un 30% los pasos (y, por tanto, las llamadas al modelo) frente al tool calling basado en JSON.
  • Es agnóstica respecto al modelo: funciona con la API de inferencia de Hugging Face, con OpenAI o Anthropic vía LiteLLM y con modelos que ejecutas en tu propio equipo mediante Transformers u Ollama.
  • Las herramientas pueden venir de un decorador @tool, de LangChain, de un servidor MCP o de un Space del Hub.
  • Para ejecutar el código generado de forma segura ofrece entornos aislados con E2B, Docker, Modal o Blaxel.

¿Qué es smolagents?

smolagents es una biblioteca de Python creada por Hugging Face para construir y ejecutar agentes de IA con muy poco código. El equipo la define como «una biblioteca minimalista para agentes que piensan en código», y esa frase resume su filosofía: mantener las abstracciones al mínimo por encima del código en crudo. El núcleo del agente ocupa menos de mil líneas en un solo archivo, frente a las capas de clases de otros frameworks.

El proyecto es abierto (Apache-2.0), supera las 28.000 estrellas en GitHub y avanza rápido: la versión 1.26.0 es del 29 de mayo de 2026. No es un producto cerrado ni un servicio de pago, sino una dependencia que instalas y controlas por completo. Si vienes de haber montado el bucle de un agente a mano, como en el tutorial del SDK de Anthropic, smolagents te ahorra ese trabajo repetitivo sin esconderte lo que ocurre por dentro.

Instalarla es una línea:

pip install 'smolagents[toolkit]'

El extra toolkit añade herramientas por defecto, como una de búsqueda web. A partir de ahí, todo gira en torno a dos tipos de agente y a la libertad de elegir el modelo.

Agentes que escriben código (CodeAgent)

El elemento distintivo de smolagents es el CodeAgent. En cada paso del bucle razonar-actuar-observar, el modelo no devuelve un JSON con el nombre de una herramienta y sus argumentos, sino un bloque de código Python. Ese bloque se ejecuta y su resultado vuelve al modelo como la siguiente observación. Llamar a una herramienta es, simplemente, invocar una función de Python.

La ventaja es la componibilidad. En código puedes anidar llamadas, usar bucles y condicionales, guardar un resultado en una variable y reutilizarlo, todo en una sola acción. Con JSON necesitarías un paso y una llamada al modelo por cada operación. Hugging Face sostiene que este enfoque da alrededor de un 30% menos de pasos y mejor rendimiento en las tareas difíciles, una idea que procede del artículo «Executable Code Actions Elicit Better LLM Agents» (CodeAct), que midió hasta un 20% más de tasa de éxito al actuar con código en lugar de con texto estructurado.

Si prefieres el paradigma clásico, existe también ToolCallingAgent, que usa el tool calling en JSON de toda la vida. Conviene cuando el modelo tiene un soporte de function calling muy afinado o cuando tus herramientas son sencillas y no necesitas encadenarlas.

Herramientas y modelos (locales o API)

smolagents es agnóstica respecto al modelo: no te ata a ningún proveedor. Eliges la clase de modelo según dónde quieras ejecutar la inferencia.

  • InferenceClientModel: usa los proveedores de inferencia del Hub de Hugging Face. Es la opción por defecto del inicio rápido.
  • LiteLLMModel: conecta con OpenAI, Anthropic, Gemini y más de cien proveedores a través de LiteLLM. También sirve para Ollama con model_id="ollama_chat/llama3.2".
  • TransformersModel: carga un modelo abierto y lo ejecuta en tu propia máquina con la biblioteca transformers.
  • OpenAIServerModel: apunta a cualquier endpoint compatible con la API de OpenAI, incluido un servidor local.

Para un modelo que corras con Ollama en tu propio equipo, basta con apuntar LiteLLMModel u OpenAIServerModel a http://localhost:11434. Las herramientas son igual de flexibles: defines una función y le pones el decorador @tool, o importas una colección desde un servidor MCP con ToolCollection.from_mcp, desde LangChain o desde un Space del Hub.

Un ejemplo mínimo

Este es un agente completo. Crea un CodeAgent con una herramienta de búsqueda web y le pides una tarea; el agente escribirá y ejecutará el Python necesario para resolverla:

from smolagents import CodeAgent, InferenceClientModel, DuckDuckGoSearchTool

model = InferenceClientModel()  # modelo por defecto del Hub
agent = CodeAgent(tools=[DuckDuckGoSearchTool()], model=model)

resultado = agent.run(
    "Busca la altura del Teide y dime cuántas veces cabe en el Everest."
)
print(resultado)

El agente decidirá por su cuenta buscar la altura de ambas montañas, hará la división en Python y devolverá el número. Definir tu propia herramienta es igual de directo:

from smolagents import tool

@tool
def precio_con_iva(precio: float, tipo: float = 21.0) -> float:
    """Calcula el precio final con IVA.

    Args:
        precio: precio base en euros.
        tipo: porcentaje de IVA, 21 por defecto.
    """
    return round(precio * (1 + tipo / 100), 2)

Le pasas la función en la lista tools y el agente ya puede llamarla dentro de su código.

smolagents frente a frameworks más grandes

La pregunta habitual es cuándo elegir smolagents en lugar de LangGraph, LlamaIndex o el Agents SDK de OpenAI. La respuesta corta: smolagents brilla cuando quieres un agente que actúa escribiendo código y prefieres poca ceremonia. Al ocupar tan poco, es fácil de leer entero y de depurar; no hay grafos de estado ni capas de orquestación que aprender.

Los frameworks más grandes ganan cuando necesitas flujos de trabajo con estado explícito, ramas condicionales complejas, persistencia de larga duración o sistemas multiagente muy estructurados. smolagents también hace multiagente (un agente puede gestionar a otros), pero su terreno natural son los agentes autónomos que resuelven una tarea razonando con código. Para el código generado, recuerda ejecutarlo siempre en un entorno aislado, nunca directamente en tu servidor.

Preguntas frecuentes

¿Por qué un agente escribe código en vez de JSON?

Porque el código es más expresivo. En un solo bloque puede encadenar varias herramientas, usar bucles y guardar resultados intermedios en variables, algo que en JSON exigiría un paso y una llamada al modelo por operación. Según Hugging Face, actuar con código reduce alrededor de un 30% los pasos y mejora los resultados en tareas complejas.

¿Necesito una clave de API de pago para usar smolagents?

No necesariamente. Con InferenceClientModel usas la inferencia gratuita del Hub dentro de sus límites, y con TransformersModel u Ollama ejecutas un modelo abierto en tu propio equipo sin coste por token. Las clases LiteLLMModel y OpenAIServerModel te dejan pasar a un proveedor de pago cuando lo necesites.

¿Es seguro que un agente ejecute el código que genera?

Solo si lo aíslas. smolagents integra entornos de ejecución seguros con E2B, Docker, Modal o Blaxel precisamente para eso. Ejecutar el código generado directamente en tu máquina es arriesgado; usa siempre un sandbox en cualquier despliegue real.

Conclusión

smolagents apuesta por una idea concreta: un agente rinde mejor cuando expresa sus acciones como código Python. Esa decisión, sumada a un núcleo de menos de mil líneas y a la compatibilidad con cualquier modelo, la convierte en una puerta de entrada muy práctica al desarrollo de agentes. Empieza por el CodeAgent del ejemplo, dale una herramienta útil y, cuando pases a producción, envuelve la ejecución en un sandbox. Si quieres respaldarlo con un modelo abierto, el siguiente paso natural es aprender a instalar Ollama en tu propio equipo.

Fuentes: [1] Documentación de smolagents[1], [2] smolagents en GitHub[2], [3] Introducing smolagents (blog de Hugging Face)[3], [4] Executable Code Actions Elicit Better LLM Agents[4].

Visitas: 0

Fuentes

  1. Documentación de smolagents
  2. smolagents en GitHub
  3. Introducing smolagents (blog de Hugging Face)
  4. Executable Code Actions Elicit Better LLM Agents

Ruta: Frameworks para construir agentes de IA