2026年8月16日agno 正式发布 v2.9.0。此次更新覆盖了 Studio 调度能力、组件发现、A2A 流式通信、工作流 WebSocket 执行、Team 人机协作暂停恢复、组件重建、框架注解处理以及 MCP 工具调用安全和工具缓存隔离等多个关键环节。如果用一句话概括 agno v2.9.0 的核心方向那就是让组件调度更安全让用户身份传递更准确让持久化组件在恢复时更可靠让多用户场景下的缓存与审批边界更清晰。本次版本中最值得关注的是全新的StudioRunnerTools、MCP 工具名称覆盖漏洞修复、按用户隔离的工具结果缓存以及组件重建失败时由静默降级改为明确报错。这些变化不仅影响开发体验也直接关系到多用户 Agent 系统、Studio 组件分发、HITL 审批流和生产环境安全性。一、全新 StudioRunnerTools把“运行组件”和“管理组件”彻底拆开agno v2.9.0 新增了一个身份感知型调度工具包agno.tools.studio_runner.StudioRunnerTools它的核心价值在于将原先集中在StudioTools中的执行能力拆分出来形成更清晰的职责边界。过去Studio 相关能力可能同时包含组件创建、编辑、删除、发现和运行等操作。对于某些场景来说这种能力集合过于宽泛。例如一个团队负责人、路由器或者上游 Agent只需要根据任务去发现并运行 Studio 中已经构建好的 Agent、Team 或 Workflow但并不应该拥有创建、修改、删除 Studio 组件的权限。v2.9.0 中的StudioRunnerTools正是为这一需求而设计。它允许任意组件挂载这一工具包包括但不限于Team LeadRouter上层调度 Agent负责请求路由的组件需要调用 Studio 内部已构建组件的执行节点挂载后这些组件可以发现并运行 Studio 中构建好的AgentTeamWorkflow但不会获得 Studio 的创建、编辑、删除能力。这意味着 agno 在 Studio 调度层面实现了更细粒度的职责切分能力类型StudioRunnerTools 的定位发现 Studio 组件支持运行 Studio Agent支持运行 Studio Team支持运行 Studio Workflow支持创建 Studio 组件不提供编辑 Studio 组件不提供删除 Studio 组件不提供这种拆分的意义非常明显。对于生产系统而言能够运行某个组件不代表应当拥有修改该组件的权限。一个 Router 的职责应当是判断任务该交给哪个 Agent、哪个 Team 或哪个 Workflow而不是在运行过程中任意改变 Studio 内已有组件的定义。StudioRunnerTools的出现让“调度者”和“管理者”的边界更加清晰调度者负责发现与运行Studio 管理面负责创建、编辑与删除组件执行权限不再天然绑定组件管理权限这也让 Studio 组件被上层 Agent、Team Lead 或路由逻辑复用时更加稳妥。二、身份感知执行run 工具会将调用方 user_id 传入子运行StudioRunnerTools不只是简单地把执行能力从StudioTools中拆出来它还带来了一个非常关键的机制身份感知调度。在 v2.9.0 中run_*工具会把调用方的user_id传递到子运行中。也就是说当一个组件通过 StudioRunnerTools 去启动另一个 Studio 构建的 Agent、Team 或 Workflow 时当前调用者的用户身份不会在子运行中丢失。这项设计解决的是多用户运行上下文中的一个核心问题子组件执行时产生的用户级状态必须归属于正确的用户。例如在一个多用户系统中不同用户可能通过同一个上层 Router 调用下游 Agent。如果用户身份没有继续传递到子运行中那么下游组件保存的状态、读取的上下文或运行结果就可能无法正确对应到真正的调用用户。v2.9.0 通过将调用者的user_id贯穿到子运行确保按用户维度维护的状态会落在正确的人身上。这意味着上游组件识别到的用户身份可以继续传递给下游组件Studio 中被调度执行的组件可以在正确的用户上下文中运行用户级状态不再因为子运行而偏离原始调用者Team Lead、Router 等调度型组件在调用下游组件时身份信息能够持续保留对于需要区分不同用户状态的 Agent 系统来说这一点尤其重要。因为一旦用户身份在组件嵌套调用中断裂后续的状态归属就可能出现偏差。StudioRunnerTools 的新增因此不仅是一次工具拆分更是一次围绕用户身份和运行归属的能力升级。三、list_components 新增 name 过滤组件发现更精准在组件发现能力方面v2.9.0 为list_components新增了name过滤功能。这意味着在列出组件时可以通过名称进一步筛选目标组件。这一改动看起来很小但对于 Studio 中组件数量不断增加的场景非常实用。当 Studio 内同时存在多个 Agent、Team 或 Workflow 时仅仅获取完整组件列表可能会让上层调度逻辑面对大量无关结果。尤其是当组件命名存在固定规则、业务前缀或模块划分时按名称过滤能够帮助调用方更快缩小候选范围。新增name过滤后组件发现流程可以更加聚焦只查询名称匹配的组件降低无关组件出现在发现结果中的概率让 Router 或 Team Lead 更高效地查找目标组件让 Studio 组件的检索粒度更加灵活这项能力与StudioRunnerTools的定位形成了很好配合。前者解决“如何更准确发现组件”后者解决“如何在不拥有管理权限的前提下运行组件”。两者结合后调度型组件可以在受控边界中完成更精确的组件选择与执行。四、MCP 工具调用安全修复禁止调用时覆盖 tool_namev2.9.0 最重要的安全修复之一来自 MCP 工具入口。本次更新后MCP 工具入口不再允许模型在调用时覆盖tool_name。此前模型可能向任意 MCP 工具传入类似下面的参数tool_namedelete_repo而服务端可能会根据这个调用时提供的名称去执行对应工具。问题在于工具执行名称被调用参数影响后允许列表、是否需要确认、HITL 审批以及日志记录等机制可能仍然按照声明时的工具名称进行处理而实际执行的却是另一个工具。这会造成一个严重的安全风险声明名称与实际执行名称不一致允许列表可能对错误名称进行判断requires_confirmation可能无法对应真实执行的工具HITL 审批可能绕过实际需要审批的工具日志记录可能反映的是声明名称而不是实际执行名称模型可能借助tool_name覆盖触发本不该直接执行的操作换句话说过去模型可能把一个普通 MCP 工具调用伪装成另一个工具的执行请求而安全控制逻辑与实际执行目标之间出现错位。v2.9.0 对这一问题进行了明确修复。现在实际执行的工具名称会从tool.name中闭包确定不再由模型调用时传入的tool_name决定。也就是说模型无法通过调用参数切换实际执行的 MCP 工具实际执行目标由工具自身声明的名称固定安全控制逻辑将围绕真实声明的工具名称生效allow-list 不会再因为名称错位而失去意义requires_confirmation不会再被调用时名称覆盖绕过HITL 审批不会再因为名称替换而失效日志记录与实际执行工具之间的对应关系更加一致值得注意的是这一改动并不是简单删除所有名为tool_name的参数。如果某个工具本身就合法地声明了一个tool_name参数那么模型传入的该参数仍会作为普通参数继续转发给工具。区别在于tool_name参数不再用于选择或切换要执行的工具它只会作为该工具定义中的普通入参存在真正执行哪个工具始终由tool.name固定这是一项兼顾安全性和兼容性的修复。它阻止了调用时工具名称覆盖带来的安全绕过同时保留了那些确实需要tool_name作为业务参数的工具使用方式。五、工具结果缓存改为按用户隔离修复跨用户缓存泄漏另一个极其关键的安全与行为变更是工具结果缓存机制的调整。当启用cache_resultsTrue时agno v2.9.0 的缓存键将不再仅按原有方式生成而是加入稳定的运行上下文身份信息user_idsession_id这意味着工具缓存正式具备按用户、按会话的隔离能力。此前存在一个跨用户缓存泄漏问题。如果某个工具接受run_context例如 MemoryTools 一类工具并且工具结果被缓存那么一个用户产生的缓存结果可能会被另一个用户命中并复用。这显然会带来严重问题。因为工具的结果可能依赖用户上下文。即使工具调用参数表面上相同不同用户对应的run_context、记忆内容、会话状态或上下文环境也可能完全不同。如果缓存没有将用户身份纳入键的一部分那么以下情况就可能发生用户 A 调用某个依赖运行上下文的工具。工具结果被缓存。用户 B 发起看似相同的调用。系统命中用户 A 的缓存结果。用户 B 获得原本属于用户 A 的结果。v2.9.0 通过将user_id和session_id加入缓存键修复了这一问题。新的缓存键将包含稳定的运行上下文身份信息因此缓存结果不再简单地跨用户共享。这带来几个直接影响用户 A 的缓存不会被用户 B 直接复用不同会话之间的缓存边界更加明确接受run_context的工具在缓存场景下更安全多用户系统中的工具执行结果归属更清晰缓存机制不再可能把一个用户的数据错误地服务给另一个用户需要注意的是run_id不会加入缓存键。这是一个经过权衡的设计。如果把run_id放进缓存键中每一次运行都会形成新的缓存维度缓存几乎无法在同一用户后续运行中复用缓存的实际价值会明显降低。因此v2.9.0 的策略是加入user_id加入session_id不加入run_id这样既能够保障用户与会话维度的隔离又能让同一用户在后续运行中继续获得缓存带来的收益。六、缓存行为变化旧缓存命中逻辑将不再完全一致由于缓存键的组成方式发生变化v2.9.0 也带来了一项明确的行为变化。此前已经存在的缓存键与新版本的缓存键不再保持一致。因此升级后原先可以命中的缓存结果可能不会再按相同方式命中。这不是缓存功能失效而是缓存键结构调整后的自然结果。因为新版本加入了用户身份信息会话身份信息缓存从“可能跨用户共用”的模式转向“面向稳定运行上下文身份隔离”的模式。所以已有缓存行为会发生变化过去的缓存键与新版本缓存键不一致旧的缓存命中关系不会完全延续升级后部分原有缓存可能无法按原逻辑命中同一用户、同一会话下的跨运行缓存仍然有价值不同用户之间不再共享可能包含上下文差异的缓存结果除了缓存键变更外本次修复还涉及ToolResult 的往返处理缓存命中时 Hook 的执行也就是说缓存能力不只是完成用户级键隔离还同步处理了工具结果对象在缓存过程中的往返表现以及缓存命中时相关 Hook 的行为。对于依赖工具缓存的应用来说升级 v2.9.0 后需要理解这一点缓存仍然存在但缓存命中边界已经变得更加严格也更加符合多用户运行环境的安全要求。七、组件重建不再静默降级无法解析引用时明确失败v2.9.0 对组件重建机制进行了重要调整。过去当系统反序列化一个持久化组件时如果组件内部存在无法解析的引用系统可能不会直接报错而是选择静默降级后继续运行。例如一个 Agent 的工具可能变成空数组一个 Team 可能丢失成员Schema 可能被丢弃Knowledge 可能被丢弃这种静默降级的问题在于组件表面上看起来仍然可以运行但实际运行的已经不是原本被保存和定义的组件。一个 Agent 丢掉工具后继续执行可能无法完成任务。一个 Team 丢掉成员后继续执行可能失去原有分工。Schema 或 Knowledge 丢失后继续执行也可能让行为与预期严重偏离。更危险的是这类问题不一定会立刻暴露。系统可能继续运行但运行结果已经因为组件被悄悄降级而不再可信。v2.9.0 改变了这一行为。当持久化组件在反序列化时存在无法解析的引用在严格路径中将直接抛出ComponentRehydrationError该错误属于AgnoError状态码为422这意味着系统不再默认接受“缺失部分依赖但仍勉强运行”的组件状态。相反系统会明确告诉调用方组件无法被完整重建具体存在无法解析的部分。这项变化的核心价值在于宁可明确失败也不让一个被破坏或被降级的组件在不知情的情况下继续运行。八、严格模式是调用方属性公开加载保持兼容调度路径默认严格v2.9.0 对重建严格性的设计非常明确严格与否是调用方的属性。这意味着不同入口可以根据自身场景选择不同的默认行为。公开的from_dictload默认仍然是strictFalse这一设计保证了常规 round-trip 场景仍然可以工作也就是说公开的反序列化和加载行为保留了兼容性。但对于 AgentOS 查询和所有调度执行路径默认会采用strictTrue包括RESTPOST /runscontinueMCP run 工具StudioRunner在这些严格路径中如果组件存在无法解析的引用系统会返回 422 错误而不是运行一个已经被降级的组件。返回的错误会指出无法解析的部分。这一设计体现了两类需求之间的平衡。一方面公开的from_dict和load保持默认非严格模式避免破坏已有 round-trip 使用方式。另一方面真正进入执行与调度流程时系统必须确保组件引用完整可用不能容忍缺失工具、缺失成员、缺失 Schema 或缺失 Knowledge 后仍继续运行。因此v2.9.0 的组件重建策略可以概括为场景默认严格性from_dictstrictFalseloadstrictFalseAgentOS 查询strictTrueRESTPOST /runsstrictTruecontinuestrictTrueMCP run 工具strictTrueStudioRunner 调度strictTrue这项变化将显著提升生产执行路径的可靠性。因为在真正运行前系统会先确认组件是否能够被完整、正确地重建而不是带着丢失的关键部分继续执行。九、固定成员版本得到尊重重建与执行更符合已保存定义在组件重建相关修复中v2.9.0 还明确支持了固定成员版本。也就是说被固定的成员版本将得到正确遵循。这一点对于 Team、组件组合以及持久化后的组件引用尤其重要。当一个组件保存了对特定成员版本的引用时重建和后续执行应当遵循该固定版本而不是在恢复过程中忽略版本约束或使用不符合预期的成员版本。结合前面“无法解析引用时明确失败”的变化v2.9.0 在组件恢复逻辑上形成了更完整的保障无法解析的引用不再静默丢弃严格执行路径会明确报错被固定的成员版本会得到遵循恢复后的组件更接近原始保存定义调度执行不再轻易建立在降级组件之上这对于依赖 Studio 持久化组件、Team 成员组合和版本固定关系的使用场景非常关键。十、Team HITL 暂停成员运行持久化会话重载后仍可继续恢复在人机协作流程方面v2.9.0 修复了 Team HITL 的一个重要问题。此前如果 Team 中的成员运行因为 HITL 暂停暂停状态可能无法在会话重新加载后正确恢复。本次更新后暂停的成员运行会被持久化。这意味着Team HITL 的恢复能力可以跨越会话重新加载。这项修复解决的是一个非常实际的问题。在需要人工确认、审批或介入的 Team 执行流中某个成员可能在中途进入暂停状态。此时系统需要等待人工处理后再继续。如果暂停中的成员运行没有被持久化那么一旦会话被重新加载原本暂停在哪一步、哪个成员正在等待恢复等信息就可能丢失。v2.9.0 通过持久化已暂停的成员运行使 Team 的 HITL 恢复过程更加可靠。更新后的效果包括Team 成员进入 HITL 暂停状态后暂停运行会被保存会话重新加载后暂停状态不会轻易丢失原本等待人工处理的 Team 流程可以继续恢复Team HITL 的执行连续性得到增强人工介入与系统恢复之间的衔接更加稳定对于包含审批、确认或人工审核环节的 Team 执行流程来说这是一项直接提升可用性的修复。十一、A2A 流式客户端修复不再因状态更新提前丢失 Task 元数据v2.9.0 还修复了 A2A 流客户端中的一个问题。此前A2A stream client 在收到状态更新时可能直接中断处理从而导致 Task 级别的元数据被丢失。具体来说客户端此前可能因为在status-update处提前 break导致后续与 Task 相关的元数据无法被正确保留。本次修复后A2A 流式客户端不会再因为状态更新而错误地提前结束处理从而保留 Task 级别元数据。这项修复的重要性在于状态更新与 Task 元数据并不是互斥信息。一个流式执行过程中状态发生变化并不意味着 Task 层面的信息已经全部处理完毕。如果客户端一收到状态更新就停止读取就可能遗漏仍然需要保留的元数据。v2.9.0 修复后状态更新不会再导致客户端过早退出处理Task 级元数据不会因为status-update而被丢失A2A 流式通信中的信息保留更加完整流式客户端对任务级数据的处理更加可靠对于依赖 A2A 流式返回内容的场景这一修复可以避免任务元数据在传输和处理过程中被意外忽略。十二、Workflow WebSocket 修复遵循用户选择的工作流版本在 Workflow 的 WebSocket 执行路径中v2.9.0 修复了工作流版本选择问题。更新后系统会在 WebSocket 场景下遵循用户选定的 Workflow 版本。这意味着当用户明确选择某个工作流版本时通过 WebSocket 执行时将正确使用这个被选择的版本。这一修复确保了不同执行入口在版本行为上的一致性。工作流版本通常代表不同的配置、逻辑或组件组合。如果用户已经选择了特定版本但 WebSocket 执行时没有遵循该选择就可能导致实际执行的内容与用户预期不一致。v2.9.0 解决了这一问题后WebSocket 执行将遵循已选 Workflow 版本用户选择的版本不会在 WebSocket 路径中被忽略工作流版本控制在实时连接执行场景下更加可靠不同版本之间的执行边界更加明确对于通过 WebSocket 启动或交互式运行 Workflow 的场景来说这是一次必要的正确性修复。十三、组件重建时保留 Toolkit Instructionsv2.9.0 修复了组件重建过程中 Toolkit Instructions 丢失的问题。当组件被重新加载或重建时Toolkit Instructions 现在能够被正确保留。Toolkit Instructions 是工具包相关的重要指令信息。如果组件在持久化后再恢复时丢失这些指令那么恢复后的工具行为和原始配置可能出现偏差。本次修复意味着Toolkit Instructions 在 rehydration 过程中得到保留持久化后恢复的组件可以保留原有工具包指令组件重建后的工具行为更接近保存前状态不会因为重建流程而悄悄丢失工具包层面的关键信息这一项修复与“重建失败不再静默降级”形成呼应。一个是对无法解析引用时明确失败另一个是对可解析组件中的 Toolkit Instructions 确保保留。两者共同提升了组件持久化、加载和恢复后的完整性。十四、框架返回注解保护增强框架注解处理稳定性v2.9.0 还加入了对框架返回注解的保护。该修复用于防护框架返回注解相关的处理情况提升框架在面对返回注解时的稳定性。虽然这项更新在发布说明中的描述较为简洁但它属于框架层面的兼容性和健壮性修复。通过对框架返回注解进行保护agno 可以避免在相关注解处理路径中出现不符合预期的问题。此次更新同时与list_components的名称过滤能力一同被纳入版本变更中体现出 v2.9.0 不仅关注调度、安全和持久化也持续完善底层框架行为与组件发现体验。十五、v2.9.0 的核心变化全景总结agno v2.9.0 的更新可以归纳为四个关键词调度、身份、安全、可靠性。在调度层面新增StudioRunnerTools将 Studio 组件运行能力从管理能力中拆分出来。Team Lead、Router 等组件可以发现并运行 Studio 中的 Agent、Team 和 Workflow但不会获得创建、编辑、删除组件的操作面。在身份层面StudioRunnerTools 的run_*工具会将调用方的user_id传递到子运行中确保用户级状态归属于正确用户。同时工具结果缓存键加入user_id和session_id解决跨用户缓存泄漏问题。在安全层面MCP 工具入口禁止调用时覆盖tool_name真实执行工具名称由tool.name固定避免 allow-list、确认机制、HITL 审批与日志记录因名称错位而被绕过。在可靠性层面组件重建不再允许在严格执行路径中静默降级。无法解析的引用会抛出ComponentRehydrationError并以 422 的方式返回问题而不是让缺失工具、成员、Schema 或 Knowledge 的组件继续运行。固定成员版本也会被正确遵循。此外本次版本还修复并完善了多个执行细节list_components增加name过滤Team HITL 暂停成员运行会被持久化会话重新加载后可继续恢复 Team HITLToolkit Instructions 在重建时得到保留A2A 流客户端不再因状态更新丢失 Task 级元数据Workflow WebSocket 执行会遵循所选版本框架返回注解处理获得保护ToolResult 往返处理得到修复缓存命中时 Hook 行为得到处理十六、结语agno v2.9.0 不只是功能更新更是执行边界的系统性收紧代码地址github.com/agno-agi/agnoagno v2.9.0 并非单纯增加几个工具或修补几个边缘问题而是围绕真实运行环境中的关键边界进行了系统性调整。StudioRunnerTools 让运行权限与管理权限分离。用户身份在子运行中的传递让状态能够落在正确用户身上。缓存键引入用户与会话维度让多用户场景下的缓存不再可能跨用户泄漏。MCP 工具名称固定让审批、确认、允许列表和日志机制重新与真实执行目标保持一致。组件重建从静默降级转向严格报错让生产执行路径不再建立在不完整组件之上。Team HITL、A2A 流式通信和 Workflow WebSocket 的修复则进一步增强了暂停恢复、元数据保留与版本选择的正确性。整体来看agno v2.9.0 的核心价值在于让 Agent、Team、Workflow 与工具在多用户、多组件、多入口的运行环境中拥有更清晰的身份归属、更严格的安全边界、更可靠的重建机制以及更一致的执行行为。