高级 📋 6 个步骤 第 627 / 632 篇

Agno v3.2.0 升级实操:A2A v1.0 路由迁移、Slack Bolt 审批人与 OSManager 默认值核验

Agno v3.2.0 于 2026 年 11 月 12 日发布,官方 Release 列出三组破坏性变更:OSManager 默认值调整与工具名校验、A2A 升到官方 1.0 协议并移除旧路由、Slack 接口改用 Bolt SDK 并收紧审批人。本教程按发行包实测六步落地:隔离环境锁版本、体检依赖约束、核对默认值与保留工具名、探活 agent-card 路由、检查 Slack 参数,最后写成可放进 CI 的升级验收脚本与灰度回退顺序。全程不新增模型密钥,服务只绑回环地址。

2026.11.16· 18 分钟阅读· 约 4008 字· 🧩 Agno 3.2.0 / 🔗 A2A v1.0

把 AgentOS 从 3.1.x 升到 3.2.0,最危险的不是新功能,而是几处会直接让服务起不来的破坏性变更。Agno v3.2.0 于 2026 年 11 月 12 日发布,官方 Release 明确列出三组 Breaking changes:OSManager 默认值调整与工具名校验、A2A 升级到官方 1.0 协议并移除旧路由、Slack 接口改用 Bolt SDK 并收紧审批人。本教程不重写业务代码,而是按官方 Release 与 3.2.0 发行包逐项做「可跑通、可打印结果」的升级验收:锁版本、体检依赖、核对默认值、验证冲突校验、探活 A2A 卡片、检查 Slack 参数,最后给出灰度与回退顺序。所有命令都在本机虚拟环境里执行,不需要接入线上 Slack 或真实模型密钥。

🧩 适合谁:已经在生产或预发环境跑 Agno AgentOS、A2A 服务端或 Slack 接口的后端 / 平台工程师;也适合准备把 3.1.x 项目升到 3.2.0 的技术负责人。前置准备:Python 3.9 及以上(官方 PyPI 标注 requires_python 为 >=3.9、<4)、能联网安装 pip 包、一个可随时丢弃的练习目录、用 git 或文件副本保存现有依赖清单与配置。建议先在一个空白虚拟环境里跑完本教程,再动真实部署;升级本身不新增模型密钥,但如果你随后让 Agent 真跑一轮推理,模型用量仍按你的账号计费。

先把安全边界说清楚:本教程的检查脚本只读取本机安装的包、类签名和路由常量,不会启动对外服务、不会发送 Slack 消息、也不会调用模型。若要启动 AgentOS 做端到端探活,请只绑定回环地址;任何 Slack bot token、signing secret、模型 API Key 都不要写进仓库、脚本或截图,用环境变量注入即可。另外,官方 Release 说 v0.3 客户端默认仍可通过兼容线工作,但这是协议兼容而不是长期承诺,别把它当成可以一直跳过客户端升级的理由。

先弄清:这次升级到底改了什么

v3.2.0 的 Summary 写着:Super Agent 改为自己直接调工具、Company 任务治理扩展、AgentOS 首页指标改为数据库支撑、A2A 升到官方 1.0 协议、Slack 接口改用 Bolt SDK、外部 Agent 变成可存储组件。对升级者而言,真正会打断部署的是下面这张表里的四条,其余属于新增能力,可以随后再评估。

变更点官方 3.2.0 口径本教程的验证方式
OSManager 默认值tool_call_limit 由 8 变 24,num_history_runs 由 7 变 5读取 3.2.0 发行包里的配置类字段默认值
工具名冲突校验OSManager(root=...) 与名为 read_file、list_files、search_content 的自定义工具同时出现时,AgentOS 拒绝启动打印发行包内的保留名集合,并用最小构造触发 ValueError
A2A v1.0移除 /v1/message:* 与 /v1/tasks:* 路由,改用各实体的 A2A 端点;a2a extra 需要 a2a-sdk[http-server]>=1.2.2,<2检查依赖约束与 agent-card 路径常量
Slack / Bolt需要 slack_bolt>=1.29.0,<2 与 slack_sdk>=3.43.0,<4;默认仅任务发起人可 Approve / Deny,除非显式配置 approvers= 或 users=核对 Slack 构造参数与依赖版本

版本口径不要靠记忆:本教程按 2026-11-16 核对到的 PyPI 最新正式版 3.2.0(Release 发布时间 2026-11-12)撰写;官方 Release 标题日期与 published_at 可能差一天,属正常现象。请以你机器上 python -c "import agno; print(agno.__version__)" 的输出为准,别把本文任何版本号当成命令前提。若你仍在 3.1.x,先读完下面的回退顺序再升级。

Step 1:开一个隔离环境,锁版本并体检依赖

1 先建可丢弃的虚拟环境,再做依赖体检

升级事故里最常见的一类,是直接在全局环境覆盖安装,导致旧项目无法复现。这里新建练习目录与虚拟环境,把版本锁死在 3.2.0,同时把 A2A 与 Slack 两个 extra 一起装上,便于后面逐项检查。安装前把现有项目的 requirements.txt 或锁文件备份到别处。

# 新建练习目录,别在真实项目里直接跑
mkdir agno-320-check && cd agno-320-check
python -m venv .venv
# Windows PowerShell 用: .\.venv\Scripts\Activate.ps1
source .venv/bin/activate

# 锁定 3.2.0,并带上 a2a 与 slack 两个官方 extra
pip install "agno==3.2.0" "agno[a2a]" "agno[slack]"

# 打印实际装到的版本,确认没有被别的包顶掉
python -c "import agno; print('agno', agno.__version__)"
pip show agno a2a-sdk slack-bolt slack-sdk

# 依赖一致性体检:有冲突会直接报出来
pip check
💡 pip show 的输出里应能看到官方 Release 与 PyPI 元数据给出的约束:a2a-sdk[http-server]<2,>=1.2.2、slack_bolt<2,>=1.29.0、slack_sdk<4,>=3.43.0。如果你的旧锁文件把这些依赖钉在更低版本,pip check 会给出明确的冲突包名,按提示调整后再继续;不要靠手工删包硬凑。

Step 2:核对 OSManager 默认值与保留工具名

2 用本机代码把「口头变更」变成可打印的事实

官方 Release 说 OSManager.tool_call_limit 默认从 8 升到 24、num_history_runs 从 7 降到 5,并新增保留工具名校验。与其相信文档文字,不如直接读已安装包里的配置类与常量。下面这段脚本只做读取与打印,不会启动任何服务。

# check_defaults.py —— 读取本机 agno 3.2.0 的实现
import inspect
from agno.os.manager.config import OSManager
from agno.os.manager import manager as mgr

# dataclass 字段默认值(3.2.0 实测:5 / 24 / 24)
for name in ("num_history_runs", "tool_call_limit", "member_tool_call_limit"):
    print(name, "=", getattr(OSManager, name, "字段不存在"))

# 保留工具名集合(3.2.0 实测为三个源文件工具名)
print("reserved =", sorted(getattr(mgr, "_SOURCE_TOOL_NAMES", set())))

# 打印构造签名,确认参数名没有在升级中改掉
print("signature:", inspect.signature(OSManager))

把输出和你项目里显式传过的值对一遍:如果旧代码依赖「默认 8 次工具调用」来做成本控制,升级后行为会明显变化,需要显式写回 tool_call_limit=8;依赖「默认带 7 条历史」的上下文也会变短。

工具名冲突是启动级错误:官方 Release 写明,当 OSManager(root=...) 与名为 read_file、list_files、search_content 的自定义工具一起出现,AgentOS 会拒绝启动。3.2.0 源码里这组名字被定义为 _SOURCE_TOOL_NAMES 冻结集合,并在校验分支抛出 ValueError。若你的项目恰好用了同名工具,先改名或移除,再升级;具体异常文案以本机输出为准,别照抄本文措辞。

Step 3:验证 A2A v1.0 路由与 agent-card 端点

3 找出被移除的旧路由,改用实体级卡片地址

这次 A2A 迁移把 /v1/message:* 与 /v1/tasks:* 路由移除,改为各实体的 A2A 端点;流事件与 artifacts 也换成 v1.0 的形状。3.2.0 发行包的路由模块里能直接读到卡片路径模板,先用脚本把它打印出来,再去核对你的网关白名单、健康检查与客户端配置。

# check_a2a.py —— 读取 A2A 路由常量,不启动服务
from importlib.metadata import version
import inspect
from agno.client.a2a import A2AClient
from agno.os.interfaces.a2a import A2A
from agno.os.interfaces.a2a import router as a2a_router

print("agno =", version("agno"))
print("client =", inspect.signature(A2AClient.__init__))
print("interface =", inspect.signature(A2A.__init__))

src = inspect.getsource(a2a_router)
for line in src.splitlines():
    if ".well-known" in line or "add_api_route" in line:
        print("route:", line.strip())

# 3.2.0 实测可见的三类卡片路径模板:
# /agents/{id}/.well-known/agent-card.json
# /teams/{id}/.well-known/agent-card.json
# /workflows/{id}/.well-known/agent-card.json

拿到路径模板后,把旧配置文件里所有 /v1/message:send 之类的调用点列成清单,逐项改到 agent / team / workflow 对应的 A2A 端点。官方同时说明:Agent Cards 会同时宣告 v1.0 与 v0.3 接口,标准 v0.3 客户端默认走兼容线,这只是迁移期的缓冲,不是免升级通行证。

💡 服务端与客户端要一起升:官方 Release 明确要求 AgentOS 和 A2AClient 同步升级到 3.2.0,且 a2a extra 已收紧到 a2a-sdk[http-server]>=1.2.2,<2。只升服务端、留着旧客户端,最容易在流式事件解析处出现「连得上但读不懂」的故障。

Step 4:检查 Slack / Bolt 依赖与审批人配置

4 把「谁能点 Approve」写进配置,而不是靠提示词

Slack 接口改用 Bolt SDK 后,默认的审批权收窄为「发起该次 run 的人」;其他人想审批,需要显式写进 approvers=,或通过 users= 把 Slack 成员映射到 AgentOS 主体。3.2.0 的 Slack 构造签名里能直接看到这些参数,先用本机包核对,再改你的配置。

# check_slack.py —— 只检查参数名与启动校验,不联网
import inspect
from agno.os.interfaces.slack import Slack

sig = inspect.signature(Slack.__init__)
for name in ("token", "signing_secret", "approvers", "users", "team"):
    print(name, "=", sig.parameters.get(name, "缺失"))

# 官方 Release:缺少 token 或 signing secret 时 Slack(...) 在启动期抛 ValueError;
# 未签名请求返回 403。这里不构造真实实例,避免误触发凭据读取。
src = inspect.getsource(Slack.__init__)
print("has_startup_guard =", "Slack requires an agent, team, or workflow" in src)

# 配置写法示意(真实凭据请走环境变量,不要硬编码):
# Slack(
#     team=agent_os.manager,
#     approvers=["U0123ABC"],
#     users={"U0123ABC": "platform-admin"},
#     token=os.environ["SLACK_BOT_TOKEN"],
#     signing_secret=os.environ["SLACK_SIGNING_SECRET"],
# )

有三处启动期硬约束:① 官方 Release 写明,在 AgentOS(authorization=...) 下让 Slack 服务 agent_os.manager、或使用了不带 users= 的鉴权中间件时,AgentOS 会拒绝启动;② 直接 import 被移除的内部 Slack 辅助类(SlackEventHandler、HITLHandler、verify_slack_signature)的代码需要改写;③ 缺少 token 或 signing secret 会抛 ValueError。把这三项当作升级前的静态检查项,别等线上启动时才发现。

Step 5:写一个可重复执行的升级验收脚本

5 把四项检查收进一个文件,交给 CI 或发布清单

前面四步是分散的探查,交付前最好合成一个脚本:版本、默认值、A2A 路由、Slack 参数一次跑完,任何一项不符合预期就以非零码退出。下面这份脚本刻意只做「本地可观测」断言,不依赖网络、不依赖 Slack 工作区、不调用模型,适合放在预发流水线的门禁环节。

# verify_agno_320.py
import sys
import inspect
import agno
from agno.os.manager.config import OSManager
from agno.os.manager import manager as mgr
from agno.os.interfaces.slack import Slack
from agno.os.interfaces.a2a import router as a2a_router

problems = []

if agno.__version__ != "3.2.0":
    problems.append("agno 版本不是 3.2.0: " + agno.__version__)

if getattr(OSManager, "num_history_runs", None) != 5:
    problems.append("num_history_runs 默认值与 3.2.0 不符")
if getattr(OSManager, "tool_call_limit", None) != 24:
    problems.append("tool_call_limit 默认值与 3.2.0 不符")

reserved = getattr(mgr, "_SOURCE_TOOL_NAMES", set())
if not {"read_file", "list_files", "search_content"}.issubset(reserved):
    problems.append("保留工具名集合与 3.2.0 不符")

slack_params = inspect.signature(Slack.__init__).parameters
if not {"approvers", "users", "signing_secret"}.issubset(slack_params):
    problems.append("Slack 构造参数缺少审批相关字段")

route_src = inspect.getsource(a2a_router)
if ".well-known/agent-card.json" not in route_src:
    problems.append("未找到 v1.0 agent-card 路由")
if "/v1/message:" in route_src or "/v1/tasks:" in route_src:
    problems.append("路由源码仍含已移除的旧 A2A 路由")

if problems:
    print("FAIL")
    for p in problems:
        print(" -", p)
    sys.exit(1)
print("PASS: agno 3.2.0 升级四项检查全部符合预期")
sys.exit(0)
💡 保存为 verify_agno_320.py 后执行 python verify_agno_320.py && echo READY;看到 PASS 再进入灰度。脚本里的断言值来自 3.2.0 发行包实测,若日后升级到更高版本,请按新版本的实测结果更新断言,别让它变成永远报错的僵尸门禁。

Step 6:按灰度顺序升级,并留好回退路径

6 先客户端与依赖,再服务端,最后放开流量

官方要求服务端与客户端一起升,实际执行时仍要有顺序:先在预发把依赖与静态检查跑通,再升 AgentOS 进程,最后切流量。回退时用同一份锁文件把版本钉回去,避免「升级用了 3.2.0、回退却装到更新的版本」这类二次事故。

# 1) 保存当前可回退的依赖快照(在真实项目里执行)
pip freeze > requirements-before-320.txt
cp -r config/ config-backup-320/

# 2) 预发:先跑静态门禁,再启动服务(只绑回环地址)
python verify_agno_320.py
# 按你项目自己的启动命令启动 AgentOS,例如:
# uvicorn myapp:app --host 127.0.0.1 --port 8000

# 3) 用 curl 探活实体卡片地址(id 换成你自己的 agent id)
curl -sS -o card.json -w "%{http_code}\n" \
  http://127.0.0.1:8000/agents/YOUR_AGENT_ID/.well-known/agent-card.json
python -c "import json; d=json.load(open('card.json')); print(sorted(d.keys()))"

# 4) 旧路由应已不存在;具体返回码以你项目的路由层为准
curl -sS -o /dev/null -w "%{http_code}\n" \
  -X POST http://127.0.0.1:8000/v1/message:send

# 5) 回退:用同一份快照把环境还原
pip install -r requirements-before-320.txt
python -c "import agno; print('rolled back to', agno.__version__)"

回退不等于数据回滚:官方提到 3.2.0 的 A2A 任务会入库,并新增了首页指标相关的数据表;回退 pip 包只会还原代码,不会自动清理或迁移数据库结构。生产升级前先备份数据库,并确认回退后旧版本能读取已写入的数据。此外,curl 探活用到的实体 id 与端口由你自己的项目决定,本文不臆造默认值。

做到哪一步算成功:交付前自查

把下面这张表当成升级工单的验收栏,逐项打勾再合并。只要有一项没过,就别把 3.2.0 推到生产。

检查项预期结果没过怎么办
版本号agno.__version__ 输出 3.2.0,pip check 无冲突按 pip 冲突提示调整锁文件
依赖约束能看到 a2a-sdk 1.2.2 以上、slack_bolt 1.29.0 以上升级 extras,别手工降级绕过
默认值打印出 5 / 24 / 24,并已核对业务里显式传入的值把旧行为显式写回配置
工具名自定义工具不与三个保留名撞车,AgentOS 能启动改名或移除同名工具
A2A卡片地址返回 200 且能解析 JSON,旧调用点已改完同步升级 A2AClient 与网关配置
Slack构造参数含 approvers / users,凭据由环境变量注入补齐映射,检查鉴权中间件
回退快照文件与数据库备份都在,回退命令演练过先补齐再放量
🎉 做到这些,说明你已经把「看 Release 文档」变成了「有证据的升级」:版本可打印、默认值可核对、路由可探活、审批配置可静态检查、回退可复现。之后再去评估 Super Agent 直连工具、Company 任务治理等新能力,风险会小很多。

交付前自查的最后一条:本教程的检查项来自官方 v3.2.0 Release 与 3.2.0 发行包实测,属于「迁移期门禁」,不覆盖你业务里的自定义中间件、数据库连接与鉴权策略。请在预发环境按真实流量形态再跑一轮,尤其确认 A2A 流事件解析与 Slack 审批链路。

常见问题速查

现象大概率原因与处理
pip check 报 a2a-sdk 版本冲突旧锁文件钉了 1.2.2 以下版本;按官方约束放宽到 >=1.2.2,<2
AgentOS 启动直接抛 ValueError先查是不是 OSManager(root=...) 撞上三个保留工具名,再查 Slack 是否缺 token / signing secret
旧 A2A 客户端连得上但解析不了流事件3.2.0 的事件与 artifacts 换成 v1.0 形状;服务端与 A2AClient 一起升
Slack 里别人点不了 Approve3.2.0 默认仅发起人可审批;把成员 ID 写进 approvers= 或配置 users= 映射
升级后工具调用次数明显变多tool_call_limit 默认由 8 变 24;若依赖旧上限做成本控制,显式写回 8
上下文里历史 run 变少num_history_runs 默认由 7 变 5;按业务需要显式设置
回退后数据库读不出来pip 回退不回滚数据结构;用升级前的数据库备份恢复
📌 延伸阅读:本中心《用 Agno 框架 10 分钟搭一个会调用工具的智能体》讲的是从零搭基础 Agent;《让不同 AI 智能体会「对话」:A2A 协议实战》讲的是协议本身;本篇只处理 3.1.x 到 3.2.0 的迁移验收,三者不互相替代。
← 返回教程中心