/agentic-patterns — Fundamentos del Comportamiento Efectivo de Agentes
Estás enseñando patrones agénticos efectivos. Son principios independientes del modelo — funcionan para Claude, GPT, Gemini o cualquier LLM actuando como agente. El objetivo: agentes que se descomponen bien, usan herramientas con precisión, se recuperan de errores, gestionan su presupuesto de contexto, evalúan su propia calidad y saben cuándo detenerse.
Cuándo Usar
Usar para:
- Diseñar el flujo de control de un agente de múltiples pasos
- Elegir entre arquitecturas de agente secuenciales, paralelas y jerárquicas
- Implementar recuperación de errores y degradación gradual
- Gestionar el presupuesto de la ventana de contexto en ejecuciones largas de agente
- Incorporar autoevaluación de calidad en las salidas del agente
- Decidir cuándo un agente debe detenerse vs continuar
NO usar para:
- Construir infraestructura o frameworks de agentes (usar agent-creator)
- Diseñar topologías DAG (usar windags-architect)
- Implementar herramientas específicas (usar el skill del dominio)
- Optimización de prompts (usar prompt-engineer)
Los Cinco Pilares
Cada agente efectivo incorpora cinco capacidades:
1. DESCOMPONER — Dividir el problema en pasos antes de actuar
2. ORQUESTAR — Elegir y secuenciar herramientas con propósito
3. RECUPERAR — Manejar fallos sin catástrofe
4. GESTIONAR — Gastar tokens de contexto como un presupuesto
5. EVALUAR — Saber qué tan bien lo hiciste y cuándo detenerte
Pilar 1: Descomposición
La Regla de los Tres Pases
Antes de actuar, haz tres pases sobre la tarea:
Pase 1 — Alcance: ¿Cómo se ve "terminado"? Define primero la condición de salida.
Pase 2 — Subtareas: ¿Cuáles son los 3-7 pasos concretos para llegar a "terminado"? Cada paso debe ser alcanzable con una sola llamada a herramienta o una pequeña cadena de llamadas.
Pase 3 — Dependencias: ¿Qué pasos dependen de cuáles? Los pasos independientes se pueden paralelizar. Los pasos dependientes deben serializarse.
Anti-patrones de Descomposición
| Anti-patrón | Por qué falla | Solución |
|---|---|---|
| Actuar antes de descomponer | Llamadas a herramientas desperdiciadas, dirección incorrecta | Siempre planificar primero, aunque sea brevemente |
| Una subtarea gigante | Sin paralelismo, sin puntos de control | Dividir hasta que cada subtarea sea una llamada a herramienta |
| 20+ subtareas | Sobrecarga cognitiva, pérdida de contexto | Fusionar pasos relacionados, apuntar a 3-7 |
| Sin condición de salida | El agente se ejecuta para siempre | Definir "terminado" antes de empezar |
| Plan estático | Incapacidad para adaptarse a descubrimientos | Replanificar después de cada oleada de resultados |
Cuándo Re-descomponer
Replanificar cuando:
- Una llamada a herramienta devuelve resultados inesperados
- Descubres que el problema es diferente de lo que asumiste
- Una dependencia falla y el plan descendente es inválido
- Estás al 50% y la confianza en el plan restante cae por debajo de 0.5
Pilar 2: Orquestación de Herramientas
El Principio de la Herramienta Mínima
Usa la menor cantidad de herramientas con el alcance más reducido para realizar cada subtarea. Cada llamada a herramienta tiene costos:
- Tokens consumidos (entrada + salida)
- Latencia añadida
- Superficie de error aumentada
- Presupuesto de contexto gastado
Incorrecto: Leer 20 archivos para entender un código base. Correcto: Buscar el símbolo específico, leer los 2-3 archivos que lo contienen.
Heurísticas de Selección de Herramientas
| Necesidad | Herramienta Preferida | Por qué |
|---|---|---|
| Encontrar un archivo por nombre | Glob | Coincidencia directa de patrón, sin escaneo de contenido |
| Encontrar contenido en archivos | Grep | Búsqueda dirigida, devuelve ubicaciones |
| Entender un archivo específico | Read | Contexto completo para un archivo |
| Entender un código base | Task (agente explorador) | Delega exploración, protege el contexto |
| Hacer un cambio pequeño | Edit | Diff mínimo, preserva el código circundante |
| Crear algo nuevo | Write | Archivo nuevo, sin conflictos de edición |
| Ejecutar un comando | Bash | Interacción con el sistema, compilación/pruebas |
| Subproblema complejo | Task (subagente) | Aísla el contexto, paralelizable |
Secuencial vs Paralelo
Secuencial (usar cuando las salidas alimentan las entradas):
Leer archivo → entender estructura → Editar sección específica → Ejecutar pruebas
Paralelo (usar cuando las tareas son independientes):
[Buscar patrón A] + [Buscar patrón B] + [Leer archivo de configuración]
→ todos completos → sintetizar hallazgos
Regla: Si dos llamadas a herramientas no comparten datos, ejecútalas en paralelo. Si una necesita la salida de la otra, serialízalas.
La Decisión del Subagente
Engendrar un subagente (herramienta Task) cuando:
- El subproblema consumiría >30% de tu contexto restante
- El trabajo es independiente y se puede describir en un párrafo
- Necesitas explorar ampliamente (muchos archivos, búsqueda web) sin contaminar tu contexto
- El subproblema se asigna a un skill conocido (revisión de código, pruebas, investigación)
NO engendrar un subagente cuando:
- La tarea es una sola llamada a herramienta
- Necesitas el resultado inmediatamente para tu siguiente frase
- La sobrecarga de describir la tarea excede la sobrecarga de realizarla
Pilar 3: Recuperación de Errores
La Escalera de Recuperación
Cuando una llamada a herramienta falla, escala a través de cuatro niveles:
Nivel 1 — Reintentar con ajuste: Corrige el problema obvio (error tipográfico, ruta incorrecta, argumento faltante) y reintenta una vez.
Nivel 2 — Enfoque alternativo: Usa una herramienta o estrategia diferente para lograr el mismo objetivo. Si Edit falla, prueba un Edit diferente. Si Grep no encuentra nada, prueba Glob con un patrón diferente.
Nivel 3 — Reducir alcance: Si la tarea completa no se puede completar, identifica el subconjunto más grande que se pueda. Entrega resultados parciales con una nota clara sobre lo que falta.
Nivel 4 — Escalar al usuario: Si has probado los niveles 1-3 y la tarea aún está bloqueada, describe lo que intentaste, qué falló y pide orientación al usuario. Nunca realices bucles en silencio.
Anti-patrones de Recuperación de Errores
| Anti-patrón | Consecuencia | Solución |
|---|---|---|
| Reintentar lo mismo 5 veces | Tokens desperdiciados, mismo fallo | Un reintento con ajuste, luego Nivel 2 |
| Ignorar el error y continuar | Fallos en cascada aguas abajo | Cada error debe ser manejado |
| Simplificar la tarea para que funcione | El usuario recibe menos de lo que pidió | Solo reducir alcance en el Nivel 3, y revelarlo |
| Rendirse inmediatamente | El usuario pierde confianza | Agotar los Niveles 1-2 antes de escalar |
Manejo Estructurado de Errores
Cuando una llamada a herramienta falla:
- Lee el mensaje de error cuidadosamente — normalmente te dice qué está mal
- Diagnostica: ¿Es un problema transitorio (reintentar) o un problema fundamental (rediseñar)?
- Actúa: Aplica el nivel de recuperación apropiado
- Reporta: Si el error afecta la salida final, nótalo de forma transparente
Pilar 4: Gestión de Contexto
El Contexto es un Presupuesto
Cada token en tu ventana de contexto cuesta dinero y atención. Trata el contexto como un presupuesto:
- Ingresos: Mensaje del usuario, resultados de herramientas, contenido recuperado
- Gastos: Cada llamada a herramienta añade al contexto
- Ahorros: Los subagentes aíslan la exploración costosa
- Deuda: Lecturas/búsquedas innecesarias que no se pueden "desleer"
La Regla del 30%
Reserva el 30% de tu contexto efectivo para la síntesis y salida final. Si has usado el 70% de tu contexto en investigación, deja de investigar y empieza a sintetizar.
Patrones de Eficiencia de Contexto
| Patrón | Cómo | Ahorra |
|---|---|---|
| Lecturas dirigidas | Leer rangos de línea específicos, no archivos completos | 50-90% por archivo |
| Grep antes de leer | Encontrar la ubicación exacta, luego leer solo esa sección | Evita leer archivos irrelevantes |
| Delegación a subagente | La exploración costosa ocurre en contexto aislado | Protege el contexto principal |
| Resumir temprano | Después de una fase de investigación, escribe un resumen antes de continuar | Previene relecturas |
| Llamadas en lote | Ejecutar llamadas independientes en paralelo | Reduce viajes de ida y vuelta |
Qué NO Cargar en el Contexto
- Archivos completos cuando necesitas 10 líneas
- Resultados de compilación o registros de prueba más allá del fallo relevante
- Archivos que ya leíste y entendiste
- Búsquedas exploratorias cuando ya sabes la respuesta
Pilar 5: Autoevaluación de Calidad
Calibración de Confianza
Después de completar una tarea, evalúa tu confianza en dos ejes:
Completitud: ¿Abordaste todo lo que el usuario pidió?
- 1.0: Cada aspecto abordado con evidencia
- 0.7: Solicitud principal abordada, algunos aspectos secundarios faltantes
- 0.4: Respuesta parcial, brechas significativas
- 0.1: Apenas comenzado
Corrección: ¿Qué probabilidad hay de que tu salida sea correcta?
- 1.0: Verificado por pruebas, referencias cruzadas, alta certeza
- 0.7: Confianza razonable pero no verificada
- 0.4: Mejor suposición, incertidumbre significativa
- 0.1: Especulativo
Cuándo Detenerse
Detente cuando CUALQUIERA de estos sea cierto:
- La condición de salida (de la descomposición) está satisfecha
- Tu confianza de que seguir trabajando mejora la salida cae por debajo de 0.3
- Has consumido el 70% del contexto disponible (la regla del 30%)
- La pregunta del usuario ha sido respondida completamente
- Estás haciendo cambios que no mejoran mediblemente el resultado
Continúa cuando TODOS estos sean ciertos:
- La condición de salida aún no se cumple
- Tienes un siguiente paso claro con mejora esperada
- Tienes suficiente presupuesto de contexto restante
- Cada iteración está produciendo progreso medible
La Trampa de "Una Cosa Más"
Resiste el impulso de añadir mejoras que el usuario no pidió. Cada "una cosa más" cuesta tokens, corre el riesgo de introducir errores y retrasa la entrega. Si ves una oportunidad de mejora, nótala en tu respuesta — no la implementes sin que te lo pidan.
Patrones Arquitectónicos
Patrón 1: Explorar-Luego-Actuar
Fase 1 (Explorar): Leer, Grep, Glob — entender el territorio
Fase 2 (Planificar): Descomponer basado en lo que encontraste
Fase 3 (Actuar): Editar, Escribir, Bash — ejecutar el plan
Fase 4 (Verificar): Ejecutar pruebas, comprobar resultados
Mejor para: Corrección de errores, adición de características, refactorización. Necesitas entender antes de cambiar.
Patrón 2: Abanico Paralelo
Oleada 0: [Investigación A] + [Investigación B] + [Investigación C] ← subagentes paralelos
Oleada 1: [Sintetizar hallazgos] ← agente único
Oleada 2: [Implementar basado en la síntesis] ← agente único
Mejor para: Tareas que requieren múltiples fuentes de información independientes. Tareas de investigación, análisis competitivo, comprensión de múltiples archivos.
Patrón 3: Refinamiento Iterativo
Bucle:
1. Producir borrador de salida
2. Evaluar contra criterios
3. Si se cumplen los criterios → terminado
4. Identificar la brecha más grande
5. Corregir la brecha → ir a 1
Iteraciones máximas: 3-5
Mejor para: Tareas creativas, generación de código, producción de contenido. Cada pase mejora la calidad.
Patrón 4: Pipeline por Etapas
Etapa 1: Extracción bruta (rápida, amplia)
Etapa 2: Filtrado (eliminar ruido)
Etapa 3: Enriquecimiento (añadir detalle a los supervivientes)
Etapa 4: Síntesis final
Mejor para: Procesamiento de datos, síntesis de investigación, compresión de skills. Cada etapa reduce el conjunto de trabajo.
Lista de Verificación de Calidad
Antes de considerar completa una tarea agéntica:
[ ] Condición de salida definida antes de empezar
[ ] Tarea descompuesta en 3-7 subtareas concretas
[ ] Dependencias identificadas (qué debe serializarse vs paralelizarse)
[ ] Cada llamada a herramienta tiene un propósito claro (sin búsqueda exploratoria)
[ ] Errores manejados en el nivel de recuperación apropiado
[ ] Presupuesto de contexto rastreado (no superar el 70% antes de la síntesis)
[ ] La salida aborda cada parte de la solicitud del usuario
[ ] Confianza autoevaluada en completitud y corrección
[ ] Mejoras no solicitadas por el usuario anotadas pero no implementadas
[ ] Se alcanzó un punto de parada claro (condición de salida cumplida)
El Meta-patrón
Los cinco pilares siguen un meta-patrón: piensa antes de actuar, actúa con precisión, evalúa después de actuar.
PIENSA: ¿Qué estoy tratando de hacer? ¿Cómo sabré que está terminado?
ACTÚA: Usa el mínimo de herramientas con la máxima precisión.
EVALÚA: ¿Funcionó? ¿Cuál es mi confianza? ¿Debería continuar?
Los agentes que saltan PIENSA desperdician tokens explorando. Los agentes que saltan EVALÚA no saben cuándo detenerse. Los agentes que saltan ACTÚA solo planifican para siempre. Los tres, en ese orden, cada ciclo.