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
• Implementar funcionalidades con llamadas a herramientas, memoria o flujos de trabajo de varios pasos
• El comportamiento del agente se degrada después de añadir capas de envoltorio
• El usuario informa que "el agente está empeorando" o "las herramientas son inestables"
• El mismo modelo funciona en el playground pero falla dentro de tu envoltorio
• Depurar el comportamiento del agente durante más de 15 minutos sin encontrar la causa raíz

Especialmente crítico cuando:

• Has añadido nuevas capas de prompt, definiciones de herramientas o sistemas de memoria
• Diferentes agentes en tu sistema se comportan de manera inconsistente
• El modelo funcionaba bien ayer pero hoy está alucinando
• Sospechas de bucles de reparación/reintento ocultos que mutan silenciosamente las respuestas

No usar para:

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

La Pila de 12 Capas

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

#	Capa	Qué Sale Mal
1	Prompt del sistema	Instrucciones conflictivas, 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 nuevas conversaciones
4	Destilación	Artefactos comprimidos que reingresan como pseudofactos
5	Recuerdo activo	Capas de resumen redundantes que desperdician contexto
6	Selección de herramientas	Enrutamiento incorrecto de herramientas, 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 malinterpretada 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 mutan 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 activa

Patrones de Fallo 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 la llamada directa a la API, pero falla en tu agente
• Se añadió una nueva capa de prompt y el comportamiento existente se degradó
• El agente suena seguro pero está seguramente equivocado
• "Funcionaba antes de la última actualización"

2. Contaminación de Memoria

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

Síntomas:

• El agente saca a relucir 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 pseudofactos
• La memoria crece sin límite, degradando la calidad de la respuesta con el tiempo

3. Fallo de Disciplina de Herramientas

Las herramientas se declaran en el prompt pero no se aplican 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 debe, o la omite cuando es obligatoria

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 rota
• El renderizado de 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 "autocorrecció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" mediante capas invisibles

Flujo de Trabajo de Auditoría

Fase 1: Alcance

Define lo que estás auditando:

• Sistema objetivo — ¿qué aplicación de agente?
• Puntos de entrada — ¿cómo interactúan los usuarios con ella?
• Pila de modelos — ¿qué LLM(s) 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

Recopila evidencia del código base:

• Código fuente — bucle del agente, enrutador de herramientas, admisión de memoria, ensamblaje de prompts
• Registros — trazas históricas de sesiones, 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

Usa rg para buscar antipatrones:

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

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

# Llamadas LLM ocultas 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 LLM adicionales
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, documenta:

• 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 predeterminado (primero código, no primero prompt):

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

Modelo de Gravedad

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 suele sobrevivir 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

Presenta los hallazgos al usuario en este orden:

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

No comiences con cumplidos o resúmenes. Si el sistema está roto, dilo directamente.

Preguntas de Diagnóstico Rápido

Al auditar un sistema de agente, responde estas preguntas:

#	Pregunta	Si Sí →
1	¿Puede el modelo omitir una herramienta requerida y aun así responder?	Herramienta no aplicada en código
2	¿Aparece contenido de conversaciones anteriores en nuevos turnos?	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 herramienta X" solo en el texto del prompt?	Fallo de disciplina de herramientas
7	¿Puede el propio monólogo del agente convertirse en memoria persistente?	Envenenamiento de memoria

Antipatrones a Evitar

• Evita culpar al modelo antes de falsificar regresiones de las capas de envoltorio.
• Evita culpar a la memoria sin mostrar la ruta de contaminación.
• No permitas que un estado actual limpio borre un incidente histórico sucio.
• No trates la prosa Markdown como un protocolo interno de confianza.
• No aceptes "debe usar herramienta" en el texto del prompt cuando el código nunca lo aplica.
• Mantén los hallazgos directos, respaldados por evidencia y ordenados por gravedad.

Esquema del 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 — Depura fallos en tiempo de ejecución del agente (bucles, tiempos de espera, errores de estado)
• agent-eval — Evalúa el rendimiento de agentes cara a cara
• security-review — Auditoría de seguridad para código y configuración
• autonomous-agent-harness — Configura operaciones de agentes autónomos
• agent-harness-construction — Construye arneses de agentes desde cero