agno v3.1.4 正式发布：沙箱化 Harness Agent、持久化队列、AgentOS 与附件能力全面升级

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 Agents：ClaudeAgent 与 CodexAgent 进入隔离会话计算环境

v3.1.4 新增沙箱化 Harness Agent 能力。

ClaudeAgent 与 CodexAgent 现在可以接收sandbox=参数，将整个 Harness 执行过程运行在隔离的、每个会话独立的计算机环境中，而不是直接运行在宿主机上。

会话状态具备持久化能力。即使容器被销毁、宿主机丢失，或者执行上一轮任务的副本发生变化，系统仍可以从最近一次已提交的检查点恢复会话。

配置方式不需要引入新的协调器类。例如：

ClaudeAgent(id="coder",db=PostgresDb(...),sandbox=DockerSandbox("agno-sandbox:local",network="isolated"))

以上配置即可完成基础接入。

智能体会在首次使用时，根据自身关联的 PostgresDb 自动构建协调器。

每轮执行过程包含以下关键步骤：

• 通过 Agent 的 Postgres 数据库中的租约记录声明会话。
• 租约表为<session_table>_sandbox_bindings。
• 该表会在首次使用时自动创建。
• 启动计算环境时，从会话最近一次已经提交的检查点恢复。
• 检查点包含工作区内容，以及 Harness 自身的会话文件。
• 执行当前轮任务。
• 执行完成后，系统捕获并校验新的检查点。
• 新的运行记录与恢复点会在同一个事务中发布。

这意味着，一轮任务只有在成功完成并且检查点验证成功后，才能更新会话恢复点。

如果某一轮任务被取消或者执行失败：

• 不会发布新的运行结果。
• 不会发布新的检查点。
• 上一个成功提交的检查点仍然保留为恢复点。

这种设计确保失败或取消的执行不会污染已持久化的会话状态。

此外，系统不会在无法验证状态时继续执行。

系统会携带与上一个检查点一起提交的原生会话标识：

• Claude 使用 Claude session id。
• Codex 使用 Codex thread id。

如果恢复时发现该原生会话状态丢失，系统会在模型运行前直接失败，并返回native_state_missing，而不会静默创建一个全新的会话。

这样可以避免“工作区恢复了，但模型原生对话上下文已经丢失”的隐蔽状态错误。

Harness 设置也具备类型化传递能力，会以 JSON 形式传递到运行时环境。

而仅允许存在于宿主机侧的设置会在构造阶段被拒绝，包括：

• cwd
• retries
• env
• 原生选项对象

BaseExternalAgent新增以下选项：

• require_native_resume
• strict_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。

网络默认完全关闭，即默认network="none"。

如果设置：

network="isolated"

则 DockerSandbox 会提供受管理的桥接网络，并关闭容器之间的通信。

还可以通过subnet=指定网络子网范围。

DockerSandbox 使用确定性的会话身份与 generation 身份，用于处理创建竞争和响应丢失问题。

命令不会被自动重试。

这一点意味着，系统不会在命令结果不确定时自动重复执行可能产生副作用的命令。

DockerSandbox 还提供暂停与恢复能力：

• pause
• resume

暂停和恢复通过 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 id：

• namespace
• agent
• session
• generation

因此即使创建请求发生重试或响应丢失，也可以定位到同一个沙箱运行时会话。

在微型虚拟机中，根服务监听在 8080 端口，负责：

• 声明 microVM。
• 以 UID 1000 启动运行时。
• 对后续操作进行配置校验。
• 使用随机 incarnation 防止陈旧句柄操作后续声明。
• 转发启动与轮询调用。
• 在命令执行前使用 guard 将执行身份降级为 UID 1000。
• 将命令执行目录限制在/workspace。

检查点捕获与恢复时，系统会停止 UID 1000 的进程，避免正在写入的文件进入不一致状态。

检查点通过InvokeAgentRuntime分块传输，最大支持 2 GiB。

AgentCoreSandbox 不支持暂停。

同时，AgentCore session storage 不会被使用。

Provider 包路径也进行了调整：

agno.sandbox.docker agno.sandbox.agentcore

DockerCheckpointTransfer 现在从以下模块导入：

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_computer
• sweep_warm

在 Docker 环境中，暖启动 Claude 回合耗时为 4.6 秒，冷启动耗时为 8.2 秒。

在 AgentCore 环境中，暖启动耗时为 3.3 秒，冷启动耗时为 8.2 秒。

五、Sandbox Through AgentOS：AgentOS 支持沙箱智能体的前台、流式与后台运行

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方法支持以下参数：

images=files=

AgentOS 的运行接口也支持以上传方式传递附件。

附件处理遵循“仅字节进入沙箱”的原则。

在任何持久化写入之前，附件都会先完成校验和编码。

随后，附件会由 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。

支持内联的图片格式包括：

• PNG
• JPEG
• GIF
• WEBP

PDF 也支持内联。

图片与 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。

支持的图表类型包括：

• bar
• line
• area
• pie
• bar-horizontal
• bar-stacked
• area-stacked

如果图表载荷校验失败，工具会明确告诉模型需要修复的内容。

ChartTools 自带工具说明。

因此，智能体只需要配置：

tools=[ChartTools()]

即可使用图表能力，不需要再手动携带图表 schema 提示词。

十一、数据库组件与 Factory 组件全面进入 Durable Queue

v3.1.4 改进了 Durable Queue 对组件的覆盖范围。

以下场景中的后台运行现在都会使用 Durable Queue，而不再退化为由接收请求的副本创建 detached task：

• 通过 components API 创建的组件。
• version-pinned runs。
• AgentFactory 提交。
• TeamFactory 提交。
• WorkflowFactory 提交。

接收请求的端点会在 ticket 中写入 resolution scope，其中包括：

• source
• owner
• version
• 工厂场景下的 trusted claims
• 工厂输入

Worker 在领取任务时，会重新执行对应的 resolution。

对于 Factory，如果逻辑在 Worker 中读取ctx.request，运行将会失败，并返回明确的修复提示。

原因是实时 HTTP request 无法被写入 ticket 并随 Durable Queue 传递。

Factory Run 的读取路由也已经修复，不再在每次轮询时统一返回 400。

十二、Codex 权限策略字段调整

由于sandbox=现在用于接收沙箱 Provider，原先：

CodexAgent(sandbox="read-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 路径会按照与其他存储事务一致的顺序获取锁：

• session
• run
• binding

其次，DockerSandbox 的同步调用此前每次都会泄漏一个 HTTP client。

该问题已经修复。

另外，已取消的沙箱运行现在会记录 Durable Queue 所期待的EXECUTING取消阶段。

如果某个运行处于 cleanup 与 commit 之间被标记为 finished，系统现在会进入 stop 路径，而不会让 binding 停留在finalizing状态。

对于耗时较长的 Provider 调用，系统也会延长租约，避免执行期间租约过期。

十六、重要修复：Sandbox Submissions

v3.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/agno

agno v3.1.4 的重点不只是增加一个容器运行选项，而是建立了一套完整的沙箱化、持久化、可恢复的外部 Harness Agent 执行机制。

这一版本的关键能力包括：

• ClaudeAgent 与 CodexAgent 支持sandbox=Provider。
• 每个 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 已经将沙箱、检查点、协调器、队列、恢复与运行接口组合为完整能力。