Как тестировать асинхронные побочные эффекты AI-агента

AI-агент редко меняет систему синхронно с ответом модели. Он может создать тикет, поставить задачу в очередь, повторить запрос после тайм-аута или попытаться выполнить запрещённое действие. Поэтому тест, который просто ждёт фиксированное число секунд и проверяет один HTTP-ответ, легко даёт оба опасных результата: сообщает о падении, хотя эффект ещё не успел проявиться, или сообщает об успехе, хотя позже появится дубль.
Надёжная проверка должна наблюдать систему до понятного eventual consistency-состояния, ограничивать ожидание дедлайном, проверять количество результатов и отдельно доказывать отсутствие запрещённого эффекта. Ниже — каркас тестового harness, который можно адаптировать к конкретному агенту и хранилищу.
Что именно нужно доказать
Для каждого сценария заранее сформулируйте наблюдаемое утверждение. Например:
- после одного пользовательского запроса появился ровно один тикет;
- повторная доставка того же события не создала второй тикет;
- после временной ошибки агент повторил операцию не более разрешённого числа раз;
- при запретном намерении не появилось ни одной записи, команды или внешнего вызова;
- после достижения ожидаемого состояния система перестала производить новые результаты.
Важно различать бизнес-результат и транспортное событие. Два сообщения в очереди не обязательно означают два тикета, а один ответ API не доказывает, что побочный эффект уже записан в хранилище.
Минимальная модель harness
Harness должен иметь четыре независимые части: генератор входного события, адаптер наблюдения, polling с дедлайном и набор проверок результата. В тесте не должно быть скрытого ожидания вроде sleep(5): фиксированная пауза не знает, успела ли система завершиться, и не защищает от позднего дубля.
deadline = now() + 30s
seen = []
while now() < deadline:
state = read_effects(correlation_id)
seen = normalize(state)
if expected_state_reached(seen):
break
sleep(backoff.next())
assert exactly_one_business_result(seen)
Это псевдокод, а не готовая библиотека. Функции read_effects и normalize должны использовать только реальные интерфейсы вашего проекта. Если API возвращает пагинацию, harness обязан пройти все страницы или использовать серверный count, иначе проверка количества будет неполной.
Воспроизводимый сценарий: создание тикета
1. Подготовьте корреляцию
На каждый запуск создавайте уникальный correlation_id. Не переиспользуйте его между тестами без явной причины: старые записи могут выглядеть как новый результат. В полезную нагрузку положите стабильный idempotency_key, который останется тем же при повторной доставке события.
correlation_id=test-$(date +%s)-$RANDOM
idempotency_key=case-create-001
Эти команды безопасны в локальном окружении: они только формируют значения переменных. Отправку события выполняйте через тестовый клиент проекта и не подставляйте реальные секреты в командную строку, логи или репозиторий.
2. Отправьте событие один раз
Зафиксируйте момент отправки и идентификаторы ответа. Сохраняйте исходную полезную нагрузку рядом с логом теста. Если агент отвечает «принято», это подтверждает только приём задания, а не создание тикета.
send_agent_event \
--correlation-id "$correlation_id" \
--idempotency-key "$idempotency_key" \
--input "создай тикет по входящему обращению"
3. Ожидайте состояние polling-ом
Polling должен прекращаться по одному из двух условий: ожидаемое состояние достигнуто или истёк дедлайн. Интервал можно увеличивать постепенно, чтобы не создавать лишнюю нагрузку. При каждом чтении записывайте время, статус, количество результатов и идентификаторы найденных объектов.
deadline = monotonic_now() + 30
delay = 0.25
while monotonic_now() < deadline:
results = list_tickets(correlation_id=correlation_id)
if len(results) > 1:
fail("обнаружен дубль до истечения дедлайна")
if len(results) == 1 and results[0].status == "created":
break
sleep(delay)
delay = min(delay * 2, 2.0)
assert len(results) == 1
assert results[0].idempotency_key == idempotency_key
Здесь проверка дубля выполняется сразу, а не только в конце. Это делает причину падения понятнее и помогает обнаружить гонку: например, два воркера одновременно прошли проверку существования записи.
Почему нужна проверка ровно одного результата
Проверка «нашёлся хотя бы один тикет» недостаточна. Она пропустит повторную обработку, если первый результат корректен, а второй появляется немного позже. Минимальная проверка должна сравнивать число бизнес-объектов с единицей и дополнительно проверять их ключи:
assert count(results) == 1
assert results[0].correlation_id == correlation_id
assert results[0].idempotency_key == idempotency_key
assert results[0].source_event_id == expected_event_id
Если в доменной модели допустимы несколько технических записей на один результат, считайте не строки таблицы, а агрегированные бизнес-результаты. В тесте явно зафиксируйте правило агрегации, иначе он будет зависеть от внутренней реализации.
Идемпотентность на уровне хранилища
Проверки в коде агента недостаточно: два параллельных воркера могут одновременно прочитать отсутствие записи. Гарантия должна быть закреплена там, где создаётся результат — обычно уникальным ограничением по ключу идемпотентности или по подходящему составному ключу.
UNIQUE (tenant_id, idempotency_key)
Конкретный синтаксис зависит от выбранного хранилища; строка выше — иллюстрация требования, а не инструкция для конкретной СУБД. Тест должен доставить одно и то же событие повторно и проверить, что:
- обработчики не создали второй бизнес-объект;
- повторный вызов вернул существующий результат или безопасный конфликт;
- состояние первой записи не было случайно перезаписано данными повторной попытки;
- журнал попыток позволяет отличить повторную доставку от нового события.
Для проверки гонки запустите две одинаковые обработки одновременно в изолированном тестовом окружении. Успешным считается не отсутствие ошибок вообще, а наличие одного результата и предсказуемая обработка второй попытки.
Повторные попытки и временные ошибки
Не смешивайте retry транспорта с retry побочного эффекта. Сетевой тайм-аут может означать, что запись уже создана, но ответ потерян. Поэтому повторный вызов должен использовать тот же ключ идемпотентности и сначала безопасно разрешать неопределённый результат.
Полезный сценарий выглядит так:
- тестовый адаптер принимает запрос и имитирует потерю ответа;
- агент выполняет повторную попытку с тем же ключом;
- harness ждёт до дедлайна, а не до фиксированной паузы;
- итоговая проверка требует ровно один бизнес-результат;
- в журнале проверяется число попыток и причина повтора.
Если у системы нет управляемого fault injection, не называйте такой тест проверкой повторных попыток: обычное ожидание успешного ответа подтверждает только happy path.
Запретные действия и quiet window
Отрицательную проверку нельзя завершать в момент, когда агент ещё может выполнить отложенную команду. Утверждение «ничего не произошло» требует периода тишины — quiet window. Это интервал, в течение которого система не создаёт новых эффектов после того, как обработка входа считается завершённой.
deadline = monotonic_now() + 30
quiet_until = None
last_observed = snapshot_effects(correlation_id)
while monotonic_now() < deadline:
current = snapshot_effects(correlation_id)
if forbidden_effect_detected(current):
fail("обнаружено запрещённое действие")
if current != last_observed:
last_observed = current
quiet_until = monotonic_now() + 5
if processing_finished(correlation_id):
if quiet_until is None:
quiet_until = monotonic_now() + 5
if monotonic_now() >= quiet_until:
break
sleep(0.5)
assert no_forbidden_effects(last_observed)
Длительность quiet window должна быть частью тестовой конфигурации и соответствовать ожидаемой задержке конкретного контура. Не выбирайте число только потому, что оно «обычно работает». Если воркеры могут просыпаться позже окна, отрицательный тест будет давать ложные успехи.
Проверяйте не только итоговую таблицу. Запретное действие может проявиться в исходящей команде, записи аудита, постановке задачи в очередь или вызове внешнего адаптера. Составьте белый список допустимых событий и считайте нарушением любой эффект вне него.
Типовые ошибки
- Фиксированный sleep. Он либо слишком короткий и даёт ложное падение, либо чрезмерно длинный и скрывает проблемы с дедлайном.
- Проверка только HTTP-ответа. Ответ «принято» не равен завершённому побочному эффекту.
- Проверка «не пусто». Она не обнаруживает дубли.
- Идемпотентность только в памяти. После рестарта или при гонке она не защищает хранилище.
- Слишком ранняя отрицательная проверка. Отсутствие записи в первой выборке не доказывает, что её не будет позже.
- Один общий идентификатор на все тесты. Остатки предыдущего запуска превращаются в ложный успех.
- Неполная выборка. Пагинация, eventual consistency и кеш могут скрыть второй результат.
Проверка результата harness
Каждый запуск должен оставлять компактный диагностический отчёт: корреляционный идентификатор, idempotency key, дедлайн, число polling-итераций, найденные бизнес-результаты, замеченные попытки и время окончания quiet window. Не записывайте в отчёт токены, персональные данные и полные промпты, если они не нужны для диагностики.
Перед тем как считать тест надёжным, проверьте его на четырёх вариантах:
- обычное успешное создание одного результата;
- медленное, но допустимое создание до дедлайна;
- повторная доставка после потерянного ответа;
- запретное действие с поздним отложенным воркером.
Хороший harness падает с разными причинами для «не дождались», «получили дубль», «нарушили запрет» и «сломалась идемпотентность». Одно общее сообщение вроде «ожидаемое состояние не достигнуто» затрудняет расследование и стимулирует увеличить таймаут вместо исправления гонки.
Ограничения подхода
Polling по дедлайну не делает внешнюю систему детерминированной. Он лишь ограничивает ожидание и делает критерий завершения явным. Если у вас нет наблюдаемого источника истины, невозможно надёжно доказать ни ровно один результат, ни отсутствие запретного действия.
Quiet window также не является математическим доказательством вечного отсутствия эффекта. Это инженерный критерий, valid только относительно известных задержек очередей, ретраев и воркеров. Для критичных действий нужны дополнительные гарантии: серверная идемпотентность, аудит, блокирующие политики и отдельное тестирование восстановления после сбоев.
Итог
Чтобы избежать ложных падений и ложных успехов при тестировании AI-агента, наблюдайте не ответ модели, а жизненный цикл побочного эффекта. Используйте polling с монотонным дедлайном, требуйте ровно один бизнес-результат, закрепляйте идемпотентность уникальным ограничением хранилища и завершайте отрицательные проверки только после quiet window.
Дополнительные практические материалы собраны в разделе guides, а термины и сокращения — в глоссарии.