Microsoft Agent Framework (evolution of AutoGen, MIT, ~13k stars) is a multi-Agent framework in Python library form: build, orchestrate and deploy AI agents and multi-agent workflows. Core abstractions = Agent + clients (Azure Foundry / OpenAI / Anthropic) + workflows (sequential/parallel/graph), supporting the A2A protocol and AG-UI interaction spec.

In one sentence: it is not a ready-made tool but a "Lego box for building Agents" — your code is the master; the framework provides orchestration, memory, skills and telemetry abstractions.

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.

note: meta + core paths verified here; must use the Tsinghua mirror on mainland networks (PyPI official direct times out)

# Source: Trove detailed guide · verified 2026-08-31
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

Two steps, no business code needed:

# Source: Trove detailed guide · verified 2026-08-31
python3 -c "import agent_framework; print('agent_framework OK', agent_framework.__file__)"

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

# Source: Trove detailed guide · verified 2026-08-31
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).

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).

Measured command = pip install of meta package agent-framework (verified in a venv in this environment 2026-08-28, Python 3.14, Tsinghua mirror; direct PyPI times out); the meta package depends on agent-framework-core (core library, import agent_framework comes from core), the full chain also has agent-framework-ext and other subpackages (officially supports Python 3.10-3.13; on this environment's 3.14 some deps lack prebuilt wheels, full install times out, so measured with core + core deps); library form has no CLI binary; a full run needs an LLM provider (Azure Foundry/OpenAI/Anthropic clients)

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.

# Source: Trove detailed guide · verified 2026-08-31
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):

# Source: Trove detailed guide · verified 2026-08-31
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple agent-framework-core==1.15.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.

# Source: Trove detailed guide · verified 2026-08-31
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.

# Source: Trove detailed guide · verified 2026-08-31
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.

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)

# Source: Trove detailed guide · verified 2026-08-31
python3 -c "from agent_framework import Agent; print('Agent class OK')"

Expected output: Agent class OK

Operation 2: View the top-level capability surface

# Source: Trove detailed guide · verified 2026-08-31
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)

# Source: Trove detailed guide · verified 2026-08-31
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.

Same source as the tool-page matrix — 19 pairs total (14 measured compatible / 5 inferred possibly compatible / 0 inferred possibly conflicting); full pairs, states and evidence: Conflict pairs (co-install matrix).

• No standalone handbook yet; for install/uninstall issues first see the agent-executable guide notes

# Source: Trove detailed guide · verified 2026-08-31
pip uninstall -y agent-framework agent-framework-core agent-framework-ext 2>/dev/null || true

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

# Source: Trove detailed guide · verified 2026-08-31
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

• Runtime preflight (needs Python >= 3.10; officially supports 3.10-3.13, the 3.14 core chain measured working here)
• Official pip path (meta + core measured here); China installs must use the Tsinghua mirror (direct PyPI times out)
• Meta package = the set of all subpackages; for core orchestration only, install agent-framework-core (deps: msgspec/opentelemetry-api/pydantic/python-dotenv/typing-extensions); full install on Python 3.14 hits some deps without prebuilt wheels (measured timeout), use 3.10-3.13 or the core-only path
• Each operation = one command block + expected output; running an Agent needs an LLM provider (Azure Foundry/OpenAI/Anthropic key)
• Library form: no CLI, no config directory, no background process; the write surface is entirely decided by your code (the most co-install-friendly form)

• 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.

• Version: [1.15.0, 1.15.0] locked (verified at collection).
• 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).

• Verified: local repro log (2026-08-28, meta+core install and import smoke).
• Not tested: minimal Agent example (no API key) — commands from the official README, marked accordingly.

Third-party tutorials are not individually verified; check against this page and official docs.

• 博客园：Microsoft Agent Framework 详解与实践——牧马人win [博客园 · 牧马人win（爬虫未提取署名，页面标题带作者） · 2026-03-04]
  Agent Framework 详解与实践——定义（微软多 Agent 框架，AutoGen 后继）、核心组件（Agent/GroupChat/Team/LLM 客户端/会话）、增强组件（记忆/工具/技能/观测）、安装与最小示例（pip 安装、import 验证、团队协作代码示例）