auditoría-de-arquitectura-de-agentes

Auditoría de Arquitectura de Agentes

Un flujo de trabajo de diagnóstico para sistemas de agentes que ocultan fallos tras capas de envoltorio, memoria obsoleta, bucles de reintento o mutaciones de transporte/renderizado.

Cuándo Activarlo

OBLIGATORIO para:

• Lanzar cualquier aplicación basada en agentes o LLM a producción
• Enviar funcionalidades con llamadas a herramientas, memoria o flujos de trabajo de múltiples pasos
• El comportamiento del agente se degrada después de agregar capas de envoltorio
• El usuario reporta "el agente está empeorando" o "las herramientas son inestables"
• El mismo modelo funciona en el playground pero falla dentro de su envoltorio
• Depurar el comportamiento del agente durante más de 15 minutos sin encontrar la causa raíz

Especialmente crítico cuando:

• Ha agregado nuevas capas de prompt, definiciones de herramientas o sistemas de memoria
• Diferentes agentes en su sistema se comportan de manera inconsistente
• El modelo funcionaba bien ayer pero hoy alucina
• Sospecha bucles de reparación/reintento ocultos que mutan silenciosamente las respuestas

No usar para:

• Depuración de código general — use agent-introspection-debugging
• Revisión de código — use agentes de revisión específicos del lenguaje
• Escaneo de seguridad — use security-review o security-review/scan
• Evaluación comparativa de rendimiento de agentes — use agent-eval
• Escribir nuevas funcionalidades — use la habilidad de flujo de trabajo adecuada

Las 12 Capas de la Pila

Cada sistema de agente tiene estas capas. Cualquiera de ellas puede corromper la respuesta:

#	Capa	Qué Sale Mal
1	Prompt del sistema	Instrucciones contradictorias, hinchazón de instrucciones
2	Historial de sesión	Inyección de contexto obsoleto de turnos anteriores
3	Memoria a largo plazo	Contaminación entre sesiones, temas antiguos en conversaciones nuevas
4	Destilación	Artefactos comprimidos que reingresan como pseudo-hechos
5	Recuerdo activo	Capas de resumen redundantes que desperdician contexto
6	Selección de herramientas	Enrutamiento de herramienta incorrecto, el modelo omite herramientas requeridas
7	Ejecución de herramientas	Ejecución alucinada — afirma llamar pero no lo hace
8	Interpretación de herramientas	Salida de herramienta mal leída o ignorada
9	Modelado de respuesta	Corrupción de formato en la respuesta final
10	Renderizado de plataforma	Mutación en la capa de transporte (UI, API, CLI muta respuestas válidas)
11	Bucles de reparación ocultos	Agentes de respaldo/reintento silenciosos que ejecutan una segunda pasada del LLM
12	Persistencia	Estado caducado o artefactos en caché reutilizados como evidencia en vivo

Patrones de Falla Comunes

1. Regresión por Envoltorio

El modelo base produce respuestas correctas, pero las capas de envoltorio lo empeoran.

Síntomas:

• El modelo funciona bien en el playground o en una llamada directa a la API, pero falla en su agente
• Agregó una nueva capa de prompt y el comportamiento existente se degradó
• El agente suena seguro pero está equivocado con seguridad
• "Funcionaba antes de la última actualización"

2. Contaminación de Memoria

Temas antiguos se filtran en conversaciones nuevas a través del historial, la recuperación de memoria o la destilación.

Síntomas:

• El agente menciona temas pasados no relacionados
• Las correcciones del usuario no se mantienen (la memoria antigua sobrescribe la nueva)
• Los artefactos de la misma sesión reingresan como pseudo-hechos
• La memoria crece sin límite, degradando la calidad de la respuesta con el tiempo

3. Falla de Disciplina de Herramientas

Las herramientas se declaran en el prompt pero no se imponen en el código. El modelo las omite o alucina su ejecución.

Síntomas:

• "Debe usar la herramienta X" en el prompt, pero el modelo responde sin llamarla
• Los resultados de la herramienta parecen correctos pero nunca se ejecutaron realmente
• Diferentes herramientas compiten por la misma responsabilidad
• El modelo usa la herramienta cuando no debería, o la omite cuando debe

4. Corrupción de Renderizado/Transporte

La respuesta interna del agente es correcta, pero la capa de plataforma la muta durante la entrega.

Síntomas:

• Los registros muestran la respuesta correcta, el usuario ve una salida incorrecta
• El renderizado Markdown, el análisis JSON o los fragmentos de streaming corrompen respuestas válidas
• Un agente de respaldo oculto reemplaza silenciosamente la respuesta antes de la entrega
• La salida difiere entre el terminal y la UI

5. Capas de Agente Ocultas

Agentes de reparación, reintento, resumen o recuerdo silenciosos se ejecutan sin contratos explícitos.

Síntomas:

• La salida cambia entre la generación interna y la entrega al usuario
• Los bucles de "auto-corrección" ejecutan una segunda pasada del LLM que el usuario desconoce
• Múltiples agentes modifican la misma salida sin coordinación
• Las respuestas se "suavizan" o "corrigen" por capas invisibles

Flujo de Trabajo de Auditoría

Fase 1: Alcance

Defina lo que está auditando:

• Sistema objetivo — ¿qué aplicación de agente?
• Puntos de entrada — ¿cómo interactúan los usuarios con ella?
• Pila de modelos — ¿qué LLM y proveedores?
• Síntomas — ¿qué reporta el usuario?
• Ventana de tiempo — ¿cuándo comenzó?
• Capas a auditar — ¿cuáles de las 12 capas aplican?

Fase 2: Recopilación de Evidencia

Recopile evidencia del código base:

• Código fuente — bucle del agente, enrutador de herramientas, admisión de memoria, ensamblaje de prompt
• Registros — trazas de sesiones históricas, registros de llamadas a herramientas
• Configuración — plantillas de prompt, esquemas de herramientas, configuraciones del proveedor
• Archivos de memoria — SOPs, bases de conocimiento, archivos de sesión

Use rg para buscar anti-patrones:

# Requisitos de herramientas expresados solo en texto de prompt (no en código)
rg "must.*tool|必须.*工具|required.*call" --type md

# Ejecución de herramientas sin validación
rg "tool_call|toolCall|tool_use" --type py --type ts

# Llamadas ocultas al LLM fuera del bucle principal del agente
rg "completion|chat\.create|messages\.create|llm\.invoke"

# Admisión de memoria sin prioridad de corrección del usuario
rg "memory.*admit|long.*term.*update|persist.*memory" --type py --type ts

# Bucles de respaldo que ejecutan llamadas adicionales al LLM
rg "fallback|retry.*llm|repair.*prompt|re-?prompt" --type py --type ts

# Mutación silenciosa de la salida
rg "mutate|rewrite.*response|transform.*output|shap" --type py --type ts

Fase 3: Mapeo de Fallos

Para cada hallazgo, documente:

• Síntoma — lo que ve el usuario
• Mecanismo — cómo lo causa el envoltorio
• Capa de origen — cuál de las 12 capas
• Causa raíz — la causa más profunda
• Evidencia — referencia de archivo:línea o registro:fila
• Confianza — 0.0 a 1.0

Fase 4: Estrategia de Corrección

Orden de corrección por defecto (código primero, no prompt primero):

1. Requisitos de herramientas en código — imponer en código, no solo en texto de prompt
2. Eliminar o acotar agentes de reparación ocultos — hacer explícito el respaldo con contratos
3. Reducir duplicación de contexto — misma información a través de prompt + historial + memoria + destilación
4. Ajustar admisión de memoria — correcciones del usuario > afirmaciones del agente
5. Ajustar disparadores de destilación — no comprimir lo que no debería comprimirse
6. Reducir mutación de renderizado — pasar a través, no transformar
7. Convertir a sobres JSON tipados — flujo interno estructurado, no prosa libre

Modelo de Severidad

Nivel	Significado	Acción
critical	El agente puede producir con confianza un comportamiento operativo incorrecto	Corregir antes del próximo lanzamiento
high	El agente degrada frecuentemente la corrección o estabilidad	Corregir en este sprint
medium	La corrección generalmente sobrevive pero la salida es frágil o derrochadora	Planificar para el próximo ciclo
low	Mayormente problemas cosméticos o de mantenibilidad	Backlog

Formato de Salida

Presente los hallazgos al usuario en este orden:

1. Hallazgos clasificados por severidad (más críticos primero)
2. Diagnóstico de arquitectura (qué capa corrompió qué y por qué)
3. Plan de corrección ordenado (código primero, no prompt primero)

No comience con cumplidos o resúmenes. Si el sistema está roto, dígalo directamente.

Preguntas de Diagnóstico Rápido

Al auditar un sistema de agente, responda estas:

#	Pregunta	Si Sí →
1	¿Puede el modelo omitir una herramienta requerida y aún así responder?	Herramienta no impuesta en código
2	¿Aparece contenido de conversación anterior en turnos nuevos?	Contaminación de memoria
3	¿Está la misma información en el prompt del sistema Y en la memoria Y en el historial?	Duplicación de contexto
4	¿Ejecuta la plataforma una segunda pasada del LLM antes de la entrega?	Bucle de reparación oculto
5	¿Difiere la salida entre la generación interna y la entrega al usuario?	Corrupción de renderizado
6	¿Están las reglas "debe usar la herramienta X" solo en texto de prompt?	Falla de disciplina de herramientas
7	¿Puede el monólogo del propio agente convertirse en memoria persistente?	Envenenamiento de memoria

Anti-Patrones a Evitar

• Evite culpar al modelo antes de falsificar las regresiones de las capas de envoltorio.
• Evite culpar a la memoria sin mostrar la ruta de contaminación.
• No permita que un estado actual limpio borre un incidente histórico sucio.
• No trate el texto Markdown como un protocolo interno confiable.
• No acepte "debe usar herramienta" en texto de prompt cuando el código nunca lo impone.
• Mantenga los hallazgos directos, respaldados por evidencia y clasificados por severidad.

Esquema de Informe

Las auditorías deben producir informes estructurados siguiendo esta forma:

{
  "schema_version": "ecc.agent-architecture-audit.report.v1",
  "executive_verdict": {
    "overall_health": "high_risk",
    "primary_failure_mode": "string",
    "most_urgent_fix": "string"
  },
  "scope": {
    "target_name": "string",
    "model_stack": ["string"],
    "layers_to_audit": ["string"]
  },
  "findings": [
    {
      "severity": "critical|high|medium|low",
      "title": "string",
      "mechanism": "string",
      "source_layer": "string",
      "root_cause": "string",
      "evidence_refs": ["file:line"],
      "confidence": 0.0,
      "recommended_fix": "string"
    }
  ],
  "ordered_fix_plan": [
    { "order": 1, "goal": "string", "why_now": "string", "expected_effect": "string" }
  ]
}

Habilidades Relacionadas

• agent-introspection-debugging — Depurar fallos en tiempo de ejecución del agente (bucles, tiempos de espera, errores de estado)
• agent-eval — Evaluar comparativamente el rendimiento del agente cara a cara
• security-review — Auditoría de seguridad para código y configuración
• autonomous-agent-harness — Configurar operaciones de agentes autónomos
• agent-harness-construction — Construir arneses de agente desde cero