Microsoft Agent Framework（AutoGen 的演进，MIT，约 1.3 万星）是 Python 库形态的多 Agent 框架：构建、编排、部署 AI agents 与多 agent 工作流。核心抽象 = Agent + 客户端（Azure Foundry / OpenAI / Anthropic）+ 工作流（顺序/并行/图），支持 A2A 协议与 AG-UI 交互规范。

一句话：它不是现成工具，而是"造 Agent 的积木箱"——你的代码是主人，框架提供编排、记忆、技能、遥测抽象。

你要在自己的代码里构建多 Agent 系统：定义 Agent、配 LLM 客户端、让它们协作跑任务。这不是命令行工具，是 Python 库（微软出品）——装完没有 xxx 命令，只有 import agent_framework。所以最常见的坑是「装完不知道装没装对」：import 报错、pip 装超时（PyPI 官方直连国内实测超时）、Python 3.14 部分依赖没有预编译轮子。这篇指南把「装包 → 验证能力面 → 跑最小示例」走通，命令全部实测（最小示例需 provider，未实测已标注）。

什么时候用：

• 你要在自己的应用/脚本里内嵌多 Agent 编排；
• 你要用 Agent/AgentContext/BaseAgent/BaseChatClient 这些抽象做定制化流程；
• 你要接 Azure Foundry / OpenAI / Anthropic 任一客户端。

什么时候别用：你只是想要现成的 Agent 工具（装个 CLI 就能跑）——那是别的条目的活；库形态需要你写代码。

note: 本环境实测 meta + core 路径；国内必须带清华镜像（PyPI 官方直连超时）

# 来源: Trove 详细指南 · 验证于 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__)"

预期输出: agent_framework OK .../site-packages/agent_framework/__init__.py

两步，不用写业务代码：

# 来源: Trove 详细指南 · 验证于 2026-08-31
python3 -c "import agent_framework; print('agent_framework OK', agent_framework.__file__)"

预期输出: agent_framework OK .../site-packages/agent_framework/__init__.py

# 来源: Trove 详细指南 · 验证于 2026-08-31
python3 -c "from agent_framework import Agent; print('Agent class OK')"

预期输出: Agent class OK

• import 成功 + 打印出 site-packages 路径 = 装对位置（venv 场景确认激活的是同一个环境）；
• dir(agent_framework) 能看到 Agent/AgentContext 等抽象 = 完整形态；
• 最小示例能跑通并输出模型回复 = provider 链路通（需配环境变量）。

pip 安装后 import agent_framework 使用。meta 包 = 全子包集合（agent-framework-core + 扩展）；只跑核心编排可装 agent-framework-core（依赖 msgspec / opentelemetry-api / pydantic / python-dotenv / typing-extensions）——依赖更少、装得更快。运行 Agent 需要 LLM provider（Azure Foundry / OpenAI / Anthropic 密钥或本地 provider）。

关键概念：

• Agent：任务执行单元（可配 client/name/instructions）；
• Client：LLM 接入客户端（AzureChatClient 等）；
• core 链路：只装核心子包的轻量路径。

装完它动哪里：不动配置目录、不起后台进程；数据由你的代码写（库形态，写面为空）。

实测命令 = pip 安装 meta 包 agent-framework（2026-08-28 本环境 venv 验证，Python 3.14，清华镜像；PyPI 官方直连超时）；meta 包依赖 agent-framework-core（核心库，import agent_framework 即来自 core），完整链路还有 agent-framework-ext 等子包（官方支持 Python 3.10-3.13；本环境 3.14 部分依赖无预编译轮子，全量安装超时，故以 core + 核心依赖实测）；库形态无 CLI 二进制；完整跑通需 LLM provider（Azure Foundry/OpenAI/Anthropic 客户端）

第 1 步：装包

讲解：agent-framework 是 meta 包，pip 装一个就带齐全子包集合；如果只需要核心编排，装 agent-framework-core 更轻。国内 PyPI 官方直连实测超时，必须带清华镜像参数。Python 3.14 全量安装时部分依赖没有预编译轮子（实测超时），建议用 3.10~3.13，或走 core 精简路径。

# 来源: Trove 详细指南 · 验证于 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__)"

预期输出: agent_framework OK .../site-packages/agent_framework/__init__.py

core 精简路径（只跑核心编排）：

# 来源: Trove 详细指南 · 验证于 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')"

预期输出: Agent class OK

装好确认：

• import 成功且打印出 site-packages 路径；
• from agent_framework import Agent 不报错。

卡住怎么办：

• pip 超时 → 确认命令带 -i https://pypi.tuna.tsinghua.edu.cn/simple；
• Python 3.14 装不上部分依赖 → 用 3.10~3.13，或只装 core 精简路径；
• import 失败 → 确认 pip 与 python3 同环境（venv 场景先激活）。

第 2 步：验证顶层能力面

讲解：dir(agent_framework) 能看到库的顶层抽象——Agent / AgentContext / BaseAgent / BaseChatClient 等编排抽象。这一步确认你装的是完整形态而不是某个残缺包。

# 来源: Trove 详细指南 · 验证于 2026-08-31
python3 -c "import agent_framework; print([a for a in dir(agent_framework) if not a.startswith('_')][:20])"

预期输出: Agent/AgentContext/BaseAgent/BaseChatClient 等编排抽象

装好确认：

• 输出包含 Agent、AgentContext 等编排抽象。

卡住怎么办：

• 输出为空/只有下划线方法 → 安装不完整，重装 meta 包。

第 3 步：跑最小 Agent 示例（需先配 provider）

讲解：最小示例 = 创建 Agent + 配 LLM 客户端 + run。需要 FOUNDRY_PROJECT_ENDPOINT / FOUNDRY_MODEL_DEPLOYMENT_NAME（Azure 路径）或等价环境变量；本地 provider 不需要云 API key。命令来自官方 README，本环境未实测（无 API key）。

# 来源: Trove 详细指南 · 验证于 2026-08-31
python3 - <<'PY'
import asyncio
from agent_framework import Agent
from agent_framework.azure import AzureChatClient  # 或 OpenAI/Anthropic 客户端
# 需要 FOUNDRY_PROJECT_ENDPOINT / FOUNDRY_MODEL_DEPLOYMENT_NAME 或等价环境变量
async def main:
    agent = Agent(client=AzureChatClient, name="Demo", instructions="You are helpful.")
    print(await agent.run("hi"))
asyncio.run(main)
PY

预期输出: 模型回复（依赖 provider 配置）

装好确认：

• 输出模型回复，无 provider 报错。

卡住怎么办：

• 报 provider 配置错误 → 先确认环境变量/密钥就位；换本地 provider 免云 key。

启动与入口

库形态没有「启动」；入口就是 import agent_framework。常用抽象：Agent / AgentContext / BaseAgent / BaseChatClient。

常用操作

操作一：验证库可导入（本环境实测）

# 来源: Trove 详细指南 · 验证于 2026-08-31
python3 -c "from agent_framework import Agent; print('Agent class OK')"

预期输出: Agent class OK

操作二：查看库顶层能力面

# 来源: Trove 详细指南 · 验证于 2026-08-31
python3 -c "import agent_framework; print([a for a in dir(agent_framework) if not a.startswith('_')][:20])"

预期输出: Agent/AgentContext/BaseAgent/BaseChatClient 等编排抽象

操作三：最小 Agent 示例（需先配 provider；命令来自官方 README，本环境未实测——无 API key）

# 来源: Trove 详细指南 · 验证于 2026-08-31
python3 - <<'PY'
import asyncio
from agent_framework import Agent
from agent_framework.azure import AzureChatClient  # 或 OpenAI/Anthropic 客户端
# 需要 FOUNDRY_PROJECT_ENDPOINT / FOUNDRY_MODEL_DEPLOYMENT_NAME 或等价环境变量
async def main:
    agent = Agent(client=AzureChatClient, name="Demo", instructions="You are helpful.")
    print(await agent.run("hi"))
asyncio.run(main)
PY

预期输出: 模型回复（依赖 provider 配置）

数据与目录

• 库形态无专属数据目录；配置由你的代码/环境变量决定。

与工具页矩阵同源，共 19 对（14 实测兼容 / 5 推断可能兼容 / 0 推断可能冲突）；完整对子、状态与证据见 冲突对子（共装矩阵）。

• 暂无独立排障手册；安装/卸载问题先看 Agent 执行版 guide 注意事项

# 来源: Trove 详细指南 · 验证于 2026-08-31
pip uninstall -y agent-framework agent-framework-core agent-framework-ext 2>/dev/null || true

note: pip 包自动卸载（幂等）；库形态无配置目录/后台进程；项目代码里的 agent_framework 引用按需手动移除

# 来源: Trove 详细指南 · 验证于 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')"

预期输出: agent-framework removed: OK

• 运行环境预检（需 Python >= 3.10；官方支持 3.10-3.13，本环境实测 3.14 core 链路可用）
• 官方 pip 路径（本环境实测 meta + core）；国内必须带清华镜像（PyPI 官方直连超时）
• meta 包 = 全子包集合；只跑核心编排可装 agent-framework-core（依赖 msgspec/opentelemetry-api/pydantic/python-dotenv/typing-extensions）；Python 3.14 全量安装部分依赖无预编译轮子（实测超时），建议 3.10-3.13 或按 core 精简路径
• 每条操作 = 一个命令块 + 预期输出；运行 Agent 需要 LLM provider（Azure Foundry/OpenAI/Anthropic 密钥）
• 库形态：无 CLI、无配置目录、无后台进程；写面完全由你的代码决定（组合兼容性最好的形态）

• 问：meta 包和 core 包什么区别？答：meta = 全子包集合；core = 只核心编排（依赖更少）。只跑核心流程装 core 更轻。
• 问：Python 3.14 装不上？答：部分依赖无预编译轮子（实测超时）；用 3.10~3.13，或走 core 精简路径。
• 问：跑示例报 provider 错误？答：需要 FOUNDRY_PROJECT_ENDPOINT / FOUNDRY_MODEL_DEPLOYMENT_NAME 或等价环境变量；本地 provider 不需要云 API key。
• 问：和谁不能一起装？答：冲突矩阵 9 个对子全部 possible-compatible（库形态无写面，推断无冲突）；实测共装见组合包 combo-env-init。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。

• 版本：[1.15.0, 1.15.0] 锁定（收录实测版本）。
• 环境：Python >= 3.10；官方支持 3.10-3.13，本环境实测 3.14 core 链路可用；3.14 全量安装部分依赖无预编译轮子（实测超时）。
• 网络：PyPI 官方直连超时，必须清华镜像。
• 写面：无（库形态，由用户代码决定）。
• 共装：与 oh-my-claudecode / agent-governance-toolkit / deepcode / ruflo / superpowers / claude-code-router / code-review-graph / logfire / moltis 全部判定 possible-compatible（无写面重叠推断）。

• 条目签名：microsoft/agent-framework（MIT，原样收录 Python 包 v1.15.0）

• 实测：实测记录（本地留存）（2026-08-28，meta+core 安装与 import 冒烟）。
• 未实测：最小 Agent 示例（无 API key）——命令来自官方 README，如实标注。

第三方教学未逐条实测，仅供学习；有出入以本页与官方文档为准。

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