运行生命周期

一眼看懂

一次 agent.stream() 调用涉及 3 层 API、12 个回调、4 条消息链、2 份同名回调。这页把它们全部钉到时间线上。

三层 API 能力矩阵

在读时序图之前先建立地图——每个参数/回调属于哪一层：

L1 和 L2 的同名回调会合并：如果两层都设了 onStepFinish，L1 的先执行、L2 的后执行（源码 dist/index.js:8224-8232）。L3 的同名回调是完全独立的——和 L1/L2 不会合并、payload 也不同。

L3 的另一个入口：本页 L3 列聚焦 result.toUIMessageStream() 这条 transform 路径（被动消费 agent 结果）。L3 还有另一个入口 createUIMessageStream({ execute })——execute-driven 路径，可以在 agent 流之外主动推自定义事件、合并多条流。两者底下共用同一个 handleUIMessageStreamFinish（index.js:8100 / :8397），所以 onStepFinish / onFinish / onError 的触发时机与本页一致；但 messageMetadata 只存在于 toUIMessageStream。execute-driven 路径的细节见 UI 流编排。

完整时序图

以一次跑 N 步的 agent.stream() 为例，时间从上往下流：

三条关键观察：

1. L1/L2 的回调和 L3 的回调是并发的——L2 一边跑循环往 fullStream 推 chunk，L3 一边 pipe transform。所以 L1/L2 的 onStepFinish(n) 和 L3 的 onStepFinish(n) 在时间上几乎同时发生，但在 event-loop 里是独立任务。
2. L3 的 onFinish 一定晚于 L1/L2 的 onFinish——因为 L3 是下游 transform，必须等 fullStream 关闭 + 消费者读完才 flush。想”运行结束后做事”要分清：用 L1/L2 onFinish 做引擎侧清理（token 统计、close sandbox），用 L3 onFinish 做UI 侧持久化（保存 assistant message）。
3. messageMetadata 在每个 chunk 都被调用——包括每个 text-delta、tool-input-delta。一次多工具长回答动辄上千个 chunk，这里做任何同步 I/O 都会直接卡住流。

回调触发时机速查表

按触发顺序排列。L1 = ToolLoopAgent settings，L2 = streamText（agent.stream 直通），L3 = toUIMessageStream。

onFinish 抛错不走这里：callOnFinish（index.js:5927-5943）是裸 await，没有 try/catch——onFinish throw 会冒到 TransformStream 的 flush()，让消费端 iterator reject，不会触发 onError。任何生产级 onFinish 都必须自己在回调里兜一层 try/catch/finally。完整错误捕获分层见 UI 流编排 - 错误捕获全貌。

双层同名回调——最容易踩的坑

onStepFinish：L1/L2 vs L3

onFinish：L1/L2 vs L3

L1/L2 onFinish 的闭包陷阱：L1/L2 onFinish 的参数 payload 包含整个 steps 数组（每一步的完整 StepResult——content、toolCalls、toolResults、request、response 全在里面）。如果回调闭包捕获了这个 payload 并挂在长寿命引用上（例如存进外层 session 对象），整次调用的大对象图都会被 pin 住、GC 不掉。长链对话尤其危险——20 步累计的 StepResult 可能上百 MB。

实战建议：

• 短结算逻辑（token 计数、step 日志）可以放 L1/L2 onFinish——回调返回后闭包释放
• 长结算逻辑（持久化、后台任务、checkpoint 写入）优先放 L3 onFinish，payload 已经是折叠过的 responseMessage + messages，体量小得多
• 或者:用 L1/L2 的 onStepFinish 每步增量收集你要的数据到一个小变量（只保留数字 / 字符串 / id,不保留 StepResult 本身），然后在 L3 onFinish 用这个小变量做结算

stopWhen 默认值兜底链——第二个容易踩的坑

同一个参数名，在 L1 和 L2 的默认值不同：

L1 new ToolLoopAgent({ stopWhen? })  默认值: stepCountIs(20)   ← dist/index.js:8210
L2 streamText({ stopWhen? })         默认值: stepCountIs(1)    ← dist/index.js:6452

ToolLoopAgent.stream() 会把 L1 的 stopWhen（默认 20）传给 streamText，所以正常用法下 agent 最多跑 20 步。

但如果你直接调 streamText(...) 不设 stopWhen，agent 只会跑一步——出单个 tool call 就停，不会继续。初学者常见踩坑。

内置 stop 条件（可以组合：stopWhen: [stepCountIs(N), hasToolCall('complete')]）：

典型生产组合：[stepCountIs(N), hasToolCall('complete')]——数字作为硬性上限（避免 agent 陷入死循环），hasToolCall('complete') 作为”明确任务完成”的信号（让 agent 自己声明结束）。N 的取值取决于任务复杂度：简单问答 10-20、通用助理 30-50、深度研究 / 多步编辑 50-100。

三级 timeout——第三个容易踩的坑

timeout 是个对象，三级粒度：

agent.stream({
  timeout: {
    totalMs: 600_000,   // 整次调用：10 分钟
    stepMs: 300_000,    // 单步：5 分钟（模型+工具总和）
    chunkMs: 120_000,   // 两个 chunk 之间间隔：2 分钟
  },
});

三级独立生效，任一超时都会通过 AbortSignal.timeout() 触发 abort（dist/index.js:6483-6495）。

社区教程通常只提 totalMs——但 chunkMs 是生产里最常救命的一级。模型流可能开头吐出两行就卡住（provider TCP 半连接、reasoning 阶段 thinking 太久等），此时 totalMs 还远没到，但 chunkMs 会直接终止。生产环境一个稳妥的默认值是 chunkMs: 120_000（2 分钟）——足以覆盖大多数 reasoning 模型的长思考间隙，又不至于让真断连悄悄拖很久。

prepareCall —— 很少人用的上游钩子

除了 prepareStep（每步一次），L1 还有 prepareCall（每次 agent.stream() 一次）：

new ToolLoopAgent({
  model, instructions, tools,
  prepareCall: async (baseCallArgs) => {
    // baseCallArgs 是所有合并后的参数（settings + method 选项）
    // 返回改写版——或什么都不返回沿用 baseCallArgs
    return {
      ...baseCallArgs,
      tools: dynamicallyDeciderTools(baseCallArgs.messages),
      stopWhen: stepCountIs(deriveStepLimit(user)),
    };
  },
});

什么时候用：

• 动态切换工具集（user tier / A-B test）而不想新建 agent 实例
• 基于调用时的输入动态选 model
• 按调用动态设 stopWhen

prepareCall vs prepareStep：

实战选择建议：大多数项目用 prepareStep 就够了——运行时压缩、每步注入 reminder、根据对话长度切换工具集，都是 per-step 场景。prepareCall 更适合 agent 实例跨请求复用的部署模式（模块顶层构造一次 agent,每个 HTTP 请求内根据 user tier / AB 实验动态改写）。如果你的 agent 是每个请求重新构造的（orchestrator 层已经做了配置动态化），prepareCall 就显得多余。

experimental_* 回调——被低估的四个钩子

官方标 experimental_ 前缀，意思是 API 签名可能变；但这四个在 ai@^6 里已经稳定，是构建可观测 agent 的核心：

和 onStepFinish 的区别：onStepFinish 是 step 结束后的聚合回调（整个 StepResult），experimental_onStepStart 是 step 开始时的切换点（无 payload，纯信号）。要做 “step 间清理” 用前者，要做 “step 初始化” 用后者。

延伸阅读

相关 SDK 章节

• 消息引用模型 — 前面频繁提到的 initialMessages / responseMessages 的引用关系
• prepareStep 语义 — 最常用的钩子的深挖
• UI 流编排 — L3 createUIMessageStream 的 execute-driven 路径 + 错误捕获全貌

SDK 源码锚点（ai@6.0.134）

• dist/index.js:6441-6532 — streamText 入口
• dist/index.js:6750-6810 — onStepFinish 发射点
• dist/index.js:8180-8317 — ToolLoopAgent 实现
• dist/index.js:7839-8108 — toUIMessageStream 实现

Zapvol 落地参考

• packages/backend/src/agent/agent-stream.ts — 所有层回调的组装点（L1/L2 settings、L3 toUIMessageStream 参数、stepUsages 收集模式）
• packages/backend/src/agent/agent-factory.ts — stopConditions 数组的构造方式
• apps/server/src/services/task-orchestrator.ts — L3 onFinish 做 assistant message 持久化