Python 3.14 装 agent-framework 全量卡死：resolution-too-deep（依赖图过深）

你会遇到什么

在 Python 3.14 环境装 agent-framework，pip 一路卡在依赖解析：进度条不动、CPU 空转，最后或报 resolution-too-deep（Dependency resolution exceeded maximum depth），或拖到怀疑网络。你以为是源慢/包大，实际上是 依赖图太深，解析器收敛不了——这是解析策略问题，不是网络问题。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

先给结论：全量 meta 包 agent-framework 会拉起 core[all]（fastapi/starlette 一串 Web 依赖），依赖图深度超过 pip 解析上限；不是轮子缺失——核心依赖 pydantic-core 2.46.5 实际有 cp314 轮子。

链路：pip install agent-framework → 展开 meta 包全量依赖 → 解析器做深度搜索 → 图过深未收敛 → resolution-too-deep。断点：解析策略的深度上限 vs 巨型依赖树——2.14 版依赖图在 Python 3.14 组合下触发。

实测（2026-08-29，Python 3.14.4 venv + 清华镜像，）：全量解析约 20 分钟未收敛；同一环境换装最小核心 agent-framework-core==1.16.0 → 31MB、9 依赖装成，from agent_framework import Agent 导入验证通过。

推论：装「大 meta 包」的通用路径 = 先装最小核心验证，再按需往上加 extras；生产环境优先官方支持组合（Python 3.10–3.13）。

一步步来

1. 先装最小核心 — 必做

pip install agent-framework-core（清华镜像）；实测 31MB、9 依赖，装成速度正常。

2. 导入验证 — 必做

python -c "from agent_framework import Agent; print(Agent)" 输出类对象即成功。

3. 需要全量/扩展时 — 按场景

优先在 Python 3.10–3.13 环境装全量 meta 包；3.14 用户按报错逐个补带扩展的依赖，或只用核心 + 具体 provider 包（openai/ollama 等）。

4. 构建类失败时 — 排查

若报的是编译/构建失败（而非解析超深），检查 build-essential、Rust 工具链等构建依赖。

怎么确认修好了

• pip install agent-framework-core 正常完成（无长卡）；
• 导入 Agent 成功；
• provider 面（如 agent_framework.openai）按需导入可用。

其它环境的表现

• Python 3.10–3.13：官方支持组合，全量包也可装（推荐）；
• CI：先装 core 跑单测，全量安装放独立 job，避免 20 分钟级解析卡整个流水线；

症状

Python 3.14 环境安装报错或长时间卡在构建阶段；部分包（如带 Rust/C 扩展的）无 cp314 轮子，进入源码编译。

原因

官方支持范围 Python 3.10-3.13；3.14 较新，部分依赖没有预编译轮子（2026-08-28 本环境实测信号），编译耗时且可能失败。

解法

1. 官方支持环境：用 Python 3.10-3.13 的 venv/conda 装（最稳）。
2. 3.14 用户：装 agent-framework-core 最小集（不加 [all]）先验证核心可用；带扩展依赖按报错逐个处理。
3. 编译失败时检查缺失构建工具：build-essential、Rust 工具链（如适用）。