smolagents

smolagents es una biblioteca de Python para crear agentes de IA autónomos, lanzada por Hugging Face el 31 de diciembre de 2024. La premisa central de la biblioteca es que los agentes deben escribir y ejecutar código Python para realizar acciones, en lugar de generar diccionarios de llamadas a herramientas en JSON como hacen la mayoría de los demás frameworks. La lógica central del agente cabe en aproximadamente 1000 líneas de código, lo cual es una elección deliberada: todo el framework es legible, auditable y modificable en una tarde. Con licencia Apache 2.0, smolagents ha alcanzado las 27 000 estrellas en GitHub para mayo de 2026, convirtiéndose en uno de los frameworks de agentes de adopción más rápida desde LangChain.

La biblioteca incluye dos tipos de agentes: CodeAgent, que genera fragmentos de Python como acciones y los ejecuta en un intérprete aislado (produciendo un 30 % menos de llamadas a LLM que el uso de herramientas basadas en JSON), y ToolCallingAgent, que sigue el formato estándar de llamadas a herramientas en JSON para mantener la compatibilidad con las API de estilo OpenAI. Es compatible con más de 100 backends de modelos a través de LiteLLM, incluida la inferencia local mediante Ollama y Hugging Face Transformers, además de OpenAI, Anthropic y cualquier proveedor con un endpoint compatible con OpenAI. Los agentes y las herramientas se pueden compartir y descargar desde Hugging Face Hub. Admite entradas multimodales (texto, visión, video, audio). Las opciones de ejecución en entornos aislados (sandbox) incluyen E2B, Modal, Docker, Blaxel y WebAssembly para equipos que ejecutan código no confiable en producción.

Lo que realmente hace smolagents en abril de 2026

smolagents ejecuta un bucle de razonamiento de múltiples pasos: el agente recibe una tarea, le pregunta al LLM qué hacer a continuación, ejecuta la acción resultante (como código Python o una llamada a una herramienta), observa el resultado y repite el proceso hasta que la tarea se completa o se alcanza el límite de pasos. La variante CodeAgent convierte esto en Python ejecutable en cada paso en lugar de un objeto de acción JSON. Un agente funcional mínimo requiere tres líneas de Python: importar la biblioteca, instanciar un CodeAgent con una lista de herramientas y un modelo, y luego llamar a agent.run("your task").

La versión 1.24.0 (enero de 2026) amplió la arquitectura multiagente, donde un CodeAgent administrador puede delegar subtareas a subagentes especializados. La integración con el Hub significa que cualquier herramienta o configuración de agente publicada en Hugging Face Hub se puede importar en una sola línea. La compatibilidad con servidores MCP se agregó a principios de 2025, por lo que smolagents puede consumir herramientas expuestas a través del Model Context Protocol junto con herramientas nativas de Python y herramientas compatibles con LangChain.

El resultado del benchmark GAIA durante el período de lanzamiento de la biblioteca estableció su credibilidad: un CodeAgent construido con la arquitectura de smolagents obtuvo un 44.2 % en el conjunto de validación de GAIA (ocupando el primer lugar en el lanzamiento), superando a AutoGen de Microsoft con un 40 % y muy por encima de la puntuación base de GPT-4-Turbo de menos del 7 % en el mismo benchmark sin un framework de agentes. GAIA evalúa la planificación de alto nivel, el razonamiento multimodal y la recopilación de información en múltiples pasos a través de tareas complejas como identificar obras de arte, relacionar documentos históricos y procesar datos estructurados. A finales de 2025, una mayor optimización impulsó los sistemas basados en smolagents al 55 % en GAIA, reforzando la ventaja del enfoque centrado en el código en tareas que requieren computación componible y con estado.

Dónde se sitúa smolagents frente a LangChain y PydanticAI

Las tres comparaciones más citadas para smolagents son LangChain/LangGraph (el líder dominante), PydanticAI (el recién llegado que prioriza la seguridad de tipos) y, en menor medida, LlamaIndex. Cada uno representa una filosofía diferente sobre lo que debería ser un framework de agentes.

LangChain y LangGraph cuentan con más de 90 000 estrellas en GitHub y cinco años de historial en producción. LangGraph amplía LangChain con una arquitectura de grafo acíclico dirigido (DAG) donde los pasos del agente son nodos explícitos del grafo, lo que brinda a los desarrolladores un control preciso sobre la lógica de ramificación, las máquinas de estado, los reintentos y la propagación de errores. Ese control conlleva cierta complejidad: definir un flujo de trabajo en LangGraph requiere definiciones explícitas de nodos, bordes y esquemas de estado antes de que se ejecute una sola acción. smolagents maneja el bucle ReAct automáticamente en su núcleo de 1000 líneas; usted proporciona las herramientas y un modelo, y el bucle se gestiona por usted. LangGraph es la opción correcta para la orquestación compleja con estado, con puntos de control que incluyen intervención humana (human-in-the-loop) y un manejo detallado de errores. smolagents es más rápido para crear prototipos, pero menos controlable a gran escala.

PydanticAI, lanzado en septiembre de 2024 y que alcanzó la versión 1.0 en septiembre de 2025, aporta la validación estructurada al estilo FastAPI al desarrollo de agentes. Cada llamada a una herramienta y salida del agente se valida frente a esquemas de Pydantic antes de su procesamiento, con instrumentación OpenTelemetry integrada y un diseño que prioriza la asincronía. La diferencia mecánica de PydanticAI con respecto a smolagents es la imposición de salidas: mientras que smolagents produce cualquier código Python que escriba el LLM y confía en que el código sea válido, PydanticAI impone contratos de esquema en cada límite. Para registros médicos, canales de datos financieros o cualquier aplicación que requiera respuestas estructuradas auditables y predecibles, las garantías de validación de PydanticAI son importantes. smolagents no ofrece un mecanismo equivalente. La contrapartida es que el tipado estricto de PydanticAI añade una sobrecarga de configuración que smolagents evita deliberadamente.

Para los equipos que ya han invertido en el ecosistema de Hugging Face, que utilizan Transformers o modelos de código abierto a través de Ollama, o que construyen prototipos de investigación, smolagents tiene una clara ventaja de jugar en casa. Para los equipos que ejecutan aplicaciones en producción que procesan datos estructurados confidenciales, el control de LangGraph o la validación de PydanticAI valen la pena a pesar de la complejidad añadida. Los usuarios suelen combinar smolagents con Hugging Face Hub para acceder a modelos y compartir herramientas, o con herramientas de LangChain a través de la capa de compatibilidad con LangChain de smolagents.

"Si los fragmentos de JSON fueran una mejor expresión, JSON sería el principal lenguaje de programación y programar sería un infierno en la tierra". - Aymeric Roucher, Merve Noyan y Thomas Wolf, equipo de ingeniería de Hugging Face, blog de lanzamiento de smolagents, diciembre de 2024

Cómo es la realidad del bucle del agente

Ejecutar un CodeAgent en smolagents significa que el LLM genera código Python en cada paso. Eso funciona bien cuando el modelo tiene una gran capacidad de generación de código. Cuando no es así, el bucle se degrada rápidamente: el agente escribe código Python sintácticamente incorrecto, el intérprete lanza una excepción, el error se añade al contexto y se le pide al LLM que lo solucione. En modelos capaces (GPT-4o, Claude Sonnet, DeepSeek-R1, Qwen2.5-Coder), este bucle de autocorrección es robusto. En modelos más pequeños de propósito general, produce una espiral frustrante de código fallido que consume tokens sin lograr ningún progreso.

La gestión de la memoria es la frustración citada con mayor frecuencia en los problemas (issues) de GitHub. El agente mantiene un historial completo de cada acción y observación. En tareas largas, este historial crece más allá de la ventana de contexto del modelo. A diferencia del enfoque de resumen de Claude Code (que comprime el contexto más antiguo de forma continua), smolagents, a principios de 2026, no tiene consolidación de memoria integrada. El problema #694 de GitHub describe el problema directamente: "truncamiento básico y eliminación de mensajes, pero NINGÚN resumen integrado para gestionar el crecimiento de la memoria a largo plazo". El problema #901, presentado en marzo de 2025, confirma que "las herramientas relacionadas con la memoria aún no están expuestas en smolagents, lo cual es una limitación para aplicaciones de agentes más avanzadas". El problema #1121 (abril de 2025) es una solicitud de función para un banco de memoria persistente a largo plazo. Estas son carencias conocidas en la hoja de ruta pública.

La ejecución de código en entornos aislados (sandbox) está documentada pero estructurada en capas. La ejecución local de CodeAgent utiliza un intérprete de Python restringido (basado en AST, con controles de importación y límites en el recuento de operaciones). Para un aislamiento más estricto, están disponibles los sandboxes de E2B, Modal, Docker y WebAssembly, pero la arquitectura multiagente actualmente no es compatible con ejecutores aislados, lo que significa que el agente administrador y sus subagentes se ejecutan en el mismo contexto de ejecución. Las implementaciones en producción que manejan entradas no confiables deben diseñarse explícitamente teniendo en cuenta esta limitación.

"Hay un gran paso desde lo que hace actualmente smolagents hasta todo lo que se necesita para un framework de agentes que ejecute una aplicación a nivel de producción". - Reseña del framework en agentsdecoded.com, 2025

Los usuarios que construyen flujos de trabajo de investigación y ciencia de datos reportan la experiencia más fluida. Un patrón típico: definir de 5 a 10 herramientas (búsqueda en DuckDuckGo, un REPL de Python, un lector de archivos, un cliente de API), instanciar un CodeAgent y asignarle una tarea de investigación abierta. El agente compone código Python que encadena llamadas a herramientas, procesa resultados intermedios en variables y devuelve una salida estructurada sin que el desarrollador escriba ninguna lógica de orquestación. Los usuarios suelen combinar smolagents con DSPy para la optimización de prompts o con PydanticAI para la validación de salidas en pipelines híbridos.

Para quién está diseñado smolagents

smolagents es ideal para investigadores de ML, científicos de datos y desarrolladores backend que ya piensan en Python y desean una sobrecarga mínima del framework. La integración con el ecosistema de Hugging Face (modelos del Hub, herramientas del Hub, Transformers, Datasets) lo convierte en la primera opción natural para los equipos que ya trabajan con esa pila tecnológica. Si su implementación de modelos es Ollama ejecutando Llama o Qwen localmente, o un modelo ajustado (fine-tuned) en Hugging Face Inference Endpoints, smolagents es el punto de partida obvio: la integración es nativa, la licencia es compatible y el código base es lo suficientemente pequeño como para leerlo y parchearlo.

Los usuarios de modelos de código abierto se benefician específicamente porque smolagents trata a todos los modelos por igual a través de la compatibilidad con LiteLLM. No hay un nivel premium para modelos restringidos u optimizaciones propietarias. El mismo CodeAgent que se ejecuta con GPT-4o puede ejecutarse con un modelo local Qwen2.5-Coder con un solo cambio de configuración. Los equipos que exploran arquitecturas de agentes sin dependencia de un proveedor (vendor lock-in) apreciarán esta flexibilidad. Para explorar la coordinación multiagente, el patrón de agentes administrados (donde un agente de nivel superior orquesta a los subagentes) funciona de forma predeterminada sin configuración adicional. La biblioteca complementa a LlamaIndex en pipelines donde la generación aumentada por recuperación (RAG) alimenta a un agente que procesa el contexto recuperado mediante código.

Lo que no es smolagents

smolagents no es una plataforma de agentes empresariales a nivel de producción. No tiene observabilidad integrada, registro estructurado (logging) ni políticas de reintento más allá de lo que el desarrollador añada manualmente. No hay salidas impuestas por esquemas, ni un registro de auditoría nativo, ni certificaciones de cumplimiento. Los equipos en industrias reguladas (salud, finanzas, legal) que evalúen frameworks de agentes para implementaciones en producción encontrarán que los contratos de validación de PydanticAI o la gestión de estado explícita de LangGraph se adaptan mejor a sus requisitos de gobernanza.

Tampoco es indulgente con los modelos débiles. El enfoque centrado en el código requiere un LLM que escriba código Python limpio y funcional bajo la presión de los prompts. Intentar ejecutar smolagents con modelos más pequeños de propósito general (por debajo de aproximadamente 7B de parámetros, o modelos no entrenados específicamente en código) produce resultados poco fiables. Esta es una limitación real de hardware y costos para los equipos que desean autoalojar todo en GPU de nivel de consumidor.

Por último, smolagents no es una herramienta de orquestación de flujos de trabajo en el sentido de LangGraph. Si su caso de uso requiere una lógica de ramificación explícita (enrutar la tarea A al subagente X, la tarea B al subagente Y basándose en un clasificador), reintentos condicionales con persistencia de estado o pasos de aprobación con intervención humana, LangGraph le proporciona esas primitivas. smolagents las abstrae, lo cual es su punto fuerte para casos simples y su límite para los complejos. Los equipos que han superado el bucle ReAct automático y necesitan un control de orquestación preciso deberían tratar a smolagents como una fase de creación de prototipos antes de migrar a un framework más explícito como LangGraph o CrewAI.