agent-framework

What you will run into

You want to build a multi-agent system in your own code: define agents, configure LLM clients, let them collaborate on tasks. This is not a CLI tool, it is a Python library (from Microsoft) — after install there is no xxx command, only import agent_framework. So the most common pitfall is "installed but not sure it is installed right": import errors, pip timeouts (PyPI official direct times out on mainland networks, verified), and Python 3.14 lacking prebuilt wheels for some dependencies. This guide walks through "install package → verify capability surface → run a minimal example"; all commands verified (the minimal example needs a provider, marked not tested). When to use it:

• Embedding multi-agent orchestration in your own app/scripts;
• Using abstractions like Agent/AgentContext/BaseAgent/BaseChatClient for custom flows;
• Connecting any of Azure Foundry / OpenAI / Anthropic clients.

When not to use it: you just want a ready-made agent tool (install a CLI and run) — that is another entry's job; library form requires you to write code.

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

Installed via pip, used via import agent_framework. The meta package = the full collection of subpackages (agent-framework-core + extensions); for core orchestration only you can install agent-framework-core (deps: msgspec / opentelemetry-api / pydantic / python-dotenv / typing-extensions) — fewer dependencies, faster install. Running agents needs an LLM provider (Azure Foundry / OpenAI / Anthropic keys or a local provider). Key concepts:

• Agent: task execution unit (configurable client/name/instructions);
• Client: LLM client (AzureChatClient etc.);
• core path: the lightweight path installing only core subpackages.

Where it writes: no config directory, no background process; data is written by your code (library form, empty write surface).

Step by step

Step 1: Install the package

Why: agent-framework is the meta package; one pip install brings the full subpackage collection. If you only need core orchestration, install agent-framework-core for a lighter footprint. PyPI official direct times out on mainland networks (verified), so the Tsinghua mirror flag is required. On Python 3.14 some dependencies have no prebuilt wheels for a full install (verified timeout); use 3.10~3.13, or take the core path.

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple agent-framework
python3 -c "import agent_framework; print('agent_framework OK', agent_framework.__file__)"

Expected output: agent_framework OK .../site-packages/agent_framework/__init__.py Core path (core orchestration only):

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple agent-framework-core==1.16.0
python3 -c "from agent_framework import Agent; print('Agent class OK')"

Expected output: Agent class OK After install, confirm:

• import succeeds and prints the site-packages path;
• from agent_framework import Agent has no error.

Stuck? How to recover:

• pip timeout → make sure the command has -i https://pypi.tuna.tsinghua.edu.cn/simple;
• Python 3.14 can't install some deps → use 3.10~3.13, or install only the core path;
• import fails → confirm pip and python3 share the same environment (activate the venv first).

Step 2: Verify the top-level capability surface

Why: dir(agent_framework) reveals the library's top-level abstractions — Agent / AgentContext / BaseAgent / BaseChatClient etc. This confirms you installed the complete form, not a broken partial package.

python3 -c "import agent_framework; print([a for a in dir(agent_framework) if not a.startswith('_')][:20])"

Expected output: orchestration abstractions like Agent/AgentContext/BaseAgent/BaseChatClient After install, confirm:

• output includes Agent, AgentContext and other orchestration abstractions.

Stuck? How to recover:

• empty output / only underscore methods → incomplete install; reinstall the meta package.

Step 3: Run a minimal Agent example (configure a provider first)

Why: the minimal example = create an Agent + configure an LLM client + run. Needs FOUNDRY_PROJECT_ENDPOINT / FOUNDRY_MODEL_DEPLOYMENT_NAME (Azure path) or equivalent env vars; a local provider needs no cloud API key. Commands from the official README; not verified in this environment (no API key), marked accordingly.

python3 - <<'PY'
import asyncio
from agent_framework import Agent
from agent_framework.azure import AzureChatClient  # or OpenAI/Anthropic client
# needs FOUNDRY_PROJECT_ENDPOINT / FOUNDRY_MODEL_DEPLOYMENT_NAME or equivalent env vars
async def main:
agent = Agent(client=AzureChatClient, name="Demo", instructions="You are helpful.")
print(await agent.run("hi"))
asyncio.run(main)
PY

Expected output: model reply (depends on provider config) After install, confirm:

• output is a model reply with no provider error.

Stuck? How to recover:

• provider config error → check env vars/keys first; switch to a local provider to avoid cloud keys.

How to confirm it works

Two steps, no business code needed:

python3 -c "import agent_framework; print('agent_framework OK', agent_framework.__file__)"

Expected output: agent_framework OK .../site-packages/agent_framework/__init__.py

python3 -c "from agent_framework import Agent; print('Agent class OK')"

Expected output: Agent class OK

• import succeeds and prints the site-packages path = installed in the right place (in venv scenarios, confirm you are activating the same environment);
• dir(agent_framework) shows Agent/AgentContext abstractions = complete form;
• the minimal example runs and outputs a model reply = provider path works (needs env vars).

Other environments

• Python 3.14: some deps lack prebuilt wheels for a full install (verified timeout) → use 3.10~3.13, or take the core path (the 3.14 core path was verified usable here).
• venv environments: pip and python3 must be the same environment; verify with which python3 after install.
• Core orchestration only: install agent-framework-core==1.16.0 (fewer deps).
• Local provider: no cloud API key needed; point at a local endpoint to run examples.
• Co-install with other tools: all 9 conflict-matrix pairs judged possible-compatible (library form has no write surface, inferred no conflict).

Daily usage

Startup and entry

Library form has no "startup"; the entry point is import agent_framework. Common abstractions: Agent / AgentContext / BaseAgent / BaseChatClient.

Common operations

Operation 1: Verify the library imports (verified here)

python3 -c "from agent_framework import Agent; print('Agent class OK')"

Expected output: Agent class OK Operation 2: View the top-level capability surface

python3 -c "import agent_framework; print([a for a in dir(agent_framework) if not a.startswith('_')][:20])"

Expected output: orchestration abstractions like Agent/AgentContext/BaseAgent/BaseChatClient Operation 3: Minimal Agent example (configure a provider first; commands from the official README, not verified here — no API key)

python3 - <<'PY'
import asyncio
from agent_framework import Agent
from agent_framework.azure import AzureChatClient  # or OpenAI/Anthropic client
# needs FOUNDRY_PROJECT_ENDPOINT / FOUNDRY_MODEL_DEPLOYMENT_NAME or equivalent env vars
async def main:
agent = Agent(client=AzureChatClient, name="Demo", instructions="You are helpful.")
print(await agent.run("hi"))
asyncio.run(main)
PY

Expected output: model reply (depends on provider config)

Data and directories

• Library form has no dedicated data directory; config is decided by your code/env vars.

Uninstall & cleanup

note: pip packages uninstall automatically (idempotent); library form has no config dir/background process; remove agent_framework references in project code manually as needed

pip uninstall -y agent-framework agent-framework-core agent-framework-ext 2>/dev/null || true
python3 -c "import importlib.util; print('残留: agent_framework 仍存在' if importlib.util.find_spec('agent_framework') else 'agent-framework removed: OK')"

Expected output: agent-framework removed: OK

Dependency warnings

• Version: [1.16.0, 1.16.0] locked (upgrade retested 2026-08-31: core 1.16.0 with deps + meta --no-deps both verified, evidence）; full meta install with deps still times out on Python 3.14 (official support 3.10~3.13), noted honestly.
• Environment: Python >= 3.10; officially supported 3.10-3.13, the 3.14 core path verified usable here; 3.14 full install lacks prebuilt wheels for some deps (verified timeout).
• Network: PyPI official direct times out, must use the Tsinghua mirror.
• Write surface: none (library form, decided by user code).
• Co-install: with oh-my-claudecode / agent-governance-toolkit / deepcode / ruflo / superpowers / claude-code-router / code-review-graph / logfire / moltis all judged possible-compatible (no write-surface overlap, inferred).

FAQ

• Q: Difference between meta and core packages? A: meta = full subpackage collection; core = core orchestration only (fewer deps). Install core for a lighter footprint if you only run core flows.
• Q: Won't install on Python 3.14? A: some deps lack prebuilt wheels (verified timeout); use 3.10~3.13, or take the core path.
• Q: Provider error when running examples? A: needs FOUNDRY_PROJECT_ENDPOINT / FOUNDRY_MODEL_DEPLOYMENT_NAME or equivalent env vars; a local provider needs no cloud API key.
• Q: What cannot be installed alongside? A: all 9 conflict-matrix pairs judged possible-compatible (library form has no write surface, inferred no conflict); verified co-install in combo combo-env-init.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel; project issues go to the author's repository.