← 返回首页

Agent Framework 31 个子包:稳定线与 beta 线怎么装

Python依赖管理Agent Framework

先说测试环境:Windows 11 + CPython 3.13.12(另备 3.11.3 做对照),pip 26.1.2 与 24.3.1,安装方式为 pip install --target tmp/w46-af agent-framework(隔离目录,不动主环境)。包版本与依赖来自各包 *.dist-info/METADATA,发布日期与 requires_python 用 PyPI JSON API 逐包对拍,抓取时间 2026-11-10。本文不含任何联盟推广链接,只谈包装与版本。

31 个包,10 个稳定、21 个预发布

截至 2026-11-10 抓取,PyPI 上以 agent-framework 开头的包共 31 个,其中版本号不带 a/b/rc 字样的 10 个,带 b 的 21 个:

稳定线(10)版本
agent-framework1.25.0
agent-framework-core1.25.0
agent-framework-openai1.18.1
agent-framework-foundry1.16.1
agent-framework-ag-ui1.8.0
agent-framework-declarative1.5.0
agent-framework-orchestrations1.4.2
agent-framework-github-copilot2.1.2
agent-framework-azurefunctions1.0.0
agent-framework-durabletask1.0.0

其余 21 个全部停在 1.0.0b261106(anthropic、claude、gemini、mistral、ollama、bedrock、chatkit、copilotstudio、devui、mem0、redis、purview、tools、hyperlight、monty、foundry-local、foundry-hosting、a2a、azure-ai-search、azure-cosmos、azure-contentunderstanding),全在同一批发布里。

两天前装的名单,今天已经过期

我 11 月 8 日装完时,本地快照是 8 个稳定 + 23 个预发布。今天逐包对拍 PyPI,变成 10 + 21,差的正是 agent-framework-azurefunctions 和 agent-framework-durabletask:两个包都于 2026-11-09 17:13 UTC(17:13:00 与 17:13:02)上传了 1.0.0。也就是说,从 beta 转正这件事发生在离发稿不到一天的窗口里,而我手里那份「哪个包是 beta」的清单在任何静态文档里都会瞬间变假。

结论很直接:「谁是 beta」不是知识,是一个需要每次现算的状态。判断方式不用读文档,逐包问 PyPI 即可:

python - <<'EOF'
import requests
from packaging.version import Version
for n in ["agent-framework-gemini", "agent-framework-openai"]:
    v = requests.get(f"https://pypi.org/pypi/{n}/json", timeout=30).json()["info"]["version"]
    print(f"{n:34s} {v:14s} prerelease={Version(v).is_prerelease}")
EOF

版本号不能横着比:2.1.2 比 1.25.0「大」,但小 42 倍

上面那张表最容易被误读的一点:10 个稳定包出现了 7 个不同的版本数字(1.25.0 两个、1.18.1、1.16.1、1.8.0、1.5.0、1.4.2、2.1.2、1.0.0 两个)。按数字排序,最大的是 agent-framework-github-copilot 2.1.2,最小的是 1.0.0。

我按 .py 文件数与行数把每个包量了一遍(排除 __pycache__):

包版本.py 文件行数体积
agent-framework-core(模块名 agent_framework)1.25.08483,7443.5 MB
agent-framework-openai1.18.178,065380 KB
agent-framework-ag-ui1.8.02717,166740 KB
agent-framework-github-copilot2.1.231,96782.6 KB
agent-framework-mem01.0.0b261106334414.3 KB

2.1.2 有 1,967 行,1.25.0 有 83,744 行,相差 42.6 倍。版本号大 0.9 个 major 的包,代码量只有对方的百分之二点三。

原因是这些包各自维护独立的发布线,版本号只反映它自己发过多少次。core 从 1.0.0b251001(2025 年 10 月的首个 beta)一路走到 1.0.0(2026-04-02),再到今天的 1.25.0(2026-11-07),共 66 个版本;github-copilot 的 1.0.0 迟至 2026-07-23 才发,但两个月就冲到 2.1.2。拿 2.1.2 去和 1.25.0 比新旧,等于拿两个不同的尺子量同一块板。

beta 的版本号长什么样,为什么 `>=1.0.0` 一个都装不到

那 21 个预发布包的名字形如 1.0.0b261106。六个数字看着像日期(26 年 11 月 06 日),但在 PEP 440 里它只是「1.0.0 的第 261106 个 beta」,没有任何日期语义,只按数字比大小。于是 1.0.0b261106 < 1.0.0。

后果不是理论上的。我在 3.13.12 + pip 26.1.2 上实测:

pip install --dry-run --no-deps "agent-framework-gemini>=1.0.0"

返回码 1,原文两行:

ERROR: Could not find a version that satisfies the requirement agent-framework-gemini>=1.0.0 (from versions: 1.0.0a260421, ..., 1.0.0b261106)
ERROR: No matching distribution found for agent-framework-gemini>=1.0.0

换成 >=1.0.0b1 立刻通过(返回码 0)。也就是说:在 requirements 里给这 21 个包写下限 >=1.0.0,等于把全部候选一次性排除,而错误信息只会说「找不到版本」,不会提醒你「我看到了 26 个候选,只是它们都带 b」。

PEP 440 里预发布的排序与 ~= 位数这些细节,10 月 21 日那篇已经逐项验过(PEP 440 版本约束:~= 位数、== 零填充与 pip 误报复盘),这篇只说它在真实依赖树上的表现。

唯一一个精确钉:meta 包把 core 锁在 1.25.0

31 个包里只有 1 个用 ==,就是元包本身。它 1.25.0 版的 Requires-Dist 全文只有一行:

agent-framework-core[all]==1.25.0

其余 30 个包全是区间,最常见形态是 agent-framework-core>=X,<2,唯一的例外是 agent-framework-github-copilot 的 >=2.1.2,<3(因为它已经在 2.x 线上)。

这一条 == 的含义容易被忽略:core 的天花板是被 meta 包钉死的。只要你的项目里写了 agent-framework==1.25.0,任何要求 agent-framework-core>=1.26 的子包都会解析失败——而失败点出现在子包上,报错指向的是「你装的那个 provider」,不是「meta 包钉得太死」,排查时很容易查错方向。

碰巧的是,现在有 4 个包的下限正好卡在 >=1.25.0(ag-ui、declarative、foundry-hosting、openai),与 meta 的钉死值同一条船,所以此刻装 agent-framework==1.25.0 是全绿。这条船什么时候散,取决于这 4 个包里任意一个先要 1.26。

30 个包对 core 的下限,分 8 档

把 30 个子包对 agent-framework-core 的下限拉平排,得到一张很能说明问题的分布:

core 下限包数代表包
>=1.13.03chatkit、mem0、azure-contentunderstanding
>=1.18.01azure-ai-search
>=1.19.06durabletask、hyperlight、monty、redis、tools、azurefunctions
>=1.21.01purview
>=1.22.04a2a、claude、copilotstudio、github-copilot
>=1.23.02devui、orchestrations
>=1.24.08anthropic、bedrock、azure-cosmos、foundry、foundry-local、gemini、mistral、ollama
>=1.25.04ag-ui、declarative、foundry-hosting、openai

最松的三个(chatkit、mem0、azure-contentunderstanding)只要求 >=1.13.0,意思是它们声称能在 12 个 minor 之前的核心上工作。但真实的兼容边界不是最松的那个,而是最严的那个:你装了 openai 适配器(>=1.25.0),chatkit 那句 >=1.13.0 就完全失去意义——两个包必须共享同一个 core。

所以「这个 provider 支不支持我的 core 版本」这个问题,单看该 provider 自己的 METADATA 会被误导,必须把已装集合的下限取最大值。实践里更省事的做法是直接跟 core 走:core 升到哪,全部子包一起升。

同一条命令,3.11 和 3.13 装出两个版本,全程 0 提示

这是本轮最值得写下来的一条。agent-framework-azurefunctions 的 requires_python 在 10 月底跳了一次:

版本requires_python上传时间
1.0.0b260922>=3.102026-09-25
1.0.0b261029>=3.132026-10-30
1.0.0>=3.132026-11-09

一次抬升跨了 3 个 minor。于是同一个包名、同一条命令:

pip install --dry-run --no-deps agent-framework-azurefunctions

3.11 上拿到的是 2026-09-25 那个 beta,比 GA 早了 45 天 和一个完整的转正里程碑,没有任何警告。退到 meta 层也一样:3.11 上 pip install --dry-run agent-framework 返回码 0,解析出 173 个包,agent-framework 系仍是 31 个,但 azurefunctions 固定在 1.0.0b260922,durabletask 是 1.0.0。整条链路一句提示都没有。

而 meta 与 core 自己的元数据写的是 requires_python >=3.11。两个数字都不算错,它们描述的是两件事:>=3.11 是「官方在这个解释器上测过」,requires_python 是「解析器要不要给你这个文件」。后者会把不满足的版本从候选里直接剔除,剔除动作是静默的。

要防这一条,只有一个笨办法:装完立刻把实际落地的版本打出来对拍。

pip install agent-framework
python -m pip list --format=freeze | grep -i "^agent-framework"

`[all]` 不是所有平台都装得满

meta 包通过 agent-framework-core[all] 把所有子包拖下来,看着像「一条命令全家桶」。但 all 这个 extra 里有两条带平台 marker 的依赖,原文(agent-framework-core 元数据):

用 packaging 26.3 对四组环境求值:

环境foundry-localhyperlight
win32 AMD64 + py3.13装装
win32 ARM64 + py3.13装不装
darwin arm64 + py3.13装不装
win32 AMD64 + py3.10不装装

所以「我装了 [all],所以 provider 全都有」这句话在 Windows on ARM 和 Apple Silicon 上都不成立,少的是 hyperlight;在 Python 3.10 上少的是 foundry-local。这不是厂商疏忽,是 marker 本来就这么写的——但文档里那句 pip install agent-framework 看不出这层差别。

顺带一个体量数字:本机这样装完是 208 个 dist-info、1,046 MB。真要只为跑一个 OpenAI 客户端,agent-framework-core + agent-framework-openai 两个包就够,不必拖 1 GB。

导入路径:官方文档写嵌套,包名是平的,顶层还可能是空壳

官方总览页的 Python 示例长这样:

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient

用的是嵌套路径 agent_framework.foundry,而 pip 上的包名是 agent-framework-foundry。两条路径其实都能 import,但它们不是同一个模块对象:

agent_framework.openai is agent_framework_openai   -> False
agent_framework_openai.OpenAIChatClient is agent_framework.openai.OpenAIChatClient -> True

模块对象不同、类对象相同。这意味着 isinstance 判断不会被两条路径骗过(好事),但 sys.modules 里会同时出现两个键(排查 import 开销或热重载异常时会看到重复条目)。

更反直觉的是 agent-framework-tools。它的顶层 __init__.py 里 __all__ 只有一项:

__all__ = ["__version__"]

真正的 API 全在子模块 agent_framework_tools/shell/(15 个 .py、2,830 行,导出 LocalShellTool、DockerShellTool、ShellPolicy 等)。而嵌套路径 agent_framework.tools 反而直接有 LocalShellTool。平铺包名是空壳、嵌套路径是全的,与人的直觉正好相反。

同一类容易混的还有一对:agent_framework_anthropic 与 agent_framework_claude 版本号同为 1.0.0b261106,导出的东西完全不同——前者是 Messages API 客户端加 Bedrock/Vertex/Foundry 三个变体,后者包的是 claude_agent_sdk,导出 ClaudeAgent 系列。名字只差一个词,装错就是白装一次。

Troubleshooting:三个真实报错

报错一:`Could not find a version that satisfies the requirement agent-framework-gemini>=1.0.0`

原文两行(pip 26.1.2,返回码 1):

ERROR: Could not find a version that satisfies the requirement agent-framework-gemini>=1.0.0 (from versions: 1.0.0a260421, 1.0.0a260423, ..., 1.0.0b261106)
ERROR: No matching distribution found for agent-framework-gemini>=1.0.0

原因:该包只有 alpha 与 beta,而 >=1.0.0 按 PEP 440 不匹配任何预发布。解决:下限写成 >=1.0.0b1,或显式 --pre。

报错二:`ImportError: cannot import name 'LocalShellTool' from 'agent_framework_tools'`

原文:

File "D:\openclaw-blog\tmp\_ti.py", line 3, in 
    from agent_framework_tools import LocalShellTool
ImportError: cannot import name 'LocalShellTool' from 'agent_framework_tools' (D:\openclaw-blog\tmp\w46-af\agent_framework_tools\__init__.py)

原因:顶层 __init__.py 只导出 __version__,真实 API 在 shell 子模块。解决:from agent_framework_tools.shell import LocalShellTool,或走嵌套路径 from agent_framework.tools import LocalShellTool。

报错三:`ModuleNotFoundError: No module named 'pywintypes'`(Windows,`--target` 安装)

import agent_framework_claude 直接炸,调用链一路排到 mcp 的 Windows 分支:

File "...\agent_framework_claude\__init__.py", line 5, in 
    from ._agent import ClaudeAgent, ClaudeAgentOptions, ClaudeAgentSettings, RawClaudeAgent
File "...\agent_framework_claude\_agent.py", line 37, in 
    from claude_agent_sdk import (...)
File "...\claude_agent_sdk\__init__.py", line 29, in 
    from mcp.types import CallToolResult, Tool
...
File "...\mcp\os\win32\utilities.py", line 22, in 
    import pywintypes
ModuleNotFoundError: No module named 'pywintypes'

原因:pywintypes 不是普通模块,pywin32 靠安装时写入的 pywin32.pth 把 win32/lib 挂进 sys.path。我这个隔离目录里三样东西都在——pywin32.pth、win32/lib/pywintypes.py、pywin32_system32/——但 pip install --target 不执行 .pth 文件,路径没挂上,于是 import 失败。

解决:用 venv 而不是 --target;或手工把 win32/lib 加进 PYTHONPATH。这一条我只在 --target 环境复现过,没有在正常 venv 里复现,所以不能写成「Windows 上装 claude 适配器必挂」——正常 venv 里 .pth 会生效。

一张可以抄的检查清单

# 1. 装之前先看解释器够不够(meta 声明 >=3.11,个别包要 3.13)
python -V

# 2. 装完把落地的 31 个包版本打出来,别信清单
python -m pip list --format=freeze | grep -i "^agent-framework" | sort

# 3. 逐包确认是不是预发布(21 个是)
python -c "from packaging.version import Version as V; print(V('1.0.0b261106').is_prerelease)"

# 4. requirements 里别写 >=1.0.0,写 >=1.0.0b1
grep -n "agent-framework" requirements.txt

# 5. 先探活再 import:19 个适配器里至少 claude 会在 Windows --target 下炸在 import 期
python -c "import agent_framework_openai, agent_framework_gemini, agent_framework_ollama"

本文的边界

👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务

👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速

📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测

🔗 精选推荐工具

使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):

作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。

☁️ DigitalOcean 云服务器 ⚡ Vultr 高性能 VPS 🤖 QoderWork 中国版(推荐有奖) ☁️ 阿里云爆款 AI 产品 📚 WordPress 实用书单 🧠 AI / 大模型书单 🏗️ 系统设计/云架构书单 🐳 Docker/K8s 书单 🐧 Linux 系统管理书单 🐍 Python 编程书单 🗄️ 数据库/PostgreSQL 书单 🚀 DevOps/SRE 书单 🤖 小米 MiMo 开放平台
← 返回首页