用途
Inngest Agents 用于在用户希望构建、迁移或调试 AI 智能体、多步骤 AI 工作流、工具调用循环、支持智能体、研究智能体、人工介入审核流程或实时智能体 UI 时提供指导。其核心思路是：用 Inngest 的 AgentKit 通过 createAgent 定义智能体；当 AgentKit 运行由 Inngest 函数托管时，模型调用使用 Inngest step.ai，从而获得持久化的重试与模型结果缓存。智能体周围则使用更底层的 Inngest step 原语来处理数据库读写、工具副作用、等待、审批、实时进度与流程控制。
何时使用
适合的场景包括：智能体耗时可能超过单个 HTTP 请求；智能体需要调用工具、API、数据库、浏览器、沙箱或 MCP 服务器；智能体需要在部署、崩溃、无服务器超时或模型/API 故障后仍能存活；智能体可能需要等待人工审批、外部回调、定时跟进或用户输入；智能体进度需要从持久化工作流流式传输到 UI；模型/提供商调用需要并发或节流限制；重复发送、扣费、写入或模型调用代价高昂。
通常不值得使用的场景包括：一次简短、只读、无副作用且不需要持久化进度的模型调用；丢失请求也可接受的纯 UI 自动补全。
架构
除非仓库已有更强的既定模式，否则建议采用以下形态：HTTP/服务器操作层验证鉴权、必要时存储用户意图、发出带稳定 ID 的事件并快速返回；由 Inngest 函数托管智能体运行；在 step.run 内加载状态与外部上下文；在函数内创建 AgentKit 智能体或导入智能体/网络工厂；通过 AgentKit / step.ai 运行模型推理，将非模型的工具副作用包裹在 step.run 中；使用 step.waitForEvent 或 step.waitForSignal 处理人工审批与外部回调；用原生实时能力发布持久化进度；当智能体结果需要后续评估时添加会话与评分；在函数级别应用流控以限制提供商与租户用量。
主要能力
基础 AgentKit 函数：建议先写一个小而带类型的函数，单智能体路径验证后再添加网络与额外工具。示例中通过 inngest.createFunction 定义函数，使用 step.run 加载工单，用 createAgent 创建智能体并指定系统提示与模型，运行后保存摘要。
工具调用：工具可用 AgentKit 定义，但面向智能体的安全工具仍需遵循持久化规则。只读工具调用在重放无害时可作为智能体的一部分运行；外部副作用应通过稳定 ID 与 step.run 边界隔离，或实现为使用所提供 step 的工具处理器；工具输出应足够小以适应 step 状态限制；用 schema 校验工具参数，绝不信任模型提供的参数；使用来自已鉴权事件数据的租户/用户 ID，而非仅依赖模型文本。工具副作用检查清单包括：该工具能改变哪些外部状态、什么幂等键可防止重复写入、模型重复调用同一工具时应如何处理、输出是否可安全存入函数运行状态、工具是否需要提供商特定的并发或节流限制。
人工介入：使用持久化等待，而不是轮询数据库或在内存中保存状态。示例使用 step.waitForEvent 等待审批事件，设置超时与匹配条件；若超时则标记需人工复核并返回超时状态；否则在审批后执行发送回复的 step.run。
实时进度：对于 v4 原生实时，可在步骤之间使用 step.realtime.publish，或在已有 step.run 内使用 inngest.realtime.publish。v4 项目不要安装 v3 的 @inngest/realtime 包；不要将进程本地 WebSocket 作为持久化函数进度的唯一来源。对于 AgentKit 特定的 UI 钩子，接线 useAgent 或 useChat 前应检查已安装的 @inngest/agent-kit 版本与当前文档。
智能体评估：当用户要求给智能体评分、比较提示或模型、跟踪用户反馈、按对话/工单分组运行或随时间调试智能体质量时，使用 inngest-agent-evals。在持久化智能体工作流中，在启动或连接用户流程的事件上添加 meta.sessions；对运行期间已知的信号使用直接评分；对稍后到达的产品结果使用延迟评分器。
流控与成本：智能体工作负载常需提供商与租户限制。可对模型提供商使用账户级并发或节流键；在公平性重要处按租户或账户设置键；使用确定性事件 ID，避免重复用户操作产生重复的高成本运行；将成功的模型/工具结果保留在步骤中，使后续失败重试时不会重新扣费此前的模型调用。示例中通过 throttle 限制每分钟 120 次、以 openai 为键，并通过 concurrency 按 accountId 限制为 3。
存量迁移：迁移现有智能体时，先搜索模型调用、工具循环、内存状态、流式处理器、审批轮询与外部副作用；初期保持提示/工具行为稳定；将触发器移入事件与 Inngest 函数；将模型调用移至 AgentKit / step.ai；将带副作用的工具移入 step.run 或持久化工具处理器；用 step.waitForEvent 或 step.waitForSignal 替换进程本地等待；在持久化运行可用后再添加实时。当仓库存在多个可能工作流且用户尚未选定一个时，先使用 inngest-brownfield-audit。
反模式
智能体循环状态仅存于内存；用一个巨大的 try/catch 包裹所有模型与工具调用；一个工具失败后重试整个智能体；后续步骤失败后对已成功的模型调用重复扣费；用 setTimeout、cron 轮询或 Redis TTL 作为人工审核机制；带副作用工具没有幂等键；从可能死亡而持久化工作仍在别处继续的服务器进程流式传输进度；添加 AgentKit 却未注册周围的 Inngest 函数。
验证
对智能体、工具 schema 与事件负载做类型检查；将工具处理器与模型行为分开做单元测试；测试 HTTP 入口发出一个确定性事件并快速返回；测试重复事件 ID 不会产生重复的最终副作用；如有可能，运行 Inngest 开发服务器并检查智能体步骤/追踪。
官方参考
AgentKit 智能体：https://agentkit.inngest.com/concepts/agents createAgent：https://agentkit.inngest.com/reference/create-agent AI 推理与 step.ai：https://www.inngest.com/docs/features/inngest-functions/steps-workflows/step-ai-orchestration 智能体评估：https://www.inngest.com/docs/learn/agent-evals AgentKit 实时钩子：https://www.inngest.com/changelog/2025-09-24-agentkit-use-agent
可复制示例
从零开始构建持久化支持或工具调用智能体时，可查看配套示例 ../../examples/durable-agent。它展示了预期的智能体优先形态：快速 HTTP 触发器、带类型事件、Inngest 函数内的 AgentKit、步骤作用域上下文加载、使用 step.waitForEvent 的人工审批，以及审批后的持久化副作用。