agno v3.1.3发布：外部智能体全面进入“可持久化、可恢复、可取消、可回放”时代

2026年10月13日，agno 发布 v3.1.3。
这是一次围绕 ClaudeAgent 与 CodexAgent 的重要版本更新，核心目标非常清晰：让外部智能体具备与原生 Agent 一致的生产级运行能力，包括跨副本恢复、后台运行、任务取消、步骤回放、失败重试、指标监控、会话压缩、事件持久化、结构化输出、媒体附件、会话标识、排队控制等。

如果说此前外部智能体更像是“接入到 agno 的外部执行器”，那么 v3.1.3 则让它们真正成为 Agno AgentOS 体系中可观测、可管理、可恢复、可扩展的正式成员。

一、版本核心看点：外部智能体终于具备生产级可靠性

agno v3.1.3 的最大变化，集中在 ClaudeAgent 和 CodexAgent 两类外部智能体上。

过去，在多副本部署、服务重启、工作进程迁移、长时间运行任务、网络波动、工具调用失败等场景中，外部智能体往往面临一些典型挑战：

• 智能体会话可能依赖本地文件，切换机器后难以继续；
• 后台运行任务难以统一管理；
• 用户无法中途取消长任务；
• 一次失败后，工具调用记录、运行历史、重试过程不够完整；
• 外部智能体的运行指标无法与原生 Agent 一样纳入统一监控；
• 已结束任务难以按步骤回放；
• 附件文件难以在不同副本之间正确恢复；
• 同一个会话并发发起多个回合时，底层 SDK 的状态容易冲突。

v3.1.3 针对这些问题进行了系统性补齐。它不只是增加几个 API，而是将外部智能体接入 Agno 的会话、队列、事件、指标、运行记录和 AgentOS 管理体系。

本次更新可以概括为以下几个方向：

1. 外部智能体会话可持久化，并支持跨副本恢复；
2. 支持后台运行、持久化队列、索引化事件流与取消；
3. ClaudeAgent 支持从指定步骤继续执行和分叉运行；
4. 外部智能体支持统一重试机制；
5. ClaudeAgent 与 CodexAgent 支持完整运行指标；
6. 支持会话压缩，降低长上下文维护成本；
7. 支持事件持久化与运行重放；
8. 支持 Pydantic 模型和 JSON Schema 结构化输出；
9. 支持图片与文件附件；
10. Session API 能识别外部智能体 SDK 类型；
11. 新增 AnakinTools 工具包；
12. 优化外部智能体 API、模型标识、会话并发控制和队列调度；
13. 修复会话占用、附件暂存、输入校验、工具错误记录、恢复状态等问题。

二、跨副本恢复：外部智能体会话不再依赖本地机器

v3.1.3 新增了持久化外部智能体会话能力。

对于 ClaudeAgent，Claude SDK 的会话标识会被保存到 Agno Session 中。只要使用支持 transcript 存储的数据库，后续请求即使落到另一台机器、另一个副本或新的工作进程上，也可以从数据库恢复会话，而不再依赖某一台机器上的本地会话文件。

目前支持 transcript 存储的数据库包括：

• PostgresDb
• AsyncPostgresDb
• SqliteDb
• AsyncSqliteDb

当使用这些数据库时，外部智能体运行过程中的每一条 transcript 记录，都会同步镜像到新的agno_transcripts数据表中。

这意味着外部智能体的上下文不再只是“保存在当前进程中”，而是成为可持久化的会话资产。

例如，一个 ClaudeAgent 在副本 A 上开始执行任务，中间因为负载均衡、实例扩缩容、服务重启或者任务迁移，下一轮请求被路由到了副本 B。在 v3.1.3 中，副本 B 可以直接从数据库读取该会话的 transcript 和 SDK session id，继续此前的对话和执行过程。

这对于生产环境尤为关键，因为高可用部署通常意味着：

• 多实例；
• 多副本；
• 容器随时重建；
• 请求不一定固定命中同一台机器；
• 后台任务可能被不同 Worker 接管。

如果已保存的 SDK 会话无法恢复，agno 也提供了降级策略：系统会创建一个新的 SDK 会话，并使用 Agno 已保存的会话历史作为初始化上下文。

也就是说，即使底层 SDK 会话本身失效，也不会直接导致用户对话历史丢失。

此外，Claude 和 Codex 的非流式运行现在也会将工具调用以及工具执行结果保留在运行历史中。此前，非流式模式下的工具执行细节可能无法完整呈现；现在，无论是流式还是非流式运行，重要的工具轨迹都可以被记录和追踪。

三、后台运行与取消：外部智能体支持长任务生命周期管理

v3.1.3 为 ClaudeAgent 和 CodexAgent 增加了后台运行能力。

开发者现在可以使用background=True将外部智能体任务提交为后台运行任务。外部智能体将共享 Agno 原生 Agent 已具备的基础设施，包括：

• 持久化队列；
• 后台任务调度；
• Worker 插槽管理；
• 事件流机制；
• 可恢复运行能力；
• 任务取消能力。

外部智能体后台任务会拥有 durable queue run id，也就是持久化队列运行标识。即使 Worker 重启或服务发生切换，任务状态仍可以依赖持久化机制继续管理。

对于客户端而言，任务可以通过索引化 SSE 事件流进行实时订阅。所谓索引化事件流，意味着客户端可以根据事件索引进行续传，而不必从头重新接收全部流式内容。

取消接口为：

/agents/{id}/runs/{run_id}/cancel

这个能力对于耗时较长的任务非常重要。例如：

• 大规模检索；
• 多轮工具调用；
• 多文件分析；
• 长文本生成；
• 复杂代码执行；
• 多阶段工作流；
• 需要调用多个 MCP 服务的任务。

在具体实现层面，Claude 使用每次运行独立的 SDK Client；Codex 则保留 turn handle。这样，持有任务的进程可以真正向对应 SDK 发出中断指令，而不仅仅是从 API 层面标记任务已取消。

换句话说，v3.1.3 的取消不是简单的“停止等待结果”，而是尽可能中断底层实际执行过程。

四、ClaudeAgent 支持步骤回放：可从任意工具结果继续运行

ClaudeAgent 在 v3.1.3 中新增了步骤回放能力。

ClaudeAgent.continue_run和acontinue_run现在支持与Agent.continue_run相同的参数能力，包括：

• continue_from
• fork
• input
• stream=True
• background=True

其中最重要的是，外部智能体运行中的每一个工具结果都会成为一个 checkpoint，也就是检查点。

可以通过以下接口查看检查点：

GET /agents/{id}/runs/{run_id}/checkpoints

当开发者选择从某个检查点继续执行时，系统会从存储的 SDK transcript 中分叉出新的上下文。模型只会记得截至该消息之前发生的事情，而不会携带之后的上下文内容。

这对于以下场景非常有价值：

• 某个工具调用返回异常，需要从此前步骤重新决策；
• 希望修改某一步输入，然后重新继续后续流程；
• 需要验证不同工具结果对最终答案的影响；
• 需要从中间节点派生多个不同执行分支；
• 调试复杂智能体任务；
• 对执行链进行人工干预。

同时，continue_from="last_user"支持重新回放当前用户回合。

需要特别注意的是：已经完成的运行不会被原地改写。

当对已完成运行进行继续执行时，系统会创建一个新的 sibling run，也就是同级分支运行。这样可以确保历史记录保持不可变，避免原始运行结果被覆盖，也为后续追踪、审计和对比不同分支结果提供基础。

五、失败重试机制：外部智能体拥有一致的可靠性策略

v3.1.3 为 ClaudeAgent 和 CodexAgent 引入了重试能力。

两个外部智能体现在支持以下配置：

• retries
• delay_between_retries
• exponential_backoff

这些参数的默认行为与 Agno 原生 Agent 保持一致。

当一次运行失败后，系统会使用相同的 run id 重试，并且尝试恢复此前已经启动的 Claude SDK 会话或 Codex thread。

这意味着重试并不是从零开始重新执行，而是尽可能延续已有上下文和执行状态。

不过，并非所有失败都会重试。以下情况不会被重试：

• 认证错误；
• 计费错误；
• 非法请求；
• 上下文窗口错误；
• 策略限制错误；
• 最大轮数限制；
• 最大预算限制；
• Codex 预算限制；
• Codex 使用量限制。

这些错误通常属于永久性错误，重试并不能解决问题，因此系统会直接结束运行，避免无意义消耗资源。

对于可重试失败，运行中的工具调用记录会被严格保留一次，不会因为多次重试而重复写入。这样可以避免审计记录中出现同一工具调用被重复计算、重复展示或难以判断实际执行次数的问题。

流式消费者在每次重试之间会收到一个类型为retry的警告事件。客户端因此可以准确感知当前任务并非已经彻底失败，而是正处于下一次尝试前的恢复阶段。

完成重试后，运行记录的 metadata 中会保存：

metadata["attempts"]

该字段可用于分析任务到底经历了多少次尝试，也可辅助告警、成本分析和稳定性统计。

对于持久化队列而言，如果智能体将错误标记为不可重试，那么队列任务会立刻失败。即使 Worker 在中途发生重启，这一不可重试语义也会被正确保留。

六、运行指标补齐：外部智能体也能进入统一监控体系

v3.1.3 为 ClaudeAgent 和 CodexAgent 增加了完整运行指标。

每次运行都会在RunOutput.metrics中报告相关指标。

对于 ClaudeAgent，指标包括：

• token 使用量；
• cache 使用情况；
• 成本信息；
• Agno 侧的总耗时；
• 首 token 时间，也就是 time_to_first_token。

对于 CodexAgent，也会汇总每个模型请求的用量。这里特别优化了一点：Codex 的统计不再只记录当前回合最后一次模型请求，而是会累加一个回合中的所有模型请求。

模型级别的指标会按模型记录在：

metrics.details["model"]

完成的运行指标还会持续累积到 Session 的session_metrics中。

这意味着会话不再只是聊天历史的容器，也能够成为长期运行质量的指标载体。开发者可以通过 Session 维度分析：

• 一个会话累计消耗了多少 token；
• 哪些模型产生了最多调用；
• 长对话是否出现成本持续上升；
• 首 token 延迟是否恶化；
• 某类任务的运行耗时是否异常；
• 缓存命中是否带来实际成本收益。

这些指标会展示在 AgentOS 的多个位置，包括：

• sessions 列表；
• 单个 session 详情视图；
• /metrics接口。

对于需要进行成本治理、性能分析、模型选型和服务等级监控的团队而言，这一更新具有重要意义。

七、上下文压缩：长会话可以继续运行而不被上下文拖垮

外部智能体在长时间对话和复杂任务中，同样会遇到上下文不断膨胀的问题。

v3.1.3 增加了外部智能体的压缩能力。

对于 Claude Code，/compact命令现在可以通过数据库支持的 Session Store 工作。压缩后的会话摘要会被持久化，因此即使下一轮请求由另一台副本处理，也可以从压缩后的摘要继续会话。

对于 CodexAgent，则新增：

• CodexAgent.compact
• CodexAgent.acompact

这两个方法可以对 Agno Session 对应的 Codex thread 进行压缩。

压缩操作在运行中会被拒绝。也就是说，如果当前 Session 存在正在执行的任务，系统不会允许对该会话进行 compact，以避免压缩过程和活动运行同时修改上下文状态。

这项设计保证了会话状态的一致性。

八、事件持久化：流式内容过期后仍能重放运行过程

v3.1.3 扩展了BaseExternalAgent的事件存储能力。

现在，BaseExternalAgent与原生 Agent 一样支持：

• store_events
• events_to_skip

AgentOS 会默认对外部智能体开启事件存储。

这带来的直接收益是：即使实时事件流已经超过保留时间，用户仍然可以从数据库中重新回放已完成的运行过程。

相关接口包括运行视图以及：

/agents/{id}/runs/{run_id}/resume

当实时事件流无法继续提供历史内容时，系统会按顺序从数据库中恢复事件，并且正确遵守last_event_index。

这对于以下场景特别重要：

• 用户中途刷新页面；
• 网络连接断开；
• 前端重新连接；
• 客户端从某个事件序号继续消费；
• 需要回看完整执行过程；
• 需要排查某次任务为何失败；
• 需要展示工具调用、模型响应和状态变化轨迹。

通过事件持久化，外部智能体的可观测性从“仅限在线实时查看”升级为“支持历史可追溯”。

九、结构化输出：ClaudeAgent 与 CodexAgent 可直接返回模型对象或字典

v3.1.3 为 ClaudeAgent 和 CodexAgent 增加了output_schema支持。

output_schema可以在 Agent 级别配置，也可以在单次运行中配置。支持两种形式：

• Pydantic 模型；
• JSON Schema 字典。

当配置结构化输出后，运行的 content 将不再只是普通文本，而是解析后的模型对象或字典，并且会带有对应的content_type。

这一行为与原生 Agent 保持一致。

Claude 会通过自身的结构化输出工具交付对象。该结构化输出工具不会被记录为工具调用，因此不会干扰正常的工具调用历史。

Codex 则会接收到严格的 Schema 定义，以保证返回内容符合预期结构。

这里有一个明确限制：Schema 根节点必须描述一个 JSON object。

也就是说，以下根类型会在运行前直接被拒绝：

• 数组；
• 字符串；
• 数字；
• 布尔值；
• 空值等标量根节点。

AgentOS 的每请求output_schema表单字段，也已经可以应用到外部智能体。

这让外部智能体能够更稳定地服务于自动化系统，例如：

• 信息抽取；
• 订单字段生成；
• 表单填充；
• 报告结构化生成；
• API 参数构造；
• 工作流节点输出；
• 数据库写入前校验；
• 审批结果规范化。

十、图片和文件附件：外部智能体可接收多模态输入

v3.1.3 支持向 ClaudeAgent 和 CodexAgent 附加图片和文件。

附件可以通过两种方式传入：

• 直接调用运行接口；
• 通过 AgentOS API 与 UI。

上传内容会暂存到以下路径：

<cwd>/.agno/uploads/<run_id>/

每个附件会根据运行标识进行隔离，并且会在提示词中以文件名形式体现。

对于 Codex，图片还可以被原生传递。

附件信息会被记录到 run 的 input 中，因此后续回合即使切换到其他副本，也能够恢复附件上下文。

默认情况下，运行结束后，暂存文件会被清理。如果希望保留上传内容，可以设置：

keep_uploads=True

值得注意的是，音频和视频目前不被支持。对于音频和视频输入，系统会返回 HTTP 400，而不是此前可能出现的服务器错误。

这项改进让附件能力具备更加明确和可预测的边界。

十一、Session API 可识别外部 SDK：会话与运行信息更加完整

v3.1.3 对 Session API 做了增强。

以下接口读取到的 Session 和 Run 信息，将携带与 agents API 相同的metadata.sdk：

• GET /sessions
• GET /sessions/{session_id}
• Session 相关运行读取接口

对于外部智能体，这个字段会显示 SDK 类型，例如：

• codex
• claude-agent-sdk

该信息会在读取时基于agent_data中已持久化的外部智能体数据进行叠加，不需要执行数据库迁移，也不会改写已存储的 metadata。

原生 Agent、Team 和 Workflow 的 Session 行为保持不变。

同时，RunSchema新增metadata字段，因此运行层面也可以展示重试次数、告警等元信息。

十二、新增 AnakinTools：接入抓取、爬取、站点地图与搜索能力

v3.1.3 新增 AnakinTools 工具包。

该工具包面向 Anakin.io 的服务能力，提供四类可通过开关启用的方法：

• scrape；
• crawl；
• map；
• search。

其中，异步任务会持续轮询，直到任务完成。最终，模型得到的是页面内容或者链接，而不是一个无法直接使用的任务标识。

这降低了异步网页任务接入 Agent 时的复杂度，也让模型能够直接消费抓取与检索结果。

十三、外部智能体 API 改进：从非类型化参数走向原生 SDK 选项

在 API 层面，ClaudeAgent 和 CodexAgent 现在支持类型化的原生选项。

可传递的内容包括：

• tools；
• permissions；
• MCP servers；
• thread 选项；
• turn 选项。

此前通过非类型化_kwargs字典传递的方式仍然可用，但会产生警告。

这一变化意味着，开发者在使用外部智能体时可以获得更明确的参数边界和更好的类型支持，同时又保留一定的兼容性。

此外，适配器构造函数现在要求使用仅关键字参数的形式。

agent.sdk代表底层 SDK 名称。API 和 Session metadata 只会输出 sdk；框架别名仍然保留在 Python 对象中。

print_response和aprint_response也进行了调整：它们现在会返回最终 run，并且在失败时主动抛出异常。

这使同步调用和异步调用的结果处理更加明确。

同时，外部智能体相关 cookbook 也进行了重构，包括：

• 原生 SDK 对比；
• 示例项目；
• 可复现的可靠性工具集。

十四、模型标识完善：外部智能体运行也能进入模型运行统计

此前，如果 ClaudeAgent 或 CodexAgent 没有明确设置 model，底层选择可能由 CLI 决定，而运行记录中不一定能得到统一模型标识。

v3.1.3 改进后，外部智能体的运行会像原生 Agent 一样记录：

• model；
• model_provider。

这样，外部智能体运行也可以被 AgentOS 指标页面中的 Models Runs 卡片统计。

默认模型行为如下：

• Claude 默认使用claude-sonnet-4-6；
• Codex 默认使用gpt-5.6-luna。

如果模型没有在 Agent 上设置，也没有在 options 中设置，系统会使用上述默认值，并且将该默认值真正传递给 SDK。

如果 options 中已经设置模型，则 options 中的模型优先。

这使模型选择、模型统计与运行追踪之间保持一致。

十五、同一 Session 排队优化：避免并发任务无意义消耗重试次数

对于同一个 Session 的外部智能体任务，v3.1.3 改善了队列调度逻辑。

此前，多个排队任务可能同时声明尝试执行，随后因为 SessionBusyError 而失败，造成尝试次数被无意义消耗。

现在，所有内置队列存储都会在任务真正花费一次尝试或占用一个 Worker 插槽之前，先为同一 Session 选出下一个应该执行的回合。

涉及的内置队列存储包括：

• Postgres；
• Redis；
• 内存队列。

这意味着同一个会话中的多个任务能够更有序地串行调度，避免因为会话繁忙而提前消耗重试额度。

十六、一个 Session 同时只允许一个外部智能体回合运行

Claude Code 和 Codex 在底层都需要维持每个 Session 对应的一段连续会话。

因此，v3.1.3 明确强化了“一次只运行一个回合”的约束。

如果同一个 Session 已经有一个正在执行的外部智能体任务，再启动第二个任务时，系统会直接返回SessionBusyError。

HTTP 状态码为：

409

错误类型为：

session_busy

这比此前“先接受请求，再在更晚阶段失败”的行为更加可靠，也更便于客户端处理。

如果某个运行因为进程崩溃而处于 pending 或 running 状态，后续执行取消操作可以释放该 Session，让会话重新可用。

十七、Claude 子智能体工具调用支持父级链路追踪

Claude 子智能体执行工具调用时，现在会携带parent_tool_call_id。

该字段会同时出现在：

• ToolExecution
• 工具事件

中。

这使追踪系统能够识别嵌套工具调用关系，将子智能体工具调用展示在委派工具调用的下方。

对于复杂多智能体任务，这一点非常关键。

例如，一个主智能体调用某个委派工具，该工具又触发子智能体，子智能体继续调用多个外部工具。借助parent_tool_call_id，系统可以清晰展示整棵调用树，而不再只是平铺的工具调用列表。

十八、开发环境统一：示例与开发安装保持一致

v3.1.3 对开发环境也做了调整。

scripts/dev_setup.sh与scripts/demo_setup.sh现在会安装相同的依赖。

这意味着无论开发者使用开发环境还是演示环境，cookbook 示例都更容易直接运行，减少“示例环境能运行、开发环境却缺少依赖”的问题。

十九、关键问题修复：会话、附件、输入、恢复和工具错误全面加固

除了新功能外，v3.1.3 还修复了多个影响稳定性的细节问题。

1. Session Busy 保活修复

当外部智能体 Session 正处于繁忙状态时，系统返回的 409 错误现在会通过专门的SessionBusyError处理器响应，而不是进入通用异常处理流程。

这样可以确保 keep-alive 连接不会被关闭。

同时，该冲突会被记录为 warning，而不是 traceback。

响应体保持不变，其他异常也不会走这条新路径。

2. 附件暂存安全性修复

外部智能体运行所附带的文件，现在只会在活动 workspace 下进行暂存与恢复。

如果历史附件路径发生移动，系统会告知 harness。

当附件暂存失败时，系统会回滚本次创建的所有文件，包括部分写入的文件。即使启用了keep_uploads=True，失败过程也会正确清理本次产生的内容。

对于已有文件，系统会予以保留，不会错误删除。

此外，以下风险输入会被拒绝：

• 路径遍历形式的 run id；
• 指向上传目录的符号链接路径。

这提升了文件上传与暂存过程的安全性。

3. Run 输入校验修复

如果运行请求中的以下输入格式错误：

• images；
• audio；
• videos；
• input_files；

系统会在分发任务之前返回 HTTP 422。

此前，这些错误输入可能被悄悄忽略，或者直到运行中途才失败。现在，输入问题可以更早暴露，也更容易被调用方定位。

同样，格式错误或者根节点为标量的output_schema也会被拒绝，而不是被静默丢弃。

4. CodexAgent 工具失败记录修复

对于 CodexAgent，如果工具调用失败，例如：

• 命令返回非零退出码；
• 命令被拒绝；
• MCP 工具返回错误；

系统会将tool_call_error=True写入运行记录，而不是保留为 null。

该修复同时适用于流式和非流式运行。

这让工具失败状态具备明确语义，便于前端展示、日志分析和自动化补偿。

5. Codex 会话恢复历史补齐

当 Codex thread 无法恢复、必须创建新 thread 时，系统回放到新线程的历史内容现在不仅包含用户与助手文本，也包含此前的工具调用以及工具执行结果。

为了控制上下文体积，每个工具调用及其结果会截断到 2000 个字符。

这显著提高了 Codex 会话降级恢复时的上下文完整性。

6. 外部智能体 Resume 状态修复

对于通过stream=false提交的运行，/resume现在会返回真实运行状态。

如果运行仍在执行，接口会明确提示客户端轮询 run 端点，而不会错误地声称任务已经完成。

这避免了非流式异步任务中“状态显示已完成，但实际上仍在运行”的问题。

7. 测试稳定性修复

部分工具冲突测试不再依赖 FastMCP 的工具命名方式，测试结果更稳定，也减少了对外部命名细节的耦合。

二十、总结：v3.1.3 让外部智能体真正适合进入生产环境

代码地址：github.com/agno-agi/agno

agno v3.1.3 的重点并不是简单增加某一个模型或某一个工具，而是完成外部智能体运行基础设施的一次系统升级。

ClaudeAgent 与 CodexAgent 现在具备了更完整的能力闭环：

• 会话可跨副本恢复；
• transcript 可存入数据库；
• 任务可后台运行；
• 长任务可取消；
• 运行可从检查点继续；
• 已完成任务可以分叉而不改写历史；
• 失败可按策略重试；
• 工具调用不会因重试重复记录；
• 模型用量、缓存、成本与时延可观测；
• 长会话支持压缩；
• 事件流可持久化和重放；
• 输出可结构化；
• 图片和文件可作为输入；
• Session 与 Run 可标识外部 SDK 类型；
• 模型与模型提供方进入统一指标体系；
• 同一 Session 的队列调度更可靠；
• 并发会话冲突能够更早、更明确地处理；
• 附件暂存、输入校验、恢复逻辑和工具错误记录更加稳健。

对于正在构建 AgentOS 平台、企业级智能体应用、多副本后台任务系统、长链路工具调用系统，以及需要同时接入 Claude 与 Codex 的开发团队来说，agno v3.1.3 是一次值得重点关注的版本更新。

它推动外部智能体从“能够调用”走向“能够稳定运行、持续管理、完整追踪与可靠恢复”。