inngest-agent-evals

用途

Inngest Agent Evals 用于在生产环境中评估 AI 智能体或 AI 工作流。当用户希望为智能体结果打分、比较提示词/模型/工具、将相关运行分组，或调试某次智能体结果为何好或坏时，可使用该技能。

Agent Evals 不是单独的软件包，而是由 Inngest 函数、持久化步骤、评分、延迟评分器、会话、追踪、实验与 Insights 组合而成的生产评估工作流。

主要能力

直接评分（Direct Scoring）：在函数运行期间已知结果时使用，例如护栏通过/失败、JSON 有效性、检索置信度、工具成功、模型置信度、内联 LLM-as-judge 结果。通过 step.score() 或 inngest.score() 实现。
延迟评分（Deferred Scoring）：当有用信号在父工作流结束后才出现时使用，例如用户反馈、转化、工单重开、留存或较慢的 LLM-as-judge 运行。通过 createScorer() 与 defer() 实现。
会话（Sessions）：当事件属于用户流程、对话、工单、导入或智能体任务且会被反复检查时，通过 meta.sessions 添加稳定、非机密、高基数的标识符（如 conversation_id、ticket_id、agent_run_id、import_id）。
实验（Experiments）：通过 group.experiment() 针对真实流量比较提示词、模型、提供商、工具、工作流重写或运营设置。支持 experiment.weighted()、experiment.bucket()、experiment.custom()、experiment.fixed() 等选择策略。
追踪与洞察：将模型调用、工具调用、等待、数据库写入与评分工作保留在持久化步骤中，使追踪能解释评分原因；使用 Insights 进行临时历史分析、低基数过滤、SQL 聚合与广泛调查。

使用方式

从结果出发而非机制出发：先识别产品或质量信号（有帮助的点击、工单解决、转化、护栏通过、检索质量、模型置信度、延迟、成本、人工审核或 LLM-as-judge 结果）。
决定信号出现时机：运行期间使用直接评分；运行之后使用延迟评分。
决定人类如何检查相关工作：重复的高基数标识符使用 meta.sessions；临时历史分析使用 Insights。
决定是否比较变体：使用 group.experiment()；当评分应归属于所选变体时，将 experimentRef 传给延迟或后续评分。
保持可追溯性：将模型调用、工具调用、等待、数据库写入与评分工作保留在持久化步骤中。

设置要求

使用 TypeScript SDK v4 并安装最新 SDK：npm install inngest@latest。
评分与延迟评分为 beta API，发布面向用户的示例前需按文档核对当前导入方式。
step.score() 需要在 Inngest 客户端上使用来自 inngest/experimental 的 scoreMiddleware()。
createScorer() 从 inngest/experimental 导入，评分器必须与其他函数一起在 serve 处理器中注册。
通过 TypeScript SDK 发送的会话需要 v4.7.0 或更高版本。
步骤实验需要 v4.8.0 或更高版本以使用 group.experiment() 与来自 inngest 的 experiment 辅助函数。

客户端形态示例：

import { Inngest } from "inngest";
import { scoreMiddleware } from "inngest/experimental";

export const inngest = new Inngest({
  id: "support-agent",
  middleware: [scoreMiddleware()],
});

会话规则

使用稳定、非机密、高基数的 ID。
保持键通用，如 conversation_id；将实际 ID 放在值中。
当下游运行应加入同一会话时，通过 step.invoke() 与 step.sendEvent() 显式传递会话。
不要将会话用于 environment: prod 之类的标签；此类过滤使用 Insights。

直接评分

在函数运行期间已知评分时使用。评分名称需稳定，更改评分名称会创建单独的指标。评分值必须是有限数字或布尔值。

延迟评分

当有用信号在父工作流结束后到达时使用。注意事项：

在 serve({ functions: [...] }) 中注册评分器。
defer() 是即发即忘，不要 await。
延迟评分器会自动归属父运行。
信号超时时，根据产品语义返回默认评分或 null。

实验规则

每个变体回调必须至少调用一个 step.* 工具。
保持实验 ID 与变体名称稳定，因为它们会出现在追踪中。
所选变体会在重试与重放时被记忆化。
如果后续独立流程将为所选变体评分，需持久化 experimentRef 与父运行 ID。

棕地迁移

向现有应用添加 Agent Evals 时：

搜索现有智能体/工作流输出以及用户对其采取行动的位置。
查找领域中已有的持久标识符：会话 ID、工单 ID、账户 ID、导入 ID、运行 ID 或推荐 ID。
在围绕关联构建仪表板之前，先在事件生产者处添加 meta.sessions。
在结果已知处添加一个直接评分。
仅在信号事件存在或可干净发出后，才添加延迟评分器。
一次只围绕一个孤立决策添加 group.experiment()。
在评分证明新路径之前，保持旧提示词/模型/工具行为稳定。

当仓库有许多候选工作流时，先使用 inngest-brownfield-audit。当工作是 AgentKit 或持久化智能体工作流时，配合本技能使用 inngest-agents。

适用场景

评估生产环境中的 AI 智能体或 AI 工作流。
为智能体或工作流结果添加评分。
比较提示词、模型、提供商、工具或工作流重写。
将相关运行分组以便反复检查。
调试某次智能体结果为何好或坏。
将 Agent Evals 迁移到现有应用。

限制与反模式

在命名结果指标之前就开始提示词实验。
使用不稳定的名称、字符串、对象、NaN 或 Infinity 进行评分。
忘记 scoreMiddleware() 却误以为 step.score() 缺失。
当评分器需要持久化等待时，在外部队列中运行评分器。
仅将实验分配保留在内存中。
在没有原始 runId 的情况下从后续运行对实验变体评分。
将会话用于低基数标签或敏感个人数据。
将模型/工具工作留在步骤之外，导致追踪无法解释评分。

验证

对 Inngest 客户端、函数、评分器 schema 与 serve 处理器进行类型检查。
确认评分器已在 serve 端点注册。
测试生产者发出的事件带有预期的 meta.sessions。
测试直接评分使用稳定名称与有限数字/布尔值。
测试延迟评分器超时行为。
对于实验，测试每个变体回调包含步骤工作，且后续评分在需要时收到 experimentRef 与原始运行 ID。
如有可能，运行 Inngest 开发服务器，并在仪表板或通过可用的 CLI/API 工具检查追踪、会话、评分与实验变体选择。

规范参考

Agent Evals 概览：https://www.inngest.com/docs/learn/agent-evals
评分指南：https://www.inngest.com/docs/features/inngest-functions/steps-workflows/scoring
延迟评分指南：https://www.inngest.com/docs/features/inngest-functions/steps-workflows/deferred-scoring
步骤实验指南：https://www.inngest.com/docs/features/inngest-functions/steps-workflows/step-experiments
会话：https://www.inngest.com/docs/features/events-triggers/sessions
追踪：https://www.inngest.com/docs/platform/monitor/traces
Insights：https://www.inngest.com/docs/platform/monitor/insights
评分参考：https://www.inngest.com/docs/reference/typescript/v4/functions/scoring
group.experiment() 参考：https://www.inngest.com/docs/reference/typescript/v4/functions/group-experiment
发布背景：https://www.inngest.com/blog/introducing-agent-evals