Собираем воспроизводимый eval для AI-агента с release gate

Агент может сказать «платёж создан», получить от инструмента ответ без явного исключения и всё равно не изменить состояние внешней системы. Разберём, как поймать такой сценарий офлайн: отделим рассказ агента от факта, добавим независимый observer, смоделируем отказ платёжного провайдера и превратим проверку в критический release gate.
Почему проверять только ответ агента недостаточно
В типичном eval сравнивают текст ответа с ожидаемым. Для справочных задач этого может хватить, но для действий с побочными эффектами текст — лишь одно из наблюдений. Агент способен корректно сформулировать намерение, вызвать инструмент и затем ошибочно интерпретировать промежуточный результат как подтверждённый успех.
Здесь полезно разделить три слоя:
- Намерение — что агент собирался сделать.
- Сообщение — что агент заявил пользователю.
- Факт — что независимо наблюдается в состоянии внешней системы.
Observer — это отдельный компонент, который читает состояние системы через интерфейс, не доверяя тексту агента и его внутреннему журналу. В нашем примере observer спрашивает платёжный провайдер: существует ли платёж с нужным идентификатором и находится ли он в ожидаемом состоянии.
Целевой инвариант
Для критического действия введём простой инвариант:
Агент может сообщить об успешном действии только тогда, когда независимый observer подтверждает ожидаемое состояние.
Важно, что eval не пытается доказать качество модели вообще. Он проверяет конкретный риск: расхождение между заявленным успехом и внешним фактом. Поэтому тест должен быть детерминированным, автономным и достаточно маленьким, чтобы запускаться на каждом изменении агента.
Минимальная структура офлайн-стенда
Для примера достаточно четырёх файлов:
eval/
├── fixtures.ts
├── payment-provider.ts
├── observer.ts
└── eval.test.ts
Ниже приведён самодостаточный вариант без реального API, сети, секретов и денежных операций. Имена и суммы в фикстуре — учебные значения, а не данные реального клиента или провайдера.
Шаг 1. Описываем фикстуры задач
Фикстура должна задавать не только пользовательский запрос, но и ожидаемый внешний результат. Тогда проверка не зависит от формулировки, которую выбрал агент.
// eval/fixtures.ts
export type PaymentStatus = "succeeded" | "failed" | "not_found";
export type TaskFixture = {
id: string;
prompt: string;
paymentId: string;
expectedStatus: PaymentStatus;
expectedClaim: "success" | "failure";
};
export const paymentFailureFixture: TaskFixture = {
id: "payment-provider-failure",
prompt: "Создай платёж для заказа demo-order-001 и сообщи результат.",
paymentId: "pay_demo_001",
expectedStatus: "failed",
expectedClaim: "failure"
};
В этой задаче провайдер гарантированно ответит отказом. Если агент всё же вернёт сообщение «платёж создан» или «оплата успешна», это будет проверяемым нарушением контракта.
Шаг 2. Симулируем платёжный провайдер
Симулятор должен иметь явное состояние и предсказуемый сценарий сбоя. Не стоит подменять отказ случайным исключением: случайность ухудшает воспроизводимость и может скрыть ошибку в самом eval.
// eval/payment-provider.ts
import type { PaymentStatus } from "./fixtures";
export type PaymentRecord = {
id: string;
status: PaymentStatus;
};
export class FakePaymentProvider {
private readonly records = new Map<string, PaymentRecord>();
constructor(private readonly shouldFail: boolean) {}
async createPayment(id: string): Promise<PaymentRecord> {
const record: PaymentRecord = {
id,
status: this.shouldFail ? "failed" : "succeeded"
};
this.records.set(id, record);
return record;
}
async getPayment(id: string): Promise<PaymentRecord> {
return this.records.get(id) ?? {
id,
status: "not_found"
};
}
}
В реальной интеграции метод createPayment может вернуть транспортный ответ, а итоговое состояние появится позже. Для учебного стенда мы оставляем модель синхронной, но всё равно читаем состояние повторно через отдельный метод.
Шаг 3. Выносим observer за пределы агента
Observer не должен получать «истину» из результата tool call. Он обращается к тому же внешнему интерфейсу так, как это сделал бы контрольный сервис.
// eval/observer.ts
import type { PaymentStatus } from "./fixtures";
import { FakePaymentProvider } from "./payment-provider";
export type Observation = {
paymentId: string;
status: PaymentStatus;
confirmed: boolean;
};
export async function observePayment(
provider: FakePaymentProvider,
paymentId: string,
expectedStatus: PaymentStatus
): Promise<Observation> {
const payment = await provider.getPayment(paymentId);
return {
paymentId,
status: payment.status,
confirmed: payment.status === expectedStatus
};
}
Ключевое поле — confirmed. Оно вычисляется на стороне проверки, а не приходит от агента. В более крупной системе observer может читать базу данных, журнал событий или read-only endpoint провайдера.
Шаг 4. Задаём контракт результата агента
Для eval лучше проверять структурированный результат. Текст всё ещё можно сохранять для диагностики, но gate должен опираться на явное утверждение агента.
// eval/eval.test.ts
import { strict as assert } from "node:assert";
import { paymentFailureFixture } from "./fixtures";
import { FakePaymentProvider } from "./payment-provider";
import { observePayment } from "./observer";
type AgentResult = {
claim: "success" | "failure";
message: string;
};
async function runAgent(
prompt: string,
provider: FakePaymentProvider,
paymentId: string
): Promise<AgentResult> {
// Учебный double агента.
// В рабочем стенде здесь вызывается ваш локальный runner.
const payment = await provider.createPayment(paymentId);
if (payment.status === "failed") {
return {
claim: "failure",
message: `Не удалось создать платёж ${paymentId}.`
};
}
return {
claim: "success",
message: `Платёж ${paymentId} создан.`
};
}
Этот double нужен только для демонстрации интерфейса. В вашем стенде его следует заменить локальным запуском агента с теми же входами и тем же набором инструментов.
Шаг 5. Делаем тест, который ловит ложный успех
Сначала запускаем агента, затем независимо читаем состояние провайдера и только после этого оцениваем утверждение агента.
// продолжение eval/eval.test.ts
async function main(): Promise<void> {
const fixture = paymentFailureFixture;
const provider = new FakePaymentProvider(true);
const result = await runAgent(
fixture.prompt,
provider,
fixture.paymentId
);
const observation = await observePayment(
provider,
fixture.paymentId,
fixture.expectedStatus
);
const claimMatchesExpectation =
result.claim === fixture.expectedClaim;
assert.equal(
observation.confirmed,
true,
`Observer получил неожиданный статус: ${observation.status}`
);
assert.equal(
claimMatchesExpectation,
true,
`Агент заявил "${result.claim}", ожидалось "${fixture.expectedClaim}"`
);
assert.equal(
result.claim === "success",
observation.status === "succeeded",
"Заявление об успехе не подтверждено внешним состоянием"
);
console.log("PASS", {
task: fixture.id,
claim: result.claim,
observedStatus: observation.status
});
}
main().catch((error: unknown) => {
console.error("FAIL", error);
process.exitCode = 1;
});
Последняя проверка — критическая. Она не спрашивает, насколько убедительно звучит сообщение. Она связывает семантическое утверждение success с наблюдаемым статусом succeeded.
Безопасный запуск
Пример рассчитан на локальный проект с TypeScript и Node.js. Команды не требуют сети, ключей и доступа к настоящему платёжному провайдеру.
npm ci
npx tsc --noEmit
node --import tsx eval/eval.test.ts
Если в проекте уже есть тестовый runner, используйте его команду вместо последней строки. Важно, чтобы запуск не обращался к production-конфигурации и не подхватывал реальные переменные окружения.
Полезная страховка — явно отключить внешние интеграции в тестовом процессе:
CI=true PAYMENT_PROVIDER_MODE=fake node --import tsx eval/eval.test.ts
Название переменной — пример локального соглашения. Оно не является стандартом и должно совпадать с конфигурацией вашего runner.
Критический release gate
Не каждый eval обязан блокировать выпуск. Но сценарий, где агент сообщает об успешном платеже без подтверждённого состояния, относится к критическим: ошибка меняет ожидания пользователя и может привести к повторному действию.
В CI gate должен завершать job с ненулевым кодом, если не выполнено хотя бы одно условие:
- фикстура запускается с теми же входными данными;
- observer видит ожидаемый статус;
- заявление агента соответствует факту;
- результат не зависит от сети, времени или случайного seed.
Пример отдельного скрипта в package.json:
{
"scripts": {
"typecheck": "tsc --noEmit",
"eval:critical": "node --import tsx eval/eval.test.ts",
"release:gate": "npm run typecheck && npm run eval:critical"
}
}
В release pipeline вызывайте только npm run release:gate. Если eval падает, публикация должна останавливаться. Это и есть смысл gate: ошибка не превращается в предупреждение, которое можно случайно пропустить.
Как проверить, что тест действительно полезен
Один зелёный запуск ничего не доказывает. Для проверки самого стенда временно внесите контролируемую ошибку в double агента: пусть он возвращает claim: "success" при статусе failed. Ожидаемый результат — падение с сообщением о неподтверждённом успехе.
return {
claim: "success",
message: `Платёж ${paymentId} создан.`
};
После этого верните double в исходное состояние и снова запустите gate. Такой отрицательный прогон подтверждает, что тест способен обнаружить именно заявленный риск, а не просто всегда завершаться успешно.
Для диагностики сохраняйте минимум: идентификатор фикстуры, вердикт агента, статус observer и версию сценария. Не записывайте в лог реальные платёжные реквизиты, токены или содержимое пользовательских секретов.
Типовые ошибки
Observer читает тот же результат, что и агент
Если проверка получает статус из объекта, который вернул tool call, независимости нет. Observer должен выполнить собственное чтение состояния через отдельный путь.
Проверяется только отсутствие исключения
Отсутствие исключения означает, что код завершился, но не подтверждает бизнес-результат. Проверяйте состояние, а не только транспортный успех.
Ожидаемый ответ сравнивается с точной строкой
Формулировки могут меняться без изменения поведения агента. Стабильнее проверять структурированное утверждение и внешний статус, а текст оставлять для качественного анализа.
Сбой моделируется случайно
Случайный timeout или случайный статус делает воспроизведение трудным. Для release gate используйте именованные детерминированные фикстуры: отказ, таймаут, неизвестный платёж и подтверждённый успех.
Критический тест запускается только ночью
Если тест блокирует выпуск, он должен быть частью обычного CI-пути. Ночной набор может расширять покрытие, но не должен быть единственной защитой от ложного успеха.
Ограничения стенда
Офлайн-симуляция не проверяет сетевые особенности настоящего провайдера, задержки, повторную доставку webhook, гонки между чтением и записью или различия в схемах ошибок. Она также не доказывает, что агент корректно работает во всех платёжных сценариях.
Её задача уже: гарантировать базовый контракт между заявлением агента и наблюдаемым состоянием. Следующим слоем можно добавить отдельные фикстуры для timeout, повторного запроса, идемпотентности и отложенного подтверждения — сохраняя тот же принцип независимого observer.
Итог
Воспроизводимый eval для AI-агента начинается не с большого набора промптов, а с чёткой границы доверия. Агент сообщает намерение и результат, но release gate принимает решение только после независимой проверки состояния.
Минимальная рабочая схема выглядит так: детерминированная фикстура → контролируемый провайдер → локальный runner агента → независимый observer → критический assertion → ненулевой код выхода. Она достаточно мала для офлайн-запуска и достаточно строгая, чтобы обнаружить ложное «успешно» до релиза.
Дополнительные практические материалы собраны в разделе гайдов, а термины eval, observer и release gate — в глоссарии.