2026 年 10 月 17 日agno 发布 v3.1.4。此次版本围绕沙箱化智能体、持久化执行、AgentOS 队列、附件处理、会话并发控制、Docker 与 Amazon Bedrock AgentCore 运行环境等方向进行了大规模升级。v3.1.4 的核心变化是ClaudeAgent 与 CodexAgent 可以通过sandbox参数运行在隔离的、按会话划分的计算机中不再直接在宿主机执行 Harness 进程。结合 Postgres 持久化、检查点恢复、原生会话状态校验、暖沙箱复用、AgentOS Durable Queue 等能力智能体任务可以在容器、宿主机或副本故障后恢复到上一次已经提交的状态。同时本次更新进一步完善了 DockerSandbox、AgentCoreSandbox、附件持久化、Claude 图片与 PDF 内联、单会话队列串行、即时唤醒本地队列 Worker、ChartTools 图表工具以及数据库组件、Factory 组件的 Durable Queue 支持。一、Sandboxed Harness AgentsClaudeAgent 与 CodexAgent 进入隔离会话计算环境v3.1.4 新增沙箱化 Harness Agent 能力。ClaudeAgent 与 CodexAgent 现在可以接收sandbox参数将整个 Harness 执行过程运行在隔离的、每个会话独立的计算机环境中而不是直接运行在宿主机上。会话状态具备持久化能力。即使容器被销毁、宿主机丢失或者执行上一轮任务的副本发生变化系统仍可以从最近一次已提交的检查点恢复会话。配置方式不需要引入新的协调器类。例如ClaudeAgent(idcoder,dbPostgresDb(...),sandboxDockerSandbox(agno-sandbox:local,networkisolated))以上配置即可完成基础接入。智能体会在首次使用时根据自身关联的 PostgresDb 自动构建协调器。每轮执行过程包含以下关键步骤通过 Agent 的 Postgres 数据库中的租约记录声明会话。租约表为session_table_sandbox_bindings。该表会在首次使用时自动创建。启动计算环境时从会话最近一次已经提交的检查点恢复。检查点包含工作区内容以及 Harness 自身的会话文件。执行当前轮任务。执行完成后系统捕获并校验新的检查点。新的运行记录与恢复点会在同一个事务中发布。这意味着一轮任务只有在成功完成并且检查点验证成功后才能更新会话恢复点。如果某一轮任务被取消或者执行失败不会发布新的运行结果。不会发布新的检查点。上一个成功提交的检查点仍然保留为恢复点。这种设计确保失败或取消的执行不会污染已持久化的会话状态。此外系统不会在无法验证状态时继续执行。系统会携带与上一个检查点一起提交的原生会话标识Claude 使用 Claude session id。Codex 使用 Codex thread id。如果恢复时发现该原生会话状态丢失系统会在模型运行前直接失败并返回native_state_missing而不会静默创建一个全新的会话。这样可以避免“工作区恢复了但模型原生对话上下文已经丢失”的隐蔽状态错误。Harness 设置也具备类型化传递能力会以 JSON 形式传递到运行时环境。而仅允许存在于宿主机侧的设置会在构造阶段被拒绝包括cwdretriesenv原生选项对象BaseExternalAgent新增以下选项require_native_resumestrict_persistence另外agno[claude]与agno[codex]安装额外依赖已经覆盖对应的 Harness SDK。二、DockerSandbox面向客户自运营的隔离容器沙箱v3.1.4 提供 DockerSandbox作为由客户自行运营的沙箱 Provider。DockerSandbox 对容器运行环境进行了多层隔离与限制。容器以 UID 1000 运行并采用以下安全限制镜像文件系统为只读。删除 Linux capabilities。禁止权限提升。限制 CPU 使用量。限制内存使用量。限制进程数量。为/workspace配置有界 tmpfs。为/runtime配置有界 tmpfs。不挂载宿主机目录。不挂载 Docker Socket。仅允许显式配置的环境变量。除显式环境变量外仅提供 Harness 所需的模型 API Key。网络默认完全关闭即默认networknone。如果设置networkisolated则 DockerSandbox 会提供受管理的桥接网络并关闭容器之间的通信。还可以通过subnet指定网络子网范围。DockerSandbox 使用确定性的会话身份与 generation 身份用于处理创建竞争和响应丢失问题。命令不会被自动重试。这一点意味着系统不会在命令结果不确定时自动重复执行可能产生副作用的命令。DockerSandbox 还提供暂停与恢复能力pauseresume暂停和恢复通过 Linux kernel freezer 实现。检查点传输则通过 DockerCheckpointTransfer 完成可以在沙箱外部与沙箱内部移动检查点数据。运行时镜像可通过以下脚本构建cookbook/frameworks/sandbox/build_image.py该脚本会构建运行时镜像并将构建完成的标签加载到镜像存储中同时验证镜像确实已经存在。三、Amazon Bedrock AgentCore Sandbox基于 Firecracker MicroVM 的沙箱执行v3.1.4 同时新增 AgentCoreSandbox。AgentCoreSandbox 在 Amazon Bedrock AgentCore Runtime 上实现与 DockerSandbox 相同的沙箱契约。检查点传输能力通过 AgentCoreCheckpointTransfer 提供与 DockerCheckpointTransfer 并列。每一个沙箱 generation 对应一个 AgentCore Runtime session并在 Firecracker microVM 中运行。创建过程具备幂等性。系统会根据以下信息推导 session idnamespaceagentsessiongeneration因此即使创建请求发生重试或响应丢失也可以定位到同一个沙箱运行时会话。在微型虚拟机中根服务监听在 8080 端口负责声明 microVM。以 UID 1000 启动运行时。对后续操作进行配置校验。使用随机 incarnation 防止陈旧句柄操作后续声明。转发启动与轮询调用。在命令执行前使用 guard 将执行身份降级为 UID 1000。将命令执行目录限制在/workspace。检查点捕获与恢复时系统会停止 UID 1000 的进程避免正在写入的文件进入不一致状态。检查点通过InvokeAgentRuntime分块传输最大支持 2 GiB。AgentCoreSandbox 不支持暂停。同时AgentCore session storage 不会被使用。Provider 包路径也进行了调整agno.sandbox.docker agno.sandbox.agentcoreDockerCheckpointTransfer 现在从以下模块导入agno.sandbox.docker本次运行时还包含两项针对 Codex 的修复并同样适用于 Docker 环境自动创建CODEX_HOME。当没有匹配的已保存登录状态时使用OPENAI_API_KEY进行 Codex 登录。由于检查点不会包含auth.json因此这项登录处理可以确保恢复后的环境仍然能够使用 Codex。AgentCore 运行时的构建、推送和部署可以通过以下脚本完成cookbook/frameworks/sandbox/agentcore/agentcore_setup.py四、Warm Sandbox Turns暖沙箱会话复用缩短后续轮次执行时间v3.1.4 新增 Warm Sandbox Turns。协调器在一次任务完成后不会立即销毁该会话对应的计算机。默认情况下系统会保留计算环境warm_computer_seconds秒默认值为 300 秒。在这段时间内DockerSandbox 会暂停容器。AgentCoreSandbox 会让运行时保持空闲。如果下一轮任务在暖窗口期间到达系统会恢复现有计算环境。不需要重新从检查点恢复。可以直接继续执行。如果下一轮任务超出暖窗口系统会退役旧计算环境。创建新的 generation。从上一次检查点走冷启动恢复路径。无论是暖启动还是冷启动系统仍然会在每一轮结束后捕获检查点。因此暖计算机只是对已保存检查点状态的加速路径而不是唯一的状态来源。每一个已完成运行的metadata.sandbox.resumed字段会记录本轮任务采用了哪一种路径。协调器还提供以下方法用于主动清理未返回的会话计算机retire_computersweep_warm在 Docker 环境中暖启动 Claude 回合耗时为 4.6 秒冷启动耗时为 8.2 秒。在 AgentCore 环境中暖启动耗时为 3.3 秒冷启动耗时为 8.2 秒。五、Sandbox Through AgentOSAgentOS 支持沙箱智能体的前台、流式与后台运行v3.1.4 将沙箱智能体接入 AgentOS。对于沙箱化智能体请求POST /agents/{agent_id}/runs可以提交以下类型的任务前台请求。流式请求。后台请求。这些请求都会进入持久化队列不需要新增 API 端点。对于带有Idempotency-Key的重试请求如果请求内容一致会返回同一个 run。如果 session 不同会返回 409。如果输入不同会返回 409。如果 options 不同会返回 409。如果附件字节不同会返回 409。客户端可通过以下接口重新连接运行事件/runs/{run_id}/resume并携带last_event_index。取消任务可使用/runs/{run_id}/cancel取消能力支持跨副本处理。即使取消操作在另一个副本完成系统也会正确将运行记录标记为 cancelled并保留用户本轮输入在运行记录中。AgentOS 对沙箱化智能体增加了启动校验如果沙箱化智能体没有 Postgres 用于协调AgentOS 会在启动时失败。当队列 Worker 处于活动状态时系统会拒绝使用宿主机本地的默认检查点存储。AgentOS 会在启动时验证每个沙箱智能体的 bindings 表。在提交任务前也会再次验证 bindings 表。如果发现表来自更早的构建版本错误信息会明确说明修复方式。六、Attachments for Sandboxed Agents沙箱智能体支持图片与文件附件v3.1.4 中沙箱化 ClaudeAgent 与 CodexAgent 的run和arun方法支持以下参数imagesfilesAgentOS 的运行接口也支持以上传方式传递附件。附件处理遵循“仅字节进入沙箱”的原则。在任何持久化写入之前附件都会先完成校验和编码。随后附件会由 Harness 自身的 staging 流程写入/workspace/.agno/uploads/run_id/附件会被保留在当前轮次的检查点中。因此即使后续回合在全新的计算机中恢复智能体仍然能够读取之前上传的附件。每个请求的附件限制如下最多 16 个附件。所有附件合计不超过 512 KiB。以下输入会被拒绝URL。media reference。服务器文件路径。音频。视频。对于进入持久化队列的任务附件会与提交记录一起保存。因此重试请求会传递相同的附件字节而不是重新读取外部位置。七、Claude Code 图片与 PDF 内联避免 Read 工具读取大文件导致缓冲区溢出v3.1.4 优化了 ClaudeAgent 对附件图片和 PDF 的处理。对于符合条件的文件ClaudeAgent 不再只是把文件写入磁盘并依赖 Claude 的 Read 工具读取而是直接将附件以内联内容块的方式发送给 Claude。支持内联的图片格式包括PNGJPEGGIFWEBPPDF 也支持内联。图片与 PDF 的大小上限为 4 MiB。这种方式与 Agent SDK 的流式输入内容块形式一致。Claude 可以直接看到图片而不需要重新读取文件。此前如果 Claude 通过 Read 工具读取图片工具可能返回整个文件的 Base64 内容。这会导致以下缓冲区问题Agent SDK 的 1 MiB 消息缓冲区溢出。沙箱 256 KiB 事件帧溢出。即使图片只有数百 KB也可能因为 Base64 膨胀而触发问题。是否内联不是根据文件扩展名判断而是根据文件实际字节内容判断。因此被错误标注为图片或 PDF 的文件不会被错误内联。这类文件仍会留在磁盘中供文件工具读取。其他文件仍然采用 Read 路径。超过大小限制的图片也继续采用 Read 路径。八、Queue Per Session同一会话的 Durable Run 串行执行v3.1.4 增加单会话队列控制。对于同一个 session 的后台持久化任务系统现在确保最多只能同时运行一个任务并且严格遵循提交顺序。该机制适用于所有组件。每个队列 ticket 都会携带由存储层分配的session_seq。一个 ticket 只有同时满足以下条件时才会被领取当前 session 没有兄弟任务处于 running 状态。当前 session 没有兄弟任务处于 paused 状态。没有更早提交的兄弟任务仍然处于 queued 状态。因此正在等待的任务不会消耗执行尝试次数也不会占用 Worker 槽位。不同 session 仍然可以在max_concurrency范围内并发执行。暂停状态的运行会持续占用所属 session。继续执行或重试的运行会保留其原有顺序位置。当运行状态为PENDING时轮询结果会通过waiting_on告知它被哪个运行阻塞。配置项如下QueueConfig.queue_per_session该选项默认开启。外部智能体无论该设置如何配置都会保持串行执行。GET /config会返回实际生效的配置值。九、Instant Durable Submissions提交后立即唤醒本地 Queue Worker此前持久化任务提交后可能需要等待最多一个poll_interval才会被 Worker 领取。v3.1.4 优化了这一过程。当某个副本接收到 Durable Submission 并完成 ticket 提交后会立即唤醒本地队列 Worker。因此任务可以在毫秒级时间内开始执行而不需要等待下一轮轮询。如果当前副本已饱和当执行槽位释放时会触发唤醒。其他副本仍然会按照各自的轮询机制领取任务。该优化不会改变持久化语义。任务记录仍然会先写入并提交到数据库然后才唤醒 Worker。十、ChartTools新增内联图表工具v3.1.4 新增 ChartTools Toolkit。该工具包目前包含一个工具create_chart该工具可以校验图表载荷并返回可由 Agno OS 直接渲染的 fenced chart block。支持的图表类型包括barlineareapiebar-horizontalbar-stackedarea-stacked如果图表载荷校验失败工具会明确告诉模型需要修复的内容。ChartTools 自带工具说明。因此智能体只需要配置tools[ChartTools()]即可使用图表能力不需要再手动携带图表 schema 提示词。十一、数据库组件与 Factory 组件全面进入 Durable Queuev3.1.4 改进了 Durable Queue 对组件的覆盖范围。以下场景中的后台运行现在都会使用 Durable Queue而不再退化为由接收请求的副本创建 detached task通过 components API 创建的组件。version-pinned runs。AgentFactory 提交。TeamFactory 提交。WorkflowFactory 提交。接收请求的端点会在 ticket 中写入 resolution scope其中包括sourceownerversion工厂场景下的 trusted claims工厂输入Worker 在领取任务时会重新执行对应的 resolution。对于 Factory如果逻辑在 Worker 中读取ctx.request运行将会失败并返回明确的修复提示。原因是实时 HTTP request 无法被写入 ticket 并随 Durable Queue 传递。Factory Run 的读取路由也已经修复不再在每次轮询时统一返回 400。十二、Codex 权限策略字段调整由于sandbox现在用于接收沙箱 Provider原先CodexAgent(sandboxread-only)中的字符串形式权限策略进行了字段调整。新的字段名称为sandbox_mode这与 Codex 自身的配置键保持一致。旧的字符串形式仍然可用但会触发DeprecationWarning。十三、Sandbox Cookbook 重组与 Gemini Cookbook 更新沙箱相关 Cookbook 已经重新组织。原有目录拆分为cookbook/frameworks/sandbox/docker/ cookbook/frameworks/sandbox/agentcore/两个目录分别拥有自己的 README 和测试日志。内容覆盖以下主题Provider。检查点。协调器。恢复。取消。附件。暖沙箱轮次。AgentOS。Gemini Cookbook 也已更新至当前模型与 API。十四、重要修复Sandbox Checkpoint Restore此前沙箱会话每隔一轮恢复时可能失败并出现如下问题getent unable to find entry 1000:1000 in passwd database原因是docker cp --archive会要求 Docker daemon 将容器用户解析为名称。当前修复方式为恢复时不再使用 archive 模式复制。对每个恢复的文件项明确指定所有者为1000:1000。这样可以避免 UID 解析失败导致的第二轮任务恢复问题。十五、重要修复Sandbox Store 与 Coordinator本次版本修复了多个与沙箱存储和协调器相关的问题。首先队列取消操作与 Worker 领取同一运行任务发生竞争时可能因锁顺序不同导致死锁。现在 stop 路径会按照与其他存储事务一致的顺序获取锁sessionrunbinding其次DockerSandbox 的同步调用此前每次都会泄漏一个 HTTP client。该问题已经修复。另外已取消的沙箱运行现在会记录 Durable Queue 所期待的EXECUTING取消阶段。如果某个运行处于 cleanup 与 commit 之间被标记为 finished系统现在会进入 stop 路径而不会让 binding 停留在finalizing状态。对于耗时较长的 Provider 调用系统也会延长租约避免执行期间租约过期。十六、重要修复Sandbox Submissionsv3.1.4 修复了 session 与user_id不匹配时的错误处理。以下情况现在会在 ticket 创建之前直接返回 404提交请求带有user_id但 session 创建时没有user_id。提交请求没有user_id但 session 创建时带有user_id。此前此类情况可能返回 500并留下一个已取消任务。此外如果前台请求在 run row 创建前已经失败系统现在会直接返回 ticket 中的错误并返回 500。此前该情况可能返回 503并要求客户端重新连接。十七、重要修复WebSocket Tails 支持一个连接订阅多个运行在 Durable Queue 场景中如果聊天客户端在一个 workflow run 正在通过 WebSocket 流式输出时发送第二条消息第一条运行的事件流此前可能停止。v3.1.4 修复了这一问题。Tail pump 现在按照以下维度进行管理(socket, run)重新订阅只会替换当前 run 对应的 pump不会影响同一个 socket 上的其他运行。一个 WebSocket 最多可以附加 32 个运行。这样客户端即使在同一个连接中连续发送多条消息也可以持续接收此前运行的事件流。十八、API Docs 路由顺序修复v3.1.4 修复了 API 文档中的路由显示顺序。在 setup 和 resync 过程中FileSystem 路由现在会注册在 Database 路由之后。因此生成的 API 文档会以正确顺序展示这些路由。十九、测试调整Factory Workflow WebSocket 测试固定内联路径由于 Factory 提交现在也进入 Durable Queue原本针对 WebSocket Factory Workflow 的测试行为发生了变化。本次测试调整将相关用例固定在其原本编写时依赖的 inline path 上确保测试验证目标保持一致。二十、AgentOS Manager、Company 能力与任务管理相关更新除沙箱与队列能力外v3.1.4 还包含 AgentOS Manager 及 Company 相关功能更新。本次发布涉及以下内容新增 AgentOS Manager。保持 AgentOS Manager specialists 为内部使用。新增可选启用的 Company Products。新增 Company work records。新增 Company playbooks。新增 Product Manager。修复 Company manager 路由。修复 Company 数据库身份问题。修复 Company 工具参数问题。新增 Company Task 执行能力。新增 Company Task attention 能力。支持 Company archive 级联处理。新增 Company grouped counts。二十一、v3.1.4 版本重点总结代码地址github.com/agno-agi/agnoagno v3.1.4 的重点不只是增加一个容器运行选项而是建立了一套完整的沙箱化、持久化、可恢复的外部 Harness Agent 执行机制。这一版本的关键能力包括ClaudeAgent 与 CodexAgent 支持sandboxProvider。每个 session 拥有独立且可恢复的计算环境。Postgres 负责协调租约、绑定关系、运行记录与恢复点。每轮成功执行后提交检查点。失败与取消不会覆盖上一次成功状态。原生 Claude session id 与 Codex thread id 会被校验。原生会话状态缺失时直接失败不会静默新建会话。DockerSandbox 提供受限容器环境。AgentCoreSandbox 提供 Firecracker microVM 环境。支持 Docker 与 AgentCore 的检查点传输。支持暖沙箱恢复降低连续会话的启动成本。AgentOS 支持沙箱任务进入 Durable Queue。支持跨副本恢复、取消和事件重新连接。支持图片与文件附件持久化到检查点。Claude 图片与 PDF 支持内联输入。Durable Queue 支持同一 session 串行执行。提交后可即时唤醒本地 Worker。数据库组件、版本固定运行和 Factory 运行均支持 Durable Queue。新增 ChartTools 图表工具。修复检查点恢复、锁顺序、HTTP client 泄漏、WebSocket tail、路由排序等问题。对于需要让 ClaudeAgent 或 CodexAgent 在隔离环境中执行长链路任务、持续维护工作区、跨节点恢复会话状态、处理附件、接入 AgentOS 持久化队列的场景agno v3.1.4 已经将沙箱、检查点、协调器、队列、恢复与运行接口组合为完整能力。
