1. 端侧 Agent 工程化的核心命题1.1 从 Demo 到产品为什么工程化是分水岭很多人第一次接触端侧 Agent都是从一个几十行的脚本开始的定义一个工具函数把 JSON Schema 塞进请求体模型返回一个tool_calls解析出来执行再把结果拼回对话。跑通那一刻确实很爽但只要你试图把它变成一个真正能交付的东西问题就会像潮水一样涌上来。我自己踩过的第一个大坑是在一个本地文档助手项目里。Demo 阶段一切正常用户问“帮我总结一下这份合同”模型调用read_file返回内容总结结束。可当用户开始连续追问、切换话题、要求修改上一步结果时整个链路就崩了——模型开始胡编工具名参数类型对不上多轮之后上下文里堆满了无效的工具返回token 消耗飙升响应越来越慢。这就是端侧 Agent 工程化要解决的核心命题把“能跑”变成“稳定地跑、可观测地跑、可维护地跑”。端侧环境和云端不一样你没有无限的计算资源没有随时可查的服务端日志用户设备上的模型能力也参差不齐。工程化不是锦上添花而是决定这个 Agent 能不能活下来的底线。这一篇我们先聚焦工程化的上半场工具调用的协议层设计、JSON Schema 的实战写法、以及 Function Calling 与 MCP 的选型逻辑。这些是地基地基没打好后面做再多编排和优化都是空中楼阁。1.2 端侧 Agent 工程化的四个核心维度在展开细节之前我先把端侧 Agent 工程化的全貌摊开让你知道我们在这张地图的哪个位置。根据我自己的项目经验端侧 Agent 的工程化可以拆成四个维度协议层Agent 和模型之间、Agent 和工具之间用什么格式通信。这是最底层的东西决定了上层能做什么。执行层工具怎么注册、怎么调度、怎么处理并发和超时。这一层直接关系到用户体验。状态层多轮对话的上下文怎么管理工具调用的中间结果怎么存储和裁剪。观测层出了问题怎么排查性能瓶颈在哪里怎么量化 Agent 的表现。这一篇重点讲协议层因为协议层是端侧 Agent 最容易被忽视、也最容易埋雷的地方。很多人觉得“不就是个 JSON 吗”但恰恰是这个 JSON 的设计决定了你的 Agent 在面对复杂任务时是游刃有余还是一团乱麻。提示端侧 Agent 和云端 Agent 最大的区别在于资源约束和隐私要求。端侧意味着模型可能跑在手机、PC 或边缘设备上工具调用往往涉及本地文件、本地数据库所以协议设计必须考虑轻量化和安全性。2. Function Calling 的协议细节与实战陷阱2.1 Function Calling 到底在做什么Function Calling 这个词被用得很泛但它的本质其实很简单让模型输出一个结构化的意图而不是自然语言。传统对话里模型输出的是“好的我来帮你查一下天气”你需要用正则去解析这句话。Function Calling 让模型直接输出{ name: get_weather, arguments: { city: 杭州, unit: celsius } }这个转变的意义在于自然语言是不可靠的结构化数据是可靠的。模型可能今天说“我帮你查”明天说“正在为您查询”但tool_calls的格式是固定的。工程化的第一步就是把这个固定格式用好、用稳。但这里有个很多人忽略的点Function Calling 并不是模型“真的调用了函数”它只是生成了一个符合你定义的 JSON。真正执行函数的是你的代码。理解这一点很重要因为它意味着两件事第一模型可能生成错误的参数你必须做校验第二模型可能生成不存在的函数名你必须做兜底。2.2 JSON Schema 写得好不好直接决定 Agent 的智商我见过太多项目工具定义写得极其随意然后抱怨模型“不听话”。实际上模型的表现很大程度上取决于你的 JSON Schema 写得够不够清晰。JSON Schema 不只是给程序看的它也是给模型看的“说明书”。先看一个反面例子{ name: search, description: 搜索, parameters: { type: object, properties: { q: { type: string } } } }这个定义的问题在于description太模糊模型不知道搜什么、在哪搜、返回什么参数名q没有语义模型容易和别的工具混淆。实测下来这种定义在简单场景还能凑合一旦工具数量超过五个模型就开始乱调。再看一个我实际项目中用的版本{ name: search_local_documents, description: 在用户的本地文档库中搜索相关内容。当用户询问自己的笔记、合同、报告等本地文件时使用此工具。不适用于搜索互联网信息。, parameters: { type: object, properties: { query: { type: string, description: 搜索关键词或自然语言问题例如去年的采购合同或项目复盘要点 }, file_types: { type: array, items: { type: string, enum: [pdf, docx, md, txt] }, description: 限定搜索的文件类型不传则搜索所有类型 }, max_results: { type: integer, description: 返回的最大结果数默认5最大20, minimum: 1, maximum: 20 } }, required: [query] } }差别在哪里我总结了几个关键点description 要写“什么时候用”和“什么时候不用”。模型需要边界你告诉它“不适用于搜索互联网”它就不会在用户问新闻时乱调这个工具。参数名要有语义。query比q好max_results比n好。模型在生成参数时语义化的名字能显著降低出错率。用 enum 约束取值范围。file_types用 enum 限定模型就不会生成word这种你处理不了的值。用 minimum/maximum 约束数值。这能防止模型生成max_results: 1000这种把本地库拖垮的请求。required 要精确。只把真正必需的参数放进 required可选参数给默认值减少模型的决策负担。注意description 不是越长越好。我试过写两百字的 description结果模型反而抓不住重点。控制在两三句话第一句说用途第二句说边界必要时第三句举例。2.3 参数校验永远不要相信模型的输出即使你的 Schema 写得再好也必须假设模型会出错。这不是对模型的不信任而是工程上的基本防御。我在项目里见过模型生成过这些离谱的参数数字类型的参数返回字符串5而不是5enum 里没有的值比如file_types: [excel]必填参数缺失嵌套对象结构错误参数名拼写错误比如querys所以参数校验层是必须的。我的做法是分三层第一层是Schema 校验用 JSON Schema 校验库Python 里可以用jsonschemaJS 里可以用ajv做严格校验。这一层能拦住大部分格式错误。第二层是业务校验比如max_results虽然 Schema 允许 20但当前设备内存紧张实际只能给 10这一层做动态调整。第三层是兜底修复对于常见的类型错误做自动转换比如字符串数字转数字。但要注意修复要保守修不了就返回错误让模型重试不要强行猜。import jsonschema def validate_tool_call(tool_call, tool_schema): try: jsonschema.validate( instancetool_call[arguments], schematool_schema[parameters] ) return True, None except jsonschema.ValidationError as e: return False, str(e)校验失败后怎么办我的经验是把错误信息返回给模型让它重新生成。这比直接报错给用户体验好得多。错误信息要具体比如“参数 max_results 必须是 1 到 20 之间的整数你给的是 100”模型看到这个通常能自己纠正。2.4 多工具场景下的命名与分组策略当你的 Agent 只有两三个工具时随便命名都行。但当工具数量上到十几个命名就成了大问题。我踩过的坑是有两个工具分别叫get_user_info和fetch_user_profile功能其实差不多结果模型在两者之间反复横跳行为不稳定。后来我总结了一套命名规范动词开头语义唯一search_documents、read_file、write_note、delete_reminder。避免get、fetch、query混用表达同一个意思。按领域分组前缀文件相关的用file_前缀日程相关的用calendar_前缀。这样模型在理解工具集时能形成聚类。工具数量超过 15 个时考虑分组加载不是所有工具都需要一次性暴露给模型。可以根据当前对话的意图动态选择相关的工具子集。这能显著降低模型的决策难度。我实测过一个对比20 个工具一次性暴露模型选错工具的概率大概在 15% 左右按意图动态加载 5 到 7 个相关工具选错率降到 3% 以下。这个差距在端侧尤其重要因为端侧模型能力通常弱于云端大模型更需要减少干扰。3. MCP端侧 Agent 工具协议的新选择3.1 MCP 是什么为什么端侧需要它MCP 全称 Model Context Protocol是一个开放的工具调用协议。它的核心思路是把工具的提供方和使用方解耦。传统 Function Calling 里工具定义是硬编码在 Agent 里的MCP 里工具由独立的 Server 提供Agent 作为 Client 去发现和调用。这个设计对端侧 Agent 特别有意义。想象一下你的端侧 Agent 需要访问本地文件、本地数据库、本地日历、本地笔记软件。如果每个都硬编码代码会膨胀得难以维护。用 MCP每个能力可以做成一个独立的 ServerAgent 启动时动态发现有哪些工具可用。MCP 的基本交互流程是这样的Client 连接到 Server发送initialize请求Server 返回自己的能力列表包括支持的工具Client 发送tools/list获取工具详情Client 发送tools/call执行具体工具Server 返回执行结果这个流程看起来比 Function Calling 复杂但它带来的好处是工具的热插拔。用户装了一个新的本地应用只要它提供了 MCP Server你的 Agent 就能立刻用上不需要改一行代码。3.2 MCP 与 Function Calling 的选型对比很多人问既然有了 Function Calling为什么还要 MCP我的答案是它们解决的不是同一个问题。Function Calling 解决的是“模型怎么表达调用意图”MCP 解决的是“工具怎么被发现和提供”。维度Function CallingMCP工具定义位置硬编码在 Agent 中独立 Server 提供工具发现静态启动时确定动态可运行时发现跨应用复用差每个 Agent 都要重写好Server 可被多个 Client 复用实现复杂度低中高端侧适用场景工具固定、数量少工具多变、需要扩展通信方式随模型请求一起发送独立协议支持多种传输我的选型建议是工具数量少于 8 个且长期稳定直接用 Function Calling简单直接没必要引入 MCP 的复杂度。工具需要动态扩展或要跨多个 Agent 复用上 MCP。比如你做了一个本地文件 MCP Server那么文档助手、代码助手、笔记助手都能用。端侧资源极度受限谨慎用 MCP因为多一个 Server 就多一份内存和进程开销。可以考虑把 MCP Server 做成轻量的本地进程按需启动。提示MCP 的传输层可以选 stdio 或 HTTP。端侧场景我推荐 stdio因为不占端口、不需要网络栈进程间通信开销也小。HTTP 适合 Server 和 Client 不在同一台机器的情况。3.3 端侧 MCP Server 的实现要点如果你决定在端侧用 MCP有几个实现要点必须注意。我以本地文件 MCP Server 为例讲一下关键设计。第一能力声明要精确。MCP Server 在initialize时返回的能力列表决定了 Client 怎么和它交互。如果你声明支持tools就要确保tools/list和tools/call都实现正确。声明了不实现Client 会报错。第二工具描述要遵循和 Function Calling 一样的规范。MCP 的工具定义本质上还是 JSON Schema所以前面讲的 description 写法、参数命名、enum 约束在这里同样适用。不要因为换了协议就放松要求。第三错误处理要规范。MCP 定义了标准的错误码比如-32601表示方法不存在-32602表示参数无效。端侧场景下工具执行失败是常态文件不存在、权限不足、磁盘满要把这些错误映射到合适的错误码并给出人类可读的错误信息。# 一个简化的 MCP Server 工具调用处理 def handle_tools_call(request): tool_name request[params][name] arguments request[params].get(arguments, {}) if tool_name not in REGISTERED_TOOLS: return { error: { code: -32601, message: f工具 {tool_name} 不存在 } } try: result REGISTERED_TOOLS[tool_name](**arguments) return {result: {content: [{type: text, text: result}]}} except FileNotFoundError as e: return { error: { code: -32000, message: f文件未找到: {e} } }第四生命周期管理。端侧 MCP Server 不能一直挂着占资源。我的做法是懒加载Agent 启动时不启动所有 Server而是在第一次需要某类工具时才启动对应的 Server并设置空闲超时自动关闭。3.4 MCP 在端侧的典型应用场景MCP 在端侧最有价值的场景是把本地能力标准化地暴露给 Agent。我列几个我实际做过或见过的场景本地文件系统 MCP让 Agent 能读写本地文件支持搜索、读取、写入、删除。这是最基础也最常用的。本地数据库 MCP把 SQLite 或本地缓存暴露成工具Agent 可以查询用户的历史数据。本地应用 MCP比如笔记软件、日历、邮件客户端各自提供 MCP ServerAgent 统一调用。开发工具 MCP代码编辑器、调试器、构建工具通过 MCP 暴露能力Agent 可以辅助开发。这些场景的共同点是能力是本地独有的云端拿不到而且需要标准化接口。MCP 正好填补了这个空白。4. 工具调用的执行链路与状态管理4.1 一次工具调用的完整生命周期理解了协议层我们来看执行层。一次工具调用从模型生成意图到最终返回结果中间经过了好几个环节每个环节都可能出问题。完整链路是这样的意图生成模型根据对话上下文和工具定义生成tool_calls意图解析Agent 解析tool_calls提取工具名和参数参数校验按前面讲的三层校验做检查工具路由根据工具名找到对应的执行器执行调用实际函数可能涉及 IO、网络、计算结果封装把执行结果转成模型能理解的格式上下文回填把结果作为tool角色的消息加回对话二次生成模型基于工具结果生成最终回复这八步里第 5 步和第 8 步是最容易出问题的。第 5 步可能超时、可能抛异常第 8 步可能因为工具结果太长导致上下文溢出。4.2 超时、重试与并发控制端侧工具执行最怕的就是卡死。用户点了发送界面转圈十秒没反应体验直接崩。所以超时控制是必须的。我的经验值是本地 IO 类工具超时 3 秒网络类工具超时 10 秒计算类工具超时 30 秒。超过就中断返回超时错误给模型让模型决定是重试还是换方案。重试要谨慎。不是所有工具都适合重试。读文件失败重试一次合理写文件失败重试可能导致重复写入。我的做法是给每个工具标记retryable属性只对幂等的读操作做自动重试写操作失败直接返回错误。并发控制方面端侧资源有限不能让模型一次发起十个工具调用把设备拖垮。我通常限制单轮最多 3 个并发工具调用超过的排队执行。这个数字可以根据设备性能调整低端设备降到 1 到 2 个。import asyncio from asyncio import Semaphore class ToolExecutor: def __init__(self, max_concurrent3): self.semaphore Semaphore(max_concurrent) async def execute(self, tool_name, arguments, timeout10): async with self.semaphore: try: result await asyncio.wait_for( self._run_tool(tool_name, arguments), timeouttimeout ) return {success: True, result: result} except asyncio.TimeoutError: return {success: False, error: 工具执行超时} except Exception as e: return {success: False, error: str(e)}4.3 工具结果的裁剪与上下文管理这是端侧 Agent 最容易被忽视、但影响最大的环节。工具返回的结果往往很长比如读一个文件返回几千字搜索返回十几条结果。如果原样塞回上下文几轮之后 token 就爆了。我的裁剪策略分三步第一步工具层面做初步裁剪。读文件时只返回前 N 个字符搜索时只返回摘要而不是全文。这个 N 要根据模型上下文窗口动态调整。端侧模型上下文通常 4K 到 8K我一般给单个工具结果留 500 到 1000 token 的预算。第二步Agent 层面做结果摘要。如果工具结果确实需要完整保留可以先让模型对结果做一次摘要再把摘要放回上下文。这多了一次模型调用但能大幅节省后续的 token。第三步上下文层面做滑动窗口。保留最近 N 轮对话更早的工具结果只保留摘要或直接丢弃。丢弃时要小心如果后续对话引用了被丢弃的内容模型会答非所问。我的做法是在丢弃前把关键信息提取成一条“记忆”消息保留。注意裁剪不是简单地截断字符串。截断可能把 JSON 截坏导致模型解析失败。要么按结构裁剪比如只保留前 5 条搜索结果要么明确标注“内容已截断”。4.4 多轮对话中的工具状态保持多轮对话里工具调用的状态管理是个精细活。用户可能说“帮我查一下那份合同”Agent 调用搜索工具返回三个结果。用户接着说“看第二个”Agent 需要知道“第二个”指的是上一轮搜索结果里的第二个。这要求 Agent 维护一个工具结果引用表。每次工具返回结果给结果分配一个引用 ID并在上下文里保留这个 ID 和结果的映射。用户说“第二个”时Agent 能通过引用表找到对应的结果。实现上我通常把工具结果存成一个列表每条结果带一个序号。在回填上下文时把序号也带上比如“搜索结果 1...搜索结果 2...”。模型看到序号就能理解用户的指代。这个机制在端侧尤其重要因为端侧模型能力有限指望它自己记住上一轮的结果不现实。显式地给结果编号是最稳妥的做法。5. 常见问题排查与避坑实录5.1 模型不调用工具或调用错误工具这是最高频的问题。模型该调工具时不调或者调了错误的工具。排查思路按这个顺序来先看工具定义。description 是否清晰参数名是否有语义工具之间是否有功能重叠我遇到过两个工具search和find功能几乎一样模型就随机选。合并成一个后问题消失。再看系统提示词。系统提示里有没有明确告诉模型“你有工具可用需要时请调用”有些模型需要显式引导才会调工具。加一句“当需要获取外部信息时优先使用提供的工具”往往能解决。最后看模型能力。端侧小模型在工具调用上的表现确实弱于大模型。如果工具数量多、参数复杂小模型可能力不从心。这时候要么换模型要么简化工具集。5.2 参数格式错误与类型不匹配模型生成的参数类型不对是第二高频问题。常见的有数字给成字符串、数组给成单个值、嵌套对象结构错误。排查时先打印模型原始输出看它到底生成了什么。如果发现是系统性的类型错误比如总是把数字给成字符串可以在 description 里明确写“此参数为整数类型例如 5”。模型对显式的类型提示是有反应的。如果是个别错误靠参数校验层兜底。校验失败返回错误给模型重试通常一两次就能纠正。但要设置重试上限比如最多重试两次避免死循环。5.3 工具执行超时或卡死端侧工具卡死的原因很多文件太大、网络不通、死锁。排查时先确认是哪个工具卡住加日志记录每个工具的开始和结束时间。如果是文件太大做分块读取。如果是网络问题加超时和降级。如果是死锁检查工具实现里有没有循环等待。我踩过的一个坑是工具里用了同步 IO把整个事件循环堵死了。端侧 Agent 通常是异步架构工具实现必须用异步 IO或者放到线程池里执行。这个坑很隐蔽因为单次调用看起来正常并发时就出问题。5.4 上下文溢出与 token 爆炸多轮对话后 token 超限是端侧 Agent 的常见死法。排查时统计每轮对话的 token 消耗找出增长最快的部分。通常是工具结果太长。解决办法前面讲过工具层裁剪、结果摘要、滑动窗口。这里补充一个技巧给工具结果设置硬性 token 上限超过就强制摘要。摘要可以用一个轻量的小模型做不占用主模型的上下文。5.5 常见问题速查表问题现象可能原因排查方向解决手段模型不调工具定义不清、提示词缺失检查 description 和系统提示优化定义、加引导语调用错误工具工具功能重叠、命名混乱检查工具集合并工具、规范命名参数类型错误类型提示不足打印原始输出加类型说明、校验兜底工具执行超时IO 阻塞、网络问题加日志定位异步化、加超时上下文溢出工具结果过长统计 token 分布裁剪、摘要、滑窗多轮指代错误缺少结果引用检查上下文回填给结果编号5.6 几个我踩过的独家坑第一个坑工具返回的 JSON 里有特殊字符。有一次工具返回的内容里包含了未转义的引号导致模型解析失败。后来我在结果封装层统一做了转义处理所有工具结果都经过一次 JSON 安全化。第二个坑模型在工具调用和自然语言回复之间反复横跳。用户问“今天天气怎么样”模型先调天气工具拿到结果后不直接回答又调了一次。原因是系统提示里没告诉它“拿到结果后直接回答”。加一句“工具返回结果后请基于结果直接回复用户不要重复调用”就解决了。第三个坑端侧模型对长工具名的处理。我有个工具叫search_local_documents_by_keyword模型经常把它截断成search_local_documents。后来我把工具名缩短到search_docs问题消失。端侧模型对长标识符的处理能力有限工具名尽量短。第四个坑并发工具调用时的资源竞争。两个工具同时读写同一个文件结果互相覆盖。解决办法是给工具加锁或者串行执行有资源冲突的工具。我在工具定义里加了一个resource字段标记它访问的资源调度时同资源的工具串行执行。6. 工程化上半场的收束与下半场预告写到这里协议层和执行层的核心问题基本覆盖了。回顾一下端侧 Agent 工程化的上半场重点在于把工具调用的地基打牢JSON Schema 要写得让模型看得懂参数校验要做得让错误拦得住MCP 要用得让扩展变得容易执行链路要管得让状态不失控。这些东西听起来都是细节但恰恰是这些细节决定了你的 Agent 是玩具还是产品。我在项目里最大的体会是Agent 的智能程度一半靠模型一半靠工程。模型再强工具定义写得稀烂照样跑不起来模型一般但工程做得扎实反而能稳定输出。下半场我会讲编排层和观测层多工具怎么编排成工作流Agent 的决策过程怎么观测和调试端侧性能怎么优化以及怎么做 A/B 测试来量化 Agent 的表现。这些是让 Agent 从“能用”走向“好用”的关键。最后分享一个我一直在用的小技巧给每个工具调用打上 trace ID。从模型生成意图到参数校验到执行到结果回填全链路用同一个 trace ID 串起来。出问题时一条 trace 就能还原整个调用过程。这个习惯帮我省了无数排查时间尤其是在端侧这种日志获取困难的场景下trace ID 就是你的救命稻草。 
长河君 · 2026/10/7 19:15:22 · 阅读 1.2k 端侧Agent工程化实战：Function Calling与MCP协议设计
1. 端侧 Agent 工程化的核心命题1.1 从 Demo 到产品为什么工程化是分水岭很多人第一次接触端侧 Agent都是从一个几十行的脚本开始的定义一个工具函数把 JSON Schema 塞进请求体模型返回一个tool_calls解析出来执行再把结果拼回对话。跑通那一刻确实很爽但只要你试图把它变成一个真正能交付的东西问题就会像潮水一样涌上来。我自己踩过的第一个大坑是在一个本地文档助手项目里。Demo 阶段一切正常用户问“帮我总结一下这份合同”模型调用read_file返回内容总结结束。可当用户开始连续追问、切换话题、要求修改上一步结果时整个链路就崩了——模型开始胡编工具名参数类型对不上多轮之后上下文里堆满了无效的工具返回token 消耗飙升响应越来越慢。这就是端侧 Agent 工程化要解决的核心命题把“能跑”变成“稳定地跑、可观测地跑、可维护地跑”。端侧环境和云端不一样你没有无限的计算资源没有随时可查的服务端日志用户设备上的模型能力也参差不齐。工程化不是锦上添花而是决定这个 Agent 能不能活下来的底线。这一篇我们先聚焦工程化的上半场工具调用的协议层设计、JSON Schema 的实战写法、以及 Function Calling 与 MCP 的选型逻辑。这些是地基地基没打好后面做再多编排和优化都是空中楼阁。1.2 端侧 Agent 工程化的四个核心维度在展开细节之前我先把端侧 Agent 工程化的全貌摊开让你知道我们在这张地图的哪个位置。根据我自己的项目经验端侧 Agent 的工程化可以拆成四个维度协议层Agent 和模型之间、Agent 和工具之间用什么格式通信。这是最底层的东西决定了上层能做什么。执行层工具怎么注册、怎么调度、怎么处理并发和超时。这一层直接关系到用户体验。状态层多轮对话的上下文怎么管理工具调用的中间结果怎么存储和裁剪。观测层出了问题怎么排查性能瓶颈在哪里怎么量化 Agent 的表现。这一篇重点讲协议层因为协议层是端侧 Agent 最容易被忽视、也最容易埋雷的地方。很多人觉得“不就是个 JSON 吗”但恰恰是这个 JSON 的设计决定了你的 Agent 在面对复杂任务时是游刃有余还是一团乱麻。提示端侧 Agent 和云端 Agent 最大的区别在于资源约束和隐私要求。端侧意味着模型可能跑在手机、PC 或边缘设备上工具调用往往涉及本地文件、本地数据库所以协议设计必须考虑轻量化和安全性。2. Function Calling 的协议细节与实战陷阱2.1 Function Calling 到底在做什么Function Calling 这个词被用得很泛但它的本质其实很简单让模型输出一个结构化的意图而不是自然语言。传统对话里模型输出的是“好的我来帮你查一下天气”你需要用正则去解析这句话。Function Calling 让模型直接输出{ name: get_weather, arguments: { city: 杭州, unit: celsius } }这个转变的意义在于自然语言是不可靠的结构化数据是可靠的。模型可能今天说“我帮你查”明天说“正在为您查询”但tool_calls的格式是固定的。工程化的第一步就是把这个固定格式用好、用稳。但这里有个很多人忽略的点Function Calling 并不是模型“真的调用了函数”它只是生成了一个符合你定义的 JSON。真正执行函数的是你的代码。理解这一点很重要因为它意味着两件事第一模型可能生成错误的参数你必须做校验第二模型可能生成不存在的函数名你必须做兜底。2.2 JSON Schema 写得好不好直接决定 Agent 的智商我见过太多项目工具定义写得极其随意然后抱怨模型“不听话”。实际上模型的表现很大程度上取决于你的 JSON Schema 写得够不够清晰。JSON Schema 不只是给程序看的它也是给模型看的“说明书”。先看一个反面例子{ name: search, description: 搜索, parameters: { type: object, properties: { q: { type: string } } } }这个定义的问题在于description太模糊模型不知道搜什么、在哪搜、返回什么参数名q没有语义模型容易和别的工具混淆。实测下来这种定义在简单场景还能凑合一旦工具数量超过五个模型就开始乱调。再看一个我实际项目中用的版本{ name: search_local_documents, description: 在用户的本地文档库中搜索相关内容。当用户询问自己的笔记、合同、报告等本地文件时使用此工具。不适用于搜索互联网信息。, parameters: { type: object, properties: { query: { type: string, description: 搜索关键词或自然语言问题例如去年的采购合同或项目复盘要点 }, file_types: { type: array, items: { type: string, enum: [pdf, docx, md, txt] }, description: 限定搜索的文件类型不传则搜索所有类型 }, max_results: { type: integer, description: 返回的最大结果数默认5最大20, minimum: 1, maximum: 20 } }, required: [query] } }差别在哪里我总结了几个关键点description 要写“什么时候用”和“什么时候不用”。模型需要边界你告诉它“不适用于搜索互联网”它就不会在用户问新闻时乱调这个工具。参数名要有语义。query比q好max_results比n好。模型在生成参数时语义化的名字能显著降低出错率。用 enum 约束取值范围。file_types用 enum 限定模型就不会生成word这种你处理不了的值。用 minimum/maximum 约束数值。这能防止模型生成max_results: 1000这种把本地库拖垮的请求。required 要精确。只把真正必需的参数放进 required可选参数给默认值减少模型的决策负担。注意description 不是越长越好。我试过写两百字的 description结果模型反而抓不住重点。控制在两三句话第一句说用途第二句说边界必要时第三句举例。2.3 参数校验永远不要相信模型的输出即使你的 Schema 写得再好也必须假设模型会出错。这不是对模型的不信任而是工程上的基本防御。我在项目里见过模型生成过这些离谱的参数数字类型的参数返回字符串5而不是5enum 里没有的值比如file_types: [excel]必填参数缺失嵌套对象结构错误参数名拼写错误比如querys所以参数校验层是必须的。我的做法是分三层第一层是Schema 校验用 JSON Schema 校验库Python 里可以用jsonschemaJS 里可以用ajv做严格校验。这一层能拦住大部分格式错误。第二层是业务校验比如max_results虽然 Schema 允许 20但当前设备内存紧张实际只能给 10这一层做动态调整。第三层是兜底修复对于常见的类型错误做自动转换比如字符串数字转数字。但要注意修复要保守修不了就返回错误让模型重试不要强行猜。import jsonschema def validate_tool_call(tool_call, tool_schema): try: jsonschema.validate( instancetool_call[arguments], schematool_schema[parameters] ) return True, None except jsonschema.ValidationError as e: return False, str(e)校验失败后怎么办我的经验是把错误信息返回给模型让它重新生成。这比直接报错给用户体验好得多。错误信息要具体比如“参数 max_results 必须是 1 到 20 之间的整数你给的是 100”模型看到这个通常能自己纠正。2.4 多工具场景下的命名与分组策略当你的 Agent 只有两三个工具时随便命名都行。但当工具数量上到十几个命名就成了大问题。我踩过的坑是有两个工具分别叫get_user_info和fetch_user_profile功能其实差不多结果模型在两者之间反复横跳行为不稳定。后来我总结了一套命名规范动词开头语义唯一search_documents、read_file、write_note、delete_reminder。避免get、fetch、query混用表达同一个意思。按领域分组前缀文件相关的用file_前缀日程相关的用calendar_前缀。这样模型在理解工具集时能形成聚类。工具数量超过 15 个时考虑分组加载不是所有工具都需要一次性暴露给模型。可以根据当前对话的意图动态选择相关的工具子集。这能显著降低模型的决策难度。我实测过一个对比20 个工具一次性暴露模型选错工具的概率大概在 15% 左右按意图动态加载 5 到 7 个相关工具选错率降到 3% 以下。这个差距在端侧尤其重要因为端侧模型能力通常弱于云端大模型更需要减少干扰。3. MCP端侧 Agent 工具协议的新选择3.1 MCP 是什么为什么端侧需要它MCP 全称 Model Context Protocol是一个开放的工具调用协议。它的核心思路是把工具的提供方和使用方解耦。传统 Function Calling 里工具定义是硬编码在 Agent 里的MCP 里工具由独立的 Server 提供Agent 作为 Client 去发现和调用。这个设计对端侧 Agent 特别有意义。想象一下你的端侧 Agent 需要访问本地文件、本地数据库、本地日历、本地笔记软件。如果每个都硬编码代码会膨胀得难以维护。用 MCP每个能力可以做成一个独立的 ServerAgent 启动时动态发现有哪些工具可用。MCP 的基本交互流程是这样的Client 连接到 Server发送initialize请求Server 返回自己的能力列表包括支持的工具Client 发送tools/list获取工具详情Client 发送tools/call执行具体工具Server 返回执行结果这个流程看起来比 Function Calling 复杂但它带来的好处是工具的热插拔。用户装了一个新的本地应用只要它提供了 MCP Server你的 Agent 就能立刻用上不需要改一行代码。3.2 MCP 与 Function Calling 的选型对比很多人问既然有了 Function Calling为什么还要 MCP我的答案是它们解决的不是同一个问题。Function Calling 解决的是“模型怎么表达调用意图”MCP 解决的是“工具怎么被发现和提供”。维度Function CallingMCP工具定义位置硬编码在 Agent 中独立 Server 提供工具发现静态启动时确定动态可运行时发现跨应用复用差每个 Agent 都要重写好Server 可被多个 Client 复用实现复杂度低中高端侧适用场景工具固定、数量少工具多变、需要扩展通信方式随模型请求一起发送独立协议支持多种传输我的选型建议是工具数量少于 8 个且长期稳定直接用 Function Calling简单直接没必要引入 MCP 的复杂度。工具需要动态扩展或要跨多个 Agent 复用上 MCP。比如你做了一个本地文件 MCP Server那么文档助手、代码助手、笔记助手都能用。端侧资源极度受限谨慎用 MCP因为多一个 Server 就多一份内存和进程开销。可以考虑把 MCP Server 做成轻量的本地进程按需启动。提示MCP 的传输层可以选 stdio 或 HTTP。端侧场景我推荐 stdio因为不占端口、不需要网络栈进程间通信开销也小。HTTP 适合 Server 和 Client 不在同一台机器的情况。3.3 端侧 MCP Server 的实现要点如果你决定在端侧用 MCP有几个实现要点必须注意。我以本地文件 MCP Server 为例讲一下关键设计。第一能力声明要精确。MCP Server 在initialize时返回的能力列表决定了 Client 怎么和它交互。如果你声明支持tools就要确保tools/list和tools/call都实现正确。声明了不实现Client 会报错。第二工具描述要遵循和 Function Calling 一样的规范。MCP 的工具定义本质上还是 JSON Schema所以前面讲的 description 写法、参数命名、enum 约束在这里同样适用。不要因为换了协议就放松要求。第三错误处理要规范。MCP 定义了标准的错误码比如-32601表示方法不存在-32602表示参数无效。端侧场景下工具执行失败是常态文件不存在、权限不足、磁盘满要把这些错误映射到合适的错误码并给出人类可读的错误信息。# 一个简化的 MCP Server 工具调用处理 def handle_tools_call(request): tool_name request[params][name] arguments request[params].get(arguments, {}) if tool_name not in REGISTERED_TOOLS: return { error: { code: -32601, message: f工具 {tool_name} 不存在 } } try: result REGISTERED_TOOLS[tool_name](**arguments) return {result: {content: [{type: text, text: result}]}} except FileNotFoundError as e: return { error: { code: -32000, message: f文件未找到: {e} } }第四生命周期管理。端侧 MCP Server 不能一直挂着占资源。我的做法是懒加载Agent 启动时不启动所有 Server而是在第一次需要某类工具时才启动对应的 Server并设置空闲超时自动关闭。3.4 MCP 在端侧的典型应用场景MCP 在端侧最有价值的场景是把本地能力标准化地暴露给 Agent。我列几个我实际做过或见过的场景本地文件系统 MCP让 Agent 能读写本地文件支持搜索、读取、写入、删除。这是最基础也最常用的。本地数据库 MCP把 SQLite 或本地缓存暴露成工具Agent 可以查询用户的历史数据。本地应用 MCP比如笔记软件、日历、邮件客户端各自提供 MCP ServerAgent 统一调用。开发工具 MCP代码编辑器、调试器、构建工具通过 MCP 暴露能力Agent 可以辅助开发。这些场景的共同点是能力是本地独有的云端拿不到而且需要标准化接口。MCP 正好填补了这个空白。4. 工具调用的执行链路与状态管理4.1 一次工具调用的完整生命周期理解了协议层我们来看执行层。一次工具调用从模型生成意图到最终返回结果中间经过了好几个环节每个环节都可能出问题。完整链路是这样的意图生成模型根据对话上下文和工具定义生成tool_calls意图解析Agent 解析tool_calls提取工具名和参数参数校验按前面讲的三层校验做检查工具路由根据工具名找到对应的执行器执行调用实际函数可能涉及 IO、网络、计算结果封装把执行结果转成模型能理解的格式上下文回填把结果作为tool角色的消息加回对话二次生成模型基于工具结果生成最终回复这八步里第 5 步和第 8 步是最容易出问题的。第 5 步可能超时、可能抛异常第 8 步可能因为工具结果太长导致上下文溢出。4.2 超时、重试与并发控制端侧工具执行最怕的就是卡死。用户点了发送界面转圈十秒没反应体验直接崩。所以超时控制是必须的。我的经验值是本地 IO 类工具超时 3 秒网络类工具超时 10 秒计算类工具超时 30 秒。超过就中断返回超时错误给模型让模型决定是重试还是换方案。重试要谨慎。不是所有工具都适合重试。读文件失败重试一次合理写文件失败重试可能导致重复写入。我的做法是给每个工具标记retryable属性只对幂等的读操作做自动重试写操作失败直接返回错误。并发控制方面端侧资源有限不能让模型一次发起十个工具调用把设备拖垮。我通常限制单轮最多 3 个并发工具调用超过的排队执行。这个数字可以根据设备性能调整低端设备降到 1 到 2 个。import asyncio from asyncio import Semaphore class ToolExecutor: def __init__(self, max_concurrent3): self.semaphore Semaphore(max_concurrent) async def execute(self, tool_name, arguments, timeout10): async with self.semaphore: try: result await asyncio.wait_for( self._run_tool(tool_name, arguments), timeouttimeout ) return {success: True, result: result} except asyncio.TimeoutError: return {success: False, error: 工具执行超时} except Exception as e: return {success: False, error: str(e)}4.3 工具结果的裁剪与上下文管理这是端侧 Agent 最容易被忽视、但影响最大的环节。工具返回的结果往往很长比如读一个文件返回几千字搜索返回十几条结果。如果原样塞回上下文几轮之后 token 就爆了。我的裁剪策略分三步第一步工具层面做初步裁剪。读文件时只返回前 N 个字符搜索时只返回摘要而不是全文。这个 N 要根据模型上下文窗口动态调整。端侧模型上下文通常 4K 到 8K我一般给单个工具结果留 500 到 1000 token 的预算。第二步Agent 层面做结果摘要。如果工具结果确实需要完整保留可以先让模型对结果做一次摘要再把摘要放回上下文。这多了一次模型调用但能大幅节省后续的 token。第三步上下文层面做滑动窗口。保留最近 N 轮对话更早的工具结果只保留摘要或直接丢弃。丢弃时要小心如果后续对话引用了被丢弃的内容模型会答非所问。我的做法是在丢弃前把关键信息提取成一条“记忆”消息保留。注意裁剪不是简单地截断字符串。截断可能把 JSON 截坏导致模型解析失败。要么按结构裁剪比如只保留前 5 条搜索结果要么明确标注“内容已截断”。4.4 多轮对话中的工具状态保持多轮对话里工具调用的状态管理是个精细活。用户可能说“帮我查一下那份合同”Agent 调用搜索工具返回三个结果。用户接着说“看第二个”Agent 需要知道“第二个”指的是上一轮搜索结果里的第二个。这要求 Agent 维护一个工具结果引用表。每次工具返回结果给结果分配一个引用 ID并在上下文里保留这个 ID 和结果的映射。用户说“第二个”时Agent 能通过引用表找到对应的结果。实现上我通常把工具结果存成一个列表每条结果带一个序号。在回填上下文时把序号也带上比如“搜索结果 1...搜索结果 2...”。模型看到序号就能理解用户的指代。这个机制在端侧尤其重要因为端侧模型能力有限指望它自己记住上一轮的结果不现实。显式地给结果编号是最稳妥的做法。5. 常见问题排查与避坑实录5.1 模型不调用工具或调用错误工具这是最高频的问题。模型该调工具时不调或者调了错误的工具。排查思路按这个顺序来先看工具定义。description 是否清晰参数名是否有语义工具之间是否有功能重叠我遇到过两个工具search和find功能几乎一样模型就随机选。合并成一个后问题消失。再看系统提示词。系统提示里有没有明确告诉模型“你有工具可用需要时请调用”有些模型需要显式引导才会调工具。加一句“当需要获取外部信息时优先使用提供的工具”往往能解决。最后看模型能力。端侧小模型在工具调用上的表现确实弱于大模型。如果工具数量多、参数复杂小模型可能力不从心。这时候要么换模型要么简化工具集。5.2 参数格式错误与类型不匹配模型生成的参数类型不对是第二高频问题。常见的有数字给成字符串、数组给成单个值、嵌套对象结构错误。排查时先打印模型原始输出看它到底生成了什么。如果发现是系统性的类型错误比如总是把数字给成字符串可以在 description 里明确写“此参数为整数类型例如 5”。模型对显式的类型提示是有反应的。如果是个别错误靠参数校验层兜底。校验失败返回错误给模型重试通常一两次就能纠正。但要设置重试上限比如最多重试两次避免死循环。5.3 工具执行超时或卡死端侧工具卡死的原因很多文件太大、网络不通、死锁。排查时先确认是哪个工具卡住加日志记录每个工具的开始和结束时间。如果是文件太大做分块读取。如果是网络问题加超时和降级。如果是死锁检查工具实现里有没有循环等待。我踩过的一个坑是工具里用了同步 IO把整个事件循环堵死了。端侧 Agent 通常是异步架构工具实现必须用异步 IO或者放到线程池里执行。这个坑很隐蔽因为单次调用看起来正常并发时就出问题。5.4 上下文溢出与 token 爆炸多轮对话后 token 超限是端侧 Agent 的常见死法。排查时统计每轮对话的 token 消耗找出增长最快的部分。通常是工具结果太长。解决办法前面讲过工具层裁剪、结果摘要、滑动窗口。这里补充一个技巧给工具结果设置硬性 token 上限超过就强制摘要。摘要可以用一个轻量的小模型做不占用主模型的上下文。5.5 常见问题速查表问题现象可能原因排查方向解决手段模型不调工具定义不清、提示词缺失检查 description 和系统提示优化定义、加引导语调用错误工具工具功能重叠、命名混乱检查工具集合并工具、规范命名参数类型错误类型提示不足打印原始输出加类型说明、校验兜底工具执行超时IO 阻塞、网络问题加日志定位异步化、加超时上下文溢出工具结果过长统计 token 分布裁剪、摘要、滑窗多轮指代错误缺少结果引用检查上下文回填给结果编号5.6 几个我踩过的独家坑第一个坑工具返回的 JSON 里有特殊字符。有一次工具返回的内容里包含了未转义的引号导致模型解析失败。后来我在结果封装层统一做了转义处理所有工具结果都经过一次 JSON 安全化。第二个坑模型在工具调用和自然语言回复之间反复横跳。用户问“今天天气怎么样”模型先调天气工具拿到结果后不直接回答又调了一次。原因是系统提示里没告诉它“拿到结果后直接回答”。加一句“工具返回结果后请基于结果直接回复用户不要重复调用”就解决了。第三个坑端侧模型对长工具名的处理。我有个工具叫search_local_documents_by_keyword模型经常把它截断成search_local_documents。后来我把工具名缩短到search_docs问题消失。端侧模型对长标识符的处理能力有限工具名尽量短。第四个坑并发工具调用时的资源竞争。两个工具同时读写同一个文件结果互相覆盖。解决办法是给工具加锁或者串行执行有资源冲突的工具。我在工具定义里加了一个resource字段标记它访问的资源调度时同资源的工具串行执行。6. 工程化上半场的收束与下半场预告写到这里协议层和执行层的核心问题基本覆盖了。回顾一下端侧 Agent 工程化的上半场重点在于把工具调用的地基打牢JSON Schema 要写得让模型看得懂参数校验要做得让错误拦得住MCP 要用得让扩展变得容易执行链路要管得让状态不失控。这些东西听起来都是细节但恰恰是这些细节决定了你的 Agent 是玩具还是产品。我在项目里最大的体会是Agent 的智能程度一半靠模型一半靠工程。模型再强工具定义写得稀烂照样跑不起来模型一般但工程做得扎实反而能稳定输出。下半场我会讲编排层和观测层多工具怎么编排成工作流Agent 的决策过程怎么观测和调试端侧性能怎么优化以及怎么做 A/B 测试来量化 Agent 的表现。这些是让 Agent 从“能用”走向“好用”的关键。最后分享一个我一直在用的小技巧给每个工具调用打上 trace ID。从模型生成意图到参数校验到执行到结果回填全链路用同一个 trace ID 串起来。出问题时一条 trace 就能还原整个调用过程。这个习惯帮我省了无数排查时间尤其是在端侧这种日志获取困难的场景下trace ID 就是你的救命稻草。