Agentes de IA con smolagents: cómo funcionan y cuándo usarlos

smolagents encaja cuando tus agentes de IA en Python necesitan combinar herramientas y cálculos sobre la marcha, y puedes ofrecerles un entorno controlado donde ejecutar ese código. Hugging Face ofrece 2 clases de agentes, CodeAgent y ToolCallingAgent: la diferencia está en si el modelo expresa su siguiente acción en Python o mediante una llamada estructurada a una herramienta. Su diseño minimalista facilita resolver problemas acotados, pero sigues siendo responsable de la persistencia de los flujos de trabajo, los permisos y el aislamiento.

Información contrastada con la documentación vigente de Hugging Face, LangChain y OpenAI el 31 de octubre de 2026. Las recomendaciones comparan cómo se componen las acciones, cómo se controlan los flujos de trabajo y dónde se delimitan los entornos de ejecución. Son valoraciones de arquitectura, no pruebas comparativas de rendimiento.

Cómo funcionan los agentes de IA de smolagents en Python

smolagents es la biblioteca de Python de código abierto de Hugging Face para crear agentes de inteligencia artificial cuyas acciones pueden ser código ejecutable. Un agente funciona en un ciclo guiado por un modelo: elige una acción, observa qué ha ocurrido y decide el siguiente paso. CodeAgent expresa esa acción en Python; ToolCallingAgent utiliza llamadas estructuradas a herramientas. Ambos reciben un modelo y un conjunto de herramientas. Referencia de agentes de Hugging Face.

Piensa en CodeAgent como un investigador que puede escribir un script breve entre una observación y la siguiente. Puede pedir registros a una herramienta autorizada, transformar los datos recibidos y calcular una respuesta. Tú defines las capacidades y las restricciones; el modelo aporta parte de la lógica que las conecta.

No es lo mismo que un asistente cuyo producto final es un archivo de código que vas a revisar. Aquí, el código generado es el medio con el que el agente realiza su siguiente acción.

Para comparar las opciones, conviene identificar qué parte de la aplicación necesita flexibilidad:

Las dos últimas filas reflejan el enfoque que documentan LangGraph y OpenAI Agents SDK, no capacidades exclusivas. La decisión depende de qué parte quieres que el framework estructure por ti.

CodeAgent de smolagents: dejar que el modelo componga las acciones

CodeAgent aporta valor cuando los pasos intermedios se expresan mejor en Python que con un menú fijo de llamadas. Hugging Face destaca los bucles, los condicionales y la combinación de herramientas, junto con la necesidad de gestionar errores de sintaxis, excepciones y comportamientos inesperados. Recorrido guiado.

Imagina, por ejemplo, que un desarrollador investiga inconsistencias en un inventario. Una herramienta de consulta de solo lectura devuelve registros candidatos. Antes de decidir cuáles necesitan otra consulta, el agente podría tener que normalizar nombres, agrupar entradas similares y sumar los valores de un campo. Python permite expresar esas operaciones intermedias con naturalidad.

El resultado de la ejecución sirve de evidencia para la siguiente decisión del modelo. Si un cálculo falla, el agente recibe una observación a la que puede responder; eso no demuestra que vaya a corregirse con éxito.

ToolCallingAgent: limitar las acciones a un menú definido

ToolCallingAgent es un mejor punto de partida cuando las operaciones ya tienen contratos claros. Genera llamadas JSON estructuradas con nombres de herramientas y argumentos, en lugar de componer acciones en Python. Comparación de Hugging Face.

Un asistente de soporte que consulta un pedido y recupera una política puede no necesitar más. Deja las transformaciones previsibles en manos del código habitual de la aplicación. Introducir Python generado en un flujo que ya encaja en funciones bien definidas añade una posibilidad de fallo sin un beneficio evidente.

Las llamadas estructuradas también necesitan autorización. Una solicitud para cancelar un pedido puede tener el formato correcto y seguir siendo una acción indebida para ese cliente. El esquema indica al programa qué se ha solicitado; la aplicación decide si está permitido.

Las herramientas y los modelos se eligen por separado

Limita el conjunto de herramientas y elige el modelo de forma independiente. Esa separación es uno de los atractivos prácticos de smolagents: puedes cambiar cómo razona el agente sin redefinir todas las capacidades de negocio.

Herramientas: funciones con un contrato claro

Una herramienta de smolagents envuelve una función y le añade un nombre, una descripción, metadatos de entrada y un tipo de salida. El decorador @tool resulta adecuado para funciones sencillas con anotaciones de tipo y un docstring útil. Para una herramienta más compleja, crea una subclase de Tool e implementa su lógica de ejecución en forward. Guía de herramientas.

Para un asistente de inventario, es preferible una capacidad como «consultar registros del catálogo autorizado» al acceso sin restricciones a la base de datos. Incluye en la implementación las comprobaciones de pertenencia al cliente, las restricciones de consulta y los límites de respuesta. Un prompt convincente no sustituye esos controles.

Las herramientas también pueden llegar a través de Model Context Protocol, o MCP, una interfaz estándar para exponer herramientas a aplicaciones basadas en modelos, así como de adaptadores para herramientas de LangChain y Hugging Face Spaces. Reutilizar una herramienta no garantiza que su implementación sea confiable. Hugging Face exige expresamente trust_remote_code=True al cargar herramientas del Hub porque ejecutan código personalizado. Documentación sobre integración y carga de herramientas.

Esa decisión exige revisar el código. Inspecciona la implementación de la herramienta y sus dependencias antes de ponerla a disposición de un agente.

El backend del modelo no determina el sandbox

La referencia actual de modelos documenta varias opciones:

• InferenceClientModel se conecta a través de Hugging Face Inference Providers.
• LiteLLMModel utiliza la capa de integración de proveedores de LiteLLM.
• TransformersModel ejecuta un modelo de Transformers de forma local.
• OpenAIModel se conecta a un servidor de modelos compatible con OpenAI.

El recorrido guiado también explica el uso de Ollama para inferencia local. Son opciones de backend, no garantías de que todos los modelos generen código o seleccionen herramientas con la misma solvencia.

Separa dos preguntas: ¿dónde se ejecuta el modelo y dónde se ejecuta el Python que genera? Un modelo alojado en un servicio puede dirigir un ejecutor de Docker. Un modelo local también puede generar acciones inseguras. Llevar la inferencia a tu equipo no crea por sí solo una barrera de aislamiento para la ejecución.

Para que el comportamiento sea reproducible, configura el modelo de forma explícita cuando pases de la demostración a un uso real. Hugging Face advierte que el modelo predeterminado de InferenceClientModel puede cambiar. Configuración del modelo.

Un ejemplo sencillo basado en la documentación

Empieza por la tarea aritmética de la documentación para entender el recorrido de ejecución antes de añadir herramientas. El ejemplo introductorio de Hugging Face pide sumar los números del 1 al 10 sin proporcionar herramientas. La versión siguiente conserva esa tarea e incorpora el patrón de gestor de contexto de Docker de su guía de entornos aislados. Ejemplo original, configuración de la ejecución en Docker.

1. 1

   Preparar el entorno

   La guía de instalación exige Python 3.10 o posterior y recomienda un entorno virtual. Para este ejemplo, Docker también debe estar instalado y en ejecución. Guía de instalación.

   python -m venv .venv
   source .venv/bin/activate
   pip install 'smolagents[docker]'

   Define HF_TOKEN en el entorno con un token de Hugging Face que tenga permiso para llamar a Inference Providers. InferenceClientModel puede leer esa variable automáticamente. No incluyas el token en el script. Funcionamiento de la autenticación.

2. 2

   Ejecutar la tarea documentada en Docker

   Guarda lo siguiente en sum_agent.py:

   from smolagents import CodeAgent, InferenceClientModel
   
   model = InferenceClientModel()
   
   with CodeAgent(
       tools=[],
       model=model,
       executor_type="docker",
   ) as agent:
       result = agent.run("Calculate the sum of numbers from 1 to 10")
       print(result)

   Después, ejecuta:

   python sum_agent.py

   El gestor de contexto se ocupa de limpiar el entorno aislado al salir del bloque. Este código es una adaptación de la documentación, no el resultado de una prueba ejecutada para este artículo.

3. 3

   Comprobar el resultado y el aislamiento

   La respuesta matemática esperada es 55, calculada como 10 × 11 ÷ 2. El modelo decide qué Python genera, así que no esperes una secuencia de ejecución exacta ni una redacción idéntica en cada intento.

   tools=[] indica que no se han proporcionado herramientas personalizadas. No significa que CodeAgent haya perdido la capacidad de ejecutar Python. La configuración del ejecutor es lo que lleva ese código generado a Docker.

Para este cálculo fijo, lo sensato es escribir Python convencional en la aplicación. El ejemplo sirve para mostrar la mecánica del agente. Añade un agente cuando elegir los pasos intermedios forme parte del problema, no solo porque el cálculo pueda describirse en lenguaje natural.

Los agentes que ejecutan código necesitan un sandbox

Trata el Python generado como código no confiable y asígnale un entorno aislado explícito antes de exponerlo a entradas no confiables. El ejecutor local predeterminado es un intérprete restringido, no una garantía de aislamiento del sistema anfitrión. Hugging Face señala como riesgos los errores del modelo, la inyección de prompts y las solicitudes maliciosas. Ejecución segura de código.

El intérprete local evalúa operación por operación el árbol de sintaxis abstracta de Python, es decir, la estructura del programa tras su análisis sintáctico. Restringe las importaciones y los submódulos, y limita el número de operaciones. Estos controles reducen la exposición, pero la guía de seguridad advierte que la ejecución local sigue entrañando riesgos. Autorizar un paquete adicional amplía lo que puede alcanzar el programa generado.

Qué opciones de sandbox ofrece Hugging Face

La API actual de ejecutores admite Blaxel, E2B, Modal y Docker, además del ejecutor local. Los nombres de configuración que aparecen a continuación coinciden con la referencia de CodeAgent y la referencia de ejecutores.

Elige el proveedor y las credenciales por separado de estos ajustes. La documentación de instalación enumera las dependencias opcionales; instalar una de ellas no basta para configurar un despliegue.

Para un experimento interno, Docker puede ofrecer una barrera de ejecución concreta que puedas inspeccionar. Para un servicio que atiende solicitudes no confiables, elige el entorno según el aislamiento, el ciclo de vida y los controles operativos que necesites. La comparativa de entornos aislados para el código de agentes de IA aborda esa decisión de infraestructura con más amplitud.

Aislar fragmentos de código no equivale a aislar todo el agente

Decide qué queda dentro del entorno aislado antes de añadir más agentes. Hugging Face distingue entre ejecutar los fragmentos generados en un sandbox y ejecutar allí todo el sistema de agentes. Su guía de seguridad advierte que el enfoque que aísla solo fragmentos no admite agentes gestionados, es decir, agentes a los que otro agente llama como ayudantes. Llevar todo el sistema al interior exige más configuración y puede requerir que se proporcionen credenciales. Enfoques de aislamiento.

La consecuencia afecta a la arquitectura. Si más adelante un especialista necesita llamar a un modelo desde el entorno de ejecución, el esquema original de «enviar código y recibir un resultado» puede quedarse corto. Revisa dónde se guardan las credenciales y de qué dependen las herramientas cuando cambies la forma del despliegue.

Para un servicio de cara al cliente, define los archivos permitidos, los destinos de red y las operaciones disponibles antes de iniciar el agente. Concede a cada ejecución solo el acceso que requiere su tarea. Trata el agotamiento del tiempo de espera, la cancelación y la limpieza como rutas normales de ejecución, también cuando el modelo no consiga terminar.

Cuándo conviene el minimalismo y cuándo se queda corto

Elige el framework según el problema de control más difícil de tu aplicación. Un inicializador breve resulta útil, pero importa más el código que debes escribir a su alrededor.

smolagents vs LangGraph: acciones dinámicas o control persistente

LangGraph es un punto de partida más sólido cuando el proceso debe conservar su estado, pausarse y reanudarse pasando por estados de negocio explícitos. Es un entorno de ejecución de bajo nivel para orquestar flujos con estado, con persistencia y soporte para la intervención humana. Puede combinar pasos deterministas con otros guiados por modelos y no requiere LangChain. Introducción a LangGraph.

Piensa en un flujo de compras que reúne evidencia, espera la decisión de un responsable y se reanuda tras la aprobación. El problema central es conservar el proceso y hacer cumplir la transición autorizada. Si esos requisitos definen el producto, empieza por LangGraph.

La carga que asumes es diseñar el flujo: sus estados, sus transiciones, su persistencia y qué significa reintentar un paso. Ese esfuerzo está justificado en el proceso de compras. Puede añadir una estructura innecesaria a un asistente de investigación acotado que lee datos, calcula una respuesta y termina.

Elige smolagents cuando la principal incertidumbre sea qué operaciones de Python resuelven esta tarea. Elige LangGraph cuando sea cómo avanza este proceso de forma segura por estados persistentes. Es una recomendación de diseño, no una afirmación de que cada framework solo pueda hacer un tipo de trabajo.

OpenAI Agents SDK: traspasos, comprobaciones y trazas

OpenAI Agents SDK es una mejor opción de partida cuando la aplicación gira en torno a la coordinación de especialistas y los controles operativos. Sus traspasos transfieren la responsabilidad de la conversación a otro agente; el patrón de agentes como herramientas permite que un gestor conserve la responsabilidad de la respuesta. Documentación de orquestación.

En un asistente de atención al cliente, que un especialista en facturación tome el control de la conversación puede ser una abstracción más clara que recurrir a un solucionador general de problemas en Python. Las trazas integradas registran las llamadas al modelo, las llamadas a herramientas, los traspasos y los controles de seguridad. Estos controles, o guardrails, realizan comprobaciones automáticas, mientras que los mecanismos de revisión humana pausan las acciones sensibles hasta que se tome una decisión. Trazas, controles y revisión.

La política de la aplicación sigue siendo tu responsabilidad: decidir qué requiere aprobación, implementar correctamente la herramienta y gestionar el trabajo interrumpido. Estos componentes no redactan esa política por ti. El SDK también documenta patrones de agentes con sandbox, así que la ejecución de código no es exclusiva de smolagents.

Elige smolagents frente al SDK cuando necesites componer acciones en Python y baste con un ciclo sencillo. Elige Agents SDK cuando sus componentes de coordinación y revisión encajen con la aplicación que estás construyendo. Que una biblioteca sea «ligera» no basta para decidir.

Para ampliar la lista de opciones, consulta la comparativa de frameworks de agentes de IA. Si buscas una aplicación de agentes que puedas instalar, en lugar de una biblioteca sobre la que desarrollar, empieza por la guía de agentes de IA de código abierto.

Qué se exagera al hablar de agentes que ejecutan código

Un framework pequeño no vuelve predecible una tarea impredecible. La expresividad de Python es útil, pero no demuestra que el modelo haya elegido los registros correctos, interpretado bien una unidad o respetado una regla de negocio.

No conviertas la capacidad de combinar operaciones en una promesa universal de velocidad. Combinarlas puede cambiar el desarrollo de una ejecución; el resultado sigue dependiendo del modelo, la tarea, el comportamiento de las herramientas y el entorno. Mide tu propia tarea antes de elegir por rendimiento.

También hay un límite concreto que conviene entender: max_steps tiene un valor predeterminado de 20 en la API actual de agentes. Limita los pasos del agente, no los recursos que consume una acción individual de Python. La API también ofrece callbacks, agentes gestionados y comprobaciones de la respuesta final, así que minimalismo no equivale a ausencia de controles. Referencia de agentes.

En la práctica, debes fijar por separado los límites de tiempo de ejecución y de recursos. Un límite de pasos no sustituye una política de aislamiento, y un sandbox no sustituye un resultado correcto.

Qué puedes construir la próxima semana

Empieza con una tarea acotada, de solo lectura y cuya respuesta puedas comprobar por otros medios. Para evaluar smolagents, un desarrollador de Python podría usar una exportación de inventario depurada de datos sensibles y una herramienta de consulta de alcance limitado, y después contrastar las discrepancias que propone el agente con ejemplos conocidos.

Registra si seleccionó los registros adecuados, utilizó bien las herramientas, se recuperó de fallos previstos y se detuvo dentro de tus límites. Conserva una solución determinista como referencia. Si la tarea siempre sigue el mismo recorrido, escríbelo como código convencional; la propia guía de Hugging Face recomienda usar funciones deterministas siempre que sea posible. Cómo construir buenos agentes.

Avanza con CodeAgent cuando la composición dinámica de Python justifique su complejidad. Usa ToolCallingAgent si basta con un menú definido de herramientas. Pospón la migración si el flujo actual ya cumple sus requisitos. Reevalúa el framework cuando las aprobaciones que deban persistir en el tiempo o los traspasos entre especialistas pasen a ser centrales.

Instalación y compatibilidad

¿Cómo instalar smolagents con pip?

Instala la biblioteca principal con pip install smolagents. Añade las dependencias opcionales necesarias para tus herramientas, modelos o entorno de ejecución. El ejemplo utiliza smolagents[docker].

¿Qué usar en lugar de HfApiModel en smolagents?

Para código nuevo, sigue la interfaz InferenceClientModel de la documentación actual. Contrasta los ejemplos antiguos con la referencia vigente de modelos antes de copiar sus importaciones.

¿Cómo usar smolagents con Docker?

Instala e inicia Docker, instala la dependencia opcional de Docker y selecciona executor_type="docker". Configura el aislamiento de la ejecución para tu carga de trabajo; ese ajuste por sí solo no constituye una política de seguridad completa.

Recibe en la newsletter consejos prácticos para desarrollar con IA.