logo

Agent的工具接入方式:CLI、技能文档与上下文协议的区别

作者:php是最好的2026.11.16 11:24浏览量:0

简介:同一任务下,命令行、技能文档、上下文协议三种工具接入方式的输入token可相差约42倍。本文先给出三者的定义与区别,再用一项受控实测把上下文成本拆成“入口说明”和“结果内容”两笔账,并厘清结论的适用边界,帮助开发者做工具接入选型。

一、概念定义:什么是工具接入方式,什么是上下文成本

在智能体(Agent)开发中,“工具接入方式”指大语言模型调用外部能力的机制:查询发布记录、读取缺陷单、执行构建脚本,都通过它完成。“放弃MCP、回归命令行”的讨论指向的也是这一层。当前主流的做法有三类:

  • 命令行接入(CLI):宿主只给模型一个通用shell工具,模型自己写命令并执行。
  • 技能文档接入(Skill):能力仍由命令行提供,另加一份按需加载的说明文档,告诉模型何时用哪条命令、参数怎么填、结果怎么读。
  • 上下文协议接入(MCP):按统一的模型上下文协议规范,把外部系统封装成带名称、描述和参数schema的结构化工具,模型按schema调用。

这三者常被当作互斥选项,但实测把它们放在同一道题上对照,却发现一个比“好不好用”更可量化的差异:上下文成本。它指模型为使用工具,在请求中携带的所有文本所对应的token消耗,包括两部分:

  • 工具说明:工具定义、使用文档、协议消息;
  • 工具结果:命令输出、接口返回、执行报错。

成本之所以值得单独讨论,是因为这类调用通常多轮往返、上下文不断累积,token用量会随轮次放大。三种方式都能答对这道题,差距却出在模型读了多少说明、带了多少结果。

二、背景与价值:成本从哪里被放大

要理解这笔账,先要知道模型的每次请求由几部分组成:

  1. 固定部分:系统提示与工具定义,每次请求基本不变;
  2. 累积部分:历史对话、此前读过的文档和工具返回;
  3. 新增部分:本轮模型生成的推理文本与工具调用参数。

在后两部分中,工具结果都会被原样保留在上下文里,因此产生重复计费。成本被放大的原因有三:

  • 线性累加:第n轮请求包含前n轮的全部内容。若工具结果较大、工具较多,总量会成倍增长。
  • 预填充耗时:首token响应时间通常与需要预填充的token量正相关。上下文越长,响应越慢,也更容易接近上下文上限。
  • 价格口径差异:输入token与输出token单价不同,不同模型定价不同。命中缓存的内容在支持缓存的服务上还能折价,所以token倍数不等于费用倍数。

据此可以把工具接入的上下文成本拆成两笔账:

  • 入口账:模型动手前必须读入多少说明,包括工具定义、使用文档和协议握手信息。它每轮重复发生,适合用缓存等手段摊薄。
  • 结果账:每轮工具返回多少内容,以及后续请求要带着它们走多少轮。它在整段对话中只产生一次,却会随轮次数倍放大。

分开看这两笔账,才能知道优化应落在工具集精简,还是结果裁剪与分页上。下一节用一项受控实测说明三种方式的差别。

三、实测:三种接入方式的上下文开销

某项公开的受控对照实测以某闭源大语言模型(下称“模型甲”)为执行主体,用同一道题对比三种接入方式。任务是:

  1. 查询某个托管代码仓库的最新release(发布版本);
  2. 找出其中带“bug”标签、最近新建的三个未关闭issue(问题单)。

三者在模型侧只需一个基础工具:

接入方式 模型侧基础工具 说明入口 能力来源
裸CLI shell执行工具 一句“命令行工具已安装并完成认证” 命令行工具本身
CLI + 技能文档 shell执行工具 + 技能索引 索引行常驻,SKILL.md(1,492字符)按需读取 命令行工具 + 技能文档
默认全量MCP 结构化工具调用 46个工具的名称、描述、参数schema 某版本管理平台官方的MCP server v2.0.2(本地stdio版)

测得数据如下:

接入方式 模型甲输入token 相对裸CLI
裸CLI 1,421 1×
CLI + 技能文档 3,315 约2.3×
默认全量MCP(46个工具) 59,417 约42×

完整任务是整段多轮调用,输入token为各轮总和。裸CLI约1,400的量级,说明实际读入的说明很短;技能文档只多出一份约1,500字符的文档(按英文约4字符/token估算约375 token),整体仍不到裸CLI的2.5倍;默认全量MCP则膨胀到约6万,是裸CLI的42倍左右。差距几乎全部来自常驻的工具定义,以及结构化返回被逐轮带在上下文里。美元成本对应$0.0075对$0.1274,约17倍,明显小于token倍数。这与两类token单价不同、模型甲输出偏少有关。

实测的具体范围:

  • 模型甲,默认46个工具,本地stdio版server v2.0.2;
  • 每个组合各跑3次,表格取中位数;
  • 时间:2026年10月20日;
  • 范围:一个server,一道任务。

换模型、换工具集或换客户端实现,数字都可能大幅变化,须重新测量。

四、如何理解:三种方式如何工作

4.1 命令行:薄接口,能力在工具里

模型只看见一个shell工具,能力全在已安装的命令行工具中。以查询发布记录为例,典型过程是:

  1. 模型从“已安装并完成认证”推断可用工具,写出一条带--json参数、只取最新一条的命令;
  2. 宿主执行命令,把输出交给模型;
  3. 模型按同样方式查询缺陷单:指定open状态、--label bug标签、--limit 3条数,并选择所需字段;
  4. 模型读取两次输出,完成任务。

关键在于,读什么由模型当场决定,可按需取字段、限制条数。代价是命令写错时只能在运行时发现,模型通常要根据报错信息修正后重试。

4.2 技能文档:把用法写成可检索的知识

技能由两部分组成:

  • 索引行:常驻上下文,只说明技能名称与适用场景;
  • SKILL.md正文:按需读取,写明何时使用、命令写法、参数含义、输出如何解读及注意事项。

技能不改变执行通道,执行仍由命令行完成。它把“猜命令”变成“查文档”。代价是模型通常要先读懂文档、再组织命令,入口与轮次都会增加。

示意性结构(命令为通用示例):

  1. # 技能:repo-release-and-issues
  2. ## 何时使用
  3. 需要了解仓库最新发布版本,或按标签筛选未关闭问题单时。
  4. ## 常用命令(示意)
  5. releases list --limit 1 --json name,publishedAt
  6. issues list --state open --label <label> --limit <n> --json number,title,createdAt
  7. ## 注意事项
  8. - 输出选择 JSON 格式,便于筛选字段
  9. - 用 --limit 控制返回条数,避免一次性拉取过多内容

4.3 上下文协议:用schema声明工具

按MCP类协议,宿主在会话开始时与server协商能力,获取每个工具的名称、描述和参数schema,再把它们注入模型上下文。模型生成结构化的工具调用,宿主转发给server执行,再把结果回传。示意如下:

  1. host ──initialize──▶ server # 协商协议版本与能力
  2. host ◀─tools/list── server # 返回全部工具的名称、描述与 schema
  3. model ──tools/call──▶ host ──▶ server
  4. model ◀──tool_result─ host ◀── server # 结构化结果回传

模型看到的是“有哪些工具、每个工具收什么参数、返回什么”,而不是“有一台shell可以执行命令”。

由此带来两类负担:

  • 入口负担:工具数量乘以单个定义的体量。工具集越大,这部分越重;而当前很多客户端是全量注入。
  • 结果负担:结果的结构由服务端决定,调用方只能事后过滤。字段全、分页大时,结果可能很宽,并被后续每一轮携带。

五、成本建模:把两笔账算清楚

把上面的过程抽象成一个通用模型(N为对话轮数):

  1. 上下文总token ≈ Σ(系统提示 + 工具定义 + Σ工具结果)
  2. = N × (系统提示 + 工具定义) + Σ (轮次 × 累计工具结果)
  • 第一项对应入口账,随轮次线性增长,属于可缓存的固定开销。
  • 第二项对应结果账,随轮次近似平方增长。单轮结果越大,或后续轮次越多,这一项增长越快。

每轮多携带约500 token,10轮就是约5,000 token,100轮可达约5万 token。因此控制结果大小,往往比删减几条工具定义更有效。

同时应看到,MCP本身并不必然昂贵。工具增多带来的token增长大体是线性的。典型问题不是协议本身,而是三件事叠加:

  • 默认全量加载;
  • 缺少按需发现机制;
  • 结果没有裁剪。

按需加载、工具集分组、结果分页与摘要,都能压缩入口账与结果账。精简工具集后重测,数字很可能明显改变,但效果须以实测为准。

六、典型场景:各自适合什么

接入方式 更适合的场景 主要前提
命令行 本机开发调试;任务路径不确定、需临时探索;token预算敏感、长链路多轮任务 存在shell环境;工具已安装并完成认证
技能文档 高频、重复的操作(发布流程、缺陷筛查);团队希望把最佳实践沉淀为统一规范 工具相对稳定,文档能持续维护
上下文协议 无shell的托管或沙箱环境;需要服务端统一鉴权、参数校验与细粒度权限;多客户端共享同一套工具;接口本身已是结构化API 工具定义精简或按需加载,返回内容可控

三者可以并存:核心能力以结构化工具提供,长尾操作交给命令行,高频流程再配技能文档。具体做法因客户端而异,须以所接入平台的配置方式为准。

在云上托管智能体服务时,还需同时考虑几类基础能力:

以百度智能云为例,这些都属于可选的基础类目,按业务需要组合即可。

七、相关概念区别

  • 工具调用(function/tool calling):模型输出结构化调用的通用能力。技能文档给的是知识而非执行通道,命令行与协议则是它的两种实现路径。
  • 代码执行式工具调用:让模型直接写代码,由沙箱统一执行并只回传结果。它同样能把大量中间处理压在沙箱里,与“用命令过滤结果”的思路相近。
  • 工具网关:在模型与多个server之间做统一路由、鉴权和裁剪,可集中实施按需加载与结果截断。
  • RAG:为模型提供知识,不提供动作。技能文档在性质上接近“面向操作的程序化知识”,更接近检索增强的做法。

八、选型与使用注意事项

  1. 分开度量,而非只看总数。 分别统计“动手前读入”和“结果带回”两部分;至少记录输入token、输出token、轮次与耗时,统一计费口径后再比较。
  2. 明确数字的前提条件。 token倍数依赖模型、工具集、客户端实现和运行环境。例如同一server经远程HTTP访问与本地stdio访问,序列化开销未必相同。
  3. 控制结果规模。 优先使用筛选、分页、字段选择,必要时做摘要或落盘,只把结论带回上下文。这是成本优化中收益较直接的一环。
  4. 工具集按需组织。 可按领域分组、默认最小集,或在调用前检索相关工具定义。工具描述写得越冗余,入口账越重。
  5. 注意重复发送带来的乘数效应。 长链路任务要关注上下文随轮次的累积,及时对旧结果做压缩。
  6. 做好安全边界。 命令行方式要防注入、限制权限,可用白名单命令或沙箱隔离;协议方式要校验参数、限定工具权限、对服务端输出保持信任边界意识。
  7. 别把“答对率”与“成本”混为一谈。 单次成功的成本倍数不等于稳定可用的性价比。应结合多次运行的成功率与返工成本一起评估。
  8. 关注生态与可移植性。 协议式接入的优势在于工具服务可跨客户端复用,命令行与技能则更依赖运行环境。选型应兼顾长期维护成本。

九、总结

回到定义本身:工具接入方式是智能体获得外部能力的机制;上下文成本是它为“读说明”和“带结果”付出的token代价。在这项受控实测中,同一道题、同一个模型,裸CLI、技能文档、默认全量协议接入的输入token分别约为1,421、3,315、59,417,最高约42倍;美元成本约17倍。这说明“回归命令行”的合理内核并不是否定协议,而是两点主张:

  • 工具接入应尽量薄;
  • 说明与结果都应按需付费。

47倍与17倍的落差也提醒我们,token倍数与费用倍数并不等价。技能文档进一步说明,把用法写成按需加载的知识,能以较低代价获得接近原生的表现。结论的边界同样清晰:一个server、一道任务、三次运行,只能支持“在受控条件下成本差异显著”这一判断。换模型、换工具集、换客户端或增加任务数量后,都应重新测量。对开发者而言,可靠的做法是先定义任务、固定变量,再把两笔账分别测清楚,再决定用什么方式接入工具。

发表评论

活动