name: ai-agent-design description: Utiliza esta habilidad al construir agentes de IA, diseñar sistemas multi-agente, integrar LLMs en aplicaciones, construir pipelines RAG, trabajar con bases de datos vectoriales, implementar servidores MCP o diseñar patrones de comunicación y orquestación de agentes. Actívala con palabras clave como: agente, LLM, RAG, embeddings, vector DB, orquestación, uso de herramientas, memoria, clarificación de intención, MCP, LangChain, LangGraph, CrewAI, AutoGen, Microsoft Agent Framework.
Diseño de Agentes de IA
Filosofía Principal
Los agentes no son magia: son sistemas con entradas, salidas, memoria, herramientas y lógica de decisión. Diséñalos con el mismo rigor que cualquier software de producción. Cada agente debe tener un propósito claro, límites definidos y modos de fallo explícitos.
Principios de Diseño de Agentes
1. Clarificar la Intención Antes de Actuar
Un agente debe hacer preguntas aclaratorias cuando la intención del usuario sea ambigua — antes de ejecutar cualquier acción irreversible. Utiliza este patrón:
- ¿El objetivo es claro? Si no, haz una pregunta enfocada.
- ¿Se conocen las restricciones? (alcance, formato de salida, fuentes de datos)
- ¿Cómo se ve el éxito?
2. Especificación Antes del Código
Antes de escribir lógica de agente, genera un archivo de especificaciones o lista de tareas:
- Define el rol y las responsabilidades del agente
- Enumera todas las herramientas a las que necesita acceder
- Define los contratos de entrada/salida
- Identifica modos de fallo y comportamiento de respaldo
- Luego escribe el código
3. Responsabilidad Única
Cada agente debe hacer bien una sola cosa. Prefiere un equipo de agentes especializados sobre un solo agente de propósito general.
Patrones de Orquestación
| Patrón | Cuándo Usarlo | Descripción |
|---|---|---|
| Secuencial | Pipelines lineales | Los agentes se encadenan en orden fijo (borrador → revisión → publicación) |
| Supervisor | Tareas complejas multi-módulo | El agente líder enruta hacia trabajadores especializados |
| ReAct | Resolución autónoma de problemas | Combina razonamiento (Pensamiento) + acción (Uso de Herramientas) |
| Chat Grupal | Tareas colaborativas | Comunicación multi-agente con supervisión humana |
| DAG | Flujos de trabajo con estado | Grafo acíclico dirigido para orquestación cíclica y con estado |
Guía de Selección de Frameworks
| Framework | Mejor Para | Estado |
|---|---|---|
| LangGraph | Agentes complejos con estado, flujos de trabajo cíclicos, orquestación multi-agente, producción | ✅ Activo — GA Mayo 2025 |
| LangChain | Pipelines RAG simples, flujos de trabajo lineales, prototipos rápidos | ✅ Activo — usar para RAG, no para agentes |
| CrewAI | Equipos multi-agente basados en roles ("Gerente", "Investigador", "Escritor") | ✅ Activo |
| Microsoft Agent Framework | Agentes empresariales en el ecosistema Azure — reemplaza AutoGen + Semantic Kernel | ✅ Activo — Vista Pública Oct 2025, GA prevista Q1 2026 |
| AutoGen | Heredado — aún funciona pero sin nuevas características | ⚠️ Modo mantenimiento desde Oct 2025 |
| Personalizado (MCP) | Herramientas de agente ligeras, portátiles e interoperables mediante estándar abierto | ✅ Activo |
LangChain vs LangGraph — Cuál Usar
El equipo de LangChain ahora recomienda explícitamente esta división:
- LangGraph → para agentes: con estado, cíclicos, multi-agente, tareas de larga duración
- LangChain → para RAG y pipelines lineales: preguntas y respuestas simples sobre documentos, transformaciones paso a paso
LangGraph está construido sobre LangChain — puedes usar ambos juntos, comenzando con LangChain y recurriendo a LangGraph cuando necesites más control.
Diseño de Pipelines RAG
Flujo RAG Estándar
Consulta de Usuario → Embedding de Consulta → Búsqueda Vectorial → Recuperar Fragmentos → Aumentar Prompt → LLM → Respuesta
Estrategia de Fragmentación (Mejores Prácticas 2026)
- Usa fragmentación semántica — divide por significado, no por cantidad de caracteres
- Tamaño de fragmento: 256–512 tokens para precisión; 1024 para contenido narrativo
- Incluye siempre metadatos: fuente, página, sección, marca de tiempo
Búsqueda Híbrida (Recomendada)
Combina vectores densos (semánticos) + vectores dispersos (palabras clave) para la mejor recuperación:
Puntuación Final = α × Puntuación Densa + (1 - α) × Puntuación Dispersa
Selección de Base de Datos Vectorial
| BD | Mejor Para |
|---|---|
| pgvector | Stack PostgreSQL existente, casos de uso simples |
| Pinecone | Gestionado, escala de producción, mínima operación |
| Weaviate | Multimodal, búsqueda híbrida incorporada |
| Milvus | Alto rendimiento, auto-alojado, gran escala |
| Chroma | Desarrollo local, prototipado |
Arquitectura de Memoria del Agente
| Tipo | Descripción | Implementación |
|---|---|---|
| En contexto | Ventana de conversación actual | Arreglo de historial de chat |
| Externa a corto plazo | Memoria con alcance de sesión | Redis / almacenamiento en memoria |
| Externa a largo plazo | Persistente entre sesiones | BD Vectorial + metadatos |
| Episódica | Interacciones pasadas resumidas | Cadena de resumen → almacén vectorial |
Advertencia de Rotación de Contexto: Las ventanas largas de contexto degradan la calidad del agente con el tiempo. Implementa un paso de resumen cada N turnos para mantener la relevancia.
Uso de Herramientas y Llamadas a Funciones
Patrón de Definición de Herramienta
Cada herramienta necesita:
name: nombre_descriptivo_herramienta
description: Cuándo usar esta herramienta y qué hace (sé explícito)
parameters:
- name: nombre_parametro
type: string
description: Qué espera este parámetro
required: true
Mejores Prácticas de Uso de Herramientas
- Las herramientas deben ser idempotentes cuando sea posible
- Siempre valida las salidas de las herramientas antes de pasarlas al siguiente paso
- Implementa tiempos de espera y reintentos para llamadas a herramientas externas
- Registra todas las invocaciones de herramientas para depuración
Patrones de Comunicación entre Agentes
Protocolo de Clarificación de Intención
Cuando un agente recibe una solicitud ambigua:
- Identifica la ambigüedad — ¿qué específicamente no está claro?
- Haz una pregunta — la más importante, no todas
- Propón un valor por defecto — "Asumiré X a menos que me indiques lo contrario"
- Confirma antes de acciones irreversibles — pregunta siempre antes de eliminar, publicar o enviar
Reporte de Progreso
Para tareas de larga duración, los agentes deben informar:
[Paso 1/4] Obteniendo documentos... ✓
[Paso 2/4] Fragmentando y generando embeddings... ✓
[Paso 3/4] Consultando el almacén vectorial...
Comunicación de Errores
✗ Herramienta falló: [nombre_herramienta]
Razón: [error específico]
Respaldo: [lo que estoy haciendo en su lugar]
MCP (Model Context Protocol)
MCP es el estándar abierto para conectar agentes a herramientas y fuentes de datos externas. Úsalo al construir herramientas de agente portátiles e interoperables.
Estructura del Servidor MCP
mi-servidor-mcp/
├── server.py (o index.ts)
├── tools/
│ └── mi_herramienta.py
└── README.md
Cuándo Usar MCP vs Integración Directa
- Usa MCP cuando la herramienta necesite ser reutilizable en múltiples agentes/plataformas
- Usa integración directa para implementaciones de herramientas específicas de un proyecto y de un solo uso
Consulta la habilidad mcp-builder para obtener orientación detallada sobre la implementación de servidores MCP.
Seguridad
- Nunca permitas que los agentes ejecuten código arbitrario sin entorno aislado
- Implementa limitación de velocidad en todas las llamadas API de LLM
- Valida y sanitiza todas las entradas antes de pasarlas a las herramientas
- Registra todas las decisiones del agente para fines de auditoría
- Implementa barreras de protección para evitar costos excesivos de tokens o bucles recursivos
- Usa protección contra inyección en el prompt del sistema — separa la entrada del usuario de las instrucciones del sistema con delimitadores claros
Diseño de Agentes Resilientes (Autocuración)
Los agentes fallan en producción. Diseña para la recuperación desde el principio.
Bucle de Validación y Reintento (Patrón LoopAgent)
Generar salida → Validar salida → Si inválida: retroalimentación + regenerar
Iteraciones máximas: 3 ← disyuntor para evitar bucles infinitos
Planificar–Validar–Ejecutar–Observar–Replanificar
PLANIFICAR: Generar plan, verificar viabilidad antes de actuar
EJECUTAR: Tomar acción
OBSERVAR: ¿Tuvo éxito? Verificar salidas, ejecutar pruebas
REPLANIFICAR: Si la observación muestra fallo → ajustar y reintentar
DETENER: Si se alcanzan los reintentos máximos → informar del fallo claramente, pedir ayuda
Jerarquía de Respaldo del Agente
El enfoque principal falla → Probar enfoque alternativo
El enfoque alternativo falla → Solicitar aclaración al desarrollador
Sin aclaración → Acción segura por defecto o detención controlada
Validación de Salidas Antes de Presentar
- Ejecuta pruebas/linting sobre el código generado antes de presentarlo
- Verifica que el formato de salida cumpla con los requisitos
- Usa un paso validador separado (con un modelo o prompt diferente) para comprobar la salida del generador
- Nunca presentes salida no verificada como terminada
Disyuntor para Agentes
Establece límites estrictos para evitar comportamientos desbocados:
- Iteraciones máximas de llamadas a herramientas por tarea (ej. 10)
- Gasto máximo de tokens por sesión
- Reintentos máximos por paso fallido (ej. 3)
- Tiempo de espera por invocación de herramienta
Consulta la habilidad self-healing-mindset para la filosofía completa de resiliencia y patrones de código.