文档首页
阶段 06 · Agent 框架与 MCP 协议 在线知识文档
学习路线 第 6 / 6 步 · 模块 ⑧⑨Agent 框架 / MCP 协议← 上一站 ⑦ RAG 检索增强下一站 回看 ⑩ 多 Agent 协作 →按路线下一步回到 RAG 文档第 6 章看 ⑩;之后 ⑪~⑭ 编写中完整顺序:① Python → ② FastAPI → ③④ Prompt → ⑤⑥ Agent → ⑦ RAG → ⑧⑨ 框架与 MCP → ⑩ 多 Agent(回看)→ ⑪~⑭ 编写中 · 查看学习路线图 →

从手写循环,到标准化工具生态

阶段 03 你亲手写过一个 Agent 循环,阶段 05 你把它包成了服务。这一阶段解决两个问题:要不要用框架,以及怎么让工具接入变成标准动作而不是每个项目重写一遍。前半程讲框架的共同骨架与选型方法,后半程讲 MCP 协议并手写一个最小实现。全程只用标准库,不联网、不需要 API 密钥。

去做在线自测 → AI Agents 学习路线 →
6个章节
24个小节
30道章末小测
测
配套推荐
Agent 框架与 MCP 协议在线自测 - 我的图片

按 6 个模块、L1~L5 难度自己测一遍,10 题一组即答即批,适合学完几章之后查漏补缺。 链接:https://myimage.cn/framework-mcp/

打开在线自测 →

全部章节

第 01 章

第 1 章 从手写循环到框架

1.1 回顾:那个手写的循环

阶段 03 我们手写过一个最小 Agent 循环,回忆一下它的结构:模型输出 → 判断是不是要调工具 → 执行工具 → 把结果塞回消息列表 → 再问模型,直到模型不再要调工具。

PYTHON
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、少工具、单人项目
框架的代价抽象泄漏、版本漂移、调试难、概念多
正确顺序先手写,再上框架
第 02 章

第 2 章 框架的共同骨架

2.1 四件套:模型、工具、循环、状态

框架名字千变万化,骨架却高度一致。搞清楚这四件套,换任何框架都能快速上手:

部件职责你在业务里会写什么
模型接口发消息、拿回复,支持流式选模型、设温度、传提示
工具注册声明有哪些工具、参数长什么样写工具函数与描述
执行循环模型要调工具就调,直到收敛设最大步数、终止条件
状态消息列表、记忆、检查点决定记什么、留多久

不同框架的差别,基本都落在这四格里:模型接口抽象得深不深、工具定义方不方便、循环可控不可控、状态是隐形还是显式。

2.2 工具抽象:描述 + 参数模式 + 执行函数

一个工具被模型用起来,模型需要知道三件事:它叫什么、什么时候该用、参数怎么填。所以工具定义通常是「一份 JSON Schema + 一个执行函数 + 一段自然语言描述」。

PYTHON
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 的状态说白了就是一串消息。框架在此之上加的东西,本质都是围绕这串消息做文章:裁剪、持久化、回放。

PYTHON
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 + 执行函数
描述写给模型看说清何时用、何时别用
状态就是消息列表裁剪、持久化、回放都围着它
要自己定的事裁剪策略、检查点频率
第 03 章

第 3 章 怎么选框架

3.1 四个评估维度

别问「哪个框架最好」,要问「我的场景在哪一格」。四个维度基本能覆盖所有决策:

维度要问的问题为什么关键
抽象层次它替你管多少?你还能不能自己控制循环?抽象太高,一旦不够用就只能绕过去
状态管理状态是隐式的还是显式的?能不能存取和回放?长任务、失败重试、调试全靠它
工具生态现成工具多不多?能不能接自己的工具?决定你能不能少写代码
可观测性有没有 trace、日志、指标、回调?线上出问题时唯一的救命稻草

3.2 四类方案

类型典型形态适合不适合
通用 Agent 框架提供模型抽象、工具、循环、记忆的一站式套件多工具、多模型、要快速起步流程特别确定、想完全掌控每一步
RAG / 数据编排框架围绕检索、索引、重排、引用设计知识库问答是主要场景任务需要大量工具调用与分支判断
轻量自研几十行代码自己封装单 Agent、工具少、要极致可控多 Agent、要接很多外部系统
云厂商 SDK和自家模型、网关、鉴权深度打通就用它家的模型、要在它家环境里跑未来想换模型、想多云

一条实用建议:先用轻量自研把业务跑通,再决定要不要上框架。反过来先学框架,很容易陷入「学了一堆抽象,业务还没跑起来」。

3.3 选型决策树

TEXT
你的项目有多少个工具?
├─ 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
第 04 章

第 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 的交互是典型的「先握手,再干活」:

TEXT
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 时加前缀
第 05 章

第 5 章 写一个最小 MCP

5.1 JSON-RPC 消息格式

MCP 的消息跑在 JSON-RPC 2.0 上。它只有三种消息形态:请求(我要做某事)、响应(做完了,结果在这)、错误(做不了,原因在这)。

PYTHON
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 就是一个「能处理几种方法」的函数。下面实现最关键的两个方法:

PYTHON
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 发出去,这里直接用函数调用代替传输层:

PYTHON
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 三步握手、发现、调用
第 06 章

第 6 章 框架 + MCP 的组合实践

6.1 把 MCP 工具挂到 Agent 上

框架负责「怎么循环」,MCP 负责「怎么接工具」。两者组合起来,架构长这样:

TEXT
用户提问
   ↓
Agent 框架(循环 + 状态 + 模型接口)
   ↓ 需要调用工具
工具桥接层  ← 把 MCP 工具伪装成本地工具,白名单 + 审计 + 超时都在这层
   ↓ JSON-RPC
MCP Server(查数据库 / 跑脚本 / 调内部系统)
   ↓
真实系统

这是分层示意图,不是可执行代码。关键在中间的「工具桥接层」:白名单、审计、超时全部放这里,于是 MCP Server 不需要信任 Agent,Agent 也不需要知道工具到底跑在哪台机器上。

桥接层是整个方案的关键:框架只看到普通的本地函数,完全不需要知道背后是 MCP。这样「本地工具」和「MCP 工具」可以混在一起用,也方便以后替换实现。

PYTHON
# 说明:本段承接 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 上线清单

TEXT
上线前逐条打勾:

工具层
  □ 每个工具都有明确的描述(写给模型看的)
  □ 参数有 schema,缺参/错参能被拦住
  □ 只读工具与写操作工具分开授权
  □ 写操作工具要求二次确认或人工批准

稳定性
  □ 每个工具有超时(网络、进程、整体任务)
  □ 有最大步数与单工具调用次数上限
  □ 工具失败返回可读错误,而不是抛栈给模型
  □ MCP Server 版本锁定,能离线复现

可观测
  □ 每一步有 trace(模型输入输出、工具调用、耗时)
  □ 有 token 与成本统计
  □ 审计日志包含调用方、工具、参数摘要、结果状态

评估
  □ 有固定评测集,改提示/换模型后能回归
  □ 工具选择准确率、参数正确率有基线数据
  □ 有失败样本的复现脚本

安全
  □ 工具返回值已脱敏
  □ 密钥只从环境变量读,不进代码与日志
  □ Server 以最小权限运行(非 root、只读文件系统)
  □ 对外暴露的接口有鉴权与限流

这是一份勾选项,不需要运行。上线前逐条打勾,最要紧的两条是「写操作工具要求二次确认」和「每个工具都有超时」:前者防误操作,后者防一个卡住的工具把整个 Agent 拖死。

6.4 【本章小结】

你学到了什么关键记忆点
组合架构框架管循环,MCP 管接工具,中间加桥接层
桥接层三件事白名单、审计、脱敏
五类风险权限过大、提示注入、无限循环、泄密、无法追责
权限原则模型的权限永远小于你的权限
上线清单工具层、稳定性、可观测、评估、安全

路线提示:按 ①→⑭ 的顺序,学完 ⑧⑨ 先回到阶段 04 文档第 6 章看模块 ⑩「多 Agent 协作与工作流编排」,再往下走。之后阶段 07 会讲「记忆、上下文与评估」 —— 也就是让 Agent 记得住、不乱花钱,并且用数字证明它改进了;阶段 08 讲工程化部署与模型接入(各家模型服务横向对比),把整套东西稳稳推上线。