服务对象与地域限制
PuppyIP 仅面向海外合规企业及其授权人员提供服务，不面向中国大陆地区开放或提供代理服务。本服务仅限用于中国大陆境外的合法业务活动，严禁在中国大陆境内使用本服务。
代理 IP 或服务器位于境外，不改变上述限制。不得通过中转、转接、共享或转售向中国大陆境内的最终使用者提供本服务。使用前请阅读用户服务协议。
本文要点
- Agents SDK v0.33.0 的 PiHarness 使用 Pi 1.5；Pi Durable 仍是实验性项目，API 可能随 minor 版本变化。
- 流式内容默认在一秒内批量持久化，崩溃时最近约一秒的进度可能丢失；将 settings.progress.persistWithinMs 设为 0 会为每次更新增加一次存储写入。
- session.continue() 用现有 transcript 开始新 run；恢复时只重放明确标为 replay:safe 的工具。
- Pi 1.5 已运行过的对话不能由 Pi 1.4 读取；升级后应向前修复，不要回退到 Pi 1.4。
先确认版本和兼容范围
Cloudflare Agents SDK v0.33.0 将 PiHarness 升级到 Pi 1.5，调整了流式内容持久化、会话观察和故障恢复。版本边界按 Pi minor 版本管理：Cloudflare 文档列出的 Pi 可选 peer packages 为 ~1.5.0，每个 Agents SDK release 对应一个 Pi minor 版本。Pi Durable 仍属实验性项目，API 可能在 minor 版本之间变化；应按该 release 的升级说明核对实际解析到的兼容依赖。
调用 session.events() 的代码要改用 session.watch()；retry() 和 parked 状态已移除。session.watch() 提供较新的 transcript 条目与会话实时状态，包括正在流式输出的回答、运行中的工具，以及上一次 run 未回答结束的原因。它是内存视图，对象重启后需要重新打开会话再观察。
把写入减少与持久化窗口一起评估
Pi 1.5 将流式回答和工具输出按批次写入，而不是每次更新都写入。Cloudflare 表示，SQLite 基准中，长回答的存储事务约减少 27 倍，并行工具 turn 约减少 5.7 倍，CPU 约减少四分之一。更新仍会立即显示给调用方，但默认持久化窗口约为一秒，因此发生崩溃时，最近约一秒的流式进度可能没有保存。
若将 settings.progress.persistWithinMs 设为 0，可让每次更新都写入存储，代价是增加写入次数。上述数字来自 Cloudflare 的 SQLite 特定工作负载测量，不是对其他应用的性能或成本承诺；应根据任务能否承受最近一秒进度丢失来选择保存窗口。
先检查结果，再继续 unanswered run
长任务可把提交与等待分开：submit() 在模型运行前返回已持久化输入的 receipt，随后 wait() 按 operationId 返回完成结果。发生模型错误或达到 turn limit 后，先用 session.wait(operationId) 检查原 run，并修复导致中断的问题。只有 transcript 未回答且会话空闲时，才适合调用 session.continue({ operationId: `${operationId}:continue` })；随后再等待 receipt.operationId。
session.continue() 使用现有 transcript 启动新的 run，不会附加新的 user message。会话仍在运行时调用会被拒绝；如果 transcript 已以回答结束，结果会是 unanswered，原因是 nothing_to_answer。它不是无条件重试按钮，也不证明此前某个外部工具的副作用没有发生。
区分 harness 恢复与副作用重做
PiHarness 遇到存储错误后会重新打开 Pi；用于打开 Pi 的 harness factory 也会再次执行。Cloudflare 文档要求该 factory 可以安全地重复运行。Pi 的恢复流程只重放明确标记 replay:safe 的工具，其他被中断的工具会把中断信息交还模型处理。这个标记只是应用为工具选择的重放策略，不是外部系统保证副作用可重复的证明。
对付款、创建资源、发送消息等副作用工具，应为外部操作设计幂等键，或先核对原操作结果，再决定是否发起新操作。不要仅因 run 未返回回答就再次提交同一业务动作；也不要把 session.continue()、存储恢复与重新调用工具视为同一个动作。
把升级视作对话数据格式变更
Pi 1.5 写入的对话数据不能由 Pi 1.4 读取。只要某个 conversation 已在 Pi 1.5 上运行，回退到使用 Pi 1.4 的 Agents SDK 版本就可能使该 conversation 无法读取。Cloudflare 建议升级后通过向前发布修复部署问题，而不是回退到 Pi 1.4；因此，先验证调用方变更、工具重放规则和恢复路径，再允许新版本处理需要保留的对话。
本文依据 Cloudflare 于 2026 年 11 月 3 日发布的 changelog 与当前 Pi 文档整理，没有执行安装、升级或运行时恢复，也不构成账号、套餐、价格或地区可用性保证。请以部署所用版本的当前官方升级文档为准。
资料来源
常见问题
模型失败后，排队输入会自动删除吗？
默认 settings.afterFailedRun 为 keep：排队输入会保留，wait() 继续等待；之后 submit() 会先按原顺序处理已排队输入，再处理新输入，reset() 也可使保留输入重新开始。对象在此期间可以休眠，因此保留输入不代表它已完成；应先解决失败原因，再决定如何恢复。
abort() 会立即停止正在执行的工具吗？
不一定。abort() 会等待会话进入空闲状态；如果工具不理会中止信号，会话要等工具返回才结束忙碌状态。取消 wait() 的等待信号只停止等待，不会取消后台工作。重新执行有副作用的操作前，仍须核对外部结果。