Manejo de Transcript Hygiene: Cómo limpiar tus historiales de chat

¿Alguna vez te ha pasado que una API rechaza tu petición porque el historial de mensajes no tiene el formato exacto que el modelo espera? Es frustrante cuando un pequeño error en el orden de los turnos o un ID de herramienta mal formateado rompe toda la ejecución de tu agente.

Este proceso de limpieza, llamado Transcript Hygiene, aplica correcciones en memoria antes de construir el contexto del modelo. Esto asegura que los datos cumplan con las reglas estrictas de cada Provider sin modificar permanentemente tus archivos JSONL en el disco, a menos que sea necesario reparar un archivo corrupto al cargarlo.

Requisitos previos

• Acceso a los archivos de configuración en src/agents/transcript-policy.ts.
• Uso de los Providers soportados (OpenAI, Google, Anthropic, Mistral u OpenRouter).

Inicio rápido

El sistema aplica estas correcciones automáticamente en el runner embebido. Aquí tienes cómo funciona el flujo en menos de 5 minutos:

1. Selección de política: El sistema revisa el provider, modelApi y modelId en src/agents/transcript-policy.ts para decidir qué reglas aplicar.
2. Saneamiento en memoria: Se ejecuta la función sanitizeSessionHistory antes de enviar los mensajes al modelo.
3. Reparación de archivos: Si un archivo de sesión está malformado, repairSessionFileIfNeeded elimina las líneas inválidas antes de cargarlo y crea un backup del original.

Reglas Globales

Independientemente del Provider, siempre se aplican estas dos reglas:

• Imágenes: Se ajusta el tamaño o se recomprime cualquier imagen en base64 que exceda los límites para evitar rechazos.
• Tool calls malformados: Si un bloque de asistente pide usar una herramienta pero le falta el input o los arguments, el bloque se elimina para evitar errores de validación.

Provider Matrix

Cada Provider tiene requisitos distintos que el sistema maneja de forma específica:

Provider	Acciones de Hygiene
OpenAI / Codex	Solo saneamiento de imágenes. Si cambias de modelo a OpenAI, se eliminan fragmentos de razonamiento (reasoning) huérfanos.
Google (Gemini)	Limpieza estricta de IDs de herramientas (alfanumérico), reparación de pares de resultados de herramientas y validación de alternancia de turnos.
Anthropic / Minimax	Reparación de pares de resultados de herramientas y fusión de turnos consecutivos del usuario para mantener la alternancia.
Mistral	Saneamiento de IDs de herramientas siguiendo la regla strict9 (alfanumérico de longitud 9).
OpenRouter Gemini	Limpieza de firmas de pensamiento: se eliminan valores de thought_signature que no sean base64.

Si usas cualquier otro Provider, el sistema solo aplicará el saneamiento de imágenes por defecto.

Solución de problemas

Si encuentras problemas con el historial, estas son las soluciones integradas:

• Error por imágenes pesadas: El sistema usa sanitizeSessionMessagesImages para reducir la escala automáticamente antes de enviarlas.
• Fallo en el orden de turnos (Google): Si el historial comienza con un turno del asistente, el sistema añade un pequeño prefijo de usuario (bootstrap) para corregir el orden.
• IDs de herramientas inválidos: Los IDs se limpian para ser puramente alfanuméricos según el Provider, evitando errores de sintaxis en la API.
• Archivos JSONL corruptos: Si el archivo en disco tiene líneas inválidas, el reparador las descarta y guarda una copia de seguridad del archivo original.

Para resolver dudas específicas sobre tu configuración, consulta al AI Setup Assistant.

Próximos pasos

• /reference/session-management-compaction