Arquitectura de Agentes AI: De Agentes Individuales a Sistemas Multi-Agente

Un agente AI es un sistema que usa un modelo de lenguaje como motor de razonamiento, combinado con herramientas que le permiten tomar acciones en el mundo real. La diferencia crítica entre un chatbot y un agente es la autonomía: los agentes deciden qué herramientas usar, en qué orden, y cómo manejar fallas — todo sin intervención humana en cada paso.

El loop central del agente sigue un ciclo de 4 fases: (1) leer contexto, (2) razonar sobre qué hacer, (3) ejecutar una herramienta, (4) observar el resultado — y repetir. Este loop de 4 fases es la base del Claude Agent SDK y todos los frameworks modernos de agentes. La sofisticación viene de cómo diseñas las herramientas, gestionas el contexto, manejas errores y coordinas múltiples agentes trabajando juntos.

Las arquitecturas modernas de agentes han superado los sistemas de agente único. Los despliegues de producción típicamente involucran agentes especializados que colaboran: un agente para generación de código, otro para testing, un tercero para deployment. Esta especialización refleja cómo trabajan los equipos humanos de ingeniería.

El Claude Agent SDK provee un framework TypeScript/Python para construir agentes AI personalizados con Claude. Maneja el loop del agente, ejecución de herramientas, gestión de conversaciones y recuperación de errores, permitiéndote enfocarte en definir herramientas y comportamiento del agente.

El SDK soporta respuestas en streaming, cancelación y ejecución paralela de herramientas. También provee hooks para observabilidad — puedes loguear cada llamada a herramienta, medir latencia y trackear uso de tokens para optimización de costos.

Construir un servidor MCP (Model Context Protocol) te permite exponer cualquier API, base de datos o sistema como herramienta que los agentes AI pueden usar. La especificación MCP define una interfaz estándar para descubrimiento, invocación y formato de resultados de herramientas.

Un servidor MCP consiste en tres componentes:

• Herramientas — Funciones que el agente puede llamar, cada una con nombre, descripción y esquema tipado de parámetros
• Recursos — Datos que el agente puede leer, como archivos, registros de base de datos o respuestas de APIs
• Prompts — Plantillas de prompts preconstruidas que el agente puede usar para tareas comunes

La orquestación de herramientas es el arte de diseñar un conjunto de herramientas que permita a los agentes completar tareas complejas eficientemente. Un diseño pobre lleva a agentes confundidos que desperdician tokens en prueba y error. Un gran diseño lleva a agentes que completan tareas en 2-3 llamadas en vez de 10.

Principios clave para diseño de herramientas:

• Operaciones atómicas — Cada herramienta hace una cosa bien. Evita herramientas que combinan múltiples operaciones.
• Descripciones claras — El modelo selecciona herramientas basado en descripciones. Descripciones ambiguas llevan a selección incorrecta.
• Parámetros tipados — Usa restricciones JSON Schema (enums, patrones, min/max) para prevenir inputs inválidos.
• Errores informativos — Devuelve errores que le digan al agente qué salió mal y cómo arreglarlo.
• Componibilidad — Diseña herramientas que encadenen naturalmente. La salida de una debe ser usable como entrada de otra.

Los subagentes son instancias hijo de agentes generadas por un agente padre para manejar subtareas aisladas. Cada subagente obtiene su propio contexto de conversación, acceso a herramientas y alcance de ejecución. El padre orquesta definiendo qué debe hacer cada subagente y agregando sus resultados.

Los equipos de agentes son grupos organizados de agentes con roles definidos, protocolos de comunicación y estrategias de coordinación. A diferencia de la generación ad-hoc de subagentes, los equipos tienen roles persistentes y entendimiento compartido del proyecto.

Estructuras de equipo efectivas incluyen:

• Arquitecto + Constructores — Un agente diseña la solución, otros implementan componentes. El arquitecto revisa todos los cambios antes de mergear.
• Equipo Full-Stack — Agentes separados para frontend, backend, base de datos y testing. Cada uno es dueño de su dominio y comunica cambios que afectan a otros.
• Escritor + Revisor — Cada cambio pasa por un pipeline de dos agentes: uno escribe, otro revisa. El revisor tiene criterios de calidad más estrictos.
• Pool de Especialistas — Un agente coordinador asigna tareas al especialista más apropiado según el tipo de tarea.

Las salidas estructuradas fuerzan al modelo a devolver datos en un esquema JSON específico, eliminando errores de parsing y habilitando consumo programático confiable de resultados del agente. Esto es crítico para comunicación agente-a-agente y para integrar outputs del agente en sistemas existentes.

Casos de uso para salidas estructuradas en sistemas de agentes:

• Descomposición de tareas — El agente devuelve un array tipado de subtareas con prioridades, dependencias y complejidad estimada
• Resultados de code review — Lista estructurada de issues con severidad, ubicación en archivo, descripción y fix sugerido
• Extracción de datos — Extraer campos específicos de texto no estructurado en un esquema tipado
• Logs de decisiones — El agente documenta su razonamiento, alternativas consideradas y nivel de confianza en formato estructurado

Claude soporta salidas estructuradas vía el formato de respuesta tool_use, donde defines el esquema esperado como herramienta y el modelo la "llama" con los datos estructurados. Este enfoque es más confiable que pedir al modelo que devuelva JSON en texto plano.

Los hooks son scripts basados en eventos que se ejecutan en puntos específicos del ciclo de vida del agente. Habilitan automatización de "barandas" — chequeos de calidad, escaneo de seguridad y enforcement de compliance que ocurren automáticamente sin que el agente necesite recordar hacerlos.

El diseño de permisos determina qué puede y no puede hacer un agente. En sistemas de producción, es el mecanismo de seguridad principal. El principio de mínimo privilegio aplica: los agentes deben tener los permisos mínimos necesarios para completar sus tareas.

Capas de permisos en un sistema de agentes bien diseñado:

• Nivel de herramienta — A qué herramientas puede acceder el agente. Un agente de code review no necesita herramientas de escritura de archivos o ejecución de comandos.
• Nivel de alcance — A qué archivos, directorios o recursos puede acceder el agente. Agentes de frontend no pueden modificar código backend.
• Nivel de acción — Qué operaciones están permitidas por herramienta. La herramienta de archivos puede permitir lectura en todos lados pero escritura solo en directorios específicos.
• Nivel de aprobación — Qué acciones requieren aprobación humana antes de ejecución. Operaciones destructivas siempre necesitan aprobación.

Desplegar agentes en producción introduce preocupaciones que no existen en desarrollo: confiabilidad, control de costos, observabilidad y seguridad a escala. Acá van las consideraciones críticas:

La plataforma usa una estrategia de desarrollo multi-agente coordinada a través de un archivo AGENTS.md de 512 líneas. Este archivo funciona como configuración del agente y como playbook de desarrollo, definiendo estructuras de equipo, registros de skills y protocolos de coordinación.