Replay et debugging pour agents IA

Idée en 30 secondes

Le replay pour agents IA consiste à reprendre une trace réelle problématique, la rejouer dans des conditions contrôlées, puis trouver la cause de l'échec étape par étape.

La valeur principale est que l'équipe ne devine pas la cause de l'incident. Elle voit la chaîne complète des décisions de l'agent et le point exact où le comportement s'est cassé.

Le problème

Sans replay, les équipes déboguent souvent "de mémoire" :

• elles regardent seulement la réponse finale de l'agent ;
• elles n'ont pas le contexte complet de la requête ;
• elles ne voient pas les résultats des appels d'outils étape par étape.

Dans ce mode, il est difficile de distinguer symptôme et cause. Les fixes deviennent imprécis, et les incidents reviennent.

Conséquences typiques :

• l'erreur est corrigée localement, mais le scénario réel de production n'est pas reproduit ;
• la même classe d'échec réapparaît après la release ;
• l'équipe perd du temps sur des analyses manuelles répétées.

Quand l'utiliser

Le replay est utilisé quand :

• un incident est survenu en production et il faut trouver la root cause ;
• après changement de modèle ou de prompt, un diff inattendu apparaît dans le comportement ;
• un test de regression montre une chute sur un cas critique ;
• il faut vérifier qu'un fix ferme réellement le scénario d'incident.

Le replay est surtout utile dans les systèmes avec comportement agent multi-étapes et outils externes.

Implémentation

En pratique, le replay repose sur un principe : même trace, mêmes conditions de run, analyse pas à pas des décisions. Les exemples ci-dessous sont schématiques et non liés à un framework précis.

Comment cela fonctionne dans une analyse

1. Conserver la trace avec le contexte complet

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",
}

Sans trace complète, le replay reproduit rarement la vraie cause d'incident.

2. Rejouer la trace dans les mêmes conditions

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 modèle, timeouts ou conditions d'outils diffèrent, le replay peut paraître faussement sûr.

3. Analyser la timeline pas à pas

def find_first_bad_step(replayed_steps):
    return next(
        ((idx, step) for idx, step in enumerate(replayed_steps) if step["status"] == "unexpected"),
        None,
    )

L'objectif principal du debugging est de trouver la première étape où le système sort du scénario attendu.

4. Capturer la root cause de façon structurée

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",
}

Une root cause structurée facilite la vérification du fix et le transfert de connaissance dans l'équipe.

5. Ajouter l'incident au 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"]],
    }

Après l'analyse replay, le cas doit être ajouté à regression ou golden dataset, sinon l'incident peut revenir.

Erreurs typiques

Trace d'incident incomplète

Les logs ont la réponse finale, mais pas les étapes de l'agent ni les résultats d'outils.

Cause typique : seule la summary est stockée, sans détails step-level.

Replay dans des conditions runtime différentes

La trace est rejouée avec un autre modèle ou d'autres paramètres timeout/retry.

Cause typique : conditions runtime de l'incident non figées.

Debugging uniquement sur le texte final

L'équipe analyse seulement la dernière réponse et manque la cause de l'échec au milieu du run.

Cause typique : absence de timeline détaillée des décisions de l'agent.

Root cause non documentée de façon structurée

Après l'incident, il y a une conclusion orale mais pas de trace technique claire.

Cause typique : absence de template d'incident report.

Cas non ajouté à regression

L'incident est corrigé, mais non ajouté au set de tests permanent.

Cause typique : analyse replay déconnectée du workflow de regression.

En bref

FAQ

Q : Quelle différence entre replay et regression testing ?
R : Regression compare les versions du système sur des sets de cas, alors que replay reproduit un incident réel précis pour trouver la root cause.

Q : Quel minimum faut-il pour un replay de qualité ?
R : input, état de contexte, appels d'outils pas à pas, leurs résultats, stop_reason et config runtime.

Q : Peut-on faire du replay sans accès à l'API production ?
R : Oui. En général, on utilise des réponses sauvegardées ou des mocks pour reproduire la logique d'incident de façon stable.

Q : Quand un cas replay est-il considéré comme fermé ?
R : Quand le fix passe en replay répété et que le même scénario passe de façon stable dans le set de regression.

Et ensuite

Après les analyses replay, ajoutez les cas d'incident dans Golden Datasets et validez-les via Regression Testing. Utilisez Eval Harness pour des runs standardisés, et Unit Testing pour la logique locale.