端侧Agent工程化：Function Calling与MCP落地实践

1. 端侧 Agent 工程化的核心命题端侧 Agent 这件事从概念验证走到真正能交付的产品中间隔着的不是模型能力而是工程化。我接触过不少团队Demo 阶段跑得挺漂亮一旦要上真机、要控内存、要保证响应延迟、要处理各种边界情况问题就全冒出来了。这一篇主要聊 Agent 工程化里最基础也最容易被低估的部分Function Calling 的落地设计、JSON Schema 的约束策略以及 MCP 在端侧场景下的接入思路。先把范围界定清楚。这里说的端侧 Agent指的是推理和决策逻辑主要跑在终端设备手机、PC、车机、嵌入式设备上的智能体而不是把请求全部丢给云端大模型再等结果返回。端侧意味着几个硬约束算力有限、内存有限、功耗敏感、网络可能不稳定甚至离线。这些约束直接决定了 Agent 工程化的设计取向——你不能照搬云端那套模型足够大、上下文足够长、随便调工具的思路。Function Calling 是 Agent 和外部世界交互的核心机制。模型输出一个结构化的调用请求运行时解析这个请求执行对应的函数再把结果喂回模型。听起来简单但工程化要解决的问题一大堆Schema 怎么定义才能让模型稳定输出参数校验放在哪一层调用失败怎么重试多个工具怎么编排MCP 作为这两年被广泛讨论的工具接入协议在端侧又该怎么用这些就是本文要拆开讲的内容。适合谁看如果你正在做端侧 AI 应用或者准备把云端 Agent 往端侧迁移又或者你只是想把 Function Calling 这套机制理解透这篇应该能给你一些可以直接抄的工程方案。我会尽量把每个设计决策背后的为什么讲清楚而不是只给结论。2. Function Calling 的工程化拆解2.1 从能调通到稳定调通的差距很多人第一次跑通 Function Calling 是在云端 API 上写个 JSON Schema模型返回一个 tool_calls 数组解析出来执行完事。但端侧完全是另一回事。端侧模型参数量通常小得多指令遵循能力弱对 Schema 的理解容易出现偏差。我实测过一个 3B 级别的模型同样的 Schema云端大模型能 100% 正确输出端侧模型大概只有 70% 左右的首次正确率剩下的要么字段名拼错要么参数类型搞混要么干脆输出一段自然语言而不是结构化调用。这个差距就是工程化要填的坑。核心思路是不要指望模型一次就对而是设计一套容错和约束机制让整体成功率逼近可用水平。具体来说端侧 Function Calling 的工程化要解决四层问题Schema 层怎么定义工具描述让模型更容易理解解析层怎么从模型输出里稳健地提取结构化调用执行层怎么安全地执行函数处理异常编排层多工具场景下怎么决定调用顺序和依赖关系这四层每一层都有讲究下面逐个拆。2.2 JSON Schema 的约束策略让模型少犯错JSON Schema 是 Function Calling 的契约。模型根据 Schema 生成参数运行时根据 Schema 校验参数。端侧场景下Schema 的设计原则和云端不太一样核心是降低模型的认知负担。第一个原则字段名要语义直白别玩缩写。我见过有人把destination_city写成dest把departure_time写成dep_t。云端大模型见多识广能猜出来端侧小模型直接懵。字段名就是给模型看的提示越直白越好。第二个原则枚举值优先于自由文本。如果某个参数只有几种可能取值一定用 enum 约束死。比如查询天气的工具unit参数就用[celsius, fahrenheit]不要让模型自由发挥。端侧模型在自由文本上的稳定性远不如在枚举选择上。第三个原则必填字段尽量少。每多一个 required 字段模型出错的概率就上升一截。能通过默认值解决的就不要设成必填。比如language参数默认zh就行没必要让模型每次都输出。第四个原则描述要写什么时候用而不只是是什么。这是最容易被忽略的一点。工具描述里除了说明参数含义更要说明这个工具在什么场景下应该被调用。端侧模型对上下文的理解能力弱明确的触发条件描述能显著提升调用准确率。下面是一个对比示例左边是容易出错的写法右边是端侧友好的写法// 不推荐字段名缩写描述含糊 { name: q, description: query, parameters: { type: object, properties: { c: {type: string}, t: {type: string} } } } // 推荐字段名直白描述含触发条件 { name: search_weather, description: 查询指定城市的当前天气。当用户询问某地天气、温度、是否下雨时调用此工具。, parameters: { type: object, properties: { city_name: { type: string, description: 城市名称例如北京、上海、深圳 }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位默认摄氏度 } }, required: [city_name] } }2.3 参数校验与类型转换的实操细节Schema 定义好了模型输出的参数不一定符合预期。端侧工程化必须在执行函数之前做一层严格的校验和转换。这层我通常叫它参数网关它的职责是把模型输出的半结构化数据变成函数能安全消费的强类型数据。校验要覆盖几个维度。类型校验是基础模型可能把数字输出成字符串把布尔输出成true字符串。这种要做类型转换而不是直接报错。范围校验也重要比如page_size参数模型可能输出 10000你得 clamp 到合理范围。枚举校验必须做模型可能输出一个不在 enum 里的值这时候要么回退到默认值要么触发重新生成。我踩过的一个坑是空值和缺失值的处理。模型有时候会输出null有时候干脆不输出某个字段。这两种情况在工程上要区分对待null可能表示用户明确要求空缺失表示模型没生成。对于可选参数缺失就填默认值对于必填参数缺失就触发重试。这个逻辑不写清楚后面会出现各种诡异的 bug。还有一个细节是字符串的清洗。端侧模型输出的字符串经常带多余的空格、换行甚至带引号。比如城市名输出成 北京 或者北京。执行函数前统一做 trim 和去引号处理能省掉很多莫名其妙的失败。def validate_and_normalize(raw_args, schema): 参数网关校验并规范化模型输出的参数 normalized {} properties schema.get(properties, {}) required schema.get(required, []) for field, spec in properties.items(): value raw_args.get(field) # 缺失值处理 if value is None: if field in required: raise ValueError(f必填字段缺失: {field}) if default in spec: normalized[field] spec[default] continue # 类型转换 expected_type spec.get(type) if expected_type string: value str(value).strip().strip().strip() elif expected_type integer: value int(float(value)) elif expected_type number: value float(value) elif expected_type boolean: if isinstance(value, str): value value.lower() in (true, 1, yes) # 枚举校验 if enum in spec and value not in spec[enum]: if default in spec: value spec[default] else: raise ValueError(f字段 {field} 的值 {value} 不在允许范围内) # 范围校验 if expected_type in (integer, number): if minimum in spec: value max(value, spec[minimum]) if maximum in spec: value min(value, spec[maximum]) normalized[field] value return normalized这段代码看着简单但每一个分支都是实际踩坑踩出来的。特别是类型转换那块端侧模型输出3而不是3的情况太常见了不做转换直接崩。2.4 工具描述里的负向约束除了正向描述工具能做什么端侧场景下我强烈建议加上负向约束也就是明确告诉模型什么情况下不要调用这个工具。这听起来反直觉但实测有效。原因在于端侧模型的过度调用倾向。小模型有时候会把不相关的用户输入也匹配到某个工具上。比如用户说今天心情不错模型可能莫名其妙去调天气工具。在工具描述里加一句仅当用户明确询问天气相关信息时调用其他情况不要调用能明显降低误触发率。这个技巧在工具数量多的时候尤其重要。工具越多模型的选择困难越严重误调用率越高。负向约束相当于给每个工具划定了清晰的边界。3. MCP 在端侧 Agent 中的接入思路3.1 MCP 到底解决了什么问题MCPModel Context Protocol这两年被讨论得很多各种工具都在接入。但很多人对它的理解停留在又一个工具调用协议的层面没抓住它真正解决的问题。我的理解是MCP 把工具的定义、发现、调用标准化了让 Agent 和工具之间解耦。在没有 MCP 之前每个 Agent 框架都有自己的工具定义方式换个框架工具就得重写。MCP 定义了一套标准的通信协议工具以 Server 的形式暴露能力Agent 作为 Client 去发现和调用。这意味着一个写好的 MCP Server理论上可以被任何支持 MCP 的 Agent 使用。对端侧来说这个标准化的价值在于工具生态的复用。端侧设备算力有限不可能什么都自己实现。如果社区里有现成的 MCP Server直接接进来就能用省掉大量开发工作。当然端侧接入 MCP 也有自己的约束不能照搬云端那套。3.2 端侧 MCP 的三种接入模式根据端侧设备的资源情况MCP 接入大致有三种模式各有适用场景。模式一本地进程内 MCP。MCP Server 和 Agent 跑在同一个进程里通过函数调用直接通信省掉了网络开销。这种模式适合工具逻辑简单、不需要独立生命周期的场景。优点是延迟最低缺点是工具和 Agent 耦合紧一个崩了另一个也受影响。模式二本地独立进程 MCP。MCP Server 作为独立进程运行Agent 通过本地 IPC 或 localhost 通信。这种模式隔离性好工具崩溃不影响 Agent 主进程也方便单独更新工具。代价是多了一层进程间通信开销。端侧 PC 和车机场景我比较推荐这种。模式三远程 MCP。MCP Server 部署在远端Agent 通过网络调用。这种模式工具能力最强但对网络有依赖端侧离线场景不可用。适合作为本地工具的补充而不是主力。选择哪种模式核心看两个维度工具是否需要独立生命周期以及网络是否可靠。端侧场景下我一般建议核心工具走本地进程内或本地独立进程非核心的、需要强算力的工具走远程并且做好降级处理。3.3 MCP 工具发现与 Schema 转换MCP 的一个核心能力是工具发现Agent 连接上 MCP Server 后可以拉取到 Server 暴露的所有工具及其 Schema。这个 Schema 是 MCP 协议定义的格式需要转换成端侧模型能理解的 Function Calling Schema。这个转换过程有几个坑。MCP 的 Schema 可能比端侧模型能处理的复杂得多比如嵌套对象、数组、复杂的 oneOf/anyOf 结构。端侧模型对这些复杂结构的支持很差直接喂进去基本会输出乱七八糟的结果。我的做法是做一层Schema 简化把嵌套结构拍平把复杂的联合类型简化成枚举把用不上的可选字段裁掉。宁可损失一些表达能力也要保证模型能稳定输出。具体来说遇到嵌套对象要么拍平成parent_child这样的字段名要么拆成多个工具遇到 oneOf如果分支不多就转成 enum 加一个 type 字段。def simplify_mcp_schema(mcp_schema, max_depth2): 把 MCP 的复杂 Schema 简化成端侧模型友好的扁平结构 def flatten(schema, prefix, depth0): result {} if depth max_depth: return result props schema.get(properties, {}) for name, spec in props.items(): full_name f{prefix}_{name} if prefix else name spec_type spec.get(type) if spec_type object and properties in spec: # 嵌套对象拍平 result.update(flatten(spec, full_name, depth 1)) elif spec_type array: # 数组简化成字符串让模型输出逗号分隔 result[full_name] { type: string, description: f{spec.get(description, name)}多个值用逗号分隔 } else: # 基础类型保留但去掉复杂约束 simplified { type: spec_type or string, description: spec.get(description, ) } if enum in spec: simplified[enum] spec[enum] result[full_name] simplified return result return { type: object, properties: flatten(mcp_schema), required: mcp_schema.get(required, []) }这段简化逻辑看着粗暴但在端侧实测下来工具调用的成功率比直接用原始 Schema 高出一大截。工程上很多时候够用比完备更重要。3.4 MCP 调用的超时与降级端侧接入 MCP尤其是远程 MCP必须处理超时和降级。网络抖动、Server 无响应、返回格式异常这些都要有兜底。我的做法是给每个 MCP 调用设一个分级超时本地进程内调用 500ms本地独立进程 2s远程调用 5s。超过阈值就中断返回一个明确的错误给模型让模型决定是重试还是换工具。这里的关键是错误信息要结构化不能只返回调用失败要告诉模型失败原因模型才能做出合理决策。降级策略上核心工具要有本地备份实现。远程 MCP 挂了自动切到本地简化版。虽然能力弱一些但保证功能可用。这个降级逻辑要在 Agent 编排层实现对模型透明。4. 多工具编排与执行链路设计4.1 单轮调用与多轮调用的取舍Function Calling 有两种基本模式单轮调用和多轮调用。单轮是模型一次输出所有需要的工具调用并行执行多轮是模型调一个工具拿到结果再决定下一步。端侧场景下我倾向于优先单轮必要时多轮。原因是端侧模型的多轮推理能力弱轮次越多上下文越长出错概率越高。能在一次调用里解决的就不要拆成多轮。但有些场景确实需要多轮比如后一个工具的输入依赖前一个工具的输出。这种依赖关系要在工具描述里写清楚或者通过编排层显式处理。我的经验是依赖链超过三层端侧模型基本就hold不住了这时候要考虑把多个工具合并成一个复合工具或者把部分逻辑下沉到代码里。4.2 工具调用的并发与串行控制多个工具调用之间有些可以并发有些必须串行。判断标准是是否存在数据依赖。无依赖的并发执行能显著降低总延迟端侧尤其重要。实现上我会在编排层维护一个依赖图。模型输出的 tool_calls 数组里每个调用标注它依赖哪些前置调用的结果。编排层根据依赖图做拓扑排序无依赖的并发执行有依赖的串行执行。这里有个细节并发数要限制。端侧设备资源有限同时跑太多工具调用会拖垮系统。我一般限制并发数为 3 到 5超出的排队。这个阈值要根据设备实际性能调不能拍脑袋定。4.3 结果回填与上下文管理工具执行完结果要回填给模型。这里最容易出问题的是结果太长。端侧模型上下文窗口小工具返回一大段 JSON 或者长文本直接把上下文撑爆。我的处理方式是结果摘要 截断。工具返回的结果先做摘要只保留模型决策需要的关键信息。比如搜索工具返回 20 条结果只回填前 3 条的标题和摘要。如果结果本身就很长做硬截断并在末尾标注结果已截断。另一个细节是结果的格式。回填给模型的结果最好是结构化的字段名和工具 Schema 对应这样模型更容易理解。纯自然语言的结果虽然可读但模型解析起来不稳定。def format_tool_result(tool_name, raw_result, max_tokens500): 把工具执行结果格式化成模型友好的形式 # 先做结构化 if isinstance(raw_result, dict): # 只保留关键字段 key_fields [status, data, error, summary] filtered {k: v for k, v in raw_result.items() if k in key_fields} result_str json.dumps(filtered, ensure_asciiFalse) else: result_str str(raw_result) # 再做长度控制 if len(result_str) max_tokens * 4: # 粗略估算 token result_str result_str[:max_tokens * 4] ...[结果已截断] return { role: tool, name: tool_name, content: result_str }4.4 失败重试与错误恢复工具调用失败是常态不是异常。端侧工程化必须把失败处理当成一等公民。失败分几类参数错误模型输出不符合 Schema、执行错误函数内部抛异常、超时调用超过阈值、结果异常返回格式不对。不同类别的处理策略不一样。参数错误把校验失败的详细信息回填给模型让它重新生成参数最多重试 2 次。执行错误如果是可恢复的比如临时网络问题重试如果是不可恢复的比如参数本身非法直接返回错误让模型换方案。超时中断并返回超时信息。结果异常尝试解析解析不了就当失败处理。重试要有退避策略不能立即重试否则可能连续失败。我一般用指数退避第一次等 100ms第二次 300ms第三次 900ms。超过三次就放弃返回最终错误。5. 端侧 Agent 工程化的常见问题排查5.1 模型不调用工具或乱调用工具这是最高频的问题。表现是模型该调工具的时候不调或者不该调的时候乱调。排查思路分几步。先看工具描述。描述里有没有明确说明触发条件有没有负向约束字段名是不是够直白这些是最常见的原因。我遇到过工具描述写得太学术模型理解不了改成大白话就好了。再看 Schema 复杂度。Schema 太复杂模型处理不了会倾向于不调用。简化 Schema 通常能解决。最后看模型本身的能力。如果换了几个 Schema 写法都不行可能是模型对 Function Calling 的支持本身就弱。这时候要么换模型要么在 Prompt 里加 few-shot 示例手动教模型怎么调。5.2 参数输出不稳定同一个工具同样的输入模型输出的参数格式时好时坏。这种不稳定在端侧小模型上很常见。解决思路是增加约束。能用 enum 的用 enum能设默认值的设默认值能限制范围的限制范围。约束越多模型的自由度越小输出越稳定。代价是灵活性下降但端侧场景下稳定性优先。另一个技巧是在工具描述里给示例。比如参数描述里写例如北京、上海模型会倾向于模仿这个格式。这个技巧对字符串参数特别有效。5.3 多工具场景下的选择困难工具一多模型就不知道该选哪个。表现是频繁选错工具或者把多个工具的调用混在一起。我的经验是控制工具数量。单次暴露给模型的工具不要超过 7 个超过就分组或者用两阶段选择先让模型选工具类别再在类别内选具体工具。这个7不是拍脑袋是实测下来端侧模型能稳定处理的工具数量上限。如果工具确实多还可以用工具路由的思路。用一个轻量级的分类器先做工具预选只把相关的几个工具暴露给模型。分类器可以是很小的模型甚至基于规则的匹配成本很低。5.4 常见问题速查表问题现象可能原因排查方向解决手段模型不调用工具描述缺触发条件检查工具描述补充何时调用说明模型乱调用工具缺负向约束检查描述边界加何时不调用说明参数格式错误Schema 太复杂检查嵌套层级拍平 Schema简化类型参数值不稳定缺约束检查 enum/默认值增加枚举和默认值选错工具工具数量过多统计暴露工具数控制在 7 个以内调用超时网络或工具慢检查调用链路分级超时 降级上下文溢出结果太长检查回填内容摘要 截断重试风暴无退避策略检查重试逻辑指数退避 次数上限5.5 几个我踩过的坑第一个坑是过度依赖模型的自我纠错。我一开始觉得模型调用失败后把错误信息回填模型能自己修正。实测下来端侧小模型的自我纠错能力很弱同一个错误可能连续犯三次。后来改成在编排层做硬性校验和修正不指望模型自己改成功率才上来。第二个坑是忽略冷启动开销。端侧模型首次加载、MCP Server 首次连接都有明显的冷启动延迟。如果不在工程上处理用户第一次交互的体验会很差。我的做法是应用启动时预热把模型加载和工具连接提前做掉用户感知不到。第三个坑是Schema 版本管理混乱。工具 Schema 改了但模型侧的 Prompt 没同步更新导致调用失败。后来我强制要求 Schema 变更必须走版本号Prompt 里引用版本号不匹配就报警。这个机制救过我好几次。第四个坑是低估了字符串编码问题。端侧设备环境复杂中文、emoji、特殊字符在工具参数里传输时经常出问题。统一用 UTF-8 编码并且在参数网关里做字符清洗能避免大部分问题。6. 工程化落地的性能与资源考量6.1 端侧资源预算怎么定端侧 Agent 的资源预算是硬约束必须在设计阶段就定清楚。我一般按这几个维度做预算内存占用、CPU 占用、功耗、存储空间。内存是大头。模型本身占一部分上下文缓存占一部分工具执行占一部分。端侧设备如果总内存 4GB留给 Agent 的通常不超过 1GB。这 1GB 里模型可能占 600MB上下文缓存 200MB工具执行 200MB。预算定死了后面所有设计都要在这个框里做。CPU 占用要关注峰值。工具调用并发执行时 CPU 会飙高如果超过设备承受能力会触发降频甚至卡死。我的做法是限制并发数并且给工具执行设优先级核心工具优先。功耗在移动端特别重要。频繁的模型推理和工具调用会快速耗电。优化手段包括合并调用减少推理次数、缓存常用结果、在设备空闲时预计算。这些优化要结合具体场景做没有通用方案。6.2 延迟优化的几个实操手段端侧 Agent 的响应延迟直接影响体验。我实测下来用户能接受的首次响应延迟大概在 2 秒以内后续交互 1 秒以内。超过这个阈值体验就明显下降。优化延迟的手段按效果排序模型量化效果最明显把 FP16 量化到 INT8推理速度能提升一倍以上精度损失可控。KV Cache 复用也很关键多轮对话时复用之前的 KV Cache能省掉大量重复计算。工具预执行是另一个思路根据用户输入预测可能要调的工具提前执行等模型决策时结果已经就绪。还有一个容易被忽略的点是首 token 延迟。端侧模型的首 token 延迟往往比后续 token 高很多因为要做 prefill。优化 prefill 速度比如用 chunked prefill能明显改善首响应体验。6.3 离线场景的降级设计端侧 Agent 必须考虑离线。网络断了远程 MCP 用不了云端模型调不了Agent 不能直接罢工。我的降级设计分三层。第一层本地模型接管虽然能力弱但基本功能可用。第二层本地工具接管远程工具的能力用本地简化版替代。第三层纯规则兜底连模型都用不了的时候用预设规则处理常见请求。这三层降级要在 Agent 启动时就配置好运行时根据网络状态自动切换。切换过程对用户透明最多给个提示当前处于离线模式部分功能受限。7. 一些工程之外的体会做端侧 Agent 工程化这段时间最大的体会是别跟端侧的约束较劲。云端那套模型够大就行的思路在端侧行不通。端侧的核心是在约束下找最优解而不是突破约束。另一个体会是工程化比模型能力更重要。我见过模型能力一般但工程做得扎实的产品体验比模型强但工程粗糙的产品好得多。端侧尤其如此因为模型能力的上限被硬件卡死了能拉开差距的就是工程。还有就是别过度设计。端侧资源有限每一份开销都要花在刀刃上。我一开始想做一个很完备的工具编排系统支持各种复杂依赖后来发现实际场景里 90% 的调用都是简单的单工具或双工具复杂编排根本用不上。砍掉那些用不上的功能系统反而更稳。最后分享一个小技巧给 Agent 加一个思考预算。端侧模型推理慢如果让它无限制地思考延迟会失控。我在 Prompt 里明确告诉模型你最多有 3 步推理模型会倾向于快速决策而不是反复纠结。这个约束对端侧场景特别有效实测能把平均响应延迟降低 30% 左右。MCP 这块后续还可以继续扩展比如 MCP Server 的本地缓存策略、多 Server 的负载均衡、Server 健康检查这些都是端侧落地会遇到的工程问题。等我把这些在实际项目里跑通验证了再单独写一篇聊聊。