Problem: Installing full agent-framework on Python 3.14 hangs with resolution-too-deep (dependency graph too deep) —— Trove problem library

What you will run into

On Python 3.14, pip install agent-framework stalls in dependency resolution: the progress bar freezes, the CPU spins, and eventually you may see resolution-too-deep (Dependency resolution exceeded maximum depth) — or you wait long enough to blame the network. The real cause is a dependency graph too deep for the resolver to converge — a resolution-strategy problem, not a network one.

Why this happens

Conclusion first: the full meta package agent-framework pulls core[all] (fastapi/starlette and a web-dependency chain), and the graph depth exceeds the pip resolver limit; it is not missing wheels — the core dependency pydantic-core 2.46.5 does ship a cp314 wheel.

Chain: pip install agent-framework -> expand full meta dependencies -> resolver performs a deep search -> graph too deep to converge -> resolution-too-deep. The break: the resolver depth limit versus a huge dependency tree under the Python 3.14 combination.

Measured (2026-08-29, Python 3.14.4 venv + Tsinghua mirror,）: full resolution did not converge in ~20 minutes; in the same environment, the minimal core agent-framework-core==1.16.0 installed fine (31MB, 9 deps) and from agent_framework import Agent imports successfully.

Conclusion: for large meta packages, install the minimal core first, then add extras as needed; prefer officially supported combinations (Python 3.10-3.13) in production.

Step by step

1. Install the minimal core first — Required

pip install agent-framework-core (Tsinghua mirror); measured 31MB / 9 deps with normal install speed.

2. Verify the import — Required

python -c "from agent_framework import Agent; print(Agent)" printing the class object means success.

3. When you need the full set — By scenario

Prefer a Python 3.10-3.13 environment for the full meta package; on 3.14, add extension-backed dependencies one by one per the error, or use the core plus specific provider packages (openai/ollama and so on).

4. If it fails building instead — Diagnostic

If the error is a compile/build failure (not deep resolution), check build dependencies such as build-essential and a Rust toolchain.

How to confirm it works

• pip install agent-framework-core completes normally (no long stall);
• importing Agent succeeds;
• provider surfaces (e.g. agent_framework.openai) import as needed.

Other environments

• Python 3.10-3.13: officially supported; the full package installs as well (recommended);
• CI: install the core to run unit tests and put full installs in a separate job, so a 20-minute-class resolution does not stall the whole pipeline;
• Source material: measurements in this market (2026-08-28 baseline + 2026-08-29 Tsinghua-mirror venv install).

Symptom

On Python 3.14 the install errors out or stalls in the build phase; some packages (with Rust/C extensions) have no cp314 wheels and fall back to source builds.

Cause

Official support is Python 3.10-3.13; 3.14 is new, some dependencies lack prebuilt wheels (measured signal on 2026-08-28), and compilation is slow and may fail.

Solution

1. Use an officially supported environment: install in a Python 3.10-3.13 venv/conda (most reliable).
2. On 3.14: install the minimal agent-framework-core (without [all]) to verify the core first; handle extension-backed dependencies one by one per the errors.
3. On build failures, check missing build tools: build-essential, Rust toolchain (where applicable).