inngest-agent-evals

Inngest Agent Evals — это workflow для оценки результатов AI-агентов и функций, построенный на обычных функциях Inngest, durable steps, score-записях, deferred scorers, sessions, traces, экспериментах и Insights. Он нужен, когда качество требуется измерять не только по ответу модели, а по наблюдаемому результату: полезному клику, решённому тикету, прохождению guardrail, качеству retrieval, уверенности модели, задержке, стоимости, human review или оценке LLM-as-judge. Сам навык не является отдельным npm-пакетом и не обещает готовую метрику без определения того, что именно считается успехом. Первый шаг — назвать сигнал и момент его появления. Если результат известен внутри запуска, для него подходят прямое scoring через step.score() или inngest.score(). Так можно записывать прохождение guardrail, валидность JSON, retrieval confidence, успешность tool-вызова, confidence модели или inline LLM-as-judge. Имена score нужно считать стабильными: изменение имени создаёт отдельную метрику. Значение должно быть конечным числом или boolean, а не строкой, объектом, NaN или Infinity. Если полезный сигнал приходит после завершения родительского workflow, источник предлагает deferred scoring. Так обрабатываются feedback пользователя, конверсия, повторное открытие тикета, удержание или медленная оценка отдельным judge-процессом. createScorer() описывает scorer, а defer() запускает его из производящей функции; deferred scorer должен быть зарегистрирован вместе с остальными функциями в serve handler. defer() не нужно await-ить. При истечении ожидания нужно выбрать семантически понятный результат: значение по умолчанию или null. Для связывания повторяющейся работы используются meta.sessions. Подходят стабильные несекретные идентификаторы с высокой кардинальностью: conversation_id, ticket_id, agent_run_id или import_id. Сессии нужно явно передавать через step.invoke() и step.sendEvent(), если дочерние запуски должны остаться в том же контексте. Метки вроде environment: prod имеют низкую кардинальность и относятся к Insights, а не к sessions. Insights предназначены для исторического анализа, SQL-агрегаций, широкого расследования и фильтров. Для сравнения вариантов используется group.experiment(): вариантами могут быть prompt, model, provider, tool, workflow или operational setting. Выбор можно делать по весам, стабильно bucket-ить по пользователю, аккаунту или tenant, получать из собственной базы через custom или зафиксировать fixed-вариантом. Каждый callback варианта обязан выполнить хотя бы один step.*. Идентификаторы экспериментов и варианты должны оставаться стабильными, назначение memoized для retry и replay, а experimentRef и исходный run ID нужно сохранять, если оценка выполняется отдельным процессом. Для deferred или последующего score ref передаётся явно. Практическая граница применения важна: scoring и deferred scoring обозначены в источнике как beta API, поэтому импорты и сигнатуры нужно сверять с актуальной документацией TypeScript SDK v4 перед production-примером. Для step.score() требуется scoreMiddleware() из inngest/experimental; createScorer() также импортируется из experimental. Sessions требуют SDK v4.7.0 или новее, а group.experiment() — v4.8.0 или новее. Навык не заменяет durable steps: вызовы модели, tools, ожидания, записи в БД и scoring следует держать в шагах, чтобы trace объяснял причину результата. Не начинайте с эксперимента prompt и не используйте нестабильные имена score: сначала зафиксируйте outcome, идентификаторы корреляции и одну измеримую проверку.