1. agno v2.6.13 升级场景AgentOS 注册表、Workflows HITL 与 MCPTools 会话到底改了什么agno v2.6.13 是一次偏实用型的版本更新核心围绕 AgentOS 注册表自动填充、Workflows 的 HITL Socket 支持、MCPTools 会话关闭、JSON Schema 兼容性修复以及工具参数空白字符保留展开。如果你正在用 agno 构建多智能体系统、工作流编排或 AgentOS 接口服务这次升级直接对应了几个真实痛点注册表要手工同步、子智能体事件断流、MCP 会话刷新后不释放、Optional dataclass 字段生成 schema 报错。本文面向已经在跑 agno 项目的开发者交付可复制的 config.toml 与 settings.json 配置骨架并给出升级后验证 AgentOS 启动、Workflow 编排与 MCPTools 调用的具体操作步骤。适合人群正在做 Agent 应用迁移、需要确认版本行为差异、或者准备把 AgentOS 接入 Slack 的团队。下面按“先讲清问题、再给配置、最后验证排障”的顺序走一遍。2. 升级前先接好模型与密钥TaoToken 前置配置agno 本身负责编排但 Agent 要真正跑起来模型调用这一层得先通。我这边习惯用 TaoToken 做统一入口它的 API 兼容 OpenAI 风格agno 里配置 base_url 和 api_key 就能直接对接省去每个模型单独适配的麻烦。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。操作路径很直接先到控制台创建密钥再在 agno 的模型配置里填进去。密钥页面在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建完复制 sk- 开头的 key。如果你还没决定用哪个模型可以先在模型对话页试一下返回是否正常 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。长期跑编码类 Agent 的话Coding Plan 会更划算入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。注意密钥只放在环境变量或本地配置文件里不要提交到 git。agno 读取模型配置时优先走环境变量这样迁移环境不用改代码。3. 可复制配置骨架config.toml 与 settings.jsonagno v2.6.13 的 AgentOS 注册表支持从 agents、teams、workflows 自动填充所以配置文件的结构要能体现这三类资源。下面这份 config.toml 是我实测能跑通的骨架重点是把 registry 的 auto_populate 打开并把 MCPTools 的会话清理策略显式写出来。# config.toml - agno v2.6.13 AgentOS 配置骨架 [agentos] name my-agentos host 0.0.0.0 port 7777 registry_auto_populate true # v2.6.13 新增从 agents/teams/workflows 自动填充 [agentos.registry] sources [agents, teams, workflows] refresh_on_start true [models.default] provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model gpt-4o-mini [mcp.tools] session_close_on_refresh true # 对应 MCPTools 会话关闭修复 preserve_argument_whitespace true # 对应工具参数空白保留修复 [workflows.hitl] transport socket # v2.6.13 新增HITL over Sockets socket_path /tmp/agno-hitl.socksettings.json 这边主要管运行时行为和 schema 兼容开关尤其是 JSON Schema 对 Optional dataclass 无类型字段的处理。{ runtime: { event_streaming: { sub_agent_to_parent: true }, content_hash: { include_metadata: true } }, schema: { json_schema: { optional_dataclass_without_type: tolerate } }, mcp: { multi_mcp_cleanup_on_failure: true }, tools: { daytona_shell_quote_paths: true } }这两个文件放好后AgentOS 启动时会自动扫描 agents、teams、workflows 目录并注册不用再手工维护 registry 列表。实测下来注册表自动填充对已有大量 agent 定义的项目省事很多。4. 验证 AgentOS 启动、Workflow 编排与 MCPTools 调用配置写完不能只看日志说“启动成功”得实际发请求确认行为。下面分三步验证。4.1 验证 AgentOS 启动与注册表自动填充启动命令export TAOTOKEN_API_KEYsk-你的密钥 agno agentos start --config config.toml启动后查注册表接口确认 agents、teams、workflows 都被自动填充进来curl -s http://localhost:7777/registry | python -m json.tool返回里应该能看到agents、teams、workflows三个数组且数量和你项目里定义的一致。如果某个资源没出现先检查它是否在sources声明的目录下。4.2 验证 Workflow 编排与 HITL Socketv2.6.13 给工作流 HITL 加了 socket 支持验证方式是跑一个带人工介入节点的工作流观察 socket 是否建立from agno.workflow import Workflow from agno.workflow.hitl import HITLNode wf Workflow( namereview-flow, hitlHITLNode(transportsocket, socket_path/tmp/agno-hitl.sock), ) result wf.run(input生成一份周报草稿) print(result.status) # 期望waiting_for_human如果返回waiting_for_human说明 socket 通道已就绪人工确认后工作流能继续。这一步是 v2.6.13 相对旧版最明显的行为差异。4.3 验证 MCPTools 调用与会话关闭MCPTools 的修复点是刷新后的会话会在 call task 中关闭。验证时连续调用两次工具观察第二次是否复用干净会话from agno.tools.mcp import MCPTools tools MCPTools(servermy-mcp-server, session_close_on_refreshTrue) out1 tools.call(search, {query: agno v2.6.13}) out2 tools.call(search, {query: AgentOS registry}) print(out1, out2)两次调用都正常返回、且日志里没有残留会话告警就说明会话关闭逻辑生效了。工具参数空白保留也可以顺手测传一个带前后空格的参数看返回值里空格是否还在。5. 本篇常见错排查升级后容易踩的坑升级到 v2.6.13 后报错大多集中在配置字段和 schema 兼容上下面几个是我遇到过的。第一个是 AgentOS 注册表为空。原因通常是registry_auto_populate没开或者sources路径写错。检查 config.toml 里[agentos.registry]段确认refresh_on_start true。第二个是 JSON Schema 报Optional dataclass field without type。这是 v2.6.13 专门修的场景但如果你用的是旧版 agno就会直接抛错。升级到 v2.6.13 后settings.json 里把optional_dataclass_without_type设为tolerate即可。第三个是 MCPTools 会话泄漏。表现是长时间运行后连接数上涨。确认session_close_on_refresh true已生效并检查是否有自定义的 call task 覆盖了默认关闭逻辑。第四个是工具参数空格丢失。如果你在旧版里做过 workaround比如手动 trim升级后要把它去掉否则会和新行为冲突。第五个是 MultiMCP 连接失败后状态残留。v2.6.13 已清理但如果你的代码里捕获异常后没重新初始化仍可能拿到旧连接。建议在失败分支里显式重建 MCPTools 实例。提示排障时优先看 AgentOS 启动日志里的 registry 扫描结果和 MCP 会话生命周期日志这两处能覆盖大部分升级问题。6. 迁移收尾与后续接入建议把配置和验证跑通后迁移基本就完成了。如果你在排障阶段卡在密钥或接入层可以直接到 API Keys 页面重新生成一个干净的 key https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入细节看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。想先确认模型返回是否符合预期用模型对话页快速试 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。长期跑编码或 Agent 任务Coding Plan 的额度更稳 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。Claude Code 相关接入参考 https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。最后补一个实用技巧升级后先把registry_auto_populate和session_close_on_refresh这两个开关打开跑一天观察日志里注册表数量和 MCP 会话数是否稳定再逐步放开 HITL socket 到生产工作流。这样出问题时回滚范围小定位也快。