Week 5 — Agent Frameworks 和 MCP
Sign in
Adventure II · Week 5
Week 5 — Agent Frameworks 和 MCP
MCP 就是 AI agent 的「USB 线」。tool 写一次,每个 agent 都能用。

Adventure 8

回顾
我们上次讲到哪了
  • Week 1:LLM 是什么 — 预测下一个词
  • Week 2:它的内部 — tokens、attention、transformers
  • Week 3:怎么 prompt 它 — sampling + 5 种套路
  • Week 4:给它 tools — agent loop
  • Week 5(今天):Frameworks + MCP — 整个生态到底是怎么拼起来的

Adventure 8

今天的目标
3 小时后你会懂的事
今天结束时,你可以:
90% 的 agent 代码
讲清楚大部分 agent 代码到底在干嘛 — 提示:都是「管道工程」,不是 loop 本身
4 个主流 framework
能说出每个的名字,并讲清楚它适合什么场景
MCP — AI 的「USB」
定义它、解释这个类比、说出为什么这个标准重要
读 MCP server + 用 MCP server
看懂源码,10 分钟内给 Claude Code 加一个新的 MCP server
Multi-agent 的套路
能画出一个 multi-agent 系统,也知道什么时候「别建」

Adventure 8

几条底线
约法三章 — 3 条底线
1
「无聊」的方案通常是对的
framework 越少越好、agent 越少越好、抽象越少越好。忍住「过度工程」的冲动。
2
先试 single-agent
Multi-agent 很少是答案。先从简单开始,只在真的卡住的时候才加复杂度。
3
读源码
MCP server 一般也就 50–200 行。写之前先读一个。你会感谢你自己。

Adventure 8

热身
开始之前 — 先校准一下
花 2 分钟,把这 3 个问题的「最佳猜测」写下来:
问题 1
如果你想让你的 AI 助手读你的 Notion 笔记,你需要写什么代码?
问题 2
用你自己的话讲,「vendor lock-in」是什么意思?
问题 3
你用过 USB 线连接打印机。为什么 AI 的 tool(目前)不是这样工作的?

这里没有错的答案。这 3 个问题给今天的内容搭好框架。

Adventure 8

「管道工程」问题
「管道工程」问题
上周你用 8 行代码写出了 agent loop。看起来很简单。
在真实代码里,loop 只是 冰山一角.

水面下的所有东西 — state、streaming、errors、retries、permissions、logs、context 管理 — 才是另外 90%。

Adventure 8

agent 代码的 90% 到底在干什么
Loop 只占 agent 代码的 10%。剩下 90% 是:
01
对话 state
按顺序追踪所有 message、tool call、result
02
Tool 注册
为每个 tool 拼出 JSON schema
03
Tool 执行
解析输出、校验参数、调用函数、格式化结果
04
错误处理
Tool 失败 → 整理错误信息 → 决定是重试还是抛给用户
05
Context 管理
在 context window 满之前,把旧对话先总结一下
06
Streaming + 日志 + 权限 + 多轮 UX
实时推送 token、记录每一步、做危险动作前先问一下、保持反应灵敏

Adventure 8

为什么会有 framework
上面那 9 件事你自己都要写一遍 — 或者用一个 framework,它已经替你写好了。
你得到什么
  • 提前解好的难题(state、streaming、errors)
  • 常见 pattern 的规范写法
  • 一群踩过同样坑的社区
你失去什么
  • 对 framework 内部假设的控制权
  • 出问题时的调试难度变高了 在 framework 内部
  • 自由替换零件的能力

Adventure 8

取舍 — 代码少 vs framework 的限制

原生 API
Framework
需要写的代码
更多
更少
做出第一个 agent 要多久
几小时
几分钟
调你自己的代码
更容易
差不多
调 framework 本身
不需要
难
灵活度
完全自由
受限制
换 provider
更容易
通常要重写
做实验选原生 API,做产品选 framework。

Adventure 8

📘 概念卡片
Framework
是什么:一个帮你处理 agent「管道工程」(state、errors、streaming)的库,让你少写代码。
类比:懒人料理包 — 食材洗好切好分好。煮起来快,但没从零开始那么自由。
为什么重要:大部分「agent 代码」都是管道。Framework 帮你省下 90% 的活,代价是在剩下 10% 里失去一些灵活度。

✓ 记住:framework 是一种交换 — 你用控制权换速度。要知道自己换了什么。

Adventure 8

Frameworks
你应该认识的 4 个 framework
  • LangChain — 大块头,生态最大
  • OpenAI Assistants API — 托管的,上手最快,但被 OpenAI 锁死
  • CrewAI — 专攻 multi-agent
  • Claude Agent SDK — 原生支持 MCP,干净利落
每个都有它的「甜区」。我们一个个讲。

Adventure 8

LangChain — 大块头
优点
  • 2022 年底就开始做了 — 生态非常庞大
  • 几乎每种文件格式都有 document loader
  • Retrieval pipeline、几十个 tool 实现
  • 你想要什么,基本都能找到例子
缺点
  • 抽象层太厚
  • 调 framework 的时间和调你自己代码的时间差不多
  • API 变动很大
什么时候用
做复杂东西(RAG、多步研究)的时候,你希望从一个能跑的例子开始。

Adventure 8

OpenAI Assistants API — 上手快,但锁死
优点
  • 最快上手 — 不用写「管道」
  • 对话持久化是内置的
  • Code interpreter + 文件搜索开箱即用
缺点
  • 只能用 OpenAI 的模型
  • 之后想换成 Claude = 整个重写
什么时候用
用 OpenAI 快速做原型,而且你不在乎以后能不能搬到别处。

Adventure 8

CrewAI — 专攻 multi-agent
优点
  • 对「专门角色的 agent」有很干净的抽象
  • 「这个 agent 做调研,那个 agent 写稿,那个 agent 改稿」
  • 内置协调 pattern
缺点
  • Multi-agent 很脆弱
  • Orchestration 开销很大
  • 一个 prompt 写得好的 single agent 往往效果更好
什么时候用
你真的需要并行的专门角色,而且你已经先试过 single-agent 了。

Adventure 8

Claude Agent SDK — 原生 MCP
优点
  • 简单直接 — 抽象很少
  • 原生接入 MCP 生态
  • 文档很好,和 Claude Code 用的是同一套原语
缺点
  • 比较新 — 生态比 LangChain 小
  • 专门为 Claude 优化
什么时候用
基于 Claude 开发,而且你想要干净的 MCP 集成,不要 LangChain 那些抽象。

Adventure 8

决策树
Framework 决策树
Do you NEED multiple specialized agents?

├── Yes → CrewAI

└── No (single agent is fine):

    │

    Locked to one model provider?

    ├── OpenAI only → OpenAI Assistants

    ├── Claude only → Claude Agent SDK

    └── Want to switch / try many

              → LangChain (or raw API)

Adventure 8

知识检查 1
选一个 framework
对每个场景,猜一下你会选哪个 framework — 以及为什么:
场景 1
「用 Claude 做一个作业助手。就一个 agent。」
场景 2
「一天内在 OpenAI 上做出一个客服助手原型。」
场景 3
「做一个复杂的研究工具,要用 3 个不同的 LLM。」
场景 4
「做一个「盒装公司」,里面有分开的 Manager、Engineer 和 QA agent。」

先写下你的答案,再看决策树。然后对照检查。

Adventure 8

无聊的真相 — 大多数 app 不需要 framework
大多数新手都过度工程。真正有效的做法是:
你的前 5 个 agent
  • 用原生 API
  • 用 single agent
  • 写一个强 system prompt
什么时候加 framework
只有当你真的撞到瓶颈、而且改 prompt 或重构代码都解决不了的时候。

✓ 记住:Framework 是工具,不是起点。复杂度要「挣来」,不是默认开。

Adventure 8

MCP 要解决的问题
MCP 解决的问题
想象一下你做了一个「读 GitHub issues」的 tool,接到 Claude Code 里。跑得很好。
想在 Cursor 里也用?
格式不一样。重写。
想在 ChatGPT 里用?
格式不一样。重写。
想在 LangChain 里用?
格式不一样。重写。
同一个 tool,要写 4 份实现。 再乘以每个 tool、每个产品、每个开发者 — 这是几十亿美元的重复劳动。

Adventure 8

MCP — Model Context Protocol
MCP 就是为了解决这个问题的标准。
发布方
Anthropic,2024 年底
核心思路
用 MCP 的格式描述一次 tool。任何兼容 MCP 的 agent 都能用。
已经被这些采用
Claude Code、Cursor、OpenAI,还有很多

Adventure 8

USB 类比
USB 类比
USB 之前
  • 每台打印机都有自己的接口和线
  • 加一台打印机 = 新驱动,有时还要新硬件
  • 每家外设公司都自己做一套
USB 之后
  • 一个接口 — 什么都能插
  • 生态爆炸式增长
MCP 正在对 AI 的 tool 做同样的事。

Adventure 8

📘 概念卡片
MCP — Model Context Protocol
是什么:一个开放协议,用标准方式描述 tool,这样任何兼容的 agent 都能用任何兼容的 tool。
类比:USB。打印机厂商不会为每种电脑做一个专属接口 — 他们只实现 USB 一次,所有 USB 电脑都能用。
为什么重要:Tool 写一次,所有 MCP agent 都能用。整个生态会快得多。

✓ 记住:MCP 是一个标准,不是一个产品。标准会改变整个行业。

Adventure 8

谁做的、谁在用
发布方
Anthropic(2024 年底)
目前已采用的(暂列)
  • Claude Desktop、Claude Code
  • Cursor
  • OpenAI(已宣布支持)
  • Replit、Zed,还有几十个
  • 社区:GitHub 上有几百个 MCP server
AI 历史上普及最快的标准。

Adventure 8

MCP 解剖
MCP server 在干什么 — 3 件事
MCP server 是一个小程序,把 tool 暴露给 agent。它就做 3 件事:
1
宣告
agent 连上来的时候,告诉它有哪些 tool、各自的 schema 是什么
2
执行
agent 调用某个 tool 的时候,真的去跑那个函数
3
返回
用标准 MCP 格式把结果回传
就这样。大多数 MCP server 一共 50–200 行代码。

Adventure 8

极简例子 — 随机数 server
一个完整的 MCP server,暴露一个 tool:
@server.tool()

def get_random_number(min: int, max: int) -> int:

    """Return a random integer between min and max (inclusive)."""

    return random.randint(min, max)
这就是整个 server。现在,任何兼容 MCP 的 agent 都可以:
  • 连上它
  • 看到 get_random_number 出现在 tool 列表里
  • 需要随机数的时候就调用它

你一行 agent 代码都没写。你只写了一个函数。剩下的都是 MCP 协议干的。

Adventure 8

看一个真实 MCP server 的内部
这个 filesystem MCP server 让 agent 在你指定的文件夹里读写文件。
源码
总共 ~150 行。没有魔法。
它暴露的 tool
  • read_file(path)
  • write_file(path, content)
  • list_directory(path)
  • search_files(pattern)
每个 tool 都是
  • 一个 @server.tool() decorator
  • 一句话描述
  • 5–20 行的实现

在 GitHub 上找到它: modelcontextprotocol/servers — 今晚就读一下。

Adventure 8

用 50 行写你自己的 MCP server
每次都是同一个套路:
01
挑一个 SDK
Python 或 TypeScript — 都有官方 MCP SDK
02
定义你的 tool
用 @server.tool() decorator 写你的函数
03
把 server 跑起来
stdio transport(最简单)或者 HTTP
04
加到任意 MCP client
把那段 config 粘到 Claude Code、Cursor 或任意 MCP client 里
最难的部分是决定 要暴露哪些 tool。代码本身很简单。

Adventure 8

知识检查 2
MCP 能解决这些场景吗?
对每个场景,预测一下:MCP 有用吗?为什么?
场景 1
「我想让 Claude Code 读我的 Notion workspace。」
场景 2
「我想让我自己的 Python 脚本去跟 Claude 对话。」
场景 3
「我想在 read_email tool 在 Cursor 和 Claude Code 里都能用。」
场景 4
「我想把我的 chatbot 从 Claude 换成 GPT。」

Adventure 8

📘 概念卡片
MCP Server
是什么:一个小程序,把 tool 暴露给兼容 MCP 的 agent — 宣告、执行、返回。
类比:USB 外设。打印机不在乎什么电脑插上来;它只说 USB。MCP server 只说 MCP。
为什么重要:写一个 server 很简单;真正的价值是「即插即用」。写一次,每个 agent 都能用。

✓ 记住:你现在已经知道得够多了,可以读任何 MCP server 的源码,并搞清楚它到底在干什么。

Adventure 8

真实的 MCP server
今天就能插上用的真实 MCP server
filesystem
在一个文件夹里读/写/列出文件
github
读 repo、issue、PR;在 issue 下评论
postgres
对数据库跑 SQL 查询
slack
读频道、发消息、搜索
puppeteer
驱动一个真实浏览器 — 跳转、点击、截图
memory
跨 session 的持久化 key-value 记忆
fetch
对任意 URL 发 HTTP GET,返回干净的文本
gmail
读收件箱、搜索邮件线程、起草邮件
notion
读写 Notion 的 page 和 database

Adventure 8

3 步插上一个新的 MCP server
1
找到 config 片段
大多数 MCP server 的 README 里就有一段可以直接复制粘贴的 block
2
加到你的 config 里
粘到 ~/.claude/mcp_settings.json 或者通过 Claude Code 的 UI
3
重启 Claude Code
新的 tool 就直接出现在 Claude 的 tool 列表里。不用改代码。不用重新构建。

Adventure 8

动手做
动手做 — 加一个真实 MCP server
我们来加 memory MCP server(跨 session 的持久笔记)到 Claude Code 里。一步一步一起来:
01
找到官方的 config 片段
打开 modelcontextprotocol/servers repo,找到 memory server 的 README
02
粘到你的 MCP config 里
把那段 JSON 加到 ~/.claude/mcp_settings.json
03
重启 Claude Code
关掉再打开 — server 会自动启动
04
看新 tool 跳出来
Claude 的 tool 列表变长了。不用重新构建。
05
现场用一用
试试:「Claude,记住我最喜欢的颜色是蓝色。」然后关掉再打开。再问一次。

Adventure 8

新 tool 出现了
重启之后,Claude Code 的 tool 列表变长了。你现在可以问:
「记住……」
→ memory.set()
「我上周跟你说过什么?」
→ memory.get()
「忘掉 X」
→ memory.delete()

你一行 agent 代码都没写。MCP server 把所有东西都提供好了。

Adventure 8

Multi-Agent
1 个 agent 不够用的时候
有 3 种 multi-agent pattern 值得认识:
1
Orchestrator + Workers
一个 agent 负责派活,其他 agent 各管一摊
2
辩论
两个 agent 站在相反立场上吵,第 3 个来判
3
层级式
经理和具体执行人,层层往下派活

但首先:大多数「multi-agent」项目其实用一个 prompt 写得好的 agent 反而更好。只有在 single-agent 真的搞不定的时候,再用这些 pattern。

Adventure 8

Pattern 1 — Orchestrator + Workers
     User: "Plan my friend's birthday"

                    │

               Orchestrator

             ╱      │      ╲

    Researcher  Planner   Budgeter

             ╲      │      ╱

               Orchestrator

                    │

               Final answer
Orchestrator 派活。Worker 专心干一件事。和真实团队的工作方式一样。

Adventure 8

Pattern 2 — 辩论
两个 agent 拿到相反的立场。第 3 个看完辩论,然后做决定。
适合用在:找出薄弱论点、探索取舍、减少 single-agent 的偏见。

Adventure 8

什么时候不该用 multi-agent
大多数 multi-agent demo 用一个 system prompt 更长的 single agent 反而更好。
Multi-agent 会增加
  • 更多 token(每个 agent 都有自己的 context)
  • 更高延迟(步骤是串行的)
  • 更脆弱(一个 agent 坏掉,整条流水线就崩了)
规则
先试 single-agent。只有在你怎么 prompt 都搞不定一个 agent 的时候,再上 multi-agent。

✓ 记住:Multi-agent 是高级工具,不是起点。

Adventure 8

总结
3 小时总结
你现在懂了:
Framework 之所以存在,是因为「管道工程」
90% 的 agent 代码是 state、errors、streaming — 不是 loop 本身
4 个 framework,每个都有自己的甜区
LangChain、OpenAI Assistants、CrewAI、Claude Agent SDK
MCP 是「AI 的 USB」标准
Tool 写一次 — 所有兼容 MCP 的 agent 都能用
MCP server 就 50–200 行
你今晚就能写一个。今天你已经读了一个。
Multi-agent pattern 存在 — 但大多数项目根本不需要
Orchestrator + Workers、辩论、层级式。永远先试 single-agent。

Adventure 8

参考
术语表
Framework
处理 agent 管道(state、errors、streaming)的库,让你少写代码
MCP(Model Context Protocol)
一个开放协议,tool 描述一次,任何兼容的 agent 都能用
MCP server
通过 MCP 暴露 tool 的小程序 — 宣告、执行、返回
MCP client
agent 那一边 — 连接 MCP server 并使用它们的 tool
Orchestrator
负责把活派给其他专门 agent 的 agent
Multi-agent system
多个 agent 一起工作,每个扮演不同的角色
Vendor lock-in
代码和某个 provider 绑得太死,换一家就要整个重写

Adventure 8

Week 6 预告
本周任务 + Week 6 预告
这周 — 你的任务
  • 给你的 Claude Code 加一个新的 MCP server,用它做一件真实的事
  • 读一个不是你写的 MCP server 源码 — 也就 ~100 行
下周 — 做出你真正的产品
你现在知道:LLM 是什么、它怎么工作、怎么 prompt 它、怎么给它 tool、怎么在标准之上构建。
下周你把所有这些拼起来, 做出一个别人真的能用的东西。 PRD、wireframe、spike、deploy。
带一个你希望「有人能做个工具来解决」的问题来。它马上就会是你做出来的。

Adventure 8