这篇是我整理的一份工具调用笔记。我想理清:模型生成的一个调用请求,怎样变成程序真正执行的操作;MCP 为什么出现,又怎样把外部能力接进 Agent。
工具调用让 LLM “长了手”是一个直观的说法。沿着它往下看,还需要分清模型、宿主和工具实现的职责,以及操作结果怎样返回模型,影响下一步判断。文章会从工具的作用讲起,逐步展开 Function Calling、MCP、执行循环和使用时的注意事项,最后看看几个产品与开源项目的实现。
如果你也在梳理这些概念,欢迎一起读下去,也欢迎分享不同的理解和实践经验。
1 为什么需要工具:让 LLM 从对话走向行动
工具的作用:把语言推理连接到环境
LLM 可以解释一段代码、推导一个结果,也可以写出一条命令。但生成这些文字,并不说明文件已经被读取、计算已经完成,或者命令已经运行。要依据当前环境做事,系统需要能够执行的入口。
工具提供这样的入口。搜索和读取工具帮助模型取得任务所需的信息;代码执行工具提供实际计算;文件编辑和服务 API 则使系统能够改变环境。工具返回的内容还能帮助模型核对此前的判断,决定是否继续操作。这里的行动既包括查询和观察,也包括修改。
因此,“长了手”指的是模型能够请求系统提供的动作,并利用执行反馈继续推理。模型负责理解任务、选择动作和生成参数,真实操作由程序完成。OpenAI 的 Function calling 说明将工具调用描述为模型与应用之间的多步交互,强调的也是这种分工。
职责关系:模型提出请求,宿主组织执行
运行 Agent 的应用系统通常称为宿主(Host)。它准备模型输入,提供当前可用的工具,接收调用请求,分派执行,再整理返回结果。有些系统把这些职责写在应用代码里,有些交给 Agent SDK 或托管服务。

自绘职责图:工具将模型的判断连接到文件、程序和外部服务。模型侧的调用请求与服务侧的 MCP 接入属于不同接口;框表示职责,不能据此推断每个部分都独立部署。
工具实现可以是宿主中的一个函数,也可以通过 HTTP 访问业务服务,还可以由 MCP Server 提供。图中的两条路径最终都要落实到执行代码;MCP 的具体角色在第三章展开。
工具使 Agent 有了可用动作,执行循环则把动作、反馈和下一次判断组织起来。一次函数调用可以完成计算或查询,较复杂的任务往往要经过多轮观察和操作,直到满足结束条件。
2 Function Calling:怎样表达结构化的调用请求
工具定义:告诉模型能做什么、怎样请求
Function Calling 让模型以约定格式表达工具调用请求。本文用 JSON Schema 函数工具说明这一机制;不同平台还可能支持自由文本工具等形式,字段也不完全相同。
下面是采用 OpenAI Responses API 格式的教学定义,表示一个文档检索工具:
{
"type": "function",
"name": "search_docs",
"description": "检索当前用户可访问的产品文档,返回相关片段、文档标识和来源。需要依据文档回答问题时使用。",
"strict": true,
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "需要查证的问题或关键词"
},
"limit": {
"type": "integer",
"enum": [5, 10],
"description": "最多返回多少条结果"
}
},
"required": ["query", "limit"],
"additionalProperties": false
}
}名称帮助识别工具,描述说明职责和使用条件,参数结构规定请求可以包含哪些字段。模型看到这些定义后,可以结合任务生成工具名和参数;执行端还需要有同名工具的实现,才能真正检索文档。
strict 在支持的 schema 范围内约束参数结构。例如,上面的 limit 应是枚举中的整数。它不能保证查询语义合适、文档中一定有答案,也不会替用户取得访问权限。结构、业务条件和权限分别需要相应检查。Strict mode 文档说明了 schema 的约束要求;这些要求也不应原样推广到所有模型接口。
调用与结果:执行过程中的两种消息
模型提出调用时,可能返回下面这样的内容。这里的调用标识和查询文字都是示意:
{
"type": "function_call",
"call_id": "call_01",
"name": "search_docs",
"arguments": "{\"query\":\"升级后的配置变更\",\"limit\":5}"
}应用识别 name,解析和检查 arguments,再把请求交给已注册的执行函数。检索完成后,将结果作为与 call_01 对应的工具输出返回模型。调用与结果通过标识关联,避免多个请求的返回内容混淆。
这几种对象各有用途:工具定义描述能力,调用请求表达本次动作,工具结果记录执行反馈。模型输出一个函数名,只表明它提出了请求。真正执行、收集结果与发起下一轮模型请求,还需要外部程序配合。
SDK 的边界:接口封装与运行循环
“SDK 会处理工具调用”需要结合具体库理解。
普通模型 API SDK 主要封装请求、响应和数据类型。开发者仍可能需要自己识别调用、执行函数并回填结果。Agent SDK 则可以进一步提供 Runner,把这些步骤组织成循环。OpenAI Agents SDK 的运行说明就明确描述了工具执行、追加结果和再次调用模型的过程。
因此,判断一段代码由谁执行工具,要看调用链和执行器,不能只看它是否使用了 SDK。工具定义也不应允许模型自行填写执行身份或任意凭据;这些信息应来自宿主掌握的用户与认证上下文。
3 MCP:产生背景、核心构造与调用方式
产生背景:减少外部能力的重复接入
Function Calling 已经能表达“调用哪个工具、使用什么参数”,但工具本身怎样接进应用,仍需要开发者处理。
一个宿主要访问文件、代码仓库和业务系统,可能面对不同的目录组织、请求格式和结果约定。另一个宿主接入同样的服务,又需要维护一组适配。随着应用和服务增加,这些接入工作很容易重复。
Anthropic 在 MCP 原始公告中提出用开放协议连接 AI 应用与数据、工具所在的系统。Model Context Protocol,即模型上下文协议,提供统一的能力发现和访问约定,使服务可以暴露一次,再由支持协议的宿主接入。
统一协议减少了接入接口的差异。服务本身的业务语义、数据权限,以及宿主如何组织模型与任务,仍需要各自实现。
核心构造:Host、Client 与 Server
MCP 架构区分三个角色。Host 是使用模型和外部能力的应用,负责管理上下文、连接策略与用户交互;Client 是宿主内处理 MCP 协议交互的组件;Server 向客户端暴露特定能力,可以是本地进程或远程服务。

图源:Model Context Protocol,Architecture overview,文档许可 CC BY 4.0。按官方 Mermaid 源码重新渲染,保留节点与连接关系。图中的连接关系不表示 HTTP 必须维持持久会话。
一个 Host 可以管理多个 Client,每个 Client 对接一个 Server。图中也展示了不同 Client 连接同一远程服务的情况。Client 是协议角色,不能仅凭这个名称把它理解为用户面对的聊天客户端。
Server 提供的不只有工具。服务端规范区分了三类主要原语:
| 原语 | 提供什么 | 设计交互模型 |
|---|---|---|
| Tool | 可调用的查询或操作 | 模型根据任务选择调用,宿主落实执行策略 |
| Resource | 带 URI 的内容或上下文 | 应用决定读取和使用哪些内容 |
| Prompt | 可带参数的消息模板 | 用户选择使用相应模板 |
这些控制方式描述的是交互设计,不能替代权限规则。Resource 的 URI 也不要求是公网网页;Prompt 返回一组消息,不代表对应工具已经执行。
调用方式:从协议目录到模型可用的工具
宿主需要把 MCP 能力与模型接口连接起来。一条常见工具路径是:通过 tools/list 获取工具名称、描述和 inputSchema,适配为模型能够识别的定义;模型提出调用后,由宿主把名称与参数转换成 tools/call,接收结果,再组织进模型输入。
MCP 的消息与模型 API 的工具对象属于不同接口,结构相近也需要适配。结果可能包含文本、结构化内容、图片或资源链接,宿主应根据模型和 API 支持的形式处理。Tools 规范定义协议对象,Agents SDK 的 MCP 集成说明则展示了具体宿主如何完成连接。
消息采用 JSON-RPC 编码,传输可以使用 stdio 或 Streamable HTTP。stdio 通过本地子进程的标准流通信;Streamable HTTP 使用 HTTP 端点,响应可以是 JSON 或请求范围内的 SSE。因而 MCP 不等于“必须通过 HTTP 调用远程服务”。Transports
在采用自包含请求的交互方式中,协议元数据随请求携带,不依赖预先建立的握手会话。服务端提供 server/discover,供客户端提前了解协议支持与能力;客户端也可以直接发出具体请求并处理不兼容情况,因此发现请求不是每次工具调用的必经步骤。宿主与 SDK 需要匹配服务支持的交互方式,协议无状态也不表示业务对象没有状态。Versioning and Compatibility
授权另有适用范围:HTTP 授权规范与 stdio 的凭据处理不同,具体数据和操作权限仍由执行端判断。连接成功不代表当前用户能执行所有动作。Authorization
概念关系:工具调用、Function Calling 与 Skill
下面按本文的分工视角比较:工具调用指完整的请求、执行与反馈过程,Function Calling 侧重模型接口中的调用表达;不同平台对这两个名称的用法可能重合。
| 概念 | 主要回答的问题 | 形态与内容 | 与其他概念怎样配合 |
|---|---|---|---|
| 工具调用 | 怎样借助外部能力推进任务? | 模型提出请求、程序执行操作、结果返回模型的一段交互 | 请求可以通过 Function Calling 表达,执行可以直接接入工具,也可以经过 MCP |
| Function Calling | 模型怎样表达要调用什么、传入哪些参数? | 模型接口中的调用请求机制,本文以结构化函数工具为例 | 为宿主识别和分派请求提供依据,真实操作仍由程序执行 |
| MCP | 宿主怎样发现和访问能力服务? | Client 与 Server 之间的通信协议,服务端可提供 Tools、Resources 和 Prompts | 宿主可将 MCP 工具适配成模型可见的定义,再把模型请求转为协议调用 |
| Skill | 某类任务应该怎样做,需要哪些方法和资料? | 以 SKILL.md 为入口的指令与资源包,可附带脚本 | 可以指导 Agent 使用直接接入的工具或 MCP 工具,脚本仍依赖宿主提供的执行环境 |
在同一个任务里,Skill 可以指导处理步骤,模型通过 Function Calling 提出工具请求,宿主再直接执行,或通过 MCP 访问服务,并将结果返回模型。工具也可以不经 MCP 接入,Skill 也可以只提供知识与方法;这些概念不要求组成一条固定链路。Skill 的内容与可选脚本结构见 Agent Skills 格式规范。
4 执行循环:Agent 怎样选择、执行并使用工具结果
连续实例:让前一轮结果影响下一步
把接口连起来后,工具进入 Agent 的执行循环。宿主准备当前输入,模型选择工具并生成参数,执行端完成操作,结果返回后再请求模型。每一次反馈都可能改变后续选择。

自绘执行流程图:右侧的工具结果经宿主整理后进入下一轮输入。图中展示正常循环;预算、取消和失败导致的终止在运行规则中处理。
下面用一个教学任务说明:“依据产品文档,判断这次升级是否需要修改配置。”假设系统提供 search_docs 和按文档标识读取原文的 read_doc。表中的文档标识是示意,不是实际执行记录。
| 轮次 | 模型的选择依据与请求 | 执行反馈怎样影响后续 |
|---|---|---|
| 第一轮:检索 | 目前尚无检索材料;模型结合用户问题和工具定义选择 search_docs,生成查询和数量上限 | 执行器返回相关片段、来源及 doc_17 等标识。模型据此发现了可能相关的配置说明 |
| 第二轮:读取 | 检索片段不够完整;模型请求 read_doc 读取 doc_17 的相关部分 | 原文与来源进入后续输入,模型可以核对适用版本和条件 |
| 第三轮:回答或继续 | 模型判断现有材料能否支持结论 | 证据足够时回答;仍有缺口时继续查询,或说明无法确认的部分 |
这里的顺序来自任务和反馈。宿主没有必要预先写死“搜索后一定读取”,模型也不保证每次都走同样的路径。它需要结合工具描述、参数要求、已有材料和任务目标选择动作;宿主决定本轮暴露哪些工具,并约束真实执行。
发现服务目录与在循环中选工具也要区分。目录可以在接入时获取并缓存,需要时刷新;按需工具搜索则可能发生在任务过程中。它们不必在每次工具执行前全部重复。
最小循环:程序怎样接住模型请求
下面的 Python 伪代码展示执行骨架。model.generate、to_input_items 等都是教学接口,实际使用时应对应所选模型 API 和 SDK;它没有实现检索服务,也不是可直接运行的完整程序。
history = [user_message]
registry = {"search_docs": search_docs, "read_doc": read_doc}
for _ in range(max_rounds):
response = model.generate(input=history, tools=tool_definitions)
history.extend(to_input_items(response))
calls = get_tool_calls(response)
if not calls:
return get_final_answer(response)
for call in calls:
try:
tool = registry.get(call.name)
if tool is None:
raise ToolError("未注册的工具")
args = parse_and_validate(call.arguments, schemas[call.name])
check_permission(user_context, call.name, args)
value = tool(**args)
except ToolError as error:
value = {"status": "error", "message": error.safe_message}
history.append(make_tool_result(
call_id=call.call_id,
value=value,
))
raise RoundLimitReached()注册表把名称映射到具体实现,参数检查和权限检查发生在执行前。这里的 ToolError 表示可反馈给模型的工具失败;示意中的检查函数与执行适配层按约定将这类失败转换为该类型,其他异常仍由宿主处理。call_id 将结果与原调用关联;下一轮输入保留需要续传的模型输出,再追加工具结果。对于带推理状态或特殊消息项的接口,应按其要求续传,不能只留下最终一段文本。
这段代码顺序执行工具,目的是让控制过程清楚。真正支持并行时,还需要判断依赖关系和执行能力:读取互不相关的资料可以并行,读取文档正文则可能依赖前一次检索得到的标识。模型一次提出多个请求,不足以证明它们都能安全地同时执行。
实际框架会封装许多步骤。Claude Agent SDK 的官方示例就沿着查看失败、读取文件、修改并验证的过程,说明工具结果怎样推动下一轮;开发者可以观察消息生命周期,而不必自己重写整个循环。
反馈与结束:执行完成以后还要判断什么
空列表可能表示没有命中资料,业务错误可能表示参数不符合领域条件,权限错误表示当前身份不能访问。这些信息会影响下一步:改写查询、调整参数、处理授权,或者结束并说明限制。
MCP 还区分 JSON-RPC 协议错误与通过 isError 表达的工具执行错误。没有收到响应又可能意味着传输中断或执行状态不明,不能一律折成“再试一次”。Tools 的错误处理说明
同样,工具执行成功只说明该动作完成。搜索成功不保证材料足够,写入成功也不自动证明任务目标已经达到。是否继续取决于当前证据和任务要求;是否允许继续,还受轮次、时间、费用、取消等运行规则约束。
5 工具调用的注意事项:上下文、执行与成本控制
工具描述:足够清楚,也避免重复和膨胀
Tool Description 是模型选择工具的重要依据。描述应交代能力、使用条件、关键限制和返回内容;名称与参数也应让相近工具容易区分。多个工具职责重叠、描述堆满背景材料,会让模型需要在更多相似入口之间判断。
压缩描述时要保留影响选择的信息。将“搜索当前用户可访问的文档,返回片段与来源”缩成“搜索”,虽然更短,却丢掉了对象与结果形态。可以被参数 schema 清楚表达的字段要求,也不必在多处重复长篇解释。Ken Aizawa 的 Writing effective tools for agents从工具职责、名称空间和结果设计出发,讨论了这类取舍。
工具描述与 schema 会占用模型输入。要控制开销,先分清三个集合:服务端提供哪些能力,宿主能发现哪些能力,以及本轮实际向模型展示哪些定义。它们可以相同,也可以通过筛选或按需加载形成较小的集合。

自绘信息流图:上半部分控制定义,下半部分控制结果。筛选、搜索、裁剪与外置处理由具体宿主和工具实现决定;MCP 的接入协议不自动完成这些优化。
定义加载:直接提供、筛选与按需发现
对于少量、稳定且经常使用的工具,直接提供完整定义容易理解,也避免增加发现步骤。工具很多时,可以先按业务域缩小目录,再按任务搜索和加载相关定义。
OpenAI Tool search提供的延迟加载有具体边界:单个 deferred function 的名称和描述仍可见,主要延迟参数 schema;按 namespace 或 MCP Server 组织时,初始可以只提供组级概述,查找后再加载内部定义。它还区分平台托管搜索与由应用执行的搜索。
Anthropic 的 Tool search 文档则说明,延迟工具的完整定义仍随 API 请求提交,按需进入的是模型上下文。因此,HTTP 请求体包含什么,与模型当前看到什么,需要分别检查。
按需发现也有成本:额外搜索需要时间,漏选工具会影响后续行动。一次返回大量候选,再把它们全部注入上下文,可能只把全量加载推迟了一步。应结合任务完成情况判断收益,不能只比较初始 token 数。
这些都是模型接口或宿主的实现策略。MCP 提供能力发现与调用约定,不要求宿主把目录全量放进上下文,也不会自动替它选择最经济的加载方式。
返回结果:提供可继续使用的证据
结果太大与描述太长是不同问题。参数很少的日志查询,也可能返回大量无关内容。接口应尽量支持范围、数量、字段或时间过滤;较大结果可以分页,或者先给摘要和标识,再按需读取。
裁剪时要保留下一步需要的内容。文档查询通常需要来源、适用版本、稳定标识及相关片段;分页结果应让模型知道还有后续页。发生截断时,应明确范围和继续读取的办法,避免将局部材料误作完整证据。
另一个选择是在执行环境处理中间数据。Adam Jones、Conor Kelly 的 Code execution with MCP展示了把能力包装为代码接口、在执行环境中组合调用与过滤数据,再只返回必要结果的方式。它需要额外的执行环境与运行约束;并非接入 MCP 就自动获得,也不适合不加判断地用于所有小任务。
工具结果还有信任边界。网页、文档和评论中可能含有看似操作指导的文字,它们仍是外部数据。宿主和模型需要按来源与任务使用这些内容,不能仅因它们出现在工具结果里就赋予更高指令地位。
执行边界:校验、权限与副作用
格式合法只是检查的一部分。一个符合 schema 的路径,仍可能越出允许目录;一个存在的文档标识,仍可能属于无权访问的数据。用户身份与权限检查应落实在执行端,不能依赖模型在参数里自报身份。
读取与写入也有不同后果。查询失败后重新查询,和写操作返回不明时再次提交,风险并不相同。回执丢失时,原动作可能已经完成;继续前应根据业务回执或状态核对,避免重复动作。
这些约束应该对应实际能力。缩小可见目录有助于控制动作范围,但不能替代服务端的数据权限;工具上的只读提示也需要实现与凭据权限配合,不能只靠文字保证。
总成本:观察完整任务,而非单次调用
工具成本至少包含模型推理、实际工具执行,以及外部服务可能收取的费用。返回内容还可能在后续多轮输入中继续占用预算。缓存可以降低部分重复输入的处理或计费开销,不能直接理解为这些内容不占上下文。
端到端耗时同样包含发现、模型生成参数、网络、服务执行和结果反馈。一次工具函数运行很快,整个任务仍可能因为多轮搜索或大量结果而变慢。
因此应围绕任务完成情况,观察调用次数、token、总耗时和错误类型,再决定修描述、调接口还是改加载策略。轮次与费用上限也需要匹配任务;例如 Claude Agent SDK公开提供轮次和预算控制。上限限制的是运行范围,不能代替对结果是否足够的判断。
6 实现观察:产品与开源项目怎样组织工具调用
Codex:从工具路由到执行回填
Codex 由 Harness 组织用户输入、模型推理与工具执行。每次请求把当前上下文和可用工具交给模型,工具可以来自 Codex 内置能力、模型平台或 MCP 服务;执行后的结果进入后续输入,循环继续推进。可用工具集合还取决于模型能力、运行环境与配置。Unrolling the Codex agent loop
工具路由层的 ToolRouter分别保存工具执行注册表与 model_visible_specs。注册执行实现,与决定模型能看到哪些定义,是相关但不同的工作。收到模型调用后,Router 将其转成带名称、参数负载和调用标识的内部请求,再交给注册表分派。
ToolCallRuntime则查询工具是否支持并行,以共享锁或独占锁约束运行,再调用 Router。执行结束后,输出转换为与原调用标识对应的响应项,供后续模型请求使用。模型可以提出多个调用,运行时仍要依据工具能力安排执行,是否并行不能仅由请求数量判断。
Claude Code:把循环和工具上下文交给产品管理
Claude Code 的 架构说明将过程概括为收集上下文、行动与验证,并明确模型外负责工具和上下文的部分是 Agent Harness。每次工具反馈都可能改变模型对下一步的判断。
其 Agent SDK把同一执行循环提供给开发者:模型请求工具,SDK 执行并反馈结果,随后继续推理,直到形成无工具调用的最终回答或触发运行限制。开发者可以观察模型消息、工具结果与结束消息,并通过接口配置执行策略。
Claude Code 也给第五章的两条信息流提供了实例。它在支持的配置下默认按需发现 MCP 工具定义,初始仍会加载工具名称与服务器指导;模型、部署或配置不支持时可能预先加载,具体行为由工具搜索配置决定。MCP 工具搜索说明
对于超过相应限制、成功且不含图片的文本结果,产品可以保存到文件,在对话中提供路径供后续读取;错误结果另有处理规则。MCP output limits说明了这些条件。按需加载定义与外置结果分别控制不同内容,也都是 Claude Code 的实现,不能归为 MCP 规范自动提供的能力。
DeepSeek Harness:用插件组合工具与循环
DeepSeek Harness(dsh)是 DeepSeek 官方的开源 Agent Harness。它在架构设计中使用 Cordis 插件组合模型适配、工具注册、会话记录和 Agent 循环。
ToolsService 源码保存带执行函数的工具定义,并按作用域与当前步骤选择工具;schemas() 再投影出模型请求需要的字段。执行函数和界面展示回调不直接作为工具 schema 发给模型,这与前面区分“模型看到什么、程序实际执行什么”的思路一致。
内置执行器使用的 工具管线包含执行前策略与检查、工具实现、结果处理及会话记录。之后的循环从会话记录组织后续输入,使调用结果能够参与下一步判断。它也允许自定义执行器,因此不能把内置管线的全部细节当作扩展必须遵守的通用协议。
这个例子展示了工具与循环如何由产品架构组合起来。它与 DeepSeek 模型 API 的函数调用支持,以及第三方接入 DeepSeek 的框架,是不同对象。
开源方案:从 SDK 与 Server 观察局部设计
完整产品之外,较小的项目适合观察单项职责怎样组织:
| 实现 | 值得阅读的部分 | 与前文的联系 |
|---|---|---|
| OpenAI Agents SDK | Runner、工具执行与 MCP 集成 | 对照第四章,理解 SDK 替应用封装了哪些循环工作 |
| GitHub MCP Server | 按业务域组织的 toolsets、单独工具选择与只读过滤 | 观察服务端怎样控制暴露目录,区别于模型侧按需加载 |
| Microsoft Playwright MCP | 浏览器状态、无障碍快照、局部观察与交互工具 | 观察结果形态怎样影响后续选择和上下文占用 |
GitHub 的 配置说明允许组合业务组与具体工具,只读过滤优先;本地参数与远程请求头是不同配置入口。它说明目录组织来自具体实现,仍需与访问凭据和权限配合。
Playwright MCP 的 browser_find 可以返回命中节点附近的片段,快照也支持限制目标和深度。这些接口帮助 Agent 选择观察范围;以快照为主要交互方式,也不表示它没有截图能力。维护方还在 MCP 与 CLI 的比较中指出,具备命令执行能力的 coding agent 可以考虑 CLI + Skills,而持续状态和页面结构观察是 MCP 方案的适用方向。应结合宿主已有能力判断,不能把这个比较写成协议的统一优劣结论。
若只想查看 Tools、Resources 与 Prompts 怎样同时暴露,MCP Reference Servers 的 Everything也是教学入口。其参考定位应保留,不能仅凭官方仓库就推断生产就绪。
工具让 Agent 能够读取和改变环境,Function Calling 表达调用请求,MCP 统一能力服务的接入,宿主再将执行反馈组织成下一轮输入。阅读一个实现时,可以沿着工具定义、调用请求、执行函数与结果回填寻找代码,看清模型、运行系统与能力服务各自负责什么。

