《AI Agent 技术原理与架构·运行时、协议与系统架构》6.1 Function Calling 与 MCP

模型要调用工具,协议要把调用变成消息。MCP 把工具调用分层处理:传输层管通道,消息层校验 JSON-RPC 结构,语义层按注册表查找并执行工具。实验实现最小的 JSON-RPC 解析、工具注册表与分层 dispatch,演示合法调用、未知工具与协议错误的三种路径,错误在哪个层产生就由哪个层返回对应错误码。

以下工具、schema 与错误码均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。-32700/-32601/-32602 沿用 JSON-RPC 2.0 的错误码约定,但 MCP 消息的具体字段以官方规范为准,‘分层处理’这一条不变。

模型会"说"它要调用工具,协议负责把这句话变成可执行的消息。Function Calling 是模型侧的能力(模型输出结构化的工具调用意图),MCP 是系统侧的协议(这个意图怎么被解析、校验、路由、执行)。两者接起来,工具调用才成立。

MCP 的架构价值在于分层:传输层管通道,消息层校验 JSON-RPC 结构,语义层按注册表查找并执行工具。错误在哪个层产生,就由哪个层返回对应的错误码——这让 Agent 侧能精确区分"消息格式错了"和"工具不存在"。

三层各管什么

层职责错误示例错误码
传输层通道与连接(本实验略过)—
消息层校验 JSON-RPC 结构jsonrpc 不是 2.0、缺 method-32700
语义层查表、校验参数、执行工具不存在、参数缺失-32601 / -32602

消息层管结构。 每一条调用消息必须符合 JSON-RPC 2.0:有 jsonrpc 字段、有 method。结构错了,连"要调什么工具"都读不出来,直接返回协议错误。

语义层管内容。 method 读出来之后,要在注册表里找到这个工具:找不到是"未知工具",找到了但参数不对是"参数无效"。语义层的错误码细分(-32601 工具不存在、-32602 参数无效),让 Agent 侧不用解析消息就能知道是哪一类失败。

分层错误的好处:Agent 侧能分类响应

分层的收益在消费侧。Agent 收到不同错误码,可以做出不同反应:

错误码含义Agent 侧响应
-32700协议错误不是工具问题,是消息问题;检查调用构造
-32601工具不存在不该再调用;注册表有误
-32602参数无效重新构造参数(见 5.1 校验)

如果错误不分层,Agent 侧只能用错误消息字符串做匹配,脆且容易误判。错误码让"这是什么问题、该怎么处理"结构化。

最小实验:分层 dispatch

实验实现最小的 JSON-RPC 解析、工具注册表与分层 dispatch。

# file: agp_lab/mcp_protocol.py | write
# tier: 3
# verify: python3 -m unittest tests.test_mcp_protocol
"""Function Calling 与 MCP:协议分层、消息校验与工具注册。

MCP 把工具调用分层处理:传输层负责通道,消息层校验
JSON-RPC 结构与字段,语义层按注册表查找并执行工具。
错误在哪个层产生,就由哪个层返回对应的错误码。

本模块实现最小的 JSON-RPC 解析、工具注册表与分层 dispatch,
演示合法调用、未知工具与协议错误三种路径。
"""
from __future__ import annotations

from dataclasses import dataclass
from typing import Any, Callable


class ProtocolError(Exception):
    pass


class UnknownToolError(Exception):
    pass


@dataclass(frozen=True)
class McpMessage:
    id: int | None
    method: str
    params: dict[str, Any]


def parse_message(raw: dict[str, Any]) -> McpMessage:
    """消息层:校验 JSON-RPC 2.0 的字段。"""
    if raw.get("jsonrpc") != "2.0":
        raise ProtocolError("jsonrpc 必须为 2.0")
    if "method" not in raw:
        raise ProtocolError("缺 method")
    return McpMessage(raw.get("id"), raw["method"], raw.get("params", {}))


def _validate(params: dict[str, Any], schema: dict[str, Any]) -> list[str]:
    errors: list[str] = []
    for required in schema.get("required", []):
        if required not in params:
            errors.append(f"missing required '{required}'")
    return errors


class ToolRegistry:
    """语义层:按名称查找工具并执行。"""

    def __init__(self) -> None:
        self.tools: dict[str, tuple[Callable[[dict[str, Any]], Any], dict[str, Any]]] = {}

    def register(self, name: str, handler: Callable[[dict[str, Any]], Any], schema: dict[str, Any]) -> None:
        self.tools[name] = (handler, schema)

    def call(self, name: str, params: dict[str, Any]) -> Any:
        if name not in self.tools:
            raise UnknownToolError(f"unknown tool: {name}")
        handler, schema = self.tools[name]
        errors = _validate(params, schema)
        if errors:
            raise ValueError(f"invalid params: {errors}")
        return handler(params)


def dispatch(raw: dict[str, Any], registry: ToolRegistry) -> dict[str, Any]:
    """分层 dispatch:消息层 → 语义层,错误就近返回。"""
    try:
        message = parse_message(raw)
    except ProtocolError as error:
        return {"jsonrpc": "2.0", "error": {"code": -32700, "message": str(error)}}
    try:
        result = registry.call(message.method, message.params)
        return {"jsonrpc": "2.0", "id": message.id, "result": result}
    except UnknownToolError as error:
        return {"jsonrpc": "2.0", "id": message.id, "error": {"code": -32601, "message": str(error)}}
    except ValueError as error:
        return {"jsonrpc": "2.0", "id": message.id, "error": {"code": -32602, "message": str(error)}}


def demo() -> dict[str, Any]:
    registry = ToolRegistry()
    registry.register("read_file", lambda p: f"content of {p['file']}", {"required": ["file"]})
    return {
        "ok": dispatch({"jsonrpc": "2.0", "id": 1, "method": "read_file", "params": {"file": "a.txt"}}, registry),
        "unknown_tool": dispatch({"jsonrpc": "2.0", "id": 2, "method": "rm_rf", "params": {}}, registry),
        "protocol_error": dispatch({"id": 3, "method": "read_file"}, registry),
        "bad_params": dispatch({"jsonrpc": "2.0", "id": 4, "method": "read_file", "params": {}}, registry),
    }


if __name__ == "__main__":
    for key, value in demo().items():
        print(f"{key}: {value}")

运行:

cd private/labs/agp-lab
python3 -m agp_lab.mcp_protocol

输出:

ok: {'jsonrpc': '2.0', 'id': 1, 'result': 'content of a.txt'}
unknown_tool: {'jsonrpc': '2.0', 'id': 2, 'error': {'code': -32601, 'message': 'unknown tool: rm_rf'}}
protocol_error: {'jsonrpc': '2.0', 'error': {'code': -32700, 'message': 'jsonrpc 必须为 2.0'}}
bad_params: {'jsonrpc': '2.0', 'id': 4, 'error': {'code': -32602, 'message': 'invalid params: ["missing required \'file\'"]'}}

四条路径覆盖合法与三类失败:

  1. ok:合法调用 read_file(file=a.txt),返回 result。id 原样回显(1)。
  2. unknown_tool:调用没注册的 rm_rf,语义层返回 -32601。Agent 侧据此知道"这个工具不存在",不该再试。
  3. protocol_error:消息没有 jsonrpc 字段,消息层在解析阶段就返回 -32700。注意这条响应没有 id——因为结构都错了,连 id 都没法信任。
  4. bad_params:read_file 缺必填 file,-32602。注意它与 -32601 是不同的错误码:工具存在、参数无效。

两个值得点破的细节:

  • protocol_error 没有 id。 消息层失败发生在拿到 id 之前,响应里就没有 id。这是 JSON-RPC 的语义:id 无效时无法回显,只能返回错误对象。
  • 错误码和错误层一一对应。 -32700 只在消息层产生,-32601/-32602 只在语义层产生。这个对应关系就是"分层"的可观测保证:看到错误码,就知道故障在哪个层。

MCP 分层的另一层意义是可插拔。传输层、消息层、语义层解耦之后,替换任何一层都不影响其他层:把 stdio 传输换成 HTTP,把本地注册表换成远程注册中心,Agent 侧的调用方式不变。这正是一个协议应有的结构——它让协议本身演进,而不让使用方跟着改。

替换场景替换哪层Agent 侧影响
stdio → HTTP传输层无
本地 → 远程注册语义层无(接口不变)
JSON-RPC → 其他消息层适配器

分层的代价也有:每一层都是故障点。传输层断了、消息层解析失败、语义层查表超时,三层各自要监控。错误码的设计,让监控可以直接定位到层——看到 -32700 就知道是消息层,看到 -32601 就知道是语义层。这是"分层 + 错误码"组合的可观测价值。

MCP 的生命周期管理是把它用进生产的前提。工具要能注册、下线、灰度、回滚,而不仅仅是"能调用"。一个典型流程:新工具先在注册表里标实验态,只对部分 Agent 可见;验证稳定后转正式;废弃工具先标 deprecated 再下线,给存量会话迁移窗口。注册表不是静态清单,是带状态的工具生命周期系统。

生命周期状态调用方可见
开发中experimental部分
已验证active全部
废弃中deprecated全部(提示迁移)
已下线removed不可见

安全维度上,MCP 还有一层信任边界:工具注册源可信吗?Agent 调工具前,运行时要不要校验工具的签名或来源?对任意来源的 MCP 服务器不加校验,等于给 Agent 开放任意代码执行。MCP 的接入策略要和 4.3 的能力边界配合——谁有权限接入 MCP 服务器、能声明哪些能力,都要有约束。

MCP 的传输选择要匹配部署形态。stdio 传输适合"Agent 与工具同进程或同机",HTTP 适合分布式部署(工具服务器独立运行、Agent 通过网络访问)。传输层选择影响运维:stdio 的进程由 Agent 拉起、生命周期跟随 Agent;HTTP 的工具服务独立部署、要单独监控与扩容。

传输部署形态运维特点
stdio同进程/同机进程随 Agent 生灭
HTTP独立服务单独监控、扩容
SSE长连接流式连接管理复杂

错误码的语义要在 MCP 层与工具层对齐。 MCP 层的 -32601 表示"方法不存在",工具层的错误要复用或扩展现有语义,而不是另起一套。错误码分层(MCP 层协议错误、工具层业务错误)各司其职,Agent 侧才能按层处理——协议错误修调用,业务错误改参数。

MCP 的注册表设计决定 Agent 能发现什么工具。按能力索引(如"能做 web_search")、按领域分组、带健康状态——Agent 查询"我要做 X,有什么工具",注册表返回可用且健康的工具。注册表不只是存工具定义,还是 Agent 的"工具路由"。

注册表能力作用缺失后果
按能力索引语义查询只能按名找
健康状态剔除故障工具调到坏工具
版本信息兼容判断调用旧版本
权重/优先级排序选择随机选工具

架构判据

工具调用协议是否合格,用五条判据检查:

判据合格的样子不合格的样子
分层清晰消息层/语义层职责分明解析与执行混在一起
错误码细分协议/工具/参数错误可区分所有错误一个码
注册表单源工具按名称查注册表工具散落、无注册
参数校验调用前校验 schema参数错进到执行层
错误可分类响应Agent 侧按错误码响应靠字符串匹配错误

判据第三条"注册表单源"是 MCP 的核心:工具按名称注册、按名称查找,Agent 侧只需要知道名称和 schema。判据第四条呼应 5.1:参数校验在调用前拦截,别让坏参数进到工具。

小结

  • Function Calling 是模型侧能力,MCP 是系统侧协议;两者接起来工具调用才成立。
  • MCP 分层处理:传输层、消息层、语义层;错误在哪个层产生就由哪个层返回错误码。
  • 错误码细分让 Agent 侧能分类响应:协议错误、工具不存在、参数无效互不相同。
  • 分层是可观测保证:看到错误码就知道故障在哪个层。

阅读导航:上一节:5.3 补偿、回滚与 Saga · 下一节:6.2 A2A:Agent 间协作协议 。

常见错误与边界

  1. 解析与执行混在一起。 不校验结构就去找工具,协议错误会被误报成工具不存在。
  2. 所有错误一个码。 Agent 侧无法区分"消息坏了"与"工具没了";要按层细分错误码。
  3. 工具不注册。 工具散落在代码里,Agent 侧无从发现;要按名称查注册表。
  4. 参数错进执行层。 校验在调用前拦截;坏参数进去就是副作用已发生(见 1.1)。
  5. protocol_error 也回显 id。 消息层失败时 id 不可信,不能回显;要返回纯错误对象。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图