Agno v3.1.11 已于 2026 年 10 月 29 日发布。本次更新覆盖 Agent 团队协作、工作流编排、会话检索、Company 任务与例程管理、知识库读取、工作流状态恢复、HuggingFace 集成、Google Calendar 时区处理、Redis 检索、重排序器以及 AgentOS 客户端等多个方向。

这不是一次单纯的功能补丁更新，而是一次围绕“自我改进智能体平台”定位持续强化的版本迭代。v3.1.11 一方面让 ClaudeAgent 和 CodexAgent 能够更自然地加入 Agno Team 与 Workflow，另一方面补齐了会话高级筛选、任务状态流转、例程归档恢复等企业级管理能力，同时修复了大量容易在生产环境中暴露的问题。

一、Harness Agent 正式进入 Teams 与 Workflows

v3.1.11 最值得关注的新功能之一，是 ClaudeAgent 和 CodexAgent 现在可以作为 Agno Team 的成员，也可以作为 Workflow 中的步骤使用。

此前，团队协作和工作流编排主要围绕 Agno 自身的 Agent 能力进行组织。本次更新后，Harness Agent 被正式纳入统一的团队与工作流体系，这意味着开发者可以在同一套 Agno 编排模型中调度不同类型的智能体能力。

具体来说，ClaudeAgent 和 CodexAgent 现在可以：

• 成为 Agno Team 的成员
• 作为 Workflow 的步骤执行
• 在 Parallel 中执行
• 在 Loop 中执行
• 在 Condition 中执行
• 在 Router 中执行

这意味着 Harness Agent 不再只是一个相对独立的调用对象，而是能够进入复杂业务编排结构中。

例如，在一个多智能体团队中，Team Leader 可以像委派普通成员一样，通过delegate_task_to_member将任务分配给 ClaudeAgent 或 CodexAgent。对于 Team Leader 而言，Harness Agent 的调用方式与普通团队成员保持一致，降低了混合团队的使用门槛。

每一个 Harness Agent 都拥有独立的运行配置，包括：

• 独立模型
• 独立工具
• 独立工作空间
• 独立会话上下文

其中，“保持独立会话上下文”非常重要。对于同一个 Session 的多轮交互，Harness Agent 可以保留属于自己的对话状态，而不是每一次被委派任务时都从零开始。这使得它们能够在团队协作或多步骤流程中持续理解任务历史。

在团队和工作流执行完成后，Agno Team 或 Workflow 仍会像处理其他成员或步骤一样，统一收集 Harness Agent 的运行结果。这让开发者可以在保持原有可观测性和结果管理方式的基础上，接入更多 Agent 类型。

对于设置了sandbox=的 Harness Agent，本次版本也明确了其运行方式：每一轮执行都会在独立容器中完成。即使它作为 Team 成员或 Workflow 步骤参与运行，也会遵循每轮独立容器隔离的机制。

同时，AgentOS 的团队页面现在会列出 Harness 成员，提升了团队结构的可见性。开发者能够更直观地确认团队内是否包含 ClaudeAgent 或 CodexAgent 等 Harness Agent。

这项能力适合以下场景：

• 让团队负责人统一协调多个不同类型的 Agent
• 在工作流中混合使用不同智能体能力
• 在并行节点中同时执行多个 Harness Agent
• 在循环中让 Harness Agent 基于上下文持续处理任务
• 在条件分支中根据业务逻辑选择不同 Agent
• 在路由节点中将任务发送给更适合的执行单元
• 在容器隔离环境下运行需要沙箱保障的 Agent

与此相关的示例已加入框架相关 Cookbook，分别覆盖 Harness Teams 和 Harness Workflows 的使用方式。

二、Session Search：会话高级搜索能力上线

v3.1.11 为 Session 新增了高级搜索能力，提供了以下接口：

• GET /sessions/filter-schema
• POST /sessions/search

其中，GET /sessions/filter-schema用于获取可用筛选结构，POST /sessions/search用于执行会话搜索。

新的会话搜索支持嵌套的逻辑表达式，包括：

• AND
• OR
• NOT

这让会话查询不再局限于简单字段匹配，而是能够构建复杂组合条件。

可筛选的字段包括：

• Session 名称
• Session ID
• User ID
• Component ID
• Session 类型
• 创建时间戳
• 更新时间戳

该能力在筛选表达式设计上与 Traces API 保持一致。对于已经使用过 Traces 过滤机制的开发者来说，会话查询的使用体验更加统一。

在 PostgreSQL 和 SQLite 环境中，筛选条件会在统计数量和分页之前应用。也就是说，系统会先根据过滤规则缩小数据范围，再进行总数计算和分页查询，从而确保结果数量与分页数据保持一致。

对于其他数据库适配器，则提供了批量回退方案，以支持会话筛选能力。

同时，Agno 也提供了同步和异步客户端方法，方便不同类型的应用接入。无论是同步服务逻辑，还是异步 Web 服务和任务调度程序，都可以调用相应客户端方法进行 Session Search。

这一更新对于以下场景非常实用：

• 根据用户查找历史会话
• 根据组件定位某类 Agent 或 Workflow 运行记录
• 按创建时间或更新时间排查问题
• 查找指定类型的 Session
• 使用多层 AND、OR、NOT 组合定位复杂业务数据
• 在管理后台实现高级会话筛选功能
• 将 Session 查询能力与 Trace 查询能力形成统一运维入口

三、Company Tasks：任务创建、状态流转与重新打开能力增强

Company Tasks 在 v3.1.11 中获得了重要升级。

首先，POST /company/tasks现在接受status参数。这意味着创建任务时，不再只能使用固定的默认状态，而是可以直接创建为以下状态之一：

• Backlog
• Ready
• Cancelled

这一变化让任务录入过程更加符合真实项目管理流程。例如，一项尚未排期的需求可以直接进入 Backlog；已经确认可执行的事项可以直接进入 Ready；已明确不继续推进的任务则可以直接以 Cancelled 状态创建。

任务状态流转规则也得到放宽。现在任务可以在任意阶段之间移动，不再受限于过于严格的单向流程。

同时，Done 和 Cancelled 状态的任务可以重新打开。对于实际项目管理而言，这一点非常关键。一个已完成任务可能因为需求变化、验收问题或后续发现缺陷而重新进入处理流程；一个已取消任务也可能因优先级变化而恢复推进。v3.1.11 支持此类回流操作。

任务的标题和简介也可以在任意阶段编辑。无论任务处于 Backlog、Ready、进行中、Done 还是 Cancelled，用户都可以更新标题和 brief 信息。

不过，本次更新仍保留了对 In progress 状态的约束：

• In progress 只能通过一次运行开始
• 如果对应运行仍在执行中，则拒绝将任务移出 In progress
• 如果对应运行处于暂停状态，则同样拒绝将任务移出 In progress

这一设计能够避免任务状态与实际运行状态脱节。例如，一个正在执行的任务不能被直接标记为完成、取消或转移到其他阶段；一个暂停中的运行也不能在任务层面被错误地跳过。

整体而言，v3.1.11 让 Company Tasks 更接近可用于实际团队协作的任务系统：创建时可指定状态、执行过程中保持运行约束、完成或取消后可重新打开、各阶段都允许更新任务描述。

四、Company Routines：取消、归档、恢复与删除能力补齐

Company Routines 在本次版本中新增了多个生命周期管理接口：

• POST /company/routines/{id}/cancel
• POST /company/routines/{id}/archive
• POST /company/routines/{id}/restore
• 管理员专用的DELETE /company/routines/{id}

这意味着 Routine 不再只具备基础的运行和暂停恢复能力，而是拥有更加完整的状态管理闭环。

新增能力包括：

• 取消 Routine
• 归档 Routine
• 恢复已归档 Routine
• 由管理员彻底删除 Routine

其中，删除接口仅限管理员使用，符合对高风险操作进行权限控制的要求。

此外，GET /company/routines现在支持：

• sort_by
• sort_order

开发者可以按照指定字段与排序方向查询 Routine 列表，更方便在管理界面中实现按时间、状态或其他字段排序的展示逻辑。

本次更新还明确了按需执行 Routine 的限制：对于 on-demand Routine，暂停与恢复操作会返回409。

这意味着按需执行的 Routine 不支持被当作长期运行、可暂停恢复的调度对象处理。接口通过返回冲突状态码明确拒绝此类不适用操作。

另一个细节优化是，调度器运行 Routine 时不再更新其updated_at。这一改动避免了“仅仅因为被调度执行一次，就导致 Routine 配置更新时间被改变”的问题。

换句话说，updated_at更能反映 Routine 实体本身发生配置或状态变更的时间，而不是被调度器正常执行的时间。

五、Cookbooks 与 README：平台定位与客户反馈工作流更新

在 Cookbook 方面，v3.1.11 增加了一个面向 AgentOS UI 的客户反馈工作流。

该工作流中，Company Manager 会读取 Markdown 格式的客户反馈，并基于反馈内容提出有证据支撑的 Projects 和 Backlog Tasks。

需要注意的是，这一流程并不会自动完成最终接受。是否接受这些建议，仍然由人工决定。

这个设计体现了明确的人机协同边界：

• 智能体负责读取和理解客户反馈
• 智能体负责提出项目和待办建议
• 建议需要有证据支持
• 人工负责最终接受与决策

对于希望将用户反馈转化为项目管理输入的团队而言，这类工作流能够把非结构化 Markdown 反馈与 Project、Backlog Task 的创建建议连接起来，同时保留人工审核机制。

README 也进行了多项调整：

• 与文档介绍保持一致
• 与“自我改进智能体平台”的定位保持一致
• 进一步澄清自我改进工作流相关表述

这使得项目首页介绍、官方文档介绍与平台定位更加统一。

六、ReaderFactory 修复：每次调用都使用独立 Reader

在知识库与文档读取相关能力中，ReaderFactory.create_reader()的行为得到修复。

此前，ReaderFactory 可能返回缓存的单例 Reader，这会带来两个问题：

• 单次调用传入的配置可能无法正确生效
• Reader 的可变状态可能泄漏到其他 Knowledge 实例

v3.1.11 修复后，create_reader()会返回一个全新的 Reader，并按照每次调用传入的选项进行配置。

这意味着诸如chunk_size等按调用覆盖的参数能够被正确尊重。

例如，如果不同 Knowledge 实例对文档切分大小有不同要求，新的实现能够避免一个实例的配置影响另一个实例。同时，Reader 对象上的可变修改也不会继续跨 Knowledge 实例泄漏。

这是一个典型但十分重要的稳定性修复。对于多知识库、多文档类型或动态配置读取参数的应用来说，可以显著减少因共享可变对象导致的非预期行为。

七、Workflow Step Content 修复：保留 JSON 原生类型

v3.1.11 修复了工作流步骤输出在序列化和恢复过程中的类型问题。

现在，StepOutput.to_dict()会保留以下原始类型：

• int
• float
• bool
• str

此前，一些值可能会被统一转换为字符串。例如，步骤返回0或False时，在以下场景中重新读取后可能变成"0"或"False"：

• HITL 恢复后
• Session 重新加载后
• 通过 AgentOS Workflow API 获取时

这种类型变化在工作流中可能产生严重问题。比如，条件判断依赖布尔值时，字符串"False"本身在很多语言环境中仍可能被当作真值；数值比较和计算也会因字符串化而失效。

修复后，步骤输出可以在工作流 Session 恢复与 API 传输中保持 JSON 原生类型，确保0仍然是数值 0，False仍然是布尔值 False。

这使得工作流在暂停、人工介入、恢复执行以及跨接口读取时具有更可靠的数据一致性。

八、HuggingFace 集成修复：参数映射与无工具 Agent 行为更稳定

HuggingFace 相关集成在 v3.1.11 中进行了多项修复。

首先，default_headers会被正确映射到 SDK 所需的headers参数。

其次，store会通过extra_body发送。

此外，以下参数被标记为弃用并忽略：

• max_retries
• default_query

它们不再引发TypeError。

这意味着在使用相关配置时，系统不会因为 SDK 参数不兼容而直接报错，而是按照新的兼容策略忽略这些已弃用参数。

另一个重要修复是：当 Agent 没有工具时，不再发送tools=[]。

此前，向 HuggingFace 请求中发送空工具列表，可能导致非流式运行返回None内容。现在，无工具 Agent 不再携带空的 tools 参数，从而避免非流式运行内容为空的问题。

这些调整提升了 HuggingFace 集成在不同请求模式下的兼容性与稳定性。

九、Google Calendar：可用时间段终于按照用户时区计算

Google Calendar 的find_available_slots在本次版本中修复了时区和查询窗口问题。

首先，可用时间段计算现在使用认证用户的时区，而不再使用 UTC。

这意味着：

• 工作时间按照用户所在地时区解释
• 仅包含日期的输入按照用户本地日期理解
• 可用时间段结果更符合用户日常日历认知

例如，用户设置的工作时间是本地上午到下午，在旧逻辑中如果按 UTC 计算，可能会导致时间段整体偏移。修复后，工作时间与日期输入都会回归认证用户的本地时区。

其次，系统现在会查询完整扫描窗口内的日历事件。

此前，如果查询一个日期范围，最后一天的忙碌事件可能没有被完整纳入查询，进而被错误地当作空闲时间返回。

修复后，完整扫描窗口内的事件都会被获取，因此范围最后一天的忙碌时间不会再被错误推荐为可用时间。

对于会议排期、日程推荐、自动预约等场景，这项修复非常关键。

十、Company Archive：已归档任务不再阻塞项目或产品归档

Company Archive 逻辑得到优化。

此前，即使某些 Tasks 已经归档，它们仍可能阻塞所属 Project 或 Product 的归档流程。

v3.1.11 修复后，已归档 Tasks 不再阻塞 Project 或 Product 的归档。

同时，仍然可见的活跃 Tasks 依旧会阻塞归档操作。

这一区分符合实际管理逻辑：

• 已归档任务视为不再参与当前活跃工作
• 活跃任务仍然意味着项目或产品存在未处理事项
• 项目或产品归档时，应继续防止遗漏可见的活跃任务

此外，已归档 Tasks 也不再阻塞 Project 的完成或保留相关流程。

十一、RedisDb：keyword_search 正确传递调用方 limit

RedisDb 的keyword_search修复了 limit 参数未被正确传递的问题。

此前，调用方即使传入了自定义 limit，底层 redisvl 可能仍然使用默认值 10，导致搜索结果数量被静默限制为 10 条。

v3.1.11 修复后，keyword_search会将调用方传入的 limit 正确传递给 redisvl。

这意味着开发者设置的结果数量限制将真正生效，不再被底层默认值意外覆盖。

对于需要获取更多或更少关键词搜索结果的场景，这项修复能够让检索行为与调用代码保持一致。

十二、MMRReranker：limit 小于等于零时返回空文档

MMRReranker 的rerank和arerank行为得到修复。

当 limit 为零或负数时，现在会返回零篇文档。

此前，即使 limit 为零或负数，系统仍可能返回最接近的匹配文档。

修复后的逻辑更加符合参数语义：

• limit 大于零时，按指定数量返回重排序结果
• limit 等于零时，不返回文档
• limit 小于零时，不返回文档

这避免了调用方明确要求不返回结果时，系统却仍然返回匹配内容的情况。

十三、FieldLabeledCSVReader：page_size 为零将被拒绝

FieldLabeledCSVReader修复了page_size=0的处理问题。

此前，负数 page_size 会被拒绝，但 page_size 设置为 0 时可能不会报错，并且在较大文件上静默返回零文档。

这种行为不利于排查问题，因为调用方可能误以为文件没有内容，实际上是分页参数无效导致读取结果为空。

v3.1.11 中，page_size=0与负数值一样会被拒绝。

这让参数校验更加一致，也避免了大文件读取时出现难以定位的静默空结果问题。

十四、AgentOSClient：移除不存在的 stream 参数说明

AgentOSClient 对continue_agent_run进行了接口说明修正。

此前，文档中提到continue_agent_run存在stream参数，但该参数实际上并不存在。

v3.1.11 移除了这一不正确的说明。

如果需要以流式方式继续 Agent 运行，应使用：

continue_agent_run_stream

这一调整避免开发者按照错误文档传递不存在的参数，也明确区分了普通继续运行与流式继续运行的接口。

十五、测试与维护更新

本次版本还完成了测试维护工作。

部分 OpenAI 推理测试已迁移，不再依赖已退役的o3-mini。

团队事件流测试同样不再依赖已退役的o3-mini。

这些调整有助于保持测试环境与当前可用模型能力的一致性，减少因已退役模型带来的测试失败或维护问题。

总结

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

Agno v3.1.11 的核心价值，可以概括为四个方向：

• 扩展 Agent 编排能力
• 强化企业级会话与任务管理
• 修复工作流和数据类型一致性问题
• 提升第三方集成与检索组件的稳定性

其中，ClaudeAgent 和 CodexAgent 加入 Agno Team 与 Workflow，是本次最具代表性的能力扩展。它让 Harness Agent 可以进入团队委派、并行执行、循环处理、条件分支和路由编排结构，并且保留独立模型、工具、工作空间和会话上下文。

Session Search 则让会话管理拥有了与 Traces API 一致的复杂筛选能力。Company Tasks 与 Company Routines 的升级，进一步完善了任务和例程从创建、运行、取消、归档到恢复、删除的全生命周期管理。

此外，ReaderFactory、Workflow Step Content、HuggingFace、Google Calendar、RedisDb、MMRReranker、FieldLabeledCSVReader 和 AgentOSClient 的修复，也让 Agno 在真实生产环境中的行为更加稳定、可预测。

对于正在构建多智能体团队、复杂工作流、企业任务系统、知识库应用或日程自动化能力的开发者而言，Agno v3.1.11 是一次值得重点关注的版本更新。