Idea en 30 segundos
Replay para agentes de IA significa tomar una traza real problemática, reproducirla en condiciones controladas y encontrar la causa del fallo paso a paso.
Su valor principal es que el equipo no adivina la causa del incidente. Ve la cadena completa de decisiones del agente y el punto exacto donde el comportamiento se rompió.
Problema
Sin replay, los equipos suelen depurar "de memoria":
- miran solo la respuesta final del agente;
- no tienen el contexto completo de la solicitud;
- no ven resultados de llamadas de herramientas paso a paso.
En ese modo es difícil separar síntoma y causa. Los fixes se vuelven imprecisos y los incidentes regresan.
Consecuencias típicas:
- el error se corrige localmente, pero no se reproduce el escenario real de producción;
- después de la release aparece la misma clase de fallo;
- el equipo pierde tiempo en análisis manuales repetidos.
Cuándo usarlo
Replay se usa cuando:
- hubo un incidente en producción y hay que encontrar la root cause;
- tras cambio de modelo o prompt aparece un
diffinesperado en comportamiento; - una prueba de regression muestra caída de un caso crítico;
- hay que comprobar que un fix realmente cierra el escenario del incidente.
Replay es más útil en sistemas con comportamiento multi-paso del agente y herramientas externas.
Implementación
En práctica, replay sigue un principio: misma traza, mismas condiciones de ejecución, análisis paso a paso de decisiones. Los ejemplos de abajo son esquemáticos y no dependen de un framework concreto.
Cómo funciona en un análisis
Ciclo corto de análisis replay
- Traza - guardar input, contexto, pasos y respuestas de herramientas.
- Replay - reproducir el mismo escenario en entorno controlado.
- Timeline de pasos - revisar dónde el agente tomó la decisión incorrecta.
- Root cause - fijar causa técnica: prompt, modelo, herramienta o runtime.
- Fix y verificación - aplicar fix y confirmar con nueva ejecución.
1. Guardar traza con contexto completo
trace = {
"trace_id": "incident-2026-03-11-42",
"input": "Refund order #8472",
"conversation_state": {"user_tier": "pro"},
"steps": [
{"tool": "payments_api", "args": {"order_id": "8472"}, "result": {"status": "timeout"}},
{"tool": "fallback_policy", "args": {}, "result": {"action": "ask_for_retry"}}
],
"final_output": "Please try again later.",
"stop_reason": "fallback_used",
}
Sin traza completa, replay casi nunca reproduce la causa real del incidente.
2. Reproducir traza en las mismas condiciones
def replay_trace(agent, trace, runtime_config):
return agent.replay(
trace=trace,
model_version=runtime_config["model_version"],
tool_mocks=runtime_config["tool_mocks"],
timeout_sec=runtime_config["timeout_sec"],
)
Si cambian modelo, timeouts o condiciones de herramientas, el replay puede parecer falsamente seguro.
3. Analizar timeline paso a paso
def find_first_bad_step(replayed_steps):
return next(
((idx, step) for idx, step in enumerate(replayed_steps) if step["status"] == "unexpected"),
None,
)
El objetivo clave del debugging es encontrar el primer paso donde el sistema se desvía del escenario esperado.
4. Capturar root cause de forma estructurada
incident_report = {
"trace_id": "incident-2026-03-11-42",
"root_cause": "tool_timeout_not_handled_as_retryable",
"affected_component": "retry_policy",
"fix_plan": "treat payments timeout as retryable before fallback",
}
Una root cause estructurada simplifica la validación del fix y la transferencia de conocimiento en el equipo.
5. Añadir incidente al set de regression
def promote_to_regression_case(trace, report):
return {
"id": trace["trace_id"],
"input": trace["input"],
"expected_behavior": {"stop_reason": "resolved"},
"tags": ["incident", "replay", report["affected_component"]],
}
Después del análisis replay, el caso debe entrar en regression o golden dataset; de lo contrario, el incidente puede repetirse.
Errores típicos
Traza de incidente incompleta
En logs está la respuesta final, pero faltan pasos del agente y resultados de herramientas.
Causa típica: se guarda solo summary, sin detalles step-level.
Replay en condiciones runtime distintas
La traza se reproduce con otro modelo o con parámetros timeout/retry diferentes.
Causa típica: no se fijan las condiciones runtime del incidente.
Debugging solo del texto final
El equipo analiza solo la última respuesta y pierde la causa del fallo en medio del run.
Causa típica: no hay timeline paso a paso de decisiones del agente.
Root cause no se documenta de forma estructurada
Tras el incidente hay conclusión verbal, pero no registro técnico claro.
Causa típica: falta plantilla de incident report.
Caso no entra en regression
El incidente se arregló, pero no se agregó al set de pruebas permanente.
Causa típica: análisis replay desconectado del workflow de regression.
Resumen
- Replay y debugging dan análisis reproducible de incidentes de producción.
- Un replay de calidad exige la misma traza y las mismas condiciones de runtime.
- El debugging debe seguir pasos del agente, no solo texto final.
- Tras el fix, el caso de incidente debe promoverse a regression o golden dataset.
FAQ
Q: ¿En qué se diferencia replay de regression testing?
A: Regression compara versiones del sistema en sets de casos, mientras replay reproduce un incidente real concreto para encontrar root cause.
Q: ¿Qué mínimo se necesita para un replay de calidad?
A: input, estado de contexto, llamadas de herramientas paso a paso, sus resultados, stop_reason y config de runtime.
Q: ¿Se puede hacer replay sin acceso a API de producción?
A: Sí. Normalmente se usan respuestas guardadas o mocks para reproducir la lógica del incidente de forma estable.
Q: ¿Cuándo se considera cerrado un caso replay?
A: Cuando el fix pasa replay repetido y ese mismo escenario pasa de forma estable en el set de regression.
Qué sigue
Después de los análisis replay, agrega casos de incidente a Golden Datasets y valídalos con Regression Testing. Usa Eval Harness para ejecuciones estandarizadas, y Unit Testing para lógica local.