Agentes de IA: arquitectura e implementación en Python

Cómo se construyen los agentes de IA: arquitectura, ReAct e implementación práctica en Python

Los agentes de IA no son simplemente 'chatbots inteligentes'; son sistemas autónomos capaces de planificar, seleccionar herramientas, realizar llamadas externas y ajustar sus acciones en tiempo real. A diferencia de RAG, que solo proporciona contexto antes de la generación, un agente gestiona todo el ciclo de resolución de tareas—desde el análisis del objetivo hasta el resultado final con autoverificación. Esto representa un nivel fundamentalmente nuevo de automatización para los desarrolladores, especialmente en escenarios que requieren interacciones de múltiples pasos con APIs, código, bases de datos o servicios externos.

Por qué RAG es insuficiente para tareas complejas

RAG aborda un problema específico: actualizar el conocimiento a través de fuentes externas. Sin embargo, es estático: el modelo recibe un conjunto de fragmentos y genera una respuesta solo una vez. No existe un mecanismo para volver a consultar cuando los resultados son irrelevantes, ni para evaluar la confiabilidad de las salidas intermedias, ni para replanificar. En flujos de trabajo reales, esto es crucial:

• Al analizar documentación técnica, puede ser necesario seguir enlaces secuencialmente, extraer código de diferentes archivos y validarlo;
• Al generar un informe basado en datos de Excel, primero hay que leer la tabla, luego determinar métricas, calcularlas y solo después formatear el resultado;
• Al automatizar CI/CD, hay que interpretar registros de errores, ejecutar diagnósticos, aplicar correcciones y confirmar el resultado.

Todos estos escenarios van más allá de la generación de una sola vez. Es ahí donde se necesita una arquitectura dinámica—es decir, un agente.

Componentes clave de un agente de IA moderno

Un agente no es un monolito; es un sistema coordinado de módulos interactivos. Cada componente desempeña una función estrictamente definida y puede ser reemplazado o ampliado sin reescribir toda la lógica.

LLM como núcleo de toma de decisiones

El modelo no genera la respuesta final directamente; en cambio, actúa como el “cerebro”: formula un plan, selecciona herramientas, interpreta los resultados de las llamadas y decide el siguiente paso. Su rol es la gestión estratégica, no la producción de texto.

Herramientas como interfaz con el entorno

Estas son cualquier capacidad externa: solicitudes HTTP a APIs REST, ejecución de código Python en un sandbox, lectura/escritura de archivos, ejecución de consultas SQL, llamadas a utilidades de línea de comandos. Una herramienta debe tener una descripción clara (docstring), argumentos tipados y manejo de errores—solo así el LLM puede usarla de manera segura.

Memoria: a corto y largo plazo

La memoria a corto plazo consiste en el contexto actual del diálogo y los resultados intermedios (por ejemplo, el ID de un recurso creado). La memoria a largo plazo incluye bases de conocimiento basadas en vectores, respuestas en caché y datos históricos de sesiones de usuario. Permite al agente “recordar” el contexto entre llamadas y aprender de la experiencia.

Planificador y controlador de errores

El planificador divide el objetivo en pasos, rastrea el progreso y evita bucles. El controlador de errores verifica la validez de los resultados de las herramientas, coteja hechos con fuentes y reinicia intentos si algo sale mal. Sin estos componentes, el agente es inestable e impredecible.

ReAct: un patrón de comportamiento transparente para LLMs

ReAct (Reason + Act + Observe) no es un marco; es una plantilla de comportamiento que define un ciclo claro de trabajo del agente. Hace visible y controlable el razonamiento interno del modelo:

• Reason—el modelo analiza el estado actual, formula una hipótesis sobre la próxima acción y explica por qué es necesaria;
• Act—el modelo llama a una herramienta con argumentos específicos;
• Observe—el modelo recibe el resultado de la llamada y evalúa su aplicabilidad a la tarea.

Este ciclo se repite hasta que se alcanza el objetivo. Por ejemplo, al buscar información sobre la compatibilidad de una biblioteca con Python 3.12, el modelo primero “razona” que debe consultar PyPI y GitHub; luego “actúa” llamando a get_pypi_info('requests'); después de “observar” la respuesta, decide si debe analizar el código fuente del repositorio.

La ventaja de ReAct es la reproducibilidad y la capacidad de depuración. Cada paso se registra: plan → llamada → resultado → nueva decisión. Esto es crucial para sistemas en producción, donde se requiere auditoría y trazabilidad.

Sistemas multi-agente: escalando mediante especialización

Un único agente universal rápidamente alcanza un límite de complejidad. Los sistemas multi-agente (MAS) resuelven esto dividiendo roles. En lugar de un monolito, hay un equipo de agentes especializados coordinados por un orquestador.

Los roles típicos en MAS incluyen:

• Planner—descompone el objetivo, determina el orden de las sub-tareas y las asigna a los ejecutores;
• Researcher—trabaja con fuentes externas: APIs, documentación, bases de datos;
• Executor—ejecuta código, modifica archivos, aplica configuraciones;
• Validator—verifica los resultados para asegurar su corrección, cumplimiento de requisitos y seguridad.

El coordinador recopila resultados, resuelve conflictos y forma la respuesta final. Este enfoque ofrece tres ventajas clave:

• Paralelismo: varios agentes pueden manejar sub-tareas independientes simultáneamente;
• Mayor confiabilidad: el validador detecta errores que el ejecutor podría pasar por alto;
• Simplificación de la depuración: un fallo en un rol no paraliza todo el sistema.

Sin embargo, MAS requiere un protocolo de interacción bien pensado y protección contra dependencias cíclicas—por ejemplo, cuando el investigador solicita datos al validador, pero el validador espera confirmación del investigador.

Práctica: un agente asistente mínimo en LangChain

Construyamos un agente simple pero completamente funcional capaz de obtener el clima, encontrar eventos y enviar correos electrónicos. El objetivo es mostrar cómo los componentes se unen en un sistema unificado, en lugar de crear una solución lista para producción.

Inicialización del modelo y el entorno

Usaremos Qwen 3.5 (9B) a través de Ollama—un modelo lo suficientemente potente para tareas de agente y lo bastante pequeño para ejecutarse en Google Colab. La conexión es estándar:

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="qwen3.5:9b",
    base_url="http://localhost:11434/v1",
    api_key="ollama",
    temperature=0.3,
)

Definición de herramientas

Cada herramienta es una función de Python decorada con @tool, completa con una docstring clara y argumentos tipados. Por ejemplo, get_weather:

@tool
def get_weather(city: str) -> str:
    """Devuelve el clima actual en la ciudad especificada.
Acepta el nombre de la ciudad en ruso o inglés."""
    # ... implementación usando la API Open-Meteo
    return f"{name}: {weather['temperature_2m']}°C, {desc}, viento {weather['wind_speed_10m']} km/h"

Es importante que la función maneje errores de red, ciudades inexistentes y códigos de clima inválidos—de lo contrario, el agente recibirá texto no estructurado en lugar de la respuesta esperada.

Prompts del usuario y contexto

El prompt define el rol, las restricciones y el tono de la respuesta. Para un agente técnico, es crucial especificar explícitamente:

• Qué herramientas están disponibles y cuándo usarlas;
• Qué hacer en caso de error (reintentar, pedir aclaraciones al usuario o negarse);
• Cómo formatear la respuesta final (por ejemplo, solo JSON, sin explicaciones).

USER_CONTEXT contiene datos personalizados—nombre, preferencias, historial de interacción. Esto permite al agente adaptar el tono y el nivel de detalle.

Lo que importa

• Un agente de IA no es un LLM con un prompt extendido; es un sistema arquitectónicamente complejo con una clara división de responsabilidades entre los componentes.
• ReAct no es solo una “característica”; es un patrón necesario para garantizar transparencia, capacidad de depuración y seguridad en producción.
• Las herramientas deben estar tipadas, documentadas y resistentes a errores—de lo contrario, el agente pierde el control sobre la ejecución.
• Los sistemas multi-agente no se justifican por moda; se necesitan para escalar la complejidad: un solo agente no puede gestionar de manera confiable decenas de herramientas y fuentes.
• Los agentes en producción requieren mecanismos de trazabilidad, registro de cada paso del ciclo y validación estricta de datos de entrada/salida.

— Editorial Team