Ідея за 30 секунд
Replay для AI-агентів означає: взяти реальний проблемний трейс, відтворити його в контрольованих умовах і покроково знайти причину збою.
Головна цінність у тому, що команда не вгадує причину інциденту, а бачить повний ланцюг рішень агента і точку, де поведінка зламалася.
Проблема
Без replay команди часто дебажать "по пам'яті":
- дивляться лише фінальну відповідь агента;
- не мають повного контексту запиту;
- не бачать результати викликів інструментів по кроках.
У такому режимі важко відрізнити симптом від причини. Фікси стають неточними, а інциденти повертаються.
Типові наслідки такого підходу:
- помилку виправили локально, але не відтворили реальний production-сценарій;
- після релізу з'являється той самий клас збоїв;
- команда втрачає час на повторні ручні розбори.
Коли використовувати
Replay використовують, коли:
- у production стався інцидент і треба знайти root cause;
- після зміни моделі або промпту з'явився неочікуваний
diffу поведінці; - regression тест показує падіння критичного кейсу;
- треба перевірити, що фікс реально закриває сценарій інциденту.
Replay найкорисніший у системах із багатокроковою поведінкою агента і зовнішніми інструментами.
Реалізація
На практиці replay тримається на одному принципі: той самий трейс, ті самі умови прогону, покроковий розбір рішень. Приклади нижче схематичні і не прив'язані до конкретного фреймворку.
Як це працює в одному розборі
Короткий цикл replay-розбору
- Трейс — зберігаємо вхід, контекст, кроки і відповіді інструментів.
- Replay — відтворюємо цей самий сценарій у контрольованому середовищі.
- Таймлайн кроків — дивимось, де агент прийняв неправильне рішення.
- Root cause — фіксуємо технічну причину: промпт, модель, інструмент або runtime.
- Фікс і перевірка — вносимо фікс і підтверджуємо його повторним прогоном.
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, інакше інцидент може повторитися.
Типові помилки
Неповний трейс інциденту
У логах є фінальна відповідь, але немає кроків агента і результатів інструментів.
Типова причина: зберігається тільки summary без step-level деталей.
Replay у різних runtime-умовах
Трейс відтворюють на іншій моделі або з іншими timeout/retry параметрами.
Типова причина: не зафіксовані runtime-умови інциденту.
Дебаг тільки фінального тексту
Команда аналізує лише останню відповідь і пропускає причину збою в середині run.
Типова причина: немає покрокового таймлайну рішень агента.
Root cause не фіксується структуровано
Після інциденту є усний висновок, але немає чіткого технічного запису.
Типова причина: відсутній шаблон incident report.
Кейс не потрапляє в regression
Інцидент виправили, але не додали в постійний тестовий набір.
Типова причина: replay-розбір від'єднаний від regression workflow.
Коротко
- Replay і debugging дають відтворюваний розбір production-інцидентів.
- Якісний replay вимагає того самого трейсу і тих самих runtime-умов.
- Дебаг має йти по кроках агента, а не лише по фінальному тексту.
- Після фіксу інцидентний кейс треба переносити у regression або golden dataset.
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.