Agno v3.1.3：外部智能体会话可跨副本恢复，后台运行、取消与逐步回放一起补齐

Agno 于 2026 年 10 月 12 日发布 v3.1.3（GitHub Release 的 published_at 为 2026-10-12T11:22:21Z，非预发布）。这一版的新增能力几乎全部围绕外部智能体展开：会话跨副本恢复、后台运行与取消、按步骤回放、失败重试、运行指标、上下文压缩与事件落库。

这次发布的是什么

Agno 是用于构建多智能体系统的 Python 框架。2026 年 10 月 12 日，agno-agi/agno 发布 v3.1.3（GitHub Release 的 published_at 为 2026-10-12T11:22:21Z，非预发布）。

这一版的新增能力几乎全部落在同一件事上：把 Claude Agent SDK 与 Codex 这类由第三方 SDK 驱动执行循环的「外部智能体」接进 Agno 之后，让它们用起来跟原生智能体一样可控。具体包括会话跨副本恢复、后台运行与取消、按步骤回放、失败重试、运行指标、上下文压缩、事件落库、结构化输出与媒体附件。

外部智能体此前在 Agno 里能跑，但会话状态依赖本地文件；一旦换机器或换副本，上下文就接不上。这一版把 SDK 的会话标识存进 Agno 会话，并在支持转录存储的数据库里镜像每一行记录。

可用性与限制

• 依赖数据库：会话跨副本恢复需要支持转录存储的数据库，发布正文点名了 PostgresDb、AsyncPostgresDb、SqliteDb、AsyncSqliteDb；不接数据库仍可运行，但无法跨副本恢复。
• 降级行为：无法恢复的会话会退回为一个用 Agno 历史初始化的全新 SDK 会话，原会话里由 SDK 持有的上下文不会保留。
• 覆盖对象：后台运行、取消、回放、重试与指标等能力，发布正文中对应 ClaudeAgent 与 CodexAgent 两个类；其余外部智能体适配器是否适用，以官方说明为准。
• 并发限制：同一会话同一时刻只允许一个进行中的轮次，第二个轮次会被拒绝并返回 HTTP 409（错误类型为 session_busy）。
• 沙箱边界：为受沙箱保护的代码发起的模型调用只接受生成类参数，不能设置模型、接口地址、密钥或请求头。
• 附件限制：发布正文提到音频与视频附件会被拒绝并返回 400，而不是等到运行中途才失败。
• 版本会漂移：接口名、默认值与表结构随版本调整，本文描述基于 v3.1.3 的发布正文。

主要功能

• 会话持久化：把 SDK 的会话标识写入 Agno 会话，并在支持转录的库中镜像每一行
• 后台运行：以后台方式提交，配合持久化队列的运行标识
• 运行取消：通过取消接口中断进行中的外部智能体运行
• 逐步回放：从任一工具结果处继续，续跑生成的是新的同级运行
• 失败重试：可设置重试次数、间隔与指数退避，并保留失败尝试的工具调用
• 运行指标：上报 token、缓存用量、成本与首 token 延迟
• 上下文压缩：压缩后的会话可在任意副本从摘要恢复
• 结构化输出：传入 Pydantic 模型或 JSON Schema，返回即为解析后的对象
• 媒体附件：可为运行附带图片与文件，并在后续轮次中恢复
• 新增工具集：面向 Anakin.io 的抓取、爬取、站点地图与搜索接口

技术原理

发布正文里能确认的实现路径有三条。

第一条是「把会话标识搬进 Agno」。外部 SDK 原本把会话状态写在本地文件里，现在 SDK 的会话标识被存到 Agno 会话上；配合支持转录存储的数据库，每一行转录被同步进新建的转录表。于是一次运行在 A 机器上开始、下一轮在 B 机器上继续，也能从数据库里恢复，而不是去找那个已经不在本地的文件。恢复失败时的兜底，是用 Agno 自己的历史去初始化一个新会话。发布正文还提到，Claude 与 Codex 的非流式运行现在也会保留工具调用与结果。

第二条是「复用原生智能体的运行时设施」。后台运行、可恢复的索引化事件流与取消接口，都不是为外部智能体另写一套，而是直接复用原生智能体已有的后台任务、槽位与事件流基础设施。真正的差别在中断方式：Claude 侧为每次运行单独建一个 SDK 客户端，Codex 侧保留轮次句柄，因此宿主进程可以真正打断其中任意一个。

第三条是「把失败变成可观测的」。重试那一项写得很细：失败后用同一个运行标识重试，并接着原来的 SDK 会话或 Codex 线程继续；但触及上限与永久性错误不重试。具体说，轮次上限、预算上限、Codex 的预算与用量上限不重试；鉴权、计费、请求格式、上下文长度与策略类错误也不重试。失败尝试里的工具调用只保留一次，流式消费端会在两次尝试之间收到一条重试事件，重试过的运行会在元数据里记下尝试次数。

实际体验

可以按下面几步自己验证：

1. 用 pip show agno 或官方 Release 页确认当前安装版本为 3.1.3。
2. 接一个 PostgresDb 或 SqliteDb，跑一轮 ClaudeAgent，再到另一个进程或另一台机器继续同一会话，观察是否能从数据库恢复。
3. 打开数据库里的转录表，确认每一行对话都被镜像写入。
4. 以后台方式提交一次耗时较长的运行，再调用取消接口，确认运行被中断且状态被正确记录。
5. 查询检查点接口，确认每个工具结果都被列为一个可继续的检查点。
6. 给输出模式传一个 Pydantic 模型，确认返回内容是被解析后的对象；再传一个数组作为根节点，确认请求被拒绝。
7. 在一次运行进行中再提交一轮，确认返回 HTTP 409，而不是先接受后失败。

任一步与描述不符时，先确认所用数据库是否支持转录存储，再回到官方 Release 正文核对。

项目地址与获取方式

Release 页：https://github.com/agno-agi/agno/releases/tag/v3.1.3

仓库：https://github.com/agno-agi/agno

安装方式与版本要求以官方仓库说明为准。请通过官方仓库与官方包管理渠道获取，核对包名拼写，避免安装同名或近似名的第三方包。是否收费与额度限制，以官方说明为准。

适合谁用

• 把 Claude Agent SDK 或 Codex 接进自有系统的开发者：这一版解决的是「换台机器就断线」的问题。
• 需要后台跑长任务、并要求能中途取消的团队。
• 关心成本与延迟的人：运行指标一项把 token、缓存用量与首 token 延迟显式暴露了出来。
• 做故障复盘的人：事件落库后，即使事件流的保留期已过，也能按序重放一次已结束的运行。
• 不适合：只用原生智能体、不接外部 SDK 的项目——这一版的改动基本与你无关。
• 不适合：不能引入数据库依赖的轻量脚本——会话恢复这条路径需要数据库支持。

常见问题

不接数据库还能用外部智能体吗？

可以。发布正文把数据库支持与「跨副本恢复」绑定在一起：不接数据库仍能运行，只是会话无法在另一台机器上续上，恢复失败时会退回为一个用 Agno 历史初始化的新会话。

重试会不会把一次工具调用执行两遍？

按发布正文的说明，失败尝试里的工具调用会被保留且只保留一次，重复执行不是重试机制的预期行为。是否在你的工具上成立，取决于工具本身是否幂等，需要在接入时自行确认。

一次运行结束后还能改吗？

不能原样改写。发布正文写明，已结束的运行不会被就地重写；继续它产生的是一个新的同级运行，原运行保持不变。

为什么第二轮请求会被拒绝？

因为 Claude Code 与 Codex 在同一会话下只保留一条对话。同一会话里已有进行中的轮次时，新的轮次会被拒绝并返回 HTTP 409，而不是先接受、之后才失败。

受沙箱保护的代码能自己换模型吗？

不能。为受沙箱保护的代码发起的模型调用只接受温度、长度上限、输出格式、推理强度、工具设置与缓存选项这类生成参数，无法指定模型、接口地址、密钥与请求头。

相关工具与内容

• 分类：AI 智能体、AI 编程
• 同题材快讯：Claude Code Mods 发布
• 同题材快讯：MCP 官方参考服务器发布 1.0.0
• 延伸阅读：智能体与网页搜索配置
• 工具页：Claude Code、Dify、扣子 Coze