AgentOS 沙箱检查点该放哪

结论先说

AgentOS v3.1.8 把沙箱检查点存储从单机文件路径扩展到 PostgreSQL，而前一版已加入 S3 兼容存储；对多副本部署来说，关键不再是“沙箱能不能启动”，而是每个处理后续轮次的副本能否读到同一份已提交检查点。检查点保存着沙箱工作区快照，若队列任务落到另一个副本而它访问不到文件，恢复就会失败。上线前应显式选择共享存储，并理解默认保留策略会限制旧运行的可恢复范围。

检查点不是普通日志

沙箱型 Agent 会跨多个运行轮次继续使用工作区。检查点用于保存某次运行提交的沙箱状态，使后续轮次能从已有状态恢复，而不是只依赖接受请求的进程内存或本机目录。因此，队列把任务交给另一副本时，存储可见性是正确性的前提：所有可能执行同一会话后续任务的副本，都必须能打开对应检查点。

Agno 的 S3 存储合并说明直接点出原有边界：FileCheckpointStore 是核心中的文件存储； durable queue 不接受其默认本地路径，因为另一副本无法读取。此前，多副本部署需要共享文件系统。S3CheckpointStore 将同一检查点协议放到 S3 兼容存储上；v3.1.8 又增加 PostgresCheckpointStore，让已有 PostgreSQL 的部署可以把检查点写进数据库。后者是可选项，默认存储没有因此自动切换。

这对开发者的直接影响是：启用 durable queue 或多副本，并不等于检查点已经跨副本共享。不要因为会话记录、队列票据在数据库里，就推断沙箱归档也在数据库里。应分别确认队列状态和检查点对象的存放位置，并让每个工作副本配置相同的后端及访问凭证。

PostgreSQL 与 S3 的取舍

选择时先看现有基础设施和检查点数据规模，而不是把两种后端当成无差别开关。

如果服务已经有 PostgreSQL，并希望减少额外对象存储依赖，可以评估 PostgresCheckpointStore。合并请求展示的接入方式是把该存储对象传给沙箱，例如：

from agno.sandbox.postgres_checkpoints import PostgresCheckpointStore

sandbox = DockerSandbox(
    image="your-sandbox-image",
    checkpoints=PostgresCheckpointStore(db),
)

其实现把归档拆成头部记录与分块数据，默认块大小为 8 MiB；头部按 SHA-256 键控，写入采用事务，并在读取时校验。表在首次使用时创建，分块表会随头部删除而级联清理。这样的设计让归档可以随数据库事务与现有运维体系管理，但也意味着检查点会占用数据库存储与备份容量。评估时要把写入量、备份恢复时间、数据库扩容和清理策略纳入容量规划，不要只看接入代码短不短。

如果团队已有 S3 兼容对象存储，或沙箱归档不适合进入关系数据库，则可以评估 S3CheckpointStore。其实现遵循同一存储协议，包含写入、校验、打开归档和删除等操作；合并说明也以对象存储适合较大的检查点作为设计理由。此时需要确认所有副本能访问同一 bucket 与对象，并把凭证、网络访问和对象生命周期策略作为部署配置的一部分。

两者都解决“副本之间共享检查点”这个问题，但并不替代部署验证。最小验证应在副本 A 执行并提交一轮后，让副本 B 接手同一会话，确认它能够打开该轮检查点并继续运行；还要验证删除会话时相关检查点是否按预期清理。测试不能只在同一进程里连续运行，因为那无法覆盖副本边界。

默认保留三份会改变恢复边界

v3.1.8 同时调整了沙箱检查点保留：每个会话默认保留最新的三个检查点。未发布或被新版本取代的检查点，会在运行结果安全保存后退役并删除。若业务需要保留所有检查点，可设置 retain_checkpoints=None；这会回到不限制数量的保留方式，但也意味着存储增长需要自行管理。

因此，检查点保留不是单纯的清理细节，而是恢复策略的一部分。如果运维流程假设可以随时回到很久以前的运行状态，就不能直接套用默认值。应先定义需要回看的时间范围或运行数量，再决定是否采用默认保留；如果无限保留，则应另外安排容量监控与清理，而不能假设数据库或对象存储会自动替应用做业务级淘汰。

还应把“旧检查点不存在”当成明确的恢复失败处理。发布说明指出，检查点对象缺失现在会以清晰、不可重试的错误结束该轮，退役新建的计算环境并释放会话；此前可能让队列反复重试、持续处于运行态，并阻塞同一会话的后续轮次。这个变化有助于避免无意义重试，但它并不能找回已经删除的状态。应用侧需要让错误可见，并提供重新开始会话或人工恢复的路径。

上线前逐项核对

第一，确认实际使用的组件确实启用了 durable queue 与沙箱，不要把普通 Agent 的运行方式和沙箱检查点混为一谈。第二，在多副本场景中选择共享检查点后端，并确保所有副本使用一致配置。第三，核对保留数量是否符合产品承诺；默认三个检查点不等于无限历史。第四，演练对象缺失或数据库不可用时的失败行为，确认会话不会被无限重试锁住。第五，检查删除会话后的存储清理与备份策略，尤其是数据库归档对数据库体积的影响。

如果你的系统还在比较不同 Agent 框架的会话与部署能力，可以先从平台目录梳理框架与接入类型；如果正在维护网关或中转 API，也可参考多模型接入的兼容性排障文章，把模型调用链路和沙箱状态恢复分别纳入故障演练。

这次变化适合已经使用 AgentOS 沙箱、且正在部署多副本或 durable queue 的团队：可以在共享文件系统、S3 兼容存储与 PostgreSQL 之间选择检查点后端。它不意味着默认配置自动具备跨副本恢复能力，也不意味着保留策略、备份和缺失检查点恢复都无需设计。