简体中文 · English
Microsoft Agent Framework 1.0 GA（2026-04-03 发布）所有核心能力的可运行、有诊断注释、附测试结果的参考实现。后端用 DeepSeek V4-Flash（OpenAI 兼容端点，便宜）。
适合：第一次接触 MAF 想知道"它能干啥" / 已经用 MAF 想看"业界踩过哪些坑" / 给团队做技术选型对照。
# 1) 安装依赖（要精确复现 README 结果用 requirements.lock）
pip install -r requirements.txt
# 2) 配 key
cp .env.example .env
# 编辑 .env 填 DEEPSEEK_API_KEY，可选 GEMINI_API_KEY
# 3) 跑单个 pattern 看效果（三种写法等价）
python3 -m patterns sequential # 推荐：统一入口
python3 -m patterns.sequential # 等价：直接跑模块
python3 -m patterns --list # 列出全部 pattern
# 4) 跑全部 16 个（约 5 分钟，结果归档到 runs/<日期>/）
python3 scripts/run_all.py # 跨平台
# 或 ./scripts/run_all.sh # 仅 *nix 薄 wrapper
# 5) 跑测试
python3 -m pytest tests/test_smoke.py -v # 不调 LLM（CI 跑这一组）
python3 -m pytest -v -m live # 调真实 LLM| # | Pattern | 类别 | 一句话 |
|---|---|---|---|
| 1 | sequential | 编排 | A → B → C 顺序流水线 |
| 2 | concurrent | 编排 | N agent 并行 + 自动 aggregator |
| 3 | handoff | 编排 | triage 显式交棒到 specialist |
| 4 | group_chat | 编排 | 多 agent 多轮共享 transcript |
| 5 | magentic ⭐ | 编排 | manager 动态规划（MAF 独家） |
| 6 | skills | 能力 | Anthropic SKILL.md 标准（32 产品采纳） |
| 7 | tools_and_mcp | 能力 | 自定义工具 + 远程 MCP server 混挂 |
| 8 | agent_as_mcp_server | 能力 | 把 agent 反向暴露为 MCP 工具 |
| 9 | a2a | 能力 | A2A 协议跨框架 agent 互操作 |
| 10 | checkpointing | 生产 | 长任务断点续跑 |
| 11 | hitl ⭐ | 生产 | 人在回路审批（含核心修复） |
| 12 | middleware | 生产 | 3 层拦截器（Agent/Chat/Function） |
| 13 | otel | 生产 | OpenTelemetry GenAI Semantic Conventions |
| 14 | memory | 生产 | 跨 session 持久化用户偏好 |
| 15 | declarative | 工程 | YAML 配置驱动 workflow |
| 16 | multi_provider | 工程 | DeepSeek + Gemini 混编 |
详细对照表 + 选型决策树 + 完整代码 → docs/PATTERNS.md
Microsoft-Agent-Framework/
├── README.md # 本文件
├── pyproject.toml + requirements.txt
├── .env.example # 复制为 .env 后填 key
├── common.py # 共享：client 工厂 / specialists / trace 打印器
│
├── patterns/ # ⭐ 16 个 pattern，每个独立可跑
│ ├── __init__.py # ALL_PATTERNS 顺序列表
│ ├── sequential.py
│ ├── concurrent.py
│ ├── ...（共 16 个）
│ └── multi_provider.py
│
├── skills/shot-list-spec/ # Skills pattern 用的 SKILL.md 资源
│ ├── SKILL.md
│ ├── references/example.md
│ └── scripts/validate.py
│
├── declarative/ # Declarative pattern 用的 YAML
│ └── critic_workflow.yaml
│
├── tests/ # pytest 测试
│ ├── test_smoke.py # 不调 LLM（21 个 case，秒级跑完）
│ ├── test_orchestration.py # 5 个 pattern（live，调 LLM）
│ ├── test_capabilities.py # 4 个 pattern（live）
│ ├── test_production.py # 5 个 pattern（live）
│ └── test_engineering.py # 2 个 pattern（live）
│
├── docs/ # 文档
│ ├── INDEX.md
│ ├── PATTERNS.md # ⭐ 核心文档：16 个 pattern 详解
│ ├── decision-tree.md # 选型决策树
│ └── known-issues.md # 11 个兼容性坑 + 修复
│
├── runs/ # 测试运行结果归档（按日期）
│ └── 2026-05-16_xxx/
│ ├── SUMMARY.txt # 状态总览
│ └── <pattern>.log # 每个 pattern 的完整输出
│
└── scripts/
├── run_all.sh # 串行跑全部 16 pattern
└── run_one.sh # 单跑某个 pattern
跑这个参考时已经替你绕过/修复的 11 个兼容性坑（详见 docs/known-issues.md）：
| # | 坑 | 修复 |
|---|---|---|
| 1 | DeepSeek 404（默认走 Responses API） | 用 OpenAIChatCompletionClient（非 OpenAIChatClient） |
| 2 | HandoffBuilder require_per_service_call_history_persistence | 所有 agent 都设这个参数 |
| 3 | GroupChatBuilder 无 orchestrator | 传 selection_func 轮询 |
| 4 | Magentic 成本失控 | 必设 max_round_count + max_stall_count |
| 5 | ⭐ HITL approval 续跑 spec 冲突 | 必须加 InMemoryHistoryProvider(load_messages=True) |
| 6 | Middleware 类型推断失败 | 用 @*_middleware decorator |
| 7 | MemoryFileStore owner_state_key | session.state["xxx"] = "xxx" |
| 8 | A2A + macOS 系统 proxy = 502 | httpx trust_env=False |
| 9 | a2a-sdk 1.0 API 重命名 | 用 route factory + supported_interfaces |
| 10 | Skills script_runner API | script.full_path 不是 script.path |
| 11 | patterns/concurrent.py 跟 stdlib 冲突 |
用 python -m patterns.xxx 运行 |
需要 pattern X 怎么写 → 直接打开 patterns/X.py 看，注释里有完整说明。
把 patterns/<想要的 pattern>.py + common.py 复制到你的项目，改 instructions 和业务逻辑即可。
代码报错 → 看 known-issues.md 11 条对照。
不确定该用 MAF / OpenAI Agents SDK / LangGraph / Claude Agent SDK → 跑这 16 个 pattern，对比同任务在 MAF 下需要多少代码、效果如何。
| 框架 | 厂商 | 适合什么团队 |
|---|---|---|
| Microsoft Agent Framework 1.0 | Microsoft | .NET / Azure / SK 老用户 / 多云多模型反 lock-in |
| OpenAI Agents SDK | OpenAI | Python 重度 OpenAI 用户、要极简 API |
| LangGraph | LangChain | 生产级有状态系统、time-travel 调试 |
| Claude Agent SDK | Anthropic | Claude 重度用户 + 深度 MCP 集成 |
| CrewAI | CrewAI | 原型最快、role-based 思维 |
详见 docs/PATTERNS.md 末尾的"业界 2026 主流方案对照"。
本工程默认用 DeepSeek V4-Flash（OpenAI 兼容端点）：
- 便宜（约 OpenAI 价格 1/10，跑完 16 个 pattern 约 $0.5）
- 中文优秀
- 但 stateless chat-completions 协议，需要
InMemoryHistoryProvider才能做 HITL 续跑
切换到其他后端只改 common.py:make_client()：
# 切 Gemini
return OpenAIChatCompletionClient(
api_key=os.environ["GEMINI_API_KEY"],
base_url="https://generativelanguage.googleapis.com/v1beta/openai",
model="gemini-2.5-flash",
)
# 切 OpenAI 直连
return OpenAIChatCompletionClient(
api_key=os.environ["OPENAI_API_KEY"],
model="gpt-5-mini",
)
# 切 Anthropic（需装 agent-framework-anthropic 子包）
from agent_framework.anthropic import AnthropicChatClient
return AnthropicChatClient(api_key=..., model="claude-opus-4-7")每次 ./scripts/run_all.sh 跑完，产物在 runs/<时间戳>/：
runs/2026-05-16_143028/
├── SUMMARY.txt # 16 行：[pattern] 状态 耗时 摘要
├── sequential.log
├── concurrent.log
├── ...（16 个完整输出）
最近一次成功的归档目录见 runs/ 下最新日期。
代码 Apache 2.0。
本参考工程不属于 Microsoft 官方，仅基于公开文档 + 官方 sample 整理。"Microsoft" / "Agent Framework" 是各自所有人的商标。
- 完整流程见 CONTRIBUTING.md
- 新踩坑 → 新建 known-issue issue
- 新 pattern → 新建 pattern proposal
- 安全问题 → 见 SECURITY.md（请不要公开 issue）
- 社区行为规范 → CODE_OF_CONDUCT.md