从手写循环,到标准化工具生态
阶段 03 你亲手写过一个 Agent 循环,阶段 05 你把它包成了服务。这一阶段解决两个问题:要不要用框架,以及怎么让工具接入变成标准动作而不是每个项目重写一遍。前半程讲框架的共同骨架与选型方法,后半程讲 MCP 协议并手写一个最小实现。全程只用标准库,不联网、不需要 API 密钥。
按 6 个模块、L1~L5 难度自己测一遍,10 题一组即答即批,适合学完几章之后查漏补缺。 链接:https://myimage.cn/framework-mcp/
全部章节
第 1 章 从手写循环到框架
1.1 回顾:那个手写的循环
阶段 03 我们手写过一个最小 Agent 循环,回忆一下它的结构:模型输出 → 判断是不是要调工具 → 执行工具 → 把结果塞回消息列表 → 再问模型,直到模型不再要调工具。
TOOLS = {
"get_weather": lambda city: f"{city} 现在 26℃,晴",
"get_time": lambda: "2026-11-12 09:30",
}
def run_agent(user_input, max_steps=5):
"""最小 Agent 循环:模型说要调工具就调,直到它给出最终答案"""
messages = [{"role": "user", "content": user_input}]
# 真实场景这里换成模型调用;此处用规则模拟「模型这一轮想调哪些工具」
wanted = []
if "天气" in user_input:
wanted.append(("get_weather", {"city": "上海"}))
if "几点" in user_input:
wanted.append(("get_time", {}))
calls = 0
for step in range(1, max_steps + 1):
if not wanted:
messages.append({"role": "assistant", "content": "我查到了,直接回答你。"})
return messages, calls
tool_name, args = wanted.pop(0)
calls += 1
result = TOOLS[tool_name](**args)
messages.append({"role": "tool", "name": tool_name, "content": result})
messages.append({"role": "assistant", "content": "达到最大步数,停止。"})
return messages, calls
msgs, steps = run_agent("上海天气怎么样?现在几点?")
for m in msgs:
print(f"[{m['role']}] {m['content']}")
print("共用了", steps, "步")
# 输出:
# [user] 上海天气怎么样?现在几点?
# [tool] 上海 现在 26℃,晴
# [tool] 2026-11-12 09:30
# [assistant] 我查到了,直接回答你。
# 共用了 2 步
这几行就是「没有框架时的样子」:自己维护消息、自己挑工具、自己数步数。后面所有框架,本质都是把这几行包装起来,所以先读懂它,再看框架就不会觉得神秘。
这段代码不到 30 行,但它已经包含了 Agent 的全部核心要素:工具表、执行循环、消息列表、终止条件。你后面用任何框架,写出来的业务代码本质上都是这四样东西的排列组合。
1.2 框架到底替你做了什么
框架的价值不在「帮你写循环」(那部分你自己也能写),而在那些重复、脏、容易错的地方:
| 框架替你做的事 | 自己写会遇到什么 |
|---|---|
| 模型适配层 | 换一家模型就要改请求格式、重试、错误码、流式解析 |
| 工具注册与参数校验 | 每个工具都要自己写 JSON Schema 和校验 |
| 执行循环与终止条件 | 死循环、步数失控、递归过深 |
| 状态与记忆管理 | 上下文裁剪、checkpoint、回滚 |
| 流式输出与事件回调 | 自己处理分片、工具调用中间态、最终消息 |
| 追踪与可观测 | 出问题时不知道卡在哪一步 |
判断标准:如果你的项目只有一个 Agent、工具少于五个、团队只有你一个人,手写循环通常更快、更可控、更好调试;框架的收益要到「多 Agent、多工具、多人协作、要接很多模型」时才明显。
1.3 框架的代价
框架不是免费的。常见的四个代价:
- 抽象泄漏:框架某个抽象不满足你的需求时,你得绕过它直接调底层 API,最后代码里一半是框架一半是自己的。
- 版本漂移:框架迭代快,三个月前写的示例今天可能报错;生产项目会被迫锁版本。
- 调试困难:出问题时栈很深,异常被框架包装过好几层,真正的原因被藏起来。
- 学习成本:概念多、名词多,容易「学了很久框架还是不会写 Agent」。
所以正确的顺序是:先手写一遍,再上框架。你现在已经手写过了,接下来学框架会非常快 —— 因为你知道它在替你做哪几件事。
1.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| Agent 的四要素 | 工具表、执行循环、消息列表、终止条件 |
| 框架的真正价值 | 模型适配、参数校验、状态管理、流式、追踪 |
| 什么时候不用框架 | 单 Agent、少工具、单人项目 |
| 框架的代价 | 抽象泄漏、版本漂移、调试难、概念多 |
| 正确顺序 | 先手写,再上框架 |
第 2 章 框架的共同骨架
2.1 四件套:模型、工具、循环、状态
框架名字千变万化,骨架却高度一致。搞清楚这四件套,换任何框架都能快速上手:
| 部件 | 职责 | 你在业务里会写什么 |
|---|---|---|
| 模型接口 | 发消息、拿回复,支持流式 | 选模型、设温度、传提示 |
| 工具注册 | 声明有哪些工具、参数长什么样 | 写工具函数与描述 |
| 执行循环 | 模型要调工具就调,直到收敛 | 设最大步数、终止条件 |
| 状态 | 消息列表、记忆、检查点 | 决定记什么、留多久 |
不同框架的差别,基本都落在这四格里:模型接口抽象得深不深、工具定义方不方便、循环可控不可控、状态是隐形还是显式。
2.2 工具抽象:描述 + 参数模式 + 执行函数
一个工具被模型用起来,模型需要知道三件事:它叫什么、什么时候该用、参数怎么填。所以工具定义通常是「一份 JSON Schema + 一个执行函数 + 一段自然语言描述」。
import json
# 工具注册表:名字 -> (描述, 参数 schema, 执行函数)
TOOLS = {
"add": {
"description": "把两个数相加。用于任何需要算数的地方。",
"parameters": {
"type": "object",
"properties": {
"a": {"type": "number", "description": "第一个加数"},
"b": {"type": "number", "description": "第二个加数"},
},
"required": ["a", "b"],
},
"fn": lambda a, b: a + b,
},
"upper": {
"description": "把文本转成大写。",
"parameters": {
"type": "object",
"properties": {"text": {"type": "string", "description": "要处理的文本"}},
"required": ["text"],
},
"fn": lambda text: text.upper(),
},
}
def list_tools():
"""给模型看的工具清单:只有描述和参数结构,没有实现"""
return [
{"name": name, "description": t["description"], "parameters": t["parameters"]}
for name, t in TOOLS.items()
]
def call_tool(name, args):
"""真正执行工具:不在清单里就报错,参数缺失也报错"""
if name not in TOOLS:
raise KeyError(f"没有这个工具: {name}")
spec = TOOLS[name]
missing = [k for k in spec["parameters"].get("required", []) if k not in args]
if missing:
raise ValueError(f"缺少参数: {missing}")
return spec["fn"](**args)
print("工具数量:", len(list_tools()))
print("第一个工具:", json.dumps(list_tools()[0], ensure_ascii=False))
print("add(2, 3) =", call_tool("add", {"a": 2, "b": 3}))
print("upper('hi') =", call_tool("upper", {"text": "hi"}))
try:
call_tool("add", {"a": 1})
except ValueError as e:
print("参数校验拦住了:", e)
try:
call_tool("div", {})
except KeyError as e:
print("未知工具拦住了:", e)
# 输出:
# 工具数量: 2
# 第一个工具: {"name": "add", "description": "把两个数相加。用于任何需要算数的地方。", "parameters": {"type": "object", "properties": {"a": {"type": "number", "description": "第一个加数"}, "b": {"type": "number", "description": "第二个加数"}}, "required": ["a", "b"]}}
# add(2, 3) = 5
# upper('hi') = HI
# 参数校验拦住了: 缺少参数: ['b']
# 未知工具拦住了: '没有这个工具: div'
小白提示:
description/parameters/ 执行函数,就是工具抽象的「三件套」。输出里两个「拦住了」很重要:缺参数、未知工具都必须在调用前拦下,不能指望模型永远守规矩——模型只是给建议,你的代码才是最终执行者。
写工具描述的诀窍:描述是写给模型看的,不是写给同事看的。要说清「什么时候用我、什么时候别用我」,比如「用于纯数值加法;需要单位换算时不要用我」。描述含糊,模型就会乱调。
2.3 状态与记忆:消息列表就是全部
Agent 的状态说白了就是一串消息。框架在此之上加的东西,本质都是围绕这串消息做文章:裁剪、持久化、回放。
import json
def trim_messages(messages, keep_last=4, max_chars=800):
"""上下文裁剪:保留最近若干条,再按总长度兜底截断"""
trimmed = messages[-keep_last:]
total = sum(len(m["content"]) for m in trimmed)
while total > max_chars and len(trimmed) > 1:
total -= len(trimmed[0]["content"])
trimmed = trimmed[1:]
return trimmed
def checkpoint(messages, path="checkpoint.json"):
"""把状态落盘,方便失败后从断点继续"""
with open(path, "w", encoding="utf-8") as f:
json.dump(messages, f, ensure_ascii=False, indent=2)
return path
msgs = [
{"role": "user", "content": "帮我查一下北京明天的天气"},
{"role": "assistant", "content": "好的,我去查"},
{"role": "tool", "content": "北京明天 18℃,多云"},
{"role": "assistant", "content": "北京明天 18℃,多云,记得带件外套。"},
{"role": "user", "content": "那上海呢"},
]
kept = trim_messages(msgs)
print("裁剪后剩", len(kept), "条:", [m["role"] for m in kept])
path = checkpoint(msgs)
with open(path, encoding="utf-8") as f:
restored = json.load(f)
print("检查点里", len(restored), "条消息,最后一条是:", restored[-1]["content"])
# 输出:
# 裁剪后剩 4 条: ['assistant', 'tool', 'assistant', 'user']
# 检查点里 5 条消息,最后一条是: 那上海呢
上下文窗口有上限,消息攒多了会超限、会变贵。trim_messages 先保留最近几条,再按总字符数截断,是最便宜的一种「记忆管理」。注意别把第一条 system 指令裁掉,否则模型会忘了自己该扮演什么角色。
两个必须自己定的问题:裁剪策略(按条数、按 token、还是按语义摘要)和 检查点频率(每步都存太贵,任务结束才存则失败全丢)。
2.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| 框架共同骨架 | 模型接口、工具注册、执行循环、状态 |
| 工具三要素 | 名字、描述、参数 schema + 执行函数 |
| 描述写给模型看 | 说清何时用、何时别用 |
| 状态就是消息列表 | 裁剪、持久化、回放都围着它 |
| 要自己定的事 | 裁剪策略、检查点频率 |
第 3 章 怎么选框架
3.1 四个评估维度
别问「哪个框架最好」,要问「我的场景在哪一格」。四个维度基本能覆盖所有决策:
| 维度 | 要问的问题 | 为什么关键 |
|---|---|---|
| 抽象层次 | 它替你管多少?你还能不能自己控制循环? | 抽象太高,一旦不够用就只能绕过去 |
| 状态管理 | 状态是隐式的还是显式的?能不能存取和回放? | 长任务、失败重试、调试全靠它 |
| 工具生态 | 现成工具多不多?能不能接自己的工具? | 决定你能不能少写代码 |
| 可观测性 | 有没有 trace、日志、指标、回调? | 线上出问题时唯一的救命稻草 |
3.2 四类方案
| 类型 | 典型形态 | 适合 | 不适合 |
|---|---|---|---|
| 通用 Agent 框架 | 提供模型抽象、工具、循环、记忆的一站式套件 | 多工具、多模型、要快速起步 | 流程特别确定、想完全掌控每一步 |
| RAG / 数据编排框架 | 围绕检索、索引、重排、引用设计 | 知识库问答是主要场景 | 任务需要大量工具调用与分支判断 |
| 轻量自研 | 几十行代码自己封装 | 单 Agent、工具少、要极致可控 | 多 Agent、要接很多外部系统 |
| 云厂商 SDK | 和自家模型、网关、鉴权深度打通 | 就用它家的模型、要在它家环境里跑 | 未来想换模型、想多云 |
一条实用建议:先用轻量自研把业务跑通,再决定要不要上框架。反过来先学框架,很容易陷入「学了一堆抽象,业务还没跑起来」。
3.3 选型决策树
你的项目有多少个工具?
├─ 1~3 个,单人维护,流程确定
│ └─ 手写自研(几十行),保留框架里的"四件套"抽象即可
└─ 5 个以上,或多个 Agent 协作
├─ 主要痛点是知识检索?
│ └─ 选 RAG / 数据编排框架
├─ 主要痛点是工具接入和标准化?
│ └─ 选通用 Agent 框架 + MCP(见第 4~5 章)
├─ 必须用某家的模型/网关/鉴权?
│ └─ 选云厂商 SDK
└─ 需要多人协作、长期维护、线上可观测?
└─ 通用 Agent 框架,并优先评估它的 trace / 评估体系
落地前必查的 5 件事:
1. 能不能锁定版本(生产不能跟着上游漂)
2. 异常栈是否可读(出问题时能不能定位)
3. 工具能否自定义(不锁死在框架的封装里)
4. 有没有 trace / token 统计 / 成本统计
5. 文档与社区是否匹配你要用的模型版本
这不是代码,是一张选型问答图,从「你有几个工具」开始一路按自己的情况往下走就行。下面的 5 条是落地前必查项,尤其「能不能锁定版本」——生产环境跟着上游版本漂,是最容易半夜出事的原因。
另外三条工程上的共识:① 在框架外面包一层自己的接口(将来换框架只改这一层);② 框架只用来做编排,业务规则留在自己代码里;③ 先写 10 个工具的真实用例再评估,别看 hello world 演示。
3.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| 评估四维度 | 抽象层次、状态管理、工具生态、可观测性 |
| 四类方案 | 通用 Agent 框架、RAG 框架、轻量自研、云厂商 SDK |
| 推荐顺序 | 先自研跑通,再上框架 |
| 自研也要有抽象 | 模型接口、工具、循环、状态 |
| 落地前必查 | 锁版本、栈可读、可自定义、有 trace |
第 4 章 MCP:它要解决什么
4.1 工具接入的三种土办法
想把「查数据库」「跑脚本」「调内部系统」接给 Agent,历史上大致有三种做法:
| 做法 | 怎么接 | 痛点 |
|---|---|---|
| 直接写函数 | 在项目里 import 进来注册 | 换项目要重写,工具无法给别人复用 |
| HTTP 接口 + 手写适配 | 每个工具写一个适配函数去调接口 | 鉴权、参数、错误处理每次重写一遍 |
| 各自定义插件协议 | 每个平台一套私有格式 | 工具作者要为每个平台各写一遍 |
共同的痛点是:工具的描述、参数、调用方式、返回格式,每次对接都要重新约定一遍。工具作者痛苦,使用者也痛苦。
4.2 MCP 的三个角色 + 传输层
MCP(Model Context Protocol)就是为这件事定的一套标准:让工具以统一的方式暴露给任何支持 MCP 的客户端。
| 角色 | 是谁 | 职责 |
|---|---|---|
| Host(宿主) | 用户实际在用的应用,比如编辑器、IDE、聊天软件 | 承载对话与用户界面 |
| Client(客户端) | Host 内部的一个连接 | 与某个 Server 建立会话、请求工具 |
| Server(服务器) | 提供工具的一方 | 暴露工具列表、执行工具、返回结果 |
| 传输 | 进程内、stdio、SSE、HTTP 等 | 消息怎么送过去 |
一句话记法:Host 里跑 Client,Client 连 Server,Server 供工具。工具作者只要写一个 Server,所有支持 MCP 的 Host 都能用上 —— 这就是标准化的价值。
4.3 能力协商:initialize → tools/list → tools/call
MCP 的交互是典型的「先握手,再干活」:
1) initialize —— 握手:双方交换协议版本与能力(我是 2024-11-05,我支持什么)
2) initialized —— 客户端确认,握手完成
3) tools/list —— 客户端问:这个 Server 有哪些工具?(名字 + 描述 + 参数 schema)
4) tools/call —— 客户端调用:{"name": "工具名", "arguments": {...}}
5) 响应 —— 返回内容(文本、结构化数据,或出错的 isError 标记)
要点:
- 列表和调用是两回事:先 list 才知道能调什么
- 参数用 JSON Schema 描述,和模型 Function Calling 的思路一致
- 错误也是正常返回,只是带错误标记,不要当成传输失败
- 一次会话里可以调用多个 Server 的工具,名字冲突要加前缀
这也不是代码,是 MCP 客户端和服务器建立连接时的三个标准动作:先握手交换协议版本与能力,再列出可用工具,最后才真正调用。顺序不能反:没握手就调工具,服务端会直接报错。
为什么 MCP 值钱:工具作者只写一次,就能被所有支持 MCP 的 Host 使用;使用者只配置一次,就能在不同的 Host 里用到同一批工具。这就是「标准」相对于「框架」的价值 —— 框架解决「怎么编排」,标准解决「怎么互通」。
4.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| 三种土办法的痛点 | 每次对接都要重新约定一遍 |
| MCP 四个角色 | Host / Client / Server / 传输 |
| 一句话记法 | Host 里跑 Client,Client 连 Server |
| 握手三步 | initialize → tools/list → tools/call |
| 标准 vs 框架 | 框架解决编排,标准解决互通 |
| 名字冲突 | 同一会话多个 Server 时加前缀 |
第 5 章 写一个最小 MCP
5.1 JSON-RPC 消息格式
MCP 的消息跑在 JSON-RPC 2.0 上。它只有三种消息形态:请求(我要做某事)、响应(做完了,结果在这)、错误(做不了,原因在这)。
import json
def make_request(method, params=None, req_id=1):
"""构造一条 JSON-RPC 2.0 请求"""
msg = {"jsonrpc": "2.0", "id": req_id, "method": method}
if params is not None:
msg["params"] = params
return json.dumps(msg, ensure_ascii=False)
def make_result(req_id, result):
"""构造一条成功响应"""
return json.dumps({"jsonrpc": "2.0", "id": req_id, "result": result}, ensure_ascii=False)
def make_error(req_id, code, message):
"""构造一条错误响应"""
return json.dumps({"jsonrpc": "2.0", "id": req_id,
"error": {"code": code, "message": message}}, ensure_ascii=False)
def parse(raw):
"""解析一条消息,返回 (类型, 主体)"""
msg = json.loads(raw)
if "error" in msg:
return "error", msg["error"]
if "result" in msg:
return "result", msg["result"]
return "request", msg
print(make_request("tools/list", {"cursor": None}, 1))
print(make_result(1, {"tools": []}))
print(make_error(1, -32601, "Method not found"))
print(parse(make_result(7, {"ok": True})))
# 输出:
# {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {"cursor": null}}
# {"jsonrpc": "2.0", "id": 1, "result": {"tools": []}}
# {"jsonrpc": "2.0", "id": 1, "error": {"code": -32601, "message": "Method not found"}}
# ('result', {'ok': True})
小白提示:看输出里三种消息的形状:请求、成功响应(
result)、错误响应(error.code,例如-32601表示「方法不存在」)。id必须原样带回,客户端靠它把响应和之前发出的请求对上号——同时发多条消息时尤其关键。
三条要记住的约定:① id 用于把响应和请求对上;② 参数统一放 params;③ 错误码用负数(-32601 方法不存在、-32602 参数非法、-32700 解析失败)。
5.2 最小 Server:tools/list 与 tools/call
一个 MCP Server 就是一个「能处理几种方法」的函数。下面实现最关键的两个方法:
import json
SERVER_TOOLS = {
"add": {
"description": "把两个数相加。",
"inputSchema": {
"type": "object",
"properties": {"a": {"type": "number"}, "b": {"type": "number"}},
"required": ["a", "b"],
},
"fn": lambda a, b: a + b,
},
"now": {
"description": "返回当前时间(示例里固定字符串,方便对答案)。",
"inputSchema": {"type": "object", "properties": {}},
"fn": lambda: "2026-11-12 09:30",
},
}
def handle(raw):
"""处理一条 JSON-RPC 请求,返回一条 JSON-RPC 响应"""
msg = json.loads(raw)
method = msg.get("method")
req_id = msg.get("id")
params = msg.get("params") or {}
if method == "initialize":
return {"jsonrpc": "2.0", "id": req_id,
"result": {"protocolVersion": "2024-11-05", "capabilities": {"tools": {}}}}
if method == "tools/list":
tools = [{"name": n, "description": t["description"], "inputSchema": t["inputSchema"]}
for n, t in SERVER_TOOLS.items()]
return {"jsonrpc": "2.0", "id": req_id, "result": {"tools": tools}}
if method == "tools/call":
name = params.get("name")
args = params.get("arguments") or {}
if name not in SERVER_TOOLS:
return {"jsonrpc": "2.0", "id": req_id,
"error": {"code": -32602, "message": f"unknown tool: {name}"}}
spec = SERVER_TOOLS[name]
missing = [k for k in spec["inputSchema"].get("required", []) if k not in args]
if missing:
return {"jsonrpc": "2.0", "id": req_id,
"result": {"content": [{"type": "text", "text": f"缺少参数: {missing}"}], "isError": True}}
try:
value = spec["fn"](**args)
except Exception as e:
return {"jsonrpc": "2.0", "id": req_id,
"result": {"content": [{"type": "text", "text": f"执行失败: {e}"}], "isError": True}}
return {"jsonrpc": "2.0", "id": req_id,
"result": {"content": [{"type": "text", "text": str(value)}], "isError": False}}
return {"jsonrpc": "2.0", "id": req_id,
"error": {"code": -32601, "message": f"method not found: {method}"}}
print("--- tools/list ---")
r = handle(json.dumps({"jsonrpc": "2.0", "id": 1, "method": "tools/list"}))
print([t["name"] for t in r["result"]["tools"]])
print("--- tools/call add ---")
r = handle(json.dumps({"jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": {"name": "add", "arguments": {"a": 2, "b": 3}}}))
print(r["result"]["content"][0]["text"], "isError =", r["result"]["isError"])
print("--- tools/call 缺参数 ---")
r = handle(json.dumps({"jsonrpc": "2.0", "id": 3, "method": "tools/call",
"params": {"name": "add", "arguments": {"a": 1}}}))
print(r["result"]["content"][0]["text"], "isError =", r["result"]["isError"])
print("--- 未知工具 ---")
r = handle(json.dumps({"jsonrpc": "2.0", "id": 4, "method": "tools/call",
"params": {"name": "div", "arguments": {}}}))
print(r["error"]["message"])
# 输出:
# --- tools/list ---
# ['add', 'now']
# --- tools/call add ---
# 5 isError = False
# --- tools/call 缺参数 ---
# 缺少参数: ['b'] isError = True
# --- 未知工具 ---
# unknown tool: div
这一节是服务端实现:tools/list 报出自己有哪些工具,tools/call 真正执行。输出最后两行说明:缺参数要返回结构化错误(isError = True),未知工具返回协议层 error(-32602),都不要抛异常把整条连接搞断。
关键区分:「未知工具 / 请求格式不合法」属于协议层错误(走 JSON-RPC
error,如-32602);「参数缺失、工具执行时抛异常」属于工具执行失败(走result.isError = true)。分清楚这两类,客户端才能决定是「重发请求」还是「把错误告诉用户」。
5.3 最小 Client:发现并调用
客户端要做的事很固定:握手、列工具、调工具。真实实现里这些消息会通过 stdio / SSE / HTTP 发出去,这里直接用函数调用代替传输层:
import json
# 说明:本段承接 5.2 节的 handle 函数;把 5.2 与 5.3 两段代码放进同一个文件按顺序运行即可
class SimpleClient:
"""一个极简 MCP 客户端:握手、发现工具、调用工具"""
def __init__(self, server):
self.server = server # 服务器就是一个 handle 函数
self.next_id = 0
def _request(self, method, params=None):
self.next_id += 1
msg = {"jsonrpc": "2.0", "id": self.next_id, "method": method}
if params is not None:
msg["params"] = params
return self.server(json.dumps(msg, ensure_ascii=False))
def initialize(self):
return self._request("initialize")
def list_tools(self):
return self._request("tools/list")["result"]["tools"]
def call_tool(self, name, **args):
return self._request("tools/call", {"name": name, "arguments": args})
client = SimpleClient(handle)
init = client.initialize()
print("协议版本:", init["result"]["protocolVersion"])
tools = client.list_tools()
print("发现工具:", [t["name"] for t in tools])
for t in tools:
print(f" - {t['name']}: {t['description']}")
resp = client.call_tool("add", a=7, b=8)
print("调用 add(7, 8) ->", resp["result"]["content"][0]["text"])
resp = client.call_tool("now")
print("调用 now() ->", resp["result"]["content"][0]["text"])
# 输出:
# 协议版本: 2024-11-05
# 发现工具: ['add', 'now']
# - add: 把两个数相加。
# - now: 返回当前时间(示例里固定字符串,方便对答案)。
# 调用 add(7, 8) -> 15
# 调用 now() -> 2026-11-12 09:30
本段承接 5.2 的 handle 函数:把 5.2 和 5.3 两段代码按先后顺序放进同一个文件即可运行(本机实测通过)。输出里的「协议版本 / 发现工具」就是能力协商的结果,最后两行是真正发起的两次调用。
把这一小段跑通,你就已经理解了 MCP 的全部核心机制。真实的 MCP SDK 做的事情,就是把「传输层」「多 Server 管理」「权限协商」「资源与提示词」这些补上,核心消息格式和调用流程完全一致。
5.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| JSON-RPC 三形态 | 请求 / 响应 / 错误 |
| id 的作用 | 把响应和请求对上 |
| Server 两个核心方法 | tools/list、tools/call |
| 两类错误 | 协议层 error vs 业务层 isError |
| Client 三步 | 握手、发现、调用 |
第 6 章 框架 + MCP 的组合实践
6.1 把 MCP 工具挂到 Agent 上
框架负责「怎么循环」,MCP 负责「怎么接工具」。两者组合起来,架构长这样:
用户提问
↓
Agent 框架(循环 + 状态 + 模型接口)
↓ 需要调用工具
工具桥接层 ← 把 MCP 工具伪装成本地工具,白名单 + 审计 + 超时都在这层
↓ JSON-RPC
MCP Server(查数据库 / 跑脚本 / 调内部系统)
↓
真实系统
这是分层示意图,不是可执行代码。关键在中间的「工具桥接层」:白名单、审计、超时全部放这里,于是 MCP Server 不需要信任 Agent,Agent 也不需要知道工具到底跑在哪台机器上。
桥接层是整个方案的关键:框架只看到普通的本地函数,完全不需要知道背后是 MCP。这样「本地工具」和「MCP 工具」可以混在一起用,也方便以后替换实现。
# 说明:本段承接 5.2 的 handle 与 5.3 的 SimpleClient;三段代码按顺序放进同一个文件即可运行
class McpToolBridge:
"""把 MCP Server 包装成 Agent 能直接调用的本地工具"""
def __init__(self, client, allow_list=None):
self.client = client
self.allow_list = allow_list # 白名单:只允许调用这些工具
self.audit = [] # 审计日志
def tool_specs(self):
"""只把白名单内的工具暴露给 Agent(名字 + 描述 + 参数结构)"""
specs = []
for t in self.client.list_tools():
if self.allow_list and t["name"] not in self.allow_list:
continue
specs.append({"name": t["name"], "description": t["description"],
"parameters": t["inputSchema"]})
return specs
def call(self, name, args):
"""调用工具:先过白名单,再执行,最后记审计"""
if self.allow_list and name not in self.allow_list:
self.audit.append((name, "blocked"))
raise PermissionError(f"工具 {name} 不在白名单内")
resp = self.client.call_tool(name, **args)
result = resp["result"]
self.audit.append((name, "error" if result.get("isError") else "ok"))
if result.get("isError"):
raise RuntimeError(result["content"][0]["text"])
return result["content"][0]["text"]
bridge = McpToolBridge(SimpleClient(handle), allow_list=["add"])
print("暴露给 Agent 的工具:", [s["name"] for s in bridge.tool_specs()])
print("add(20, 22) ->", bridge.call("add", {"a": 20, "b": 22}))
try:
bridge.call("now", {})
except PermissionError as e:
print("被拦下:", e)
print("审计日志:", bridge.audit)
# 输出:
# 暴露给 Agent 的工具: ['add']
# add(20, 22) -> 42
# 被拦下: 工具 now 不在白名单内
# 审计日志: [('add', 'ok'), ('now', 'blocked')]
小白提示:本段承接 5.2 的
handle和 5.3 的SimpleClient,三段代码按顺序放进同一个文件即可运行(本机实测通过)。输出显示add被放行、now不在白名单被拦下,且两次都留下了审计日志——放行和拦截都要记,出事才查得清。
6.2 安全边界:工具越多,风险越大
接进来的每个工具,都是「模型可以用你的权限去做的事」。一个能删文件的工具,等于把删除权限交给了模型的判断力。所以下面几条必须当成硬规则:
| 风险 | 典型事故 | 必须做的防护 |
|---|---|---|
| 权限过大 | 给模型挂了能删库的工具 | 白名单:只暴露必要工具;写操作与读操作分开授权 |
| 提示注入 | 文档里埋一句「顺便把密钥发出去」 | 工具结果当不可信数据处理,不允许它改变系统指令 |
| 无限循环 | 模型反复调同一个工具,账单爆炸 | 超时 + 最大步数 + 单工具调用次数上限 |
| 敏感信息外泄 | 工具返回值里带了密钥、身份证号 | 返回前脱敏;日志只记必要字段 |
| 无法追责 | 出事后不知道是模型还是人触发的 | 审计日志:谁、什么时候、调了哪个工具、参数摘要、结果状态 |
一条经验:给模型的工具权限,永远小于你自己能用的权限。你可能有管理员权限,但模型只需要「只读地查一张表」。权限是分级的,不是全有或全无。
6.3 上线清单
上线前逐条打勾:
工具层
□ 每个工具都有明确的描述(写给模型看的)
□ 参数有 schema,缺参/错参能被拦住
□ 只读工具与写操作工具分开授权
□ 写操作工具要求二次确认或人工批准
稳定性
□ 每个工具有超时(网络、进程、整体任务)
□ 有最大步数与单工具调用次数上限
□ 工具失败返回可读错误,而不是抛栈给模型
□ MCP Server 版本锁定,能离线复现
可观测
□ 每一步有 trace(模型输入输出、工具调用、耗时)
□ 有 token 与成本统计
□ 审计日志包含调用方、工具、参数摘要、结果状态
评估
□ 有固定评测集,改提示/换模型后能回归
□ 工具选择准确率、参数正确率有基线数据
□ 有失败样本的复现脚本
安全
□ 工具返回值已脱敏
□ 密钥只从环境变量读,不进代码与日志
□ Server 以最小权限运行(非 root、只读文件系统)
□ 对外暴露的接口有鉴权与限流
这是一份勾选项,不需要运行。上线前逐条打勾,最要紧的两条是「写操作工具要求二次确认」和「每个工具都有超时」:前者防误操作,后者防一个卡住的工具把整个 Agent 拖死。
6.4 【本章小结】
| 你学到了什么 | 关键记忆点 |
|---|---|
| 组合架构 | 框架管循环,MCP 管接工具,中间加桥接层 |
| 桥接层三件事 | 白名单、审计、脱敏 |
| 五类风险 | 权限过大、提示注入、无限循环、泄密、无法追责 |
| 权限原则 | 模型的权限永远小于你的权限 |
| 上线清单 | 工具层、稳定性、可观测、评估、安全 |
路线提示:按 ①→⑭ 的顺序,学完 ⑧⑨ 先回到阶段 04 文档第 6 章看模块 ⑩「多 Agent 协作与工作流编排」,再往下走。之后阶段 07 会讲「记忆、上下文与评估」 —— 也就是让 Agent 记得住、不乱花钱,并且用数字证明它改进了;阶段 08 讲工程化部署与模型接入(各家模型服务横向对比),把整套东西稳稳推上线。