¿Qué hace agenttrace Auditoría de Sesiones?
Descripción General
Usa este skill para inspeccionar sesiones locales de agentes de codificación de IA con agenttrace. Se enfoca en el proceso detrás de una ejecución: picos de tokens y costos, fallos de herramientas, bucles de reintento, brechas de latencia, anomalías, puntuaciones de salud y diferencias entre sesiones.
agenttrace es local-first y lee registros de sesiones de herramientas como Claude Code, Codex CLI, Gemini CLI, Aider, exportaciones de Cursor, OpenCode, Qwen Code, Kimi y rastros JSON o JSONL genéricos.
Cuándo Usar Este Skill
- Úsalo cuando un usuario pregunte por qué una ejecución de IA fue lenta, costosa, superficial o poco fiable.
- Úsalo al revisar registros de agentes locales antes de reintentar una tarea fallida o sospechosa.
- Úsalo al construir una puerta de salud ligera en CI para sesiones de codificación asistida por IA.
- Úsalo al comparar dos intentos y buscar cambios en rutas de herramientas, reintentos o patrones de costos.
Cómo Funciona
Paso 1: Descubrir Sesiones Disponibles
Prefiere un binario agenttrace instalado cuando esté disponible en PATH. Si el
repositorio actual es luoyuctl/agenttrace, usa go run ./cmd/agenttrace en su lugar.
agenttrace --doctor
agenttrace --overview
Si no se detectan sesiones, informa los directorios verificados por --doctor y
pide el archivo de sesión exportado o el directorio de registros.
Paso 2: Producir una Auditoría Legible por Humanos
Usa Markdown cuando el usuario quiera un informe conciso que pueda inspeccionar o compartir.
agenttrace --overview -f markdown -o agenttrace-overview.md
En el informe, comienza con las sesiones de mayor riesgo y explica por qué son importantes: anomalías críticas, fallos repetidos de herramientas, desperdicio de tokens o costos, largas brechas de latencia, puntuaciones de salud bajas y sesiones sospechosamente superficiales.
Paso 3: Inspeccionar una Sesión o Directorio
Usa la sesión más reciente para una verificación rápida, o pasa una ruta de exportación explícita cuando el usuario la proporcione.
agenttrace --latest
agenttrace --latest -f json
agenttrace ruta/a/sesion-o-exportacion.json
agenttrace --overview -d ruta/al/directorio-de-sesion
Paso 4: Comparar Intentos Cuando la Semántica Importa
Las métricas de tokens y latencia pueden verse saludables incluso cuando un agente toma con confianza la ruta de implementación incorrecta. Cuando el riesgo es deriva semántica, combina la auditoría de rastros con un diff contra un intento anterior o conocido como bueno.
Busca:
- archivos o comandos cambiados que se desvíen de la tarea prevista
- pruebas o pasos de verificación faltantes en comparación con el intento de referencia
- ediciones repetidas alrededor de los mismos archivos sin una razón clara
- menor costo que provino de saltar la exploración necesaria
Paso 5: Agregar Puertas de Automatización
Para flujos de trabajo de CI o de equipo repetibles, usa salida JSON o umbrales de salud.
agenttrace --overview -f json -o agenttrace-overview.json
agenttrace --overview --fail-under-health 80 --fail-on-critical --max-tool-fail-rate 15
Ajusta los umbrales al proyecto. Una puerta estricta es útil para flujos de trabajo críticos; un comando solo de reporte es mejor mientras el equipo aprende su línea base.
Ejemplos
Revisión Local Rápida
agenttrace --overview
agenttrace --latest
Usa esto después de una ejecución larga de un agente de codificación para decidir si el siguiente prompt debería dividir la tarea, evitar una ruta de herramientas fallida, agregar pruebas faltantes o restablecer el contexto.
Verificación de Salud en CI
agenttrace --overview --fail-under-health 80 --fail-on-critical
Usa esto cuando los registros de sesiones del agente estén disponibles en CI y el equipo quiera una protección simple contra anomalías críticas o ejecuciones no saludables.
Mejores Prácticas
- Comienza con
--doctorcuando el descubrimiento de sesiones sea incierto. - Reporta los campos faltantes claramente; no inventes datos de costo, modelo, latencia o salud.
- Trata los prompts, el código y los contenidos de la sesión como datos locales privados.
- Prefiere salida JSON para automatización y salida Markdown para revisión humana.
- Usa métricas de rastreo para fallos de proceso y revisión de diff/referencia para deriva semántica.
Limitaciones
- agenttrace solo puede analizar registros que estén presentes localmente o proporcionados como exportaciones.
- Algunos agentes no exponen suficientes campos para inferir costo, modelo, uso de caché o latencia.
- Las métricas de rastreo saludables no prueban que el código final sea correcto; aún así ejecuta pruebas y revisa los diffs.
- Las puertas de CI deberían comenzar como consultivas hasta que el equipo entienda el comportamiento normal de línea base.
Notas de Seguridad y Protección
- No subas registros de sesiones privados a servicios externos a menos que el usuario lo apruebe explícitamente.
- No sobrescribas informes de usuario a menos que hayan solicitado esa ruta de salida exacta.
- Evita imprimir secretos encontrados en prompts, salida de herramientas, variables de entorno o registros.
Errores Comunes
-
Problema: No se encuentran sesiones. Solución: Ejecuta
agenttrace --doctor, luego apunta agenttrace al archivo exportado o al directorio de registros. -
Problema: Una ejecución parece barata y rápida pero produjo la refactorización incorrecta. Solución: Compara la sesión con un intento anterior o un diff conocido como bueno; las métricas de costo por sí solas pasarán por alto la deriva semántica.
-
Problema: CI falla demasiado seguido después de agregar una puerta de salud. Solución: Comienza con informes en JSON o Markdown, inspecciona las líneas base normales, luego ajusta los umbrales gradualmente.
Skills Relacionados
@langfuse- Úsalo para rastreo y evaluación de aplicaciones LLM en producción.@observability-engineer- Úsalo para monitoreo de servicios más amplio, SLOs y flujos de trabajo de incidentes.