Replay і debugging AI-агентів

Ідея за 30 секунд

Replay для AI-агентів означає: взяти реальний проблемний трейс, відтворити його в контрольованих умовах і покроково знайти причину збою.

Головна цінність у тому, що команда не вгадує причину інциденту, а бачить повний ланцюг рішень агента і точку, де поведінка зламалася.

Проблема

Без replay команди часто дебажать "по пам'яті":

• дивляться лише фінальну відповідь агента;
• не мають повного контексту запиту;
• не бачать результати викликів інструментів по кроках.

У такому режимі важко відрізнити симптом від причини. Фікси стають неточними, а інциденти повертаються.

Типові наслідки такого підходу:

• помилку виправили локально, але не відтворили реальний production-сценарій;
• після релізу з'являється той самий клас збоїв;
• команда втрачає час на повторні ручні розбори.

Коли використовувати

Replay використовують, коли:

• у production стався інцидент і треба знайти root cause;
• після зміни моделі або промпту з'явився неочікуваний diff у поведінці;
• regression тест показує падіння критичного кейсу;
• треба перевірити, що фікс реально закриває сценарій інциденту.

Replay найкорисніший у системах із багатокроковою поведінкою агента і зовнішніми інструментами.

Реалізація

На практиці replay тримається на одному принципі: той самий трейс, ті самі умови прогону, покроковий розбір рішень. Приклади нижче схематичні і не прив'язані до конкретного фреймворку.

Як це працює в одному розборі

1. Зберігайте трейс із повним контекстом

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

Без повного трейсу replay майже ніколи не відтворює реальну причину інциденту.

2. Відтворюйте трейс у тих самих умовах

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"],
    )

Якщо модель, таймаути або умови інструментів інші, результат replay може виглядати хибно безпечним.

3. Аналізуйте покроковий таймлайн

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

Ключова ціль дебагу — знайти перший крок, де система пішла не за очікуваним сценарієм.

4. Фіксуйте root cause у структурованому вигляді

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

Структурований root cause спрощує перевірку фіксу і передачу знань у команді.

5. Додавайте інцидент у 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"]],
    }

Після replay-розбору кейс має потрапити в regression або golden dataset, інакше інцидент може повторитися.

Нотатки для QA та автоматизації

QA-команди зазвичай використовують replay, щоб відтворювати production-збої в контрольованому середовищі та покроково розслідувати причину інциденту.

Практично це працює як автоматизований цикл: інцидентний трейс подається у replay-прогін, результати фіксуються у звіті розслідування, а підтверджений кейс додається до regression-набору.

Типові помилки

Неповний трейс інциденту

У логах є фінальна відповідь, але немає кроків агента і результатів інструментів.

Типова причина: зберігається тільки summary без step-level деталей.

Replay у різних runtime-умовах

Трейс відтворюють на іншій моделі або з іншими timeout/retry параметрами.

Типова причина: не зафіксовані runtime-умови інциденту.

Дебаг тільки фінального тексту

Команда аналізує лише останню відповідь і пропускає причину збою в середині run.

Типова причина: немає покрокового таймлайну рішень агента.

Root cause не фіксується структуровано

Після інциденту є усний висновок, але немає чіткого технічного запису.

Типова причина: відсутній шаблон incident report.

Кейс не потрапляє в regression

Інцидент виправили, але не додали в постійний тестовий набір.

Типова причина: replay-розбір від'єднаний від regression workflow.

Коротко

FAQ

Q: Чим replay відрізняється від regression testing?
A: Regression порівнює версії системи на наборах кейсів, а replay відтворює конкретний реальний інцидент для пошуку root cause.

Q: Що мінімально треба мати для якісного replay?
A: input, стан контексту, покрокові виклики інструментів, їхні результати, stop_reason і runtime-конфіг.

Q: Чи можна робити replay без доступу до production API?
A: Так. Зазвичай використовують збережені відповіді або mocks, щоб стабільно відтворити саме логіку інциденту.

Q: Коли replay-кейс вважається закритим?
A: Коли фікс проходить повторний replay і той самий сценарій стабільно проходить у regression-наборі.

Що далі

Після replay-розборів додавайте інцидентні кейси в Golden Datasets і перевіряйте їх через Regression Testing. Для стандартизованих прогонів використовуйте Eval Harness, а локальну логіку перевіряйте через Unit Testing.