1. 端侧 Agent 工程化的核心命题1.1 从 Demo 到产品为什么工程化是分水岭很多人第一次接触端侧 Agent都是从一个几十行的 Demo 开始的定义一个工具函数把 JSON Schema 塞进 prompt模型返回一段结构化文本解析出来调用本地 API跑通了感觉“不过如此”。但当你真正想把它做成一个能交付、能维护、能在真实设备上稳定运行的产品时问题会像潮水一样涌上来——工具数量从 3 个涨到 30 个模型开始选错工具上下文窗口被工具描述挤爆推理速度肉眼可见地变慢同一个工具在不同模型上的调用格式不一致换一个模型整条链路就崩用户连续追问三轮Agent 忘了自己刚才调过什么。这些问题的本质不是模型不够聪明而是工程化缺失。端侧 Agent 和云端 Agent 最大的区别在于端侧的资源是硬约束。内存可能只有几百 MB 到几 GB算力被 NPU 或移动 GPU 卡死功耗和发热直接决定用户体验模型参数量通常被压到 1B 到 7B 之间。这意味着你不能像云端那样“用更大的模型、更长的上下文、更多的工具描述”来暴力解决问题你必须把每一 KB 的上下文、每一次推理调用都花在刀刃上。我个人的判断是端侧 Agent 的工程化核心就三件事——工具接口的标准化、上下文的精细化管理、调用链路的可观测与可恢复。这三件事做不好Demo 永远只是 Demo。这一篇先聊清楚工程化的整体设计思路和工具层的关键细节下一篇再展开上下文管理和运行时调度。1.2 端侧 Agent 工程化的四个核心约束在动手写任何代码之前先把约束条件列清楚这决定了后面所有的技术选型。约束一算力与内存的硬天花板。端侧设备上模型推理本身就要占用大量内存。一个 3B 的量化模型INT4 量化后大约占 1.8 到 2.5 GB加上 KV Cache、运行时框架、系统占用留给 Agent 逻辑层的空间非常有限。工具描述、历史对话、系统提示词全部要挤在同一个上下文窗口里通常这个窗口只有 4K 到 8K token。你不能像云端那样把几十个工具的完整 JSON Schema 全塞进去。约束二模型能力的参差不齐。端侧能跑的模型Function Calling 能力差异极大。有些模型经过专门的工具调用微调输出格式很稳定有些模型只是“勉强能输出 JSON”稍微复杂一点的嵌套结构就开始胡言乱语。工程化必须假设“模型随时可能出错”在解析层做足容错。约束三延迟敏感。用户对着手机或车机说话期望 1 到 2 秒内看到响应。一次 Agent 调用如果涉及多轮推理思考→选工具→执行→再思考→生成回答每一轮都是几百毫秒到几秒的推理开销。工具描述越长prefill 阶段越慢。这就要求工具层必须极度精简。约束四离线与隐私。端侧 Agent 的一大卖点就是数据不出设备。这意味着工具执行、状态管理、日志记录全部要在本地完成不能依赖任何远程服务。这对工程实现的完整性提出了更高要求。把这四个约束放在一起你会发现端侧 Agent 的工程化本质上是一个在极度受限的资源下做取舍的过程。下面这张表是我在实际项目中总结的取舍对照维度云端常见做法端侧必须做的调整调整理由工具描述全量 JSON Schema 常驻分层加载 动态裁剪上下文窗口只有云端的 1/16模型选择固定用最强模型按任务分级路由简单任务用小模型省算力调用轮次允许多轮 ReAct限制最大轮次 快速失败每轮推理延迟累积错误处理重试 云端兜底本地降级 规则兜底无网络依赖状态管理服务端 Session本地轻量状态机内存受限1.3 工程化分层架构的整体设计端侧 Agent 的工程化我习惯把它拆成四层从下往上依次是模型推理层、工具接口层、编排调度层、应用交互层。这一篇重点讲工具接口层但先把整体架构说清楚后面才不会迷路。模型推理层负责把量化模型跑起来管理 KV Cache提供统一的推理接口。这一层通常由 llama.cpp、MLC、ONNX Runtime 或厂商的 NPU SDK 承担工程化的重点是推理参数的统一封装和流式输出的处理。工具接口层是这一篇的主角负责定义工具、描述工具、解析模型的工具调用请求、执行工具、把结果格式化回模型。这一层的核心挑战是标准化——让不同模型、不同工具、不同调用格式之间能互相适配。编排调度层负责决定“什么时候调工具、调哪个、调几次、失败了怎么办”。这一层是 Agent 的“大脑”涉及意图识别、工具路由、多轮循环控制、状态管理。应用交互层负责和用户打交道处理输入输出、UI 渲染、权限控制、日志上报。提示很多团队一上来就写编排逻辑结果工具层没标准化每加一个工具就要改一遍编排代码。正确的顺序是先把工具接口层做扎实编排层才能稳定。2. Function Calling 与 JSON Schema 的工程化落地2.1 Function Calling 的本质一场结构化输出的博弈Function Calling 听起来很玄但剥开看它的本质就是让模型输出一段符合特定结构的文本。模型本身并不“调用”任何函数它只是根据你给的 schema生成一段 JSON然后由你的代码去解析并执行真正的函数。理解这一点非常关键因为它意味着Function Calling 的可靠性取决于两件事——模型输出结构化文本的能力以及你的解析代码的健壮性。在云端OpenAI 这类服务提供了原生的 Function Calling 支持模型经过专门训练输出格式非常稳定甚至能保证返回的 JSON 一定符合 schema。但端侧模型没有这个待遇。你面对的是一个通用小模型它可能把 JSON 包在 markdown 代码块里在 JSON 前后加一堆解释性文字用单引号代替双引号漏掉必填字段把数字写成字符串在应该输出 JSON 的时候输出了一段自然语言所以端侧 Function Calling 的工程化第一步就是放弃对模型“完美输出”的幻想把解析层做成一个“宽容的解析器 严格的校验器”。2.2 JSON Schema 设计少即是多JSON Schema 是描述工具参数的标准格式但端侧场景下schema 的设计原则和云端完全不同。云端你可以写一个包含十几个字段、多层嵌套、带各种约束的 schema端侧不行——schema 越长占用的上下文越多模型理解错误的概率越高。我的经验是端侧工具的 schema 设计遵循三条铁律铁律一字段数量控制在 5 个以内。超过 5 个字段的工具模型填错的概率急剧上升。如果业务确实需要很多参数拆成多个工具或者把部分参数做成有默认值的可选字段。铁律二能用枚举就不用自由文本。比如“设置闹钟”工具时间用字符串让模型自由发挥它可能输出“明天早上七点”这种无法解析的内容。改成枚举或者明确的格式约束如HH:MM可靠性大幅提升。铁律三描述要短但要说清楚“什么时候用”。很多人的工具描述写的是“这个工具用来查询天气”但模型真正需要知道的是“当用户询问某地天气、温度、是否下雨时使用”。描述里要包含触发场景而不只是功能。下面是一个对比示例左边是云端风格的 schema右边是端侧优化后的版本// 云端风格字段多、嵌套深、描述长 { name: search_and_book_flight, description: 搜索航班并预订支持多种筛选条件和排序方式, parameters: { type: object, properties: { departure_city: {type: string, description: 出发城市名称}, arrival_city: {type: string, description: 到达城市名称}, departure_date: {type: string, description: 出发日期格式YYYY-MM-DD}, return_date: {type: string, description: 返程日期可选}, passengers: {type: integer, description: 乘客数量}, cabin_class: {type: string, enum: [economy, business, first]}, sort_by: {type: string, enum: [price, duration, departure_time]}, max_price: {type: number, description: 最高价格筛选} }, required: [departure_city, arrival_city, departure_date] } }// 端侧优化字段精简、枚举明确、描述聚焦触发场景 { name: book_flight, description: 用户要订机票、查航班时使用, parameters: { type: object, properties: { from: {type: string, description: 出发城市}, to: {type: string, description: 到达城市}, date: {type: string, description: 日期如2024-06-01}, cabin: {type: string, enum: [经济舱, 商务舱, 头等舱]} }, required: [from, to, date] } }字段从 8 个减到 4 个描述从长句变成短句去掉了排序、价格筛选这些“锦上添花”的参数。实测下来模型调用成功率从 60% 出头提升到 90% 以上。那些被砍掉的参数完全可以在工具执行后通过二次交互补充没必要一次性塞给模型。2.3 工具描述的动态裁剪策略即使每个工具的 schema 都精简了当工具数量达到 20 个以上时全部塞进上下文依然会爆。这时候需要动态裁剪——根据当前对话的意图只加载相关的工具子集。实现思路是维护一个工具分组表把工具按领域分类如“设备控制”“信息查询”“日程管理”“通讯”然后根据用户输入的关键词或轻量意图分类器决定加载哪一组。比如用户说“帮我定个明天早上的闹钟”意图分类器识别为“设备控制”就只加载闹钟、计时器、音量控制这几个工具其他工具的描述完全不进上下文。这个意图分类器不需要很复杂端侧可以用一个小的文本分类模型或者干脆用关键词匹配加规则。关键是分类要快、要准、要能兜底。如果分类失败就加载一个“通用工具集”通常是最高频的 5 到 8 个工具保证基本可用。注意动态裁剪的粒度不要太细否则每次对话都要重新加载工具描述prefill 开销反而增加。我的做法是按“会话”粒度加载一次加载一组整个会话内保持不变除非用户明确切换了话题。2.4 多模型适配一套工具定义多种调用格式端侧设备上可能同时存在多个模型或者产品需要在不同设备上适配不同模型。每个模型的 Function Calling 格式都不一样有的用特定的特殊 token 包裹有的用 XML 标签有的直接要求输出 JSON。如果每个模型都写一套工具定义维护成本会爆炸。工程化的做法是定义一套中立的工具描述格式然后写适配器转换成各模型需要的格式。中立格式可以用 JSON Schema 作为基础适配器负责把 JSON Schema 转换成模型特定的 prompt 模板把模型特定的输出格式解析回统一的调用结构处理模型特有的边界情况如某些模型不支持嵌套对象# 中立工具定义 tool_def { name: set_alarm, description: 用户要设置闹钟时使用, parameters: { type: object, properties: { time: {type: string, description: 时间如07:30}, label: {type: string, description: 闹钟标签} }, required: [time] } } # 适配器转换成不同模型的格式 class ToolAdapter: def to_qwen_format(self, tool_def): # Qwen 系列用特定的 tool 标签 return ftool{json.dumps(tool_def, ensure_asciiFalse)}/tool def to_llama_format(self, tool_def): # Llama 系列用 JSON 数组 return json.dumps([tool_def], ensure_asciiFalse) def parse_output(self, model_name, raw_output): # 统一的解析入口内部按模型分派 if model_name.startswith(qwen): return self._parse_qwen(raw_output) elif model_name.startswith(llama): return self._parse_llama(raw_output) else: return self._parse_generic(raw_output)这套适配器模式的好处是新增一个模型只需要加一个适配器工具定义本身不用动。实测下来适配 5 个不同模型的工作量从“每个模型改一遍所有工具”变成了“写 5 个适配器”维护成本降低了一个数量级。3. MCP 协议在端侧 Agent 中的角色3.1 MCP 是什么为什么端侧需要它MCPModel Context Protocol最近热度很高各种工具和平台都在接入。但很多人对它的理解停留在“又一个工具调用协议”的层面没搞清楚它真正解决什么问题。我的理解是MCP 解决的是“工具提供方”和“工具使用方”之间的解耦问题。在没有 MCP 之前每个 Agent 框架都要自己定义工具格式每个工具提供方都要为不同的框架写不同的适配。MCP 定义了一套标准的通信协议工具提供方只需要实现一个 MCP Server任何支持 MCP 的 Agent 都能直接调用。这就像 USB 接口统一了外设连接一样MCP 统一了工具接入。对端侧 Agent 来说MCP 的价值在于生态复用。端侧团队通常人手有限不可能自己实现所有工具。如果有一个现成的 MCP Server 能提供日历、邮件、文件管理等功能直接接入就能用省下大量开发时间。而且 MCP 的协议设计考虑了本地进程通信适合端侧这种不能依赖远程服务的场景。3.2 MCP 的核心概念与端侧适配要点MCP 的核心概念有三个Server、Client、Transport。Server 提供工具和资源Client 是 Agent 侧的连接器Transport 是通信方式通常是 stdio 或本地 socket。端侧场景下Transport 基本只能用 stdio 或本地 IPC因为不能开网络端口。端侧适配 MCP 有几个坑要注意坑一进程管理。MCP Server 通常是一个独立进程端侧启动 Agent 时要同时拉起 Server 进程退出时要确保清理干净。移动端对后台进程管控很严Server 进程可能被系统杀掉需要做重连和状态恢复。坑二工具发现的开销。MCP 支持动态发现工具但端侧不能每次对话都去问 Server “你有哪些工具”。我的做法是启动时发现一次缓存工具列表Server 更新工具时通过通知机制同步。坑三协议开销。MCP 的完整协议包含不少元数据端侧要精简。只保留必要的字段去掉调试信息、版本协商等非核心内容。# 端侧 MCP Client 的简化实现思路 class EdgeMCPClient: def __init__(self, server_command): self.server_command server_command self.tools_cache {} self.process None def start(self): # 启动 Server 进程建立 stdio 通道 self.process subprocess.Popen( self.server_command, stdinsubprocess.PIPE, stdoutsubprocess.PIPE ) # 启动时发现一次工具缓存起来 self.tools_cache self._discover_tools() def _discover_tools(self): # 发送 tools/list 请求解析响应 response self._send_request(tools/list, {}) return {t[name]: t for t in response.get(tools, [])} def call_tool(self, name, arguments): # 直接调用不再重新发现 return self._send_request(tools/call, { name: name, arguments: arguments })3.3 MCP 与原生 Function Calling 的取舍端侧到底该用 MCP 还是原生 Function Calling我的建议是混合使用核心高频工具用原生 Function Calling保证低延迟和稳定性长尾工具和第三方能力用 MCP 接入保证扩展性。原因很简单MCP 虽然标准化但多了一层进程通信和协议解析延迟比原生调用高。对于“设置闹钟”“调节音量”这种高频、低延迟要求的工具原生调用更合适。而对于“查询快递”“订餐”这种低频、第三方提供的工具MCP 的标准化优势就体现出来了。维度原生 Function CallingMCP 接入延迟低进程内中跨进程扩展性差每个工具要自己写好标准协议稳定性高自己控制中依赖 Server适用场景高频核心工具长尾第三方工具开发成本高每个都要适配低一次接入4. 工具执行层的工程化细节4.1 参数校验与类型转换模型输出的参数永远不能直接信任。哪怕 schema 写得再清楚模型也可能输出类型不对、范围越界、格式错误的值。工具执行层的第一道关卡就是参数校验。校验分三步结构校验、类型校验、业务校验。结构校验检查必填字段是否齐全、字段名是否正确类型校验检查值的类型是否符合 schema业务校验检查值是否在合理范围内如时间格式是否正确、枚举值是否合法。def validate_and_convert(tool_def, raw_args): 校验并转换模型输出的参数 schema tool_def[parameters] properties schema.get(properties, {}) required schema.get(required, []) # 第一步结构校验 for field in required: if field not in raw_args: raise ValidationError(f缺少必填字段: {field}) # 第二步类型校验与转换 converted {} for key, value in raw_args.items(): if key not in properties: continue # 忽略未知字段不报错 expected_type properties[key].get(type) converted[key] coerce_type(value, expected_type) # 第三步业务校验 for key, value in converted.items(): if enum in properties[key]: if value not in properties[key][enum]: raise ValidationError(f{key} 的值 {value} 不在允许范围内) return converted def coerce_type(value, expected_type): 宽容的类型转换 if expected_type string: return str(value) elif expected_type integer: try: return int(float(value)) # 处理 3.0 这种情况 except (ValueError, TypeError): raise ValidationError(f无法转换为整数: {value}) elif expected_type number: try: return float(value) except (ValueError, TypeError): raise ValidationError(f无法转换为数字: {value}) elif expected_type boolean: if isinstance(value, str): return value.lower() in (true, 1, yes) return bool(value) return value这里有个细节值得说未知字段直接忽略不要报错。模型有时候会“自作主张”加一些 schema 里没有的字段如果因此报错整个调用就失败了。忽略未知字段只处理认识的字段容错性更好。4.2 工具执行的超时与降级端侧工具执行可能涉及 IO 操作读文件、查数据库、调系统 API这些操作可能超时或失败。工程化必须给每个工具设置超时时间和降级策略。超时时间根据工具类型设定纯计算类工具 500ms本地 IO 类 2s涉及系统 API 的 3s。超时后不能直接抛异常给模型而是返回一个结构化的错误信息让模型知道“这个工具失败了”它可以决定是重试、换工具还是直接告诉用户。import signal class TimeoutError(Exception): pass def execute_with_timeout(func, args, timeout_sec): 带超时的工具执行 def handler(signum, frame): raise TimeoutError(f工具执行超时{timeout_sec}s) old_handler signal.signal(signal.SIGALRM, handler) signal.alarm(timeout_sec) try: result func(**args) return {status: success, data: result} except TimeoutError as e: return {status: timeout, message: str(e)} except Exception as e: return {status: error, message: str(e)} finally: signal.alarm(0) signal.signal(signal.SIGALRM, old_handler)返回给模型的结果统一用{status: ..., data/message: ...}的结构模型看到status就知道成功还是失败看到message就知道失败原因。这种结构化反馈比直接抛异常或返回裸数据要好得多模型能据此做出更合理的决策。4.3 工具结果的格式化与截断工具执行完结果要格式化后回传给模型。这里有两个关键点格式要统一长度要控制。格式统一是指所有工具的结果都用同一种结构返回模型不需要为每个工具学习不同的结果格式。我通常用{ tool: set_alarm, status: success, result: 闹钟已设置为明天 07:30, truncated: false }长度控制是指结果不能太长否则会挤爆上下文。比如查询通讯录返回了 500 条记录全塞回去上下文就爆了。这时候要截断 摘要只返回前 N 条并告诉模型“还有更多结果”。N 的取值根据上下文剩余空间动态调整通常 3 到 5 条。实操心得截断的时候一定要在结果里明确标注“已截断共 X 条显示前 Y 条”否则模型会以为这就是全部结果给出错误的回答。我踩过这个坑用户问“通讯录里有多少人”模型看到截断后的 5 条回答“5 个人”实际有 500 个。4.4 工具调用的幂等性设计端侧 Agent 可能因为各种原因重试工具调用模型输出不稳定、网络抖动、用户重复触发。如果工具不是幂等的重试就会产生副作用——重复设置闹钟、重复发送消息、重复扣款。幂等性设计有两个层面工具本身的幂等和调用层的去重。工具本身尽量设计成幂等的比如“设置闹钟”用“设置”而不是“添加”重复调用结果一样。调用层则维护一个近期调用记录相同工具 相同参数在短时间内重复调用直接返回缓存结果不真正执行。class IdempotentExecutor: def __init__(self, window_sec30): self.recent_calls {} # (tool_name, args_hash) - (timestamp, result) self.window_sec window_sec def execute(self, tool_name, args, func): key (tool_name, self._hash_args(args)) now time.time() # 检查是否有近期相同调用 if key in self.recent_calls: ts, result self.recent_calls[key] if now - ts self.window_sec: return result # 直接返回缓存结果 # 执行并记录 result func(**args) self.recent_calls[key] (now, result) return result def _hash_args(self, args): return hashlib.md5( json.dumps(args, sort_keysTrue).encode() ).hexdigest()这个去重窗口设 30 秒比较合适太短起不到去重效果太长可能误伤用户真实的重复操作。5. 常见问题与排查技巧实录5.1 模型不调用工具直接回答这是最常见的问题。用户说“帮我设个闹钟”模型不调用set_alarm而是回复“好的请问您想设几点”。原因通常是工具描述没有说清楚触发场景或者系统提示词没有强调“必须用工具”。排查思路先看工具描述是不是只写了“设置闹钟”而没写“用户要设置闹钟时使用”。再看系统提示词有没有明确要求“当用户请求涉及工具能力时必须调用工具不要自己回答”。最后看模型有些小模型的工具调用能力确实弱换个模型或者加 few-shot 示例。5.2 工具调用参数错误模型调用了工具但参数不对——缺字段、类型错、值越界。排查顺序先看 schema 是不是太复杂字段太多或嵌套太深再看描述是不是有歧义比如“时间”字段没说明格式最后看模型输出是不是被截断了上下文不够导致 JSON 不完整。一个容易被忽略的点是上下文长度。如果工具描述 历史对话 系统提示词加起来接近上下文窗口上限模型输出 JSON 时可能被截断导致解析失败。这时候要主动裁剪历史对话给输出留足空间。5.3 多轮调用陷入死循环Agent 调用工具 A结果不理想又调用工具 A反复循环。这是编排层的问题但工具层可以做防护限制单个工具在单次会话中的最大调用次数超过就强制返回错误让模型换策略。class CallLimiter: def __init__(self, max_calls_per_tool3): self.counts {} self.max_calls max_calls_per_tool def check(self, tool_name): count self.counts.get(tool_name, 0) if count self.max_calls: return False, f工具 {tool_name} 调用次数已达上限 self.counts[tool_name] count 1 return True, None5.4 常见问题速查表问题现象可能原因排查方法解决方案模型不调用工具描述缺触发场景检查工具 description补充“用户...时使用”参数缺失schema 太复杂数一下字段数量精简到 5 个以内参数类型错模型输出不稳定看原始输出加类型转换容错JSON 解析失败输出被截断检查上下文占用裁剪历史对话工具重复调用编排逻辑缺陷看调用日志加调用次数限制结果太长爆上下文未截断看结果长度截断 摘要换模型后全崩格式不兼容对比输出格式加适配器层5.5 几个踩过的坑坑一工具描述里的示例会误导模型。我在工具描述里写了个示例参数{time: 07:30}结果模型不管用户说什么都输出07:30。后来把示例去掉只保留格式说明问题解决。工具描述里尽量不放具体值示例放格式模板就好。坑二枚举值用英文模型输出中文。schema 里枚举写的是[economy, business]但用户说的是中文模型有时候输出中文枚举值。后来把枚举值改成中文匹配率大幅提升。端侧场景下枚举值用用户语言不要用英文。坑三工具名太长影响解析。工具名search_flight_and_book这种长名字模型有时候会拼错或者截断。工具名控制在 15 个字符以内用简短动词开头如book_flight。坑四并发调用导致状态混乱。模型一次输出了两个工具调用代码并发执行两个工具都修改了同一个状态结果错乱。端侧工具执行默认串行除非明确无状态依赖才考虑并发。工具层的工程化说到底就是把模型当成一个“能力很强但很不靠谱的实习生”——它能帮你干活但你得把任务交代清楚、把边界划明白、把错误兜住。schema 精简、描述清晰、校验严格、容错充分这十六个字是我做了多个端侧 Agent 项目后最深的体会。下一篇会聊上下文管理和运行时调度那部分才是真正决定 Agent 能不能“连续对话不崩”的关键。