你会遇到什么

你要在自己的代码里构建多 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 就能跑）——那是别的条目的活；库形态需要你写代码。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

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 链路：只装核心子包的轻量路径。

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

一步步来

第 1 步：装包

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

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 精简路径（只跑核心编排）：

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')"

预期输出: 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 等编排抽象。这一步确认你装的是完整形态而不是某个残缺包。

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）。

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。

怎么确认修好了

两步，不用写业务代码：

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

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

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

预期输出: Agent class OK

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

其它环境的表现（常见变体）

• Python 3.14：全量安装部分依赖无预编译轮子（实测超时）→ 用 3.10~3.13，或走 core 精简路径（本环境实测 3.14 core 链路可用）。
• venv 环境：pip 与 python3 必须同一环境；装完用 which python3 确认。
• 只跑核心编排：装 agent-framework-core==1.16.0（依赖更少）。
• 本地 provider：不需要云 API key，配本地端点即可跑示例。
• 与其它工具共装：冲突矩阵 9 个对子全部 possible-compatible（库形态无写面，推断无冲突）。

日常使用

启动与入口

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

常用操作

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

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

预期输出: Agent class OK

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

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）

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 配置）

数据与目录

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

卸载与清理

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

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

依赖警告

• 版本：[1.16.0, 1.16.0] 锁定（2026-08-31 升级重测：core 1.16.0 带依赖 + meta --no-deps 实测通过，证据）；全量带依赖在 Python 3.14 仍超时（官方支持 3.10~3.13），如实标注。
• 环境：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（无写面重叠推断）。

FAQ（常见问题）

• 问：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。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。