零基础搭建 Agent 框架（实战篇）
🤔 什么是 multi-agent （多智能体） framework？
1.1
两个维度先分清楚（workflow vs agent / single vs multi）
1.2
Single-agent vs multi-agent
一张对照表先看清楚差异
#bXTTiBLDaRiH text { white-space: pre; }#bXTTiBLDaRiH .fb0 { stroke: var(--N900-FG, 0.15); }#bXTTiBLDaRiH .fb0 {stroke: rgba(31,35,41, 0.15)}#bXTTiBLDaRiH .fx0 { stroke-miterlimit: 10; }#bXTTiBLDaRiH .fx0 {stroke-miterlimit: 10}#bXTTiBLDaRiH .fa1 { fill: rgb(187, 191, 196); }#bXTTiBLDaRiH .fa1 {fill: rgb(187, 191, 196)}#bXTTiBLDaRiH .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#bXTTiBLDaRiH .fx1 {font-style: normal}#bXTTiBLDaRiH .fx2 { text-anchor: middle; }#bXTTiBLDaRiH .fx2 {text-anchor: middle}#bXTTiBLDaRiH .fx3 { dominant-baseline: central; }#bXTTiBLDaRiH .fx3 {dominant-baseline: central}#bXTTiBLDaRiH .fx4 { stroke: none; }#bXTTiBLDaRiH .fx4 {stroke: none}#bXTTiBLDaRiH .fc0 { fill: var(--text-caption); }#bXTTiBLDaRiH .fc0 {fill: #646a73}#bXTTiBLDaRiH .fa2 { fill: var(--text-link-disabled); }#bXTTiBLDaRiH .fa2 {fill: rgb(187, 191, 196)}#bXTTiBLDaRiH .fa3 { fill: rgb(250, 241, 209); }#bXTTiBLDaRiH .fa3 {fill: rgb(250, 241, 209)}#bXTTiBLDaRiH .fx5 { font: 700 16px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#bXTTiBLDaRiH .fx5 {font-style: normal}#bXTTiBLDaRiH .fx6 { text-anchor: start; }#bXTTiBLDaRiH .fx6 {text-anchor: start}#bXTTiBLDaRiH .fx7 { dominant-baseline: alphabetic; }#bXTTiBLDaRiH .fx7 {dominant-baseline: alphabetic}#bXTTiBLDaRiH .fc1 { fill: rgb(0, 0, 0); }#bXTTiBLDaRiH .fc1 {fill: rgb(0, 0, 0)}#bXTTiBLDaRiH .fx8 { font: 400 13px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#bXTTiBLDaRiH .fx8 {font-style: normal}#bXTTiBLDaRiH .fb1 { fill: var(--N900-FG, 0.15); }#bXTTiBLDaRiH .fb1 {fill: rgba(31,35,41, 0.15)}#bXTTiBLDaRiH .fa4 { fill: var(--bg-body); }#bXTTiBLDaRiH .fa4 {fill: #fff}ABC12345678维度Single-agentMulti-agent system架构怎么决策State 管理适合场景Debug 成本Token 成本Latency一个 LLM + ReAct loop + 若干 tools同一个 LLM 从头想到尾线性 message history逻辑线性、tool < 20-30 个、单一目标低（单一 loop 可以一路 trace）1x低2+ LLM、各有角色（researcher / writer / critic ...）、orchestrator 协调角色拆分 + handoff、不同 LLM instance 看不同视角shared state / message passing / checkpoint任务可分解、需要 perspective diversity、长 workflow、并行化高（cross-agent 互动、error propagation 难定位）通常 3-10x（每个 sub-agent 都有自己的 prompt + thinking + tool call）高（除非 sub-agent 并行跑）
什么时候真的需要 multi-agent（不要硬上）
🌰
Multi-agent 不是 default、是 last resort。Anthropic 跟 Cognition 两家 frontier lab 在 2024-2025 都明白写过：90% 用例其实不该用 multi-agent——硬上会付 3-10× token、debug 痛苦、context fragmentation 严重。
需要 multi-agent 通常是这 4 个信号之一：
#snrtXmDGOlos text { white-space: pre; }#snrtXmDGOlos .fb0 { stroke: var(--N900-FG, 0.15); }#snrtXmDGOlos .fb0 {stroke: rgba(31,35,41, 0.15)}#snrtXmDGOlos .fx0 { stroke-miterlimit: 10; }#snrtXmDGOlos .fx0 {stroke-miterlimit: 10}#snrtXmDGOlos .fa1 { fill: rgb(187, 191, 196); }#snrtXmDGOlos .fa1 {fill: rgb(187, 191, 196)}#snrtXmDGOlos .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#snrtXmDGOlos .fx1 {font-style: normal}#snrtXmDGOlos .fx2 { text-anchor: middle; }#snrtXmDGOlos .fx2 {text-anchor: middle}#snrtXmDGOlos .fx3 { dominant-baseline: central; }#snrtXmDGOlos .fx3 {dominant-baseline: central}#snrtXmDGOlos .fx4 { stroke: none; }#snrtXmDGOlos .fx4 {stroke: none}#snrtXmDGOlos .fc0 { fill: var(--text-caption); }#snrtXmDGOlos .fc0 {fill: #646a73}#snrtXmDGOlos .fa2 { fill: var(--text-link-disabled); }#snrtXmDGOlos .fa2 {fill: rgb(187, 191, 196)}#snrtXmDGOlos .fa3 { fill: rgb(250, 241, 209); }#snrtXmDGOlos .fa3 {fill: rgb(250, 241, 209)}#snrtXmDGOlos .fx5 { font: 400 16px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#snrtXmDGOlos .fx5 {font-style: normal}#snrtXmDGOlos .fx6 { text-anchor: start; }#snrtXmDGOlos .fx6 {text-anchor: start}#snrtXmDGOlos .fx7 { dominant-baseline: alphabetic; }#snrtXmDGOlos .fx7 {dominant-baseline: alphabetic}#snrtXmDGOlos .fc1 { fill: rgb(0, 0, 0); }#snrtXmDGOlos .fc1 {fill: rgb(0, 0, 0)}#snrtXmDGOlos .fx8 { font: 400 13px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#snrtXmDGOlos .fx8 {font-style: normal}#snrtXmDGOlos .fb1 { fill: var(--N900-FG, 0.15); }#snrtXmDGOlos .fb1 {fill: rgba(31,35,41, 0.15)}#snrtXmDGOlos .fa4 { fill: var(--bg-body); }#snrtXmDGOlos .fa4 {fill: #fff}ABC12345信号描述对应 pattern1. 任务天然分解2. Token explosion3. 角色冲突4. 并行加速大任务有清楚的子步骤、step-by-step 完成single agent prompt 塞不下所有 tool description / context同一个 LLM 既当 writer 又当 critic 会 self-justify3 个 research 子任务同时跑、wall-clock 1/3Sequential / Planner-ExecutorSupervisor-Worker（分流给 sub-agent）Debate / Peer reviewParallel / Map-Reduce 变种
4 个信号都不在？ → single agent + 好 prompt + tool use 就够。硬上 multi-agent 会付 3-10x token、debug 痛苦、其实不会比较准。
Multi-agent 经典 pattern（按复杂度排序）
📝 本节这 5 个 pattern 是多个 agent 之间怎么协作——正交的两个层。
#mkbAXMNtkfyD text { white-space: pre; }#mkbAXMNtkfyD .fb0 { stroke: var(--N900-FG, 0.15); }#mkbAXMNtkfyD .fb0 {stroke: rgba(31,35,41, 0.15)}#mkbAXMNtkfyD .fx0 { stroke-miterlimit: 10; }#mkbAXMNtkfyD .fx0 {stroke-miterlimit: 10}#mkbAXMNtkfyD .fa1 { fill: rgb(187, 191, 196); }#mkbAXMNtkfyD .fa1 {fill: rgb(187, 191, 196)}#mkbAXMNtkfyD .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#mkbAXMNtkfyD .fx1 {font-style: normal}#mkbAXMNtkfyD .fx2 { text-anchor: middle; }#mkbAXMNtkfyD .fx2 {text-anchor: middle}#mkbAXMNtkfyD .fx3 { dominant-baseline: central; }#mkbAXMNtkfyD .fx3 {dominant-baseline: central}#mkbAXMNtkfyD .fx4 { stroke: none; }#mkbAXMNtkfyD .fx4 {stroke: none}#mkbAXMNtkfyD .fc0 { fill: var(--text-caption); }#mkbAXMNtkfyD .fc0 {fill: #646a73}#mkbAXMNtkfyD .fa2 { fill: var(--text-link-disabled); }#mkbAXMNtkfyD .fa2 {fill: rgb(187, 191, 196)}#mkbAXMNtkfyD .fc1 { stroke: var(--B500); }#mkbAXMNtkfyD .fc1 {stroke: #336df4}#mkbAXMNtkfyD .fx5 { font: 400 13px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#mkbAXMNtkfyD .fx5 {font-style: normal}#mkbAXMNtkfyD .fx6 { text-anchor: start; }#mkbAXMNtkfyD .fx6 {text-anchor: start}#mkbAXMNtkfyD .fx7 { dominant-baseline: alphabetic; }#mkbAXMNtkfyD .fx7 {dominant-baseline: alphabetic}#mkbAXMNtkfyD .fc2 { fill: rgb(0, 0, 0); }#mkbAXMNtkfyD .fc2 {fill: rgb(0, 0, 0)}#mkbAXMNtkfyD .fc3 { fill: var(--B500); }#mkbAXMNtkfyD .fc3 {fill: #336df4}#mkbAXMNtkfyD .fb1 { fill: var(--N900-FG, 0.15); }#mkbAXMNtkfyD .fb1 {fill: rgba(31,35,41, 0.15)}#mkbAXMNtkfyD .fa3 { fill: var(--bg-body); }#mkbAXMNtkfyD .fa3 {fill: #fff}ABCDE123456Pattern1. Routing / Handoff2. Sequential（Planner → Executor）3. Parallel（并行加速）4. Supervisor-Worker（hub-spoke）5. Debate / Society（多视角收敛）复杂度⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐什么样agent 之间 1:1 handoff、无中央 orchestratorplanner 规划多步骤 + executor 执行N 个 agent 同时跑、结果 aggregate1 主 + N worker、主分配 + 整合2+ agent 互相 critique 或角色扮演经典场景customer support routing、context switch多步骤自动化、code generationresearch / map-reduce 任务、wall-clock 1/N任务拆解、报告整合research、judgment task、social simulation代表 framework / paper、LangGraph、LangGraph parallel branches、CrewAI parallel tasks。坑点：async coordination + partial failure + state merge 一致性LangGraph、AutoGen GroupChatAutoGen GroupChat、、OpenAI SwarmOpenAI Agents SDKChatDev paperCAMEL paperGenerative Agents paper
Claude Code subagent — 另一条 orchestration 路线
这节跟上面的 5 个 pattern 不同层：上面 5 个 pattern 是 framework / 自己 code 都能实作的设计选择；本节介绍的 Claude Code subagent 是另一个 execution model（runtime 内建的 orchestration、不写 framework code）。读完 5 个 pattern 后、本节让你知道“multi-agent 还有第二条路”。
Multi-agent 不只有 framework 这条路。Anthropic 自家的 Claude Code 提供另一个 abstraction 层：subagent — 写一个 .claude/agents/
跟 framework 路线的根本差异（一句话）：framework 路线跨 LLM provider、写 Python orchestration code、checkpointing / audit trail 完整；Claude Code subagent 只在 Claude Code runtime 内、写 markdown 不写 code、天生 context 隔离。
何时选 subagent 而非 framework：
•
你已经在使用 Claude Code 跑日常工作
•
任务 context 大、会吃光主 session window（读整个 codebase 之类）
•
多 subagent 并行（research / write / critic）省 wall-clock 时间
•
不需要跨 provider migration
详细写法 + 动手练习见 Stage 5.5（建议先完成 Stage 5.1 Claude Code 基础再回来看 5.5——subagent 是 Claude Code 生态的进阶功能、需要先熟悉基础用法）。
Framework 的工作
Framework 把上面这 5 个 pattern 的 orchestration boilerplate（roles、handoff、state、retry、checkpoint、HITL pause）抽出来、让你只写角色定义跟任务描述。一句话：framework 是 multi-agent 的脚手架，不是必需品——简单情境你自己写个 dict 跟 for loop 也行（Stage 7 练习 1 就是这样）。
📚 想系统化深入？
🇺🇸 学术 paper（影响后续所有 framework 设计）：
Anthropic — "Building Effective Agents" ⭐⭐⭐ — 何时用 workflow 何时用 agent、5 个经典 orchestration pattern。英文圈 multi-agent 设计入门必读
AutoGen paper (Wu et al. 2023) — Microsoft 多 agent 对话框架原 paper
CAMEL paper (Li et al. 2023) — multi-agent role-play 开山之作
ChatDev paper (Qian et al. 2023) — multi-agent software dev、planner-executor canonical
Generative Agents paper (Park et al. 2023) — 25 个 agent 在 The Sims 互动、社会 simulation
🀄 中文系统教材：
hello-agents Ch6“框架开发实践”+ Ch7“构建你的 Agent 框架” ⭐ — 中文圈完整讲 framework 开发 + 从零构建。注意：Ch4“智能体经典范式构建”是 single-agent paradigm（ReAct / Plan-and-Solve / Reflection），不是 multi-agent
李宏毅 — 生成式 AI 导论 — 中后段有 AI agent / multi-agent 相关集数
Framework 官方 multi-agent docs：
•
LangGraph — Multi-Agent Systems — supervisor / swarm / hierarchical 三种架构官方教学
•
Anthropic Cookbook — customer_service_agent.ipynb — multi-agent orchestration canonical 范例（routing + handoff）
•
Microsoft AutoGen — Examples — group-chat / debate / peer review pattern 完整范例
💡 建议框架学习流程（5 步）：
建立 mental model（30 min）— 读 Anthropic Building Effective Agents、把 workflow vs agent 跟 single vs multi 两维度搞清楚
跑 1 个 framework quickstart（2-3 hr）— LangGraph 或 CrewAI 二选一、跑官方多 agent 教学
对照 Anthropic Cookbook customer_service_agent（1 hr）— production-style routing + handoff 范例
(可选) 深入学术侧：挑 paper 1-2 篇看（AutoGen / CAMEL / ChatDev / Generative Agents）
(Claude 用户可选) 写一个 subagent 对照：见 Stage 5.5、跟 framework 路线比较
不必把 5 个 paper 全读完、挑跟你场景最近的 1-2 个。
🛠 进阶 tool patterns⭐ Track B 必看
Stage 3 教你写 single tool / multi-tool selection（手写 if/elif/else 路由）。Framework 把这层抽掉，并加了三种更进阶的 tool pattern——这三个 pattern 都需要 framework 抽象层才写得干净，Stage 3 自己手写会炸开：
•
LangGraph — Tool Node — composition graph 写法
💡 Track B 学完本节：你应该讲得出“同一个任务”在 (a) Stage 3 手写 (b) 本 stage framework 写 (c) Stage 5.5 Claude subagent 写 三种路线的差别。这是 Track B 路线“会设计 agent”核心问题。
🛠 动手练习
练习 1：同一个 agent、两个 framework
📚 深度资源：
用以下两个 framework 各做一次同样的简单 agent（搜索 + 摘要）：
•
Anthropic — Tool Use best practices — 官方 tool design guide
•
LangGraph
•
LlamaIndex — Tool Router pattern — Dynamic selection canonical reference
•
CrewAI 比较代码行数、debug 体验、以及它们各自把哪些复杂度藏在哪里。
练习 2：多 agent 角色分配
用 CrewAI 做一个 2-3 个 agent、各自有不同角色一起完成同一个任务的 demo。（这种情境 CrewAI 最拿手。）
练习 3：图式 workflow
用 LangGraph 做一个有分支逻辑跟 human-in-the-loop checkpoint 的 workflow。（这种情境 LangGraph 最拿手。）
练习 4：CodeAct vs JSON tool
用 Smolagents 做一个会写 Python 代码当作 action 的 agent（CodeAct pattern），跟 练习 1 用的 JSON tool call 路线比较。问同一个问题，看两种路线怎么解。
练习 5：类型安全 agent
用 Pydantic AI 做一个会返回结构化输出的 agent（例如：问问题回 { "answer": str, "confidence": float, "sources": [str] }）。看 Pydantic 的 schema validation 怎么防止 agent 偷懒或 hallucinate 结构。
🎯 精选 Projects
按用途分 5 类、15 个项目一张表搞定。挑入口看“适合谁”、想深入点链接看 repo / quickstart。
💡 建议阅读路径：挑 1 个 production 等级（LangGraph）+ 1 个快速雏形（CrewAI）深入学 → 跑练习 1-3 → 其他 framework README 浏览过去、知道存在即可。特殊路线那 3 个（CodeAct / typed / memory-first）在特定场景才有对手、平常不必碰。
✅ 进 Stage 5 前的自我检查
你能不能：
•
用 LangGraph 跟 CrewAI 各做一次同一个 agent
•
替任务挑出对的 framework（production vs 雏形）
•
解释 LangGraph 的 checkpoint 跟 CrewAI 的 task delegation 差在哪
•
看出什么时候 CodeAct（Smolagents）比 JSON-tool 更好
•
判断什么时候该丢掉 framework、直接用 raw API