06.4 阶段 3:工具调用与 MCP 协议
所属:全栈开发面试题库 / 学习路径 / 06 AI Agent
本页目录
一、阶段定位
到目前为止模型只能"说",不能"做"。本阶段让模型学会调用外部工具——查天气、查数据库、调内部 API、执行计算。这是 Agent 的基础:模型负责决策,工具负责执行,二者通过结构化消息循环。
为什么这是阶段 3:前面的结构化输出(阶段 2)解决了"模型吐 JSON",本阶段的工具调用本质是把 JSON 输出定向到一个工具函数上——模型不再自己编答案,而是说"请调用 get_weather(city=北京)"。理解了这个循环,后面的 RAG(阶段 4)、Agent 编排(阶段 5)都是它的扩展。
与前后阶段的衔接:往上接 阶段 2 Prompt 工程,工具的 parameters 就是 JSON Schema,直接复用;往下接 阶段 4 RAG,RAG 的检索器本身就是一个工具;再接 阶段 5 Agent 编排,多步决策循环就是反复的"模型决策→工具执行→结果回填"。跳过本阶段直接写 Agent,常见后果是:工具描述含糊导致模型选错工具、工具不幂等导致重试产生重复动作、把写操作直接开放给模型不加确认。
本阶段的卡点(判断依据):
- 工具描述含糊导致模型选错工具:现象是你给了"查天气"和"查订单"两个工具,模型该查订单却调了天气。判断标准:你能否写出一句话工具描述,说清这个工具做什么、什么时候用、什么时候不用。
- 工具不幂等,重试后产生重复动作:现象是重试一次"提交订单",结果下了两单。判断标准:你能否说清哪些工具是只读的(可安全重试)、哪些是写操作(需幂等键或人工确认)。
- 把敏感写操作直接开放给模型而不加确认:现象是模型可以直接调"转账"工具。判断标准:你能否指出哪些工具必须加人工确认环节。
- 工具报错只抛异常不返回可读信息:现象是工具失败后模型收到一个空响应或 HTTP 500,无法自我修正。判断标准:你能否把工具失败包装成模型能读懂的文本消息回填。
二、阶段目标与投入
| 能力目标(可验证的行为) | 验证方式 |
|---|---|
| 能在请求中声明 tools 并解析模型返回的 tool_calls | 模型对"北京天气"返回正确的工具名与参数 |
| 能实现工具执行并把结果回填为 tool 角色消息 | 多轮对话中模型基于工具结果给出最终回答 |
| 能设计工具 schema(描述、参数、幂等) | 3 个工具各有清晰描述与参数约束 |
| 能把工具失败包装成可读错误让模型重试或改道 | 工具超时后模型换方案而非崩溃 |
| 能说出 MCP 的 initialize/tools/list/tools/call 消息流 | 口述一次 MCP 握手到调用的完整过程 |
| 能区分只读工具与写操作工具的权限边界 | 写操作工具加人工确认,只读工具可自动执行 |
建议学时:
- 全职(每天 4–6 小时):2 周,约 50 小时。其中 Function Calling 消息循环 14 小时、工具设计 10 小时、错误与重试 10 小时、MCP 协议 10 小时、沙箱与权限 6 小时。
- 在职(每天 2 小时、周末补 4 小时):4–5 周,约 55 小时。消息循环要动手跑通,不要只看说明。
学时分配:Function Calling 消息格式 25%、工具设计 20%、错误返回与重试 15%、并行调用 10%、MCP 协议 20%、沙箱权限 10%。消息循环是核心。
三、先修自检
| 先修项 | 合格标准 | 不合格时回到 |
|---|---|---|
| chat completions 与 messages | 能发请求并解析响应 | 06.1 阶段 0 |
| JSON Schema | 能写字段类型与必填约束 | 06.3 阶段 2 |
| 采样参数 | 能用 temperature=0 拿到稳定工具调用 | 06.2 阶段 1 |
| HTTP 状态码 | 能读 4xx/5xx 并处理 | 01.2 计算机网络 |
经验判断:如果你写过后端接口,最容易理解的是"工具就是一个 HTTP/RPC 接口,模型在帮你拼请求参数";最容易忽视的是"模型可能拼错参数,你必须校验"。
四、知识地图
| 模块 | 知识点 | 掌握程度 | 对应题库章节 |
|---|---|---|---|
| Function Calling | tools、tool_calls、tool 角色、finish_reason |
能讲清原理 | 10.4 Agent 架构 |
| 工具设计 | 描述、参数 schema、幂等、粒度 | 会用 | 10.4 Agent 架构 |
| 错误与重试 | 工具失败回填、模型自我修正 | 会用 | 10.4 Agent 架构 |
| 并行调用 | 一次多个 tool_calls、并发执行 | 会用 | 10.4 Agent 架构 |
| MCP 协议 | initialize/tools/list/tools/call、Server/Client | 能讲清原理 | 10.4 Agent 架构 |
| 沙箱与权限 | 最小权限、人工确认、写操作边界 | 会用 | 11.4 安全与合规 |
进度管理建议:用 3 个工具(检索、计算、外部 API)贯穿本阶段。《知识点全清单》给全量条目;术语查《术语表》;项目实战参考《实战项目阶梯》。
五、分模块精讲
5.1 Function Calling 原理与消息格式
为什么需要它:模型不能直接访问你的数据库和 API,它只能"说"。Function Calling 让模型在需要时输出一个结构化的"调用请求",你的代码真正执行工具后把结果喂回模型,模型再基于结果回答。这是 Agent 的最小循环。
核心机制:
- 请求体加
tools数组,每个工具含type: "function"、function.name、function.description、function.parameters(JSON Schema)。 - 模型判断需要调工具时,响应的
finish_reason为tool_calls,message.tool_calls里给出工具名、参数(JSON 字符串)、一个id。 - 你的代码执行工具,把结果用
role: "tool"的消息回填,带上tool_call_id对应之前的调用。 - 然后再次调用模型(带上更新后的 messages),模型基于工具结果给出最终回答,
finish_reason变回stop。 - 完整循环:用户输入 → 模型返回 tool_calls → 执行 → 回填 tool 消息 → 模型最终回答。
最小可运行示例:
# function_calling.py:一次完整的工具调用循环
import json
import httpx
from config import BASE_URL, API_KEY, MODEL, auth_header
# 1. 声明工具
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的实时天气。当用户问天气、气温、是否下雨时使用。",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名,如 北京"}
},
"required": ["city"],
},
},
}]
# 2. 工具实现(这里用假数据演示)
def get_weather(city: str) -> str:
return json.dumps({"city": city, "temp": 22, "weather": "晴"}, ensure_ascii=False)
messages = [{"role": "user", "content": "北京今天天气怎么样?"}]
# 3. 第一次请求:模型可能要求调工具
r = httpx.post(f"{BASE_URL}/chat/completions", headers=auth_header(),
json={"model": MODEL, "messages": messages, "tools": tools,
"temperature": 0}, timeout=30.0)
data = r.json()
msg = data["choices"][0]["message"]
messages.append(msg) # 把 assistant 的 tool_calls 消息加回
if data["choices"][0]["finish_reason"] == "tool_calls":
for call in msg["tool_calls"]:
name = call["function"]["name"]
args = json.loads(call["arguments"])
result = get_weather(**args)
# 4. 回填 tool 角色消息,带 tool_call_id
messages.append({"role": "tool", "tool_call_id": call["id"], "content": result})
# 5. 第二次请求:模型基于工具结果回答
r2 = httpx.post(f"{BASE_URL}/chat/completions", headers=auth_header(),
json={"model": MODEL, "messages": messages, "tools": tools,
"temperature": 0}, timeout=30.0)
print(r2.json()["choices"][0]["message"]["content"])
# 输出类似:北京今天晴,气温 22 摄氏度。
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 模型不调工具直接编答案 | 工具描述不清或任务不需要 | 优化 description;明确"需要实时信息时调用" |
tool_call_id 对不上 |
回填时 id 没对应 | 严格按 call["id"] 填 tool_call_id |
| 模型返回的 arguments 不是合法 JSON | 参数描述不清 | 用 JSON Schema 约束;解析失败时把错误回填让模型重试 |
finish_reason 一直是 tool_calls |
工具结果没回填或模型继续要求调工具 | 检查是否每次都把 tool 消息加回 |
面试考法:必问"Function Calling 的完整消息流是什么"。要答出:请求带 tools → 模型返回 tool_calls(含 id、函数名、参数)→ 代码执行 → 用 role: tool + tool_call_id 回填 → 再次请求 → 模型给最终答案。追问常问"finish_reason 为 tool_calls 意味着什么",答到"模型没有直接回答,而是请求调用工具,需要你执行后回填"。
5.2 工具设计原则:描述、参数、幂等、粒度
为什么需要它:工具设计直接决定模型能不能选对、调对。描述含糊、参数模糊、粒度不当,都会让工具调用失败。
核心机制:
- 工具描述(description)要说清:做什么、什么时候用、什么时候不用。这是模型选工具的唯一依据。
- 参数 schema 要具体:每个参数写
description,类型明确,枚举值用enum。 - 粒度:一个工具做一件事,不要把"查天气+发邮件"塞进一个工具。工具太粗模型不知道怎么调,太细工具列表过长。
- 幂等:只读工具(查询)可安全重试;写操作(下单、转账)要幂等键,避免重试产生重复动作。
- 工具数量控制在合理范围(5–15 个),过多会让模型选错。
最小可运行示例:
# good_tools.py:好工具 vs 坏工具描述
# 坏:描述模糊,模型不知道何时用
bad = {"name": "do_stuff", "description": "处理用户请求"}
# 好:说清用途、触发条件、参数
good = {
"type": "function",
"function": {
"name": "create_order",
"description": "创建一笔订单。仅在用户明确要求下单且已确认商品与金额时调用。不要用它查询订单。",
"parameters": {
"type": "object",
"properties": {
"product_id": {"type": "string", "description": "商品 ID"},
"amount": {"type": "number", "description": "金额,单位元"},
"idempotency_key": {"type": "string", "description": "幂等键,同一请求重复提交不会创建多笔"}
},
"required": ["product_id", "amount", "idempotency_key"],
},
},
}
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 模型选错工具 | description 没写"什么时候不用" | 描述里写"不要用它做 X" |
| 参数传错类型 | 没写参数描述 | 每个参数加 description 与类型 |
| 重试产生重复下单 | 写操作没幂等键 | 加 idempotency_key,服务端去重 |
| 工具太多模型混乱 | 一个工具做太多事 | 拆成单一职责工具 |
面试考法:问"怎么设计一个好工具"。要点:描述说清做什么/何时用/何时不用;参数 schema 具体;单一职责;写操作要幂等键;工具数量适中。追问常问"为什么要写什么时候不用",答到"避免模型把相近工具搞混,显式排除边界比隐式让模型判断更可靠"。
5.3 工具错误返回与重试
为什么需要它:工具会失败(超时、参数错、外部 API 500)。如果你的代码直接抛异常,模型收到一个空响应,无法自我修正。正确做法是把错误包装成模型能读懂的文本,回填给模型,让它决定重试、改参数还是换方案。
核心机制:
- 工具执行要 try/except,把错误信息写成 JSON 或文本,作为
role: tool的 content 回填。 - 错误信息要包含:失败原因、建议怎么改(如"参数 city 缺失,请提供城市名")。
- 模型看到错误后会自己修正参数重试,或换工具。
- 对超时类错误,可在代码层做有限次重试(指数退避),再把最终结果回填。
最小可运行示例:
# tool_error.py:把错误包装成可读消息回填
def call_tool(name: str, args: dict) -> str:
try:
if name == "get_weather":
if "city" not in args:
# 不抛异常,返回错误文本让模型修正
return json.dumps({"error": "缺少参数 city", "hint": "请提供城市名后重试"}, ensure_ascii=False)
return get_weather(args["city"])
return json.dumps({"error": f"未知工具 {name}"}, ensure_ascii=False)
except Exception as e:
return json.dumps({"error": str(e), "hint": "工具执行失败,请检查参数或换方案"}, ensure_ascii=False)
# 回填:content 就是上面的错误 JSON
messages.append({"role": "tool", "tool_call_id": call["id"], "content": call_tool(name, args)})
# 再次请求模型,它会看到错误并自我修正
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 工具失败后模型崩溃 | 代码直接抛异常没回填 | try/except,错误写成文本回填 |
| 模型反复重试同一错误参数 | 错误信息没说怎么改 | 错误里带 hint,告诉模型修正方向 |
| 工具超时一直挂着 | 没设超时 | 给工具调用设 timeout,超时返回错误 |
面试考法:问"工具失败了怎么办"。要点:不要让异常冒到模型外,把错误原因与修正建议写成文本回填为 tool 消息,模型据此改参数或换方案;代码层对超时做有限重试。
5.4 并行工具调用
为什么需要它:当用户问"北京和上海的天气",模型可以一次返回两个 tool_calls,你的代码并发执行,而不是串行等一个再问一个。这能显著降延迟。
核心机制:
- 模型一次返回多个
tool_calls在message.tool_calls数组里。 - 你的代码遍历数组,并发执行每个工具,然后按顺序把每个结果回填成对应的
role: tool消息。 - 回填顺序要和 tool_calls 顺序一致,每个带自己的
tool_call_id。 - 并行只对只读无依赖的工具有意义;有依赖的(A 的结果是 B 的参数)必须串行。
最小可运行示例:
# parallel_tools.py:并发执行多个 tool_calls
from concurrent.futures import ThreadPoolExecutor
def run_parallel(tool_calls: list[dict]) -> list[dict]:
def one(call):
name = call["function"]["name"]
args = json.loads(call["arguments"])
return {"id": call["id"], "content": call_tool(name, args)}
with ThreadPoolExecutor(max_workers=5) as ex:
return list(ex.map(one, tool_calls))
# 把每个结果回填为独立 tool 消息
for res in run_parallel(msg["tool_calls"]):
messages.append({"role": "tool", "tool_call_id": res["id"], "content": res["content"]})
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 并行结果顺序错乱 | 回填顺序与调用顺序不一致 | 按 tool_call_id 对应回填 |
| 有依赖的工具被并行 | B 需要 A 的结果 | 检测依赖关系,串行执行 |
面试考法:问"什么时候并行调用工具,什么时候串行"。要点:只读、无依赖的工具可并行降延迟;有数据依赖(A 输出是 B 输入)必须串行。
5.5 MCP 协议:服务端与客户端
为什么需要它:Function Calling 是你自己写的工具,每个应用都要重复写对接逻辑。MCP(Model Context Protocol)是一个开放协议,定义了工具/资源/提示词如何被暴露和发现,让任意 Agent 客户端都能接任意 MCP Server,工具生态可复用。
核心机制:
- MCP 是客户端-服务器架构:MCP Client(你的 Agent/应用)连 MCP Server(提供工具、资源、提示词的服务)。
- 通信是 JSON-RPC 2.0 消息,常用三种消息:
initialize:客户端与服务端握手,协商协议版本与能力。tools/list:客户端请求服务端列出所有可用工具(含 schema)。tools/call:客户端请求调用某个工具,传 name 与 arguments。
- 与 Function Calling 的关系:MCP Server 把工具列表暴露给客户端,客户端把它们转成模型认识的
toolsschema;模型决定调用后,客户端通过tools/call转发给 MCP Server 执行。 - 传输方式:stdio(本地进程)或 SSE/HTTP(远程服务)。
最小可运行示例:
// MCP 消息示例(JSON-RPC 2.0)
// 1. 握手 initialize
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {"name": "my-agent", "version": "1.0"}
}
}
// 2. 列出工具 tools/list
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}
// 3. 调用工具 tools/call
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {"city": "北京"}
}
}
# mcp_flow.py:MCP 客户端侧的逻辑(伪代码)
# 1. 连接 MCP Server,发 initialize
# 2. tools/list 拿到工具 schema,转成模型 tools 参数
# 3. 模型返回 tool_calls 后,客户端用 tools/call 转发给 MCP Server
# 4. 把 Server 返回的 content 回填为 role: tool 消息
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| MCP Server 连不上 | 传输方式(stdio/SSE)配错 | 确认是本地 stdio 还是远程 SSE 端点 |
| 工具列表为空 | initialize 握手失败 | 检查 protocolVersion 与 capabilities |
| tools/call 参数格式错 | 没按 tools/list 返回的 schema 传 | 先 list 再按其 schema 构造 arguments |
面试考法:问"MCP 和 Function Calling 是什么关系"。要点:Function Calling 是模型侧的调用约定(模型输出 tool_calls);MCP 是工具的暴露与发现协议(客户端-服务器),MCP Server 把工具 schema 通过 tools/list 给客户端,客户端转成模型 tools,模型决定后客户端用 tools/call 转发执行。追问常问"initialize/tools/list/tools/call 各做什么",答到握手、列工具、调工具。
5.6 工具沙箱与权限边界
为什么需要它:模型可能被提示注入诱导去调用危险工具(删库、转账、发邮件给外部)。必须按最小权限设计,写操作要加确认。
核心机制:
- 最小权限:只读工具(查天气、查文档)可自动执行;写操作(下单、删除、发消息)要加人工确认。
- 敏感操作(转账、删除、对外发消息)在执行前返回"请确认是否执行",等用户同意。
- 沙箱:执行不可信代码(如模型生成的脚本)时,在隔离环境跑,限制网络与文件访问。
- 工具白名单:每个用户/角色只看到自己有权限的工具,不要把所有工具都暴露给所有会话。
最小可运行示例:
# permission.py:写操作加确认
SENSITIVE_TOOLS = {"create_order", "delete_record", "transfer"}
def execute(call_name: str, args: dict) -> str:
if call_name in SENSITIVE_TOOLS:
# 不直接执行,返回确认请求
return json.dumps({
"action": "need_confirmation",
"tool": call_name,
"args": args,
"prompt": f"即将执行 {call_name},参数 {args},请用户确认。"
}, ensure_ascii=False)
return call_tool(call_name, args) # 只读工具直接执行
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 模型被诱导调了删除工具 | 写操作没加确认 | 敏感工具返回 need_confirmation |
| 不同用户看到彼此的工具 | 没按角色过滤工具列表 | 按用户权限裁剪 tools 数组 |
| 模型生成的脚本直接跑 | 没沙箱隔离 | 在沙箱/容器里执行,限制网络 |
面试考法:问"怎么防止模型被注入后乱调工具"。要点:最小权限、写操作人工确认、工具按用户角色裁剪、不可信代码放沙箱、敏感操作审计日志。这部分在阶段 7 安全里展开。
六、分层练习
6.1 复现型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 跑通一个工具 | 实现 get_weather,完整消息循环 | 模型基于工具结果给出回答 | 2.5 小时 |
| 解析 tool_calls | 打印 tool_calls 的 id/name/arguments | 能说出三者作用 | 1 小时 |
| 回填 tool 消息 | 把工具结果用 role: tool 回填 | 第二次请求模型不再要求调工具 | 1.5 小时 |
| 错误回填 | 故意缺 city 参数,把错误回填 | 模型修正参数重试 | 1.5 小时 |
| MCP 消息格式 | 手写 initialize/tools/list/tools/call | 能口述三者顺序 | 1 小时 |
6.2 改造型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 优化工具描述 | 给定模糊的 do_stuff 工具,重写 description | 模型选对工具率提升 | 1.5 小时 |
| 加幂等键 | 给 create_order 加 idempotency_key | 重复提交不创建多笔 | 2 小时 |
| 并行工具 | 给定串行执行,改为 ThreadPool 并发 | 两个城市天气并发返回 | 1.5 小时 |
| 写操作加确认 | 给敏感工具加 need_confirmation | 不直接执行,等确认 | 2 小时 |
| 错误带 hint | 给所有工具错误加修正建议 | 模型看到错误能自我修正 | 1.5 小时 |
6.3 设计型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 三工具调用链路 | 检索、计算、外部 API 三个工具 | 20 条用例工具调用成功率 ≥80% | 6 小时 |
| 轨迹日志 | 每次调用的入参出参与决策写入日志 | 能回放一次完整决策过程 | 4 小时 |
| 工具权限设计 | 区分只读/写操作/敏感工具 | 敏感工具都有人工确认 | 4 小时 |
七、排障表
| 现象 | 可能原因 | 排查步骤 | 解决办法 |
|---|---|---|---|
| 模型不调工具直接编答案 | 工具描述不清 | 看 description 是否写清触发条件 | 优化描述,明确"实时信息时调用" |
tool_call_id 对不上 |
回填 id 错误 | 打印 tool_calls 与回填消息 | 严格按 call["id"] 填 |
| arguments 不是合法 JSON | 参数描述模糊 | 打印 arguments 原文 | 用 schema 约束;解析失败回填错误 |
| 工具失败模型崩溃 | 异常没回填 | 检查是否 try/except | 错误写成文本回填为 tool 消息 |
| 重试产生重复下单 | 写操作没幂等键 | 检查服务端去重 | 加 idempotency_key |
| MCP Server 连不上 | 传输方式配错 | 确认 stdio 还是 SSE | 按 Server 文档配传输 |
| 敏感工具被模型直接调用 | 没加确认 | 检查 SENSITIVE_TOOLS 列表 | 返回 need_confirmation |
| 并行结果顺序错乱 | 回填顺序与调用不一致 | 按 id 对应 | 按 tool_call_id 逐条回填 |
八、出口条件
全部勾选后再进入 阶段 4 RAG 检索增强。
- [ ] 能跑通完整 Function Calling 循环(tools → tool_calls → 执行 → 回填 → 最终回答)
- [ ] 能解释
finish_reason: tool_calls与role: tool、tool_call_id的配合 - [ ] 能设计带描述、参数 schema、幂等键的工具,区分只读与写操作
- [ ] 能把工具失败包装成模型可读的错误回填,让模型自我修正
- [ ] 能口述 MCP 的 initialize/tools/list/tools/call 消息流
- [ ] 能说出哪些工具必须加人工确认、哪些可自动执行
- [ ] 排障表随机抽三个现象能在 5 分钟内定位
自测题(先自己想,再看要点):
- 一次 Function Calling 循环里 messages 经历了哪几轮?
- 要点:用户输入 → 模型返回 tool_calls(finish_reason=tool_calls)→ 代码执行 → 追加 role: tool 消息 → 再次请求 → 模型最终回答(finish_reason=stop)。
tool_call_id有什么用?- 要点:把工具结果和之前模型请求的那个调用对应起来,一个 tool_calls 里可能有多个调用,必须靠 id 配对回填。
- 为什么工具描述里要写"什么时候不用"?
- 要点:避免模型把相近工具搞混,显式排除边界让模型选工具更可靠。
- 工具失败为什么不能直接抛异常给模型?
- 要点:模型收到异常无法自我修正;要把错误原因与修正建议写成文本回填为 tool 消息,模型据此改参数或换方案。
- MCP 的 initialize/tools/list/tools/call 各做什么?
- 要点:initialize 握手协商能力;tools/list 列出工具 schema;tools/call 调用指定工具传参执行。
- 什么工具可以并行调用,什么必须串行?
- 要点:只读、无依赖的工具可并行降延迟;有数据依赖(A 输出是 B 输入)必须串行。
- 转账类工具为什么要加人工确认?
- 要点:防止提示注入诱导模型执行危险写操作;最小权限原则,敏感动作必须人确认,且记审计日志。