← Back to Home

Reading the Agent Framework 31-package matrix

PythonDependency ManagementAgent Framework

This article is not about wiring. It is about the question that install left open: out of those 31 packages, which ones are safe to put in a production requirements file, how do you read the version numbers, and what do you actually see when you pick wrong.

Test environment, stated up front: Windows 11, CPython 3.13.12 (with 3.11.3 as a control), pip 26.1.2 and 24.3.1, installed via pip install --target tmp/w46-af agent-framework. Versions and dependency metadata come from each package's *.dist-info/METADATA; release dates and requires_python were cross-checked against the PyPI JSON API, fetched 2026-11-10. This article contains no affiliate links.

31 packages, 10 stable, 21 pre-release

As of the 2026-11-10 snapshot, PyPI carries 31 distributions whose name starts with agent-framework. Ten have a version string with no a, b, or rc marker; the other 21 carry a b:

Stable line (10)Version
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

The remaining 21 all sit on 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.

The snapshot I installed two days ago is already stale

On 8 November my local install showed 8 stable and 23 pre-release. Checking each package against PyPI today gives 10 and 21. The two that moved are agent-framework-azurefunctions and agent-framework-durabletask, both of which published 1.0.0 on 2026-11-09 at 17:13 UTC (17:13:00 and 17:13:02). The graduation happened inside a window shorter than a day.

The lesson is blunt: "which package is still beta" is not knowledge you can store, it is state you have to recompute. You do not need docs for it, you need one API call per package:

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

Version numbers do not compare across packages

The table above shows seven distinct version numbers across ten stable packages (1.25.0 twice, then 1.18.1, 1.16.1, 1.8.0, 1.5.0, 1.4.2, 2.1.2, and 1.0.0 twice). Sorted numerically, the largest is agent-framework-github-copilot 2.1.2.

I counted .py files and lines in every package (skipping __pycache__):

PackageVersion.py filesLinesSize
agent-framework-core (module 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 is 1,967 lines. 1.25.0 is 83,744. That is a 42.6x difference. The package with the larger major number carries 2.3% of the code.

The reason is that each package keeps its own release line, so the version only counts how many times that particular package shipped. Core went from 1.0.0b251001 (the first beta, October 2025) to 1.0.0 on 2026-04-02 and to 1.25.0 on 2026-11-07, across 66 releases. github-copilot did not reach 1.0.0 until 2026-07-23, then reached 2.1.2 in about two months. Comparing 2.1.2 with 1.25.0 is comparing two different rulers.

What a beta version looks like, and why `>=1.0.0` finds nothing

Those 21 pre-release packages are named like 1.0.0b261106. The six digits look like a date (26-11-06), but under PEP 440 it is just "beta number 261106 of 1.0.0" with no date semantics at all. It sorts by number, so 1.0.0b261106 < 1.0.0.

That has a concrete consequence. On 3.13.12 with pip 26.1.2:

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

Exit code 1, two lines:

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

Swap in >=1.0.0b1 and it resolves (exit code 0). So writing a >=1.0.0 floor for these 21 packages eliminates the entire candidate set, and pip never tells you it saw 26 candidates that all happen to end in b.

The ordering rules and ~= digit behaviour were verified separately in an earlier piece (PEP 440 constraints: ~= digits, == zero padding, and a false pip claim). This article is about what that rule does to a real dependency tree.

The only exact pin in the tree

Exactly one of the 31 packages uses ==, and it is the meta package. Its 1.25.0 Requires-Dist is a single line:

agent-framework-core[all]==1.25.0

The other 30 use ranges, almost always agent-framework-core>=X,<2. The one exception is agent-framework-github-copilot with >=2.1.2,<3, because it already lives on a 2.x line.

That single == matters more than it looks: the ceiling on core is set by the meta package. If your requirements file says agent-framework==1.25.0, then any sub-package that later wants agent-framework-core>=1.26 becomes unresolvable, and the failure surfaces on the sub-package, not on the pin. You will spend the first ten minutes debugging the provider adapter instead of the pin.

Right now four packages sit exactly on >=1.25.0 (ag-ui, declarative, foundry-hosting, openai), so they are in the same boat as the meta pin and everything resolves. The boat starts leaking the moment one of those four wants 1.26.

Thirty packages, eight different core floors

Flatten the core requirements of the 30 sub-packages and you get a distribution worth looking at:

Core floorPackagesExamples
>=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

The three loosest (chatkit, mem0, azure-contentunderstanding) claim to work on a core 12 minor versions old. But the real compatibility floor is the strictest one, not the loosest: once you install the openai adapter (>=1.25.0), chatkit's >=1.13.0 is decoration, because both have to share one core.

So "does this provider support my core version" cannot be answered from that provider's own METADATA. It is max() over everything installed. In practice the cheaper rule is to follow core: bump core, bump every sub-package with it.

One command, two different versions on 3.11 and 3.13

This is the finding worth keeping. agent-framework-azurefunctions moved its requires_python at the end of October:

Versionrequires_pythonUploaded
1.0.0b260922>=3.102026-09-25
1.0.0b261029>=3.132026-10-30
1.0.0>=3.132026-11-09

One jump, three minor versions. Now the same package name and the same command:

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

On 3.11 you get the 2026-09-25 beta, 45 days and a full graduation milestone behind, with no warning. It holds at the meta level too: on 3.11, pip install --dry-run agent-framework exits 0 and resolves 173 packages, still 31 of them agent-framework*, but azurefunctions pinned at 1.0.0b260922 while durabletask lands on 1.0.0. Not one line of output mentions it.

Meanwhile the meta and core metadata both declare requires_python >=3.11. Neither number is wrong; they describe different things. >=3.11 is "we tested on this interpreter"; requires_python is "should the resolver hand you this file at all". The second one silently deletes candidates.

The only defence is boring: print what actually landed.

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

`[all]` is not all, on every platform

The meta package pulls everything in through agent-framework-core[all], which reads like a one-command bundle. But two of the extras carry platform markers. From core's metadata, verbatim:

Evaluating those markers with packaging 26.3:

Environmentfoundry-localhyperlight
win32 AMD64, py3.13yesyes
win32 ARM64, py3.13yesno
darwin arm64, py3.13yesno
win32 AMD64, py3.10noyes

So "I installed [all], therefore I have every provider" is false on Windows on ARM and on Apple Silicon (both miss hyperlight), and false on Python 3.10 (misses foundry-local). This is not an oversight in the markers, it is what they say; the one-line pip install agent-framework in the docs just does not show you the difference.

For scale: that install on this machine is 208 dist-info folders, 1,046 MB. If all you need is one OpenAI client, agent-framework-core plus agent-framework-openai is enough and skips the other 1 GB.

Import paths: docs use nesting, the wheel is flat, and the top level can be empty

The Python sample on the official overview page reads:

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient

That is the nested path agent_framework.foundry, while the package on PyPI is agent-framework-foundry. Both import fine, but they are not the same module object:

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

Different module objects, same class objects. So isinstance checks are not fooled by the path you chose (good), but sys.modules ends up holding two keys for one library (visible when you profile import time or chase oddities in hot reload).

agent-framework-tools is stranger. Its top-level __init__.py has exactly one entry in __all__:

__all__ = ["__version__"]

The actual API lives in the agent_framework_tools/shell/ subpackage (15 .py files, 2,830 lines, exporting LocalShellTool, DockerShellTool, ShellPolicy, and more). And the nested path agent_framework.tools does expose LocalShellTool directly. The flat package name is the empty shell; the nested path is the full one, which is the opposite of what the naming suggests.

One more pair worth separating: agent_framework_anthropic and agent_framework_claude share version 1.0.0b261106 and share almost nothing else. The first is a Messages API client with Bedrock, Vertex, and Foundry variants; the second wraps claude_agent_sdk and exports ClaudeAgent. One word apart, and installing the wrong one buys you nothing.

Troubleshooting: three real errors

Error 1: `Could not find a version that satisfies the requirement agent-framework-gemini>=1.0.0`

Verbatim, pip 26.1.2, exit code 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

Cause: the package only has alpha and beta releases, and >=1.0.0 does not match a pre-release under PEP 440. Fix: write >=1.0.0b1, or pass --pre.

Error 2: `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)

Cause: the top-level __init__.py exports __version__ and nothing else; the API is in the shell subpackage. Fix: from agent_framework_tools.shell import LocalShellTool, or use the nested path from agent_framework.tools import LocalShellTool.

Error 3: `ModuleNotFoundError: No module named 'pywintypes'` on Windows with `--target`

import agent_framework_claude fails at import time. The chain runs all the way into MCP's Windows branch:

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'

Cause: pywintypes is not a plain module. pywin32 relies on a pywin32.pth file written at install time to put win32/lib on sys.path. In my isolated directory all three pieces exist (the .pth, win32/lib/pywintypes.py, and pywin32_system32/), but pip install --target does not process .pth files, so the path never gets added and the import fails.

Fix: use a venv instead of --target, or add win32/lib to PYTHONPATH yourself. I only reproduced this in a --target install and did not reproduce it in a normal venv, so the honest claim is "this bites --target installs", not "the Claude adapter is broken on Windows".

A checklist you can copy

# 1. Check the interpreter before installing (meta says >=3.11, one package wants 3.13)
python -V

# 2. After installing, print what actually landed instead of trusting a list
python -m pip list --format=freeze | grep -i "^agent-framework" | sort

# 3. Confirm pre-release status package by package (21 of them are)
python -c "from packaging.version import Version as V; print(V('1.0.0b261106').is_prerelease)"

# 4. Never write >=1.0.0 for these; write >=1.0.0b1
grep -n "agent-framework" requirements.txt

# 5. Smoke-test imports, because at least claude dies at import time under --target on Windows
python -c "import agent_framework_openai, agent_framework_gemini, agent_framework_ollama"

Where this stops

👉 Join Xiaomi MiMo Platform: Leading AI model platform with cost-effective inference

👉 Join Aliyun AI: Top AI products with exclusive coupons for business innovation

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews

🔗 Recommended Tools

These are carefully selected tools. Using our affiliate links supports us to keep producing quality content:

As an Amazon Associate, I earn from qualifying purchases at no extra cost to you.

☁️ DigitalOcean Cloud ⚡ Vultr VPS 🤖 QoderWork CN (Refer & Earn) ☁️ Aliyun AI Products 📚 WordPress Books 🧠 AI & LLM Books 🏗️ System Design Books 🐳 Docker & K8s Books 🐧 Linux Admin Books 🐍 Python Books 🗄️ Database Books 🚀 DevOps & SRE Books 🤖 Xiaomi MiMo Platform
← Back to Home