罗罗编程学习记录
本页内容 展开查看

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 把工具列表暴露给客户端,客户端把它们转成模型认识的 tools schema;模型决定调用后,客户端通过 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 分钟内定位

自测题(先自己想,再看要点):

  1. 一次 Function Calling 循环里 messages 经历了哪几轮?
    • 要点:用户输入 → 模型返回 tool_calls(finish_reason=tool_calls)→ 代码执行 → 追加 role: tool 消息 → 再次请求 → 模型最终回答(finish_reason=stop)。
  2. tool_call_id 有什么用?
    • 要点:把工具结果和之前模型请求的那个调用对应起来,一个 tool_calls 里可能有多个调用,必须靠 id 配对回填。
  3. 为什么工具描述里要写"什么时候不用"?
    • 要点:避免模型把相近工具搞混,显式排除边界让模型选工具更可靠。
  4. 工具失败为什么不能直接抛异常给模型?
    • 要点:模型收到异常无法自我修正;要把错误原因与修正建议写成文本回填为 tool 消息,模型据此改参数或换方案。
  5. MCP 的 initialize/tools/list/tools/call 各做什么?
    • 要点:initialize 握手协商能力;tools/list 列出工具 schema;tools/call 调用指定工具传参执行。
  6. 什么工具可以并行调用,什么必须串行?
    • 要点:只读、无依赖的工具可并行降延迟;有数据依赖(A 输出是 B 输入)必须串行。
  7. 转账类工具为什么要加人工确认?
    • 要点:防止提示注入诱导模型执行危险写操作;最小权限原则,敏感动作必须人确认,且记审计日志。