用 Inngest 和 AgentKit 构建可持久化…

当需要构建能跨 HTTP 请求、崩溃、部署存活并支持工具调用、人工审批、实时进度和评估的持久化 AI Agent 工作流时使用。

适用场景

解决思路

1. 采用标准架构：HTTP/server action 层校验鉴权、按需存储用户意图、发出带稳定 id 的事件并快速返回；由 Inngest function 拥有 agent 运行；在 step.run 内加载状态和外部上下文；在函数内创建 AgentKit agent 或导入 agent/network 工厂；通过 AgentKit / step.ai 运行模型推理，将非模型工具副作用包在 step.run 中；用 step.waitForEvent 或 step.waitForSignal 处理人工审批和外部回调；用原生 realtime 发布持久化进度；在需要后续评估时添加 sessions 和 scores；在函数级别应用流控以限制 provider 和租户。
2. 先用小而类型化的单 agent 函数验证路径，再添加 networks 和额外工具。用 createAgent 定义 agent，模型调用使用 Inngest step.ai 以便持久化重试和缓存模型结果。
3. 工具调用规则：只读工具调用可在 agent 内运行（重放无害时）；外部副作用应通过稳定 ID 和 step.run 边界隔离，或实现为使用所提供 step 的 tool handler；工具输出要小到符合 step 状态限制；用 schema 校验工具参数，绝不信任模型提供的参数；使用来自已鉴权事件数据的租户/用户 ID，而非仅依赖模型文本。
4. 工具副作用检查清单：该工具会改变什么外部状态？什么幂等键能防止重复写入？模型重复调用同一工具时应如何处理？输出是否可安全存入函数运行状态？该工具是否需要 provider 特定的并发或节流限制？
5. 人工介入：使用持久化等待而非轮询数据库或内存状态。用 step.waitForEvent 等待审批事件，设置 timeout 和 match 字段；若超时则用 step.run 标记需人工复核并返回超时状态；收到审批后再用 step.run 执行发送等副作用。
6. 实时进度（v4 原生 realtime）：在步骤之间使用 step.realtime.publish；在已有 step.run 内使用 inngest.realtime.publish；v4 项目不要安装 v3 的 @inngest/realtime 包；不要构建仅进程内 WebSocket 作为持久化函数的唯一进度来源。对于 AgentKit 特定的 UI hooks，接线 useAgent 或 useChat 前先检查已安装的 @inngest/agent-kit 版本和当前文档。
7. Agent Evals：当用户要求给 agent 打分、比较 prompt 或模型、跟踪用户反馈、按对话/工单分组运行或调试 agent 质量时，使用 inngest-agent-evals。在持久化 agent 工作流中，在启动或连接用户流的事件上添加 meta.sessions；对运行期间已知的信号使用直接评分；对稍后到达的产品结果使用 deferred scorers。
8. 流控与成本：对模型 provider 使用按账户范围的并发或节流键；在公平性重要时按租户或账户设置键；使用确定性事件 ID 避免重复用户操作产生重复昂贵运行；将成功的模型/工具结果保留在步骤中，使后续失败重试不会重新计费之前的模型调用。
9. 棕地迁移步骤：搜索模型调用、工具循环、内存状态、流式处理器、审批轮询和外部副作用；先保持 prompt/工具行为不变；将触发器移入事件和 Inngest 函数；将模型调用移到 AgentKit / step.ai；将带副作用的工具移入 step.run 或持久化 tool handler；用 step.waitForEvent 或 step.waitForSignal 替换进程内等待；在持久化运行可用后再添加 realtime。当仓库有多个可能工作流且用户未选定一个时，先使用 inngest-brownfield-audit。
10. 验证：对 agent、工具 schema 和事件 payload 做类型检查；将 tool handler 与模型行为分开做单元测试；测试 HTTP 入口发出一个确定性事件并快速返回；测试重复事件 ID 不会产生重复最终副作用；如可能，运行 Inngest dev server 并检查 agent 步骤/追踪。

适用边界 · 注意事项

• 一次短的、只读的模型调用，无副作用且不需要持久化进度。
• 仅 UI 自动补全，丢失请求可接受。
• 仓库有多个可能工作流且用户尚未选定一个时（应先使用 inngest-brownfield-audit）。