Probado con smolagents 1.26.0 · LiteLLM 1.101.0 · Ollama 0.34.1 · Qwen3-4B-Instruct-2507 · Python 3.12 · verificado

Actualizado: 2026-09-16

smolagents es la biblioteca de agentes de Hugging Face, y su idea central: un agente razona mejor cuando escribe sus acciones como código Python en lugar de rellenar objetos JSON. Con su lógica de agente en un solo archivo y compatibilidad con casi cualquier modelo, es de las formas más directas 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. Ejecutamos sus ejemplos el 16 de septiembre de 2026 con smolagents 1.26.0 y un modelo local en Ollama, y tienes la misma explicación en inglés.

Puntos clave

  • smolagents es una biblioteca de código abierto (licencia Apache-2.0); su versión 1.26.0, del 29 de mayo de 2026, seguía siendo la última el 16 de septiembre 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 los proveedores 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 (motor gratuito que sirve modelos de lenguaje de código abierto en tu propio hardware, sin llamadas a una API externa).
  • 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; el intérprete local que usa por defecto no es una barrera de seguridad.
  • Con un modelo de 4.000 millones de parámetros en Ollama y sin GPU, el agente de búsqueda de esta guía acertó en 13 de 14 ejecuciones.

¿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. Su lema es «agentes que piensan en código», y su filosofía es mantener las abstracciones al mínimo por encima del código en crudo. Toda la lógica de los agentes vive en un archivo, agents.py, en lugar de repartirse en capas de clases como en otros frameworks.

La documentación dice que esa lógica cabe en unas mil líneas, pero en la versión 1.26.0 agents.py tiene 1.813. Sin líneas en blanco, comentarios ni docstrings quedan 1.288, según nuestro recuento.

El proyecto es abierto (Apache-2.0) y tenía 29.350 estrellas en GitHub el 16 de septiembre de 2026. Su última versión, la 1.26.0, retiró el ejecutor remoto basado en WebAssembly. 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, con Python 3.10 o posterior:

pip install 'smolagents[toolkit,litellm]'

El extra toolkit añade herramientas por defecto, como una de búsqueda web, y litellm es el que pide LiteLLMModel: sin él, falla con ModuleNotFoundError. OpenAIModel pide el extra openai, y los servidores MCP, mcp.

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. La idea 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 afinado o cuando tus herramientas hacen una sola cosa 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 (hay más, como las de Azure OpenAI, Amazon Bedrock, vLLM y MLX):

  • InferenceClientModel: usa los proveedores de inferencia del Hub de Hugging Face y es la opción del inicio rápido. Necesita un HF_TOKEN; en la 1.26.0 su modelo por defecto es Qwen/Qwen3-Next-80B-A3B-Thinking.
  • LiteLLMModel: conecta con OpenAI, Anthropic, Gemini y más de cien modelos y proveedores a través de LiteLLM. También sirve para Ollama con el prefijo ollama_chat/ en el nombre del modelo.
  • TransformersModel: carga un modelo abierto y lo ejecuta en tu propia máquina con la biblioteca transformers.
  • OpenAIModel: apunta a cualquier endpoint compatible con la API de OpenAI, incluido un servidor local. Sustituye a OpenAIServerModel, que sigue disponible como alias.

Para un modelo que ejecutes con Ollama en tu propio equipo, apunta LiteLLMModel a http://localhost:11434, u OpenAIModel a http://localhost:11434/v1. Con LiteLLM, fija num_ctx=8192, porque la guía de smolagents avisa de que el contexto por defecto de Ollama se queda corto. En nuestras pruebas, el segundo paso del agente ya enviaba más de 4.200 tokens. Para elegir modelo, repasa los modelos abiertos con tool calling.

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. Para MCP hay una trampa: el 16 de septiembre de 2026, el extra mcp instalaba el paquete mcp 2.2.0, y con él from_mcp falla con un ImportError. Fija la rama 1.x:

pip install 'smolagents[mcp]' 'mcp[ws]<2'

Así, en nuestra prueba, un servidor MCP local cargó sus herramientas. Pasa también trust_remote_code=True: sin él, from_mcp lanza un ValueError.

Un ejemplo mínimo

Este es un agente completo. Crea un CodeAgent con WebSearchTool, la herramienta de búsqueda del inicio rápido actual, y un modelo local. Antes, descarga en Ollama Qwen3-4B-Instruct cuantizado a Q4_K_M (2,5 GB):

ollama pull hf.co/unsloth/Qwen3-4B-Instruct-2507-GGUF:Q4_K_M

Le pides una tarea y el agente escribe y ejecuta el Python necesario para resolverla:

from smolagents import CodeAgent, LiteLLMModel, WebSearchTool

model = LiteLLMModel(
    model_id="ollama_chat/hf.co/unsloth/Qwen3-4B-Instruct-2507-GGUF:Q4_K_M",
    api_base="http://localhost:11434",
    num_ctx=8192,
)
agent = CodeAgent(tools=[WebSearchTool()], model=model)

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

Con una cuenta de Hugging Face, cambia el modelo por InferenceClientModel() y exporta HF_TOKEN; esa variante no la hemos ejecutado. En nuestra ejecución local, el primer paso llamó a web_search una vez por montaña. En el segundo, el modelo copió las alturas leídas y terminó (fragmento del registro):

  teide_height = 3715  # meters (official height from reliable sources)
  everest_height = 8848.86  # meters (official height from reliable sources)

  times_cape = everest_height / teide_height
  final_answer(times_cape)
Final answer: 2.38192732166891
[Step 2: Duration 33.01 seconds| Input tokens: 6,600 | Output tokens: 295]

Repetimos la tarea 14 veces entre español e inglés, y 13 devolvieron 2,38, con 3.715 o 3.718 m para el Teide según el resultado que leyó el modelo. En la otra, el modelo trató el texto de la búsqueda como una lista y el agente devolvió 0 sin ningún error.

Con Ollama limitado a 8 hilos (PARAMETER num_thread 8) en un arm64 de 18 núcleos sin GPU, compartido y con una carga media de 8 a 10, cada acierto tardó entre 33 y 58 s. Con los hilos por defecto y la carga en 23, la primera ejecución tardó 16 minutos.

Definir tu propia herramienta es igual de directo. smolagents convierte el docstring en la descripción que lee el modelo, y si falta la línea de un argumento en Args, el decorador lanza un DocstringParsingException:

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, por ejemplo 21 para el 21 %.
    """
    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, aunque sea tres veces en la misma acción:

agent = CodeAgent(tools=[precio_con_iva], model=model)
print(agent.run(
    "Suma con IVA un portátil de 899 euros y un ratón de 45,50 al 21 % "
    "y un libro de 12 euros al 4 %."
))

En las 20 ejecuciones que hicimos (10 por idioma), el modelo llamó tres veces a la herramienta en un solo paso y devolvió 1155.32, en 5 a 12 s. Con un enunciado previo más ambiguo pasó 0,21 en lugar de 21 y devolvió 958,49 sin error, así que comprueba qué argumentos recibe tu herramienta.

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, se lee entero y se depura de una sentada; 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 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. Ejecuta siempre el código generado en un entorno aislado, como el sandbox de E2B, 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 herramientas una tras otra, 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. InferenceClientModel pide un HF_TOKEN, y una cuenta gratuita de Hugging Face incluye 0,10 dólares al mes de crédito para sus proveedores de inferencia. Con TransformersModel u Ollama ejecutas un modelo abierto en tu propio equipo sin coste por token. Las clases LiteLLMModel y OpenAIModel 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, que eliges con el parámetro executor_type. Su intérprete local por defecto, LocalPythonExecutor, no es una barrera de seguridad según su propia documentación; usa siempre un sandbox en cualquier despliegue real.

¿Funciona smolagents con un modelo pequeño en local?

Sí, con matices. Con Qwen3-4B-Instruct en Ollama 0.34.1 y sin GPU, el ejemplo de búsqueda acertó en 13 de 14 ejecuciones y el de la herramienta de IVA, en 20 de 20. El único fallo fue silencioso, un 0 sin ningún error, así que revisa el código del agente y valida su respuesta antes de usarla.

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 que cabe en un archivo y a la compatibilidad con cualquier modelo, la convierte en una puerta de entrada práctica al desarrollo de agentes. Empieza por el CodeAgent del ejemplo, dale una herramienta útil, comprueba sus respuestas 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
  2. smolagents en GitHub
  3. Introducing smolagents (blog de Hugging Face)
  4. Executable Code Actions Elicit Better LLM Agents
  5. Notas de la versión 1.26.0
  6. Visita guiada de smolagents
  7. Ejecución segura de código en smolagents
  8. Precios de Inference Providers

Ruta: Frameworks para construir agentes de IA