Agent Framework 31 个子包:稳定线与 beta 线怎么装
先说测试环境: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-framework | 1.25.0 |
| agent-framework-core | 1.25.0 |
| agent-framework-openai | 1.18.1 |
| agent-framework-foundry | 1.16.1 |
| agent-framework-ag-ui | 1.8.0 |
| agent-framework-declarative | 1.5.0 |
| agent-framework-orchestrations | 1.4.2 |
| agent-framework-github-copilot | 2.1.2 |
| agent-framework-azurefunctions | 1.0.0 |
| agent-framework-durabletask | 1.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.0 | 84 | 83,744 | 3.5 MB |
| agent-framework-openai | 1.18.1 | 7 | 8,065 | 380 KB |
| agent-framework-ag-ui | 1.8.0 | 27 | 17,166 | 740 KB |
| agent-framework-github-copilot | 2.1.2 | 3 | 1,967 | 82.6 KB |
| agent-framework-mem0 | 1.0.0b261106 | 3 | 344 | 14.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.0 | 3 | chatkit、mem0、azure-contentunderstanding |
| >=1.18.0 | 1 | azure-ai-search |
| >=1.19.0 | 6 | durabletask、hyperlight、monty、redis、tools、azurefunctions |
| >=1.21.0 | 1 | purview |
| >=1.22.0 | 4 | a2a、claude、copilotstudio、github-copilot |
| >=1.23.0 | 2 | devui、orchestrations |
| >=1.24.0 | 8 | anthropic、bedrock、azure-cosmos、foundry、foundry-local、gemini、mistral、ollama |
| >=1.25.0 | 4 | ag-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.10 | 2026-09-25 |
| 1.0.0b261029 | >=3.13 | 2026-10-30 |
| 1.0.0 | >=3.13 | 2026-11-09 |
一次抬升跨了 3 个 minor。于是同一个包名、同一条命令:
pip install --dry-run --no-deps agent-framework-azurefunctions
- 在 Python 3.11.3(pip 24.3.1)上:
Would install agent-framework-azurefunctions-1.0.0b260922 - 在 Python 3.13.12(pip 26.1.2)上:
Would install agent-framework-azurefunctions-1.0.0
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 元数据):
agent-framework-foundry-local:python_version >= '3.11' and python_version < '3.15'再加 darwin arm64 / linux x86_64、aarch64 / win32 AMD64、ARM64、x86_64、aarch64agent-framework-hyperlight:只给linux x86_64或win32 AMD64
用 packaging 26.3 对四组环境求值:
| 环境 | foundry-local | hyperlight |
|---|---|---|
| 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"
本文的边界
- 版本与依赖关系是 2026-11-10 抓取的状态,两天内已经变过一次(8+23 → 10+21),照抄清单会过期。
pywintypes那条只在--target环境复现,正常 venv 未复现,正文已标注。- 本机没有 LLM 凭据,所有 provider 只做到 import 冒烟,没有任何一次真实模型调用,所以本文不谈延迟、吞吐与效果。
- 与 11 月 8 日那篇的分工:那篇答「workflow 的 executor 和 edge 怎么接、文档与实现差在哪」(Microsoft Agent Framework 工作流:六个不报错的失效),本篇只答「31 个包装哪个、装完为什么 import 不到」。依赖供应链侧的扫描另有一篇(pip-audit 实测),那篇看的是「已装的东西有没有已知漏洞」,本篇看的是「该装哪个版本」。
👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务
👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速
📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测
🔗 精选推荐工具
使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):
作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。