做端侧 Agent 的朋友应该都有同感Demo 阶段怎么跑怎么顺一到工程化就翻车。前两篇聊了端侧 Agent 为什么值得做、基础架构长什么样今天这篇就讲讲把 Agent 从“能跑”推到“能上线”中间那段最难走的路也就是 Agent 工程化。这篇先啃硬骨头架构怎么分层、harness 到底是什么、框架怎么选、工具调用和记忆怎么做工程化、并发怎么扛、安全怎么收口。调试、评测、监控那些相对独立的内容我放到“下”篇详细说。之所以把工程化单独拎出来写是因为端侧 Agent 和云端 Agent 的工程化完全是两码事。云端资源可以堆失败可以重试内存不够可以扩容端侧不行内存、功耗、算力、存储都是紧巴巴的还要面对弱网、离线、多端同步这些破事。你可以在云端把 LangChain 全家桶装上慢慢调但到了手机、平板、车机、手表上一丁点多余的开销都会直接反映到卡顿和发热上。所以端侧 Agent 工程化的核心就一句话在资源预算内把智能体的可靠性、可控性、可观测性做出来。1. 工程化之前先想清楚你的 Agent 到底要解决什么问题很多团队一上来就选框架、写代码结果做了一半发现连问题都没定义清楚。工程化不是把功能实现出来而是把功能以可复制、可运维、可演进的方式实现出来。在动手之前我建议你先回答三个问题你的 Agent 跑在什么硬件上它有什么权限它的失败代价是什么1.1 端侧 Agent 和云端 Agent 的本质差异端侧 Agent 最大的卖点是三个隐私不出设备、离线可用、端到端延迟低。但这三个卖点每一个都是工程上的紧箍咒。隐私不出设备意味着你不能把用户数据丢到云端做兜底离线可用意味着模型和知识库都得本地存低延迟意味着推理必须快而端侧芯片的算力天花板就摆在那里。云端 Agent 工程化讲究的是弹性、高可用、多租户隔离、API 网关、限流熔断这些词到了端侧全都变了味。端侧要面对的是应用被杀、系统回收内存、屏幕熄灭进入低功耗状态、弱网环境下同步超时、用户手动清缓存把自己家的向量库清没了。这些不是极端情况是每天都在发生的常态。端侧 Agent 的并发模型也和云端不同。云端一个 Agent 服务可以同时服务成千上万个用户请求靠的是水平扩展端侧一个 Agent 实例基本只服务一个用户但同一个用户的多个 Agent 可能同时跑——一个前台助手在回答用户问题一个后台 Agent 在整理相册还有一个定时 Agent 在跑日报总结。所以端侧“扛并发”的本质是在单机资源内让多个 Agent 实例并发跑起来不互相踩踏。1.2 “能跑通”和“能上线”之间隔着的四道坎从个人 Demo 到产品级端侧 Agent我总结下来至少有四道坎每一道都卡掉过不少人。第一道坎是可控性。模型是概率系统同样的输入今天给这个结果明天给那个结果。工程化要做的就是用约束把概率关进笼子里输出格式不对就重试工具参数不合规就拦截Agent 跑飞了就强制终止。最基础的做法是给模型加 system prompt 约束但工程上必须做结构化的校验和兜底不能指望提示词百分百听话。第二道坎是可观测性。Agent 是黑盒里的黑盒——你不知道它下一步要干嘛不知道它为什么调那个工具不知道它哪一步开始跑偏。没有日志、追踪、回放机制的 Agent 项目出问题只能靠猜。我在实际项目中吃过一次大亏Agent 在用户手机上半夜自动执行了一个清理任务把用户的重要文件标记成了可删除等用户第二天发现的时候已经晚了。事后排查时我发现整个执行过程几乎没有日志根本定位不了是哪一步决策出了问题。第三道坎是可演进性。模型版本要升级、工具列表要增加、技能要迭代如果 Agent 的架构是写死的每一次改动都是一次大手术。好的工程化应该让 Agent 的能力像搭积木一样可插拔而不是牵一发动全身。第四道坎是安全性。端侧 Agent 是离用户数据最近的软件它有访问通讯录、短信、相册、定位的能力一旦被滥用就是灾难。这里的安全不止是“防黑客”更核心的是“防住 Agent 自己”——权限最小化、操作可撤销、敏感行为要二次确认。2. 架构选型harness、运行时与编排到底怎么搭网上关于 Agent 框架的讨论特别多概念也特别多——agent、harness、framework、runtime、orchestration很多人被这些词绕晕了。这篇我先把最重要的两个概念掰扯清楚Agent 和 Harness。2.1 Harness 到底是什么它和 Agent 有什么区别我见过很多团队把 Agent 和 Harness 混为一谈代码里写了一个类叫 Agent其实干的是 Harness 的活。我的理解很简单Agent 是你的“大脑”负责推理和决策Harness 是“身体和神经系统”负责让大脑的想法变成现实行动并且把行动的结果反馈给大脑。具体来说Harness 至少包含五大能力一是调用底层模型并管理上下文窗口二是管理工具注册表决定 Agent 能调哪些工具、怎么调三是执行工具调用并做参数校验、结果包装四是维护循环控制防止无限循环五是做观测和中断随时可以叫停 Agent。用工程一点的类比Agent 是业务逻辑层Harness 是基础设施层。为什么要单独拆出 Harness因为端侧 Agent 的模型可以换、工具可以换但 Harness 的骨架是稳定的。今天你用的是 3B 模型明天可能换成 7B 模型今天挂了一个天气查询工具明天可能挂一个支付工具。如果这些变化都和 Agent 的核心决策耦合在一起改一次就要重新测一遍全链路。Harness 把变化的和不变的隔离开这是工程化的第一步。现在市面上的 Harness 形态已经很多了OpenAI 的 Codex CLI 是跑在终端里的命令式编码 AgentGoogle 的 ADK 是面向多 Agent 编排的 Agent Development Kit还有 Spring AI 这类给 Java 开发者用的 Agent 基础件。这些产品各有侧重但本质逻辑都是一样的——给 Agent 大脑配一台能走路、能说话、能拿东西的身子。我个人在做端侧项目时还比较喜欢 Rust 系的轻量 harness 实现内存占用小、体积可控、交叉编译方便一套代码能覆盖手机、平板、嵌入式多个端真正往 Agent Anywhere 方向走能省很多事。2.2 主流框架的真实对比端侧到底选哪个说到 Agent 框架绕不开 LangChain、LangGraph、CrewAI、Dify 这几个。我这几年基本都试过也见过不同团队拿它们做端侧项目说点真实感受。LangChain 的生态最大文档最多什么问题都能搜到答案但它的抽象层也最厚运行时体积不小而且版本迭代频繁API 碎。在云端用问题不大端侧塞这套东西启动时间和内存都受不了。LangGraph 在编排上比 LangChain 清晰适合有状态、有条件的流程但对端侧来说依然偏重。CrewAI 主打多角色协作模拟一个团队里的不同 Agent 互相配合。这个思路很贴近真实业务但多 Agent 之间的通信和协作开销在端侧是实打实的成本而且每个 Agent 都要占上下文和推理资源所以我的建议是端侧别轻易上多 Agent能单 Agent 解决的问题不要拆。Dify 是低代码友好的RAG、工作流、知识库一套全包做原型和内部工具效率很高。但它是典型的“重框架”很多能力和数据库深度绑定部署形态偏重往端侧搬基本等于做一次重构。更适合的场景是你用 Dify 快速验证产品逻辑验证完再针对端侧做轻量化实现。我最后给端侧项目的建议是要么裸写一个轻量 harness要么用极轻的运行时。我自己的项目里最终选择的是自研一个约两千行的核心 harness外加模型服务、工具执行、记忆存储三个独立模块。这么做的好处是完全掌控资源占用坏处是一切从零开始工程量大。但是端侧项目最怕的就是框架绑架——框架决定了你的架构边界而端侧的需求经常在边界之外。2.3 一套可以直接抄作业的端侧 Agent 分层架构我沉淀下来的一套分层架构按职责分五层每层只做好一件事第一层是交互层负责语音、文本、事件等输入把它们统一转换成内部消息格式。第二层是编排层也就是 harness 的主体负责上下文管理、工具调度、循环控制、中断恢复。第三层是技能层把工具、提示词模板、技能脚本打包成一个个可加载的单元。第四层是记忆层管理短期会话记忆、长期事实记忆、向量知识库。第五层是资源层封装本地推理引擎、磁盘存储、网络同步能力。这套架构的优点是每个层都可以单独替换。比如模型从 ONNX 换成 MNN只动资源层的推理接口加一个新能力只动技能层上下文溢出问题只优化编排层的压缩策略。端侧系统最关键的就是这种“可替换性”因为端侧软件的生命周期远比云端服务长手机系统更新、芯片换代你的 Agent 得跟着适应不能架构上就锁死。3. 核心能力工程化工具调用、记忆与技能机制Agent 的能力再花哨落地端侧就绕不开三个基本盘工具调用靠不靠谱、记不记得住上下文、能不能快速扩展新能力。这一节逐个聊。3.1 工具调用不是“让模型调个函数”那么简单很多初学者写 Agent 工具调用在 prompt 里写“你可以调用以下工具”然后模型返回一段 JSON代码解析后执行完事。这种实现到了真实场景必崩。真实场景里模型会返回非法的 JSON、参数类型不对、传超长字符串、调用一个根本没注册的工具还会连环调用互相对喷。工程化的工具调用至少要做四件事。第一工具描述结构化每个工具都要有标准的 JSON Schema 描述包括参数名、类型、取值范围、必填项、描述让模型好理解也方便校验。第二参数严格校验模型返回的参数在执行前必须过一套校验器不合法就返回对应的错误提示给模型让它重新生成。第三执行超时兜底每个工具调用都要有超时时间超过就中断并通知模型避免工具卡住整个 Agent 循环。第四幂等控制同一个工具可能被模型重复调用必须有幂等机制最典型的例子是支付类工具重复扣款是无法接受的。还有个细节容易被忽略工具失败信息的反馈格式。模型需要知道工具为什么失败才好重新决策。经验是尽量把失败原因结构化比如错误码加一个简短的错误描述而不要甩一整段堆栈给模型。模型看堆栈是看不懂的它只会更晕。3.2 记忆体系怎么在端侧落下来记忆是 Agent 工程化里最容易被低估的一块。Demo 阶段你只需要把用户最近几轮对话扔给模型但产品阶段你需要让 Agent 记住用户的偏好、上次没完成的任务、知识库里的最新内容还得保证这些记忆不泄露隐私、不占用太多存储。我个人推荐三层记忆架构。短期记忆是当前会话的上下文窗口用环形缓冲管理超出窗口就做摘要压缩。中期记忆存用户在当前交互周期内的任务状态和临时偏好比如“用户正在规划周末旅行偏好海边”存在 SQLite 里带过期时间。长期记忆是用户画像和持久知识比如用户的工作、家庭、常用地点存在嵌入向量库或结构化表里更新要走用户确认。端侧记忆工程化的难点在于存储空间和检索效率的平衡。一个四五百万条的向量库索引建起来轻松几百 MB手机存储根本吃不消。实际做法是分层存储高频记忆存内存或极速存储低频记忆用压缩结构存磁盘最老的记忆定期清理出系统。记忆不等于永久保存端侧的记忆必须有生命周期这个观念要一开始就建立否则后面数据膨胀到不可收拾。记忆还有一个大坑多端同步。手机上有记忆平板上没有用户就会觉得 Agent“换一个设备就失忆”。工程上这是个分布式一致性问题简单方案是增量同步加冲突处理复杂方案是云上做中心化记忆仓端侧只缓存热数据。但云端一介入隐私优势就打了折扣所以这个平衡点要产品来定技术只能给出折中方案。3.3 Skill 机制把能力做成即插即用的标准件今年 Agent 圈子里“Skills”这个概念火得不行Claude 的 Agent Skills 机制出来后很多团队开始把技能打包成标准化单元。我在自己的项目里也完整借鉴了这套思路效果非常好。Skill 本质上是一个自包含的能力包一个描述文件说明这个技能什么时候用、怎么用一组提示词模板告诉模型怎么执行一组工具脚本干具体的活一个校验器检查执行结果。举个例子我要给 Agent 加一个“分析网页并保存为 Markdown”的能力不需要改任何核心代码只需要做一个 Skill 目录描述文件里写清楚适用场景和输入要求脚本里写清楚怎么抓取、怎么转换、怎么把结果落到本地。Agent 在推理时如果发现当前任务匹配这个技能就自动加载并执行。这种机制让 Agent 的能力扩展从“改代码发版”变成了“热插拔装配”运营同学也能参与到技能设计里。但 Skill 机制有个安全副作用技能包是外部加载的可执行代码相当于给 Agent 装了一个插件系统。插件能干什么、不能干什么、访问哪些路径必须有一套沙箱机制管住。我当时直接把技能脚本丢给系统执行结果一个技能包里的路径清理逻辑把另一个技能的数据目录给误删了。后来清零重写才意识到隔离是 Skill 机制的第一优先级。现在我的技能沙箱里强制做三件事文件访问只能落在技能专属目录、网络访问只允许白名单域名、子进程超时强制回收。3.4 多 Agent 协作的工程代价能单就别多热词里“多 Agent”出现频率很高很多团队看到多 Agent 架构就想上。我的态度很明确端侧能单 Agent 解决的绝对不要拆多 Agent。原因有几点每多一个 Agent就要多一份上下文窗口、多一份推理开销、多一层通信复杂度。手机上跑两个 7B 模型同时推理发热和耗电基本是灾难级的。真需要多 Agent 协作那也要做角色裁剪。比如主 Agent 负责任务理解通过工具调用的方式“借用”其他 Agent 的专项能力而不是真的让两个独立模型在那里对话。这种“伪多 Agent”模式在端侧非常适用既有了专业化分工又避免了多模型并行推理的资源爆炸。工程实现上主 Agent 维护一个子 Agent 的结果池子 Agent 的结果作为工具返回值回到主 Agent 的上下文里整个流程依然收敛在单推理链路里成本和风险都可控。4. 资源受限下的并发与性能端侧“扛并发”到底怎么扛前面说了端侧的并发和云端不一样这里的“并发”是指多个 Agent 实例、多种任务类型在同一台设备上同时跑的工程问题。手机不是服务器它没有 64 核 CPU 和 256G 内存要在这样的环境扛住并发必须一毫一秒地精打细算。4.1 模型选型与延迟预算的计算方法模型选型是性能工程的地基。端侧常用的是量化后的 1B、3B、7B 参数模型经验公式是模型内存占用约等于参数量乘以量化位数除以 8。7B 模型用 INT4 量化大约占 3.5GB 内存用 INT8 就是 7GB。3B 模型 INT4 才 1.5GB手机完全能扛7B 就得看设备内存规格了。我做过一个内存预算表可以参考旗舰机 12GB 内存系统占用约 5GBAgent 运行时加模型推理最多只能再吃 5GB 左右剩下要留给其他 App。延迟预算上交互类任务的端到端延迟要控制在 500ms 到 1s 以内包含语音识别、推理、工具执行等全部环节。这意味着纯推理延迟不能超过 200ms。在这个预算下3B 量化模型在旗舰芯片上勉强够用7B 就必须上推理加速方案了。工程上还有一招模型常驻。模型热加载一次要两三秒用户每次交互等两秒是灾难性的所以模型要启动时预加载保持在内存里哪怕不跑任务也占着。这就要跟系统内存博弈你占着不释放可能被系统判为高耗电应用非常考验资源管理。4.2 端侧并发模型的一个靠谱设计我最终采用的并发模型是“单推理引擎 多任务队列 会话隔离”。推理引擎只有一个所有 Agent 任务的模型推理都走它但任务分成前台交互优先、后台任务低优先级、定时任务最低优先级三类。前台任务抢占推理资源后台任务在推理间隙执行定时任务在设备空闲时批量跑。这个设计解决了同设备的多个 Agent 抢资源的问题实际体验下来很稳。会话隔离同样重要。每个任务会话必须有独立的上下文缓冲、工具调用记录和执行状态互不干扰。这个看起来简单但牵涉到很多细节你不可能让后台做文档总结的上下文和前台聊天的上下文互相污染工具调用栈也不能共享。实现时我用了一个全局唯一的会话 ID 把所有数据打标从输入到工具执行到记忆写入全链路绑定这才彻底把并发问题理顺。流式输出也是扛延迟的利器。用户体感上首字出来得快比整句完成得快要紧得多。端侧推理用流式解码第一个 token 大概几十毫秒就能出用户可以立刻看到反馈。这个不是技巧是端侧 Agent 交互体验的刚需。当年我们第一批版本是等待全文生成完再一次性吐出用户反馈就是“这 Agent 怎么卡卡的”。改成流式之后同样是 800ms 的总耗时用户评价直接变了个样。4.3 内存、功耗与发热的调优实战端侧性能工程里最折磨人的不是快不快而是热不热、废不废电。推理是高负载任务跑一个 3B 模型芯片功耗轻松拉到几瓦连跑几分钟手机就明显发热。这里有几个经验限制推理频率两个任务之间加最小间隔批量推理把可以合并的任务放进一个 batch 里一次算完动态降频检测到设备温度高时自动降低推理精度或强制进入低功耗模式。还有一个很容易忽视的坑后台任务不能偷偷跑。后台 Agent 如果每隔几分钟就调一次模型一个晚上能把手机耗掉大半格电。我的方案是后台任务全部交给“充电时执行 用户空闲时段执行”的调度器完全避开用户正在使用手机的时间窗口。这个策略上线后用户对耗电的抱怨基本清零。端侧 Agent 工程化说白了不是使劲塞功能而是学会在没有余量的环境下克制。5. 端侧 Agent 的安全防线权限、数据与鲁棒性Agent 安全这个题越做越觉得水深。之前网上对 Agent 安全的讨论大多集中在提示注入、工具滥用这些偏攻防的领域但端侧 Agent 真正要解决的是三个工程问题权限怎么收、数据怎么防、失败怎么兜底。5.1 权限设计给 Agent 的权力清单画一条边界线端侧 Agent 必须有权限清单机制不能让它想干什么就干什么。我的做法是分三级权限基础权限自动授予比如查询天气、读取系统信息中危权限要用户确认比如发送消息、修改文件、访问通讯录高危权限强制二次验证涉及支付、删除数据、发布内容必须用户显式批准。工程实现上是一个权限模块所有工具执行前都要过这一关。模块维护一个权限表每个执行请求匹配工具、操作类型、作用对象后再决定是放行、询问还是拒绝。注意“作用对象”很关键Agent 读取通讯录里的联系人名片可以放行但读取通讯录然后生成一个“用户人际关系网”文档这个行为就触碰了中危权限边界必须停下来问用户。还有一点权限不能被用户授权一次后就永久放行。端侧 Agent 的权限要有有效期和上下文限定。比如用户允许了“本次发送一条消息”不代表允许这个 Agent 以后随时都可以发消息。权限上下文超时自动回收这个机制能避免很多潜在问题。5.2 数据隔离Agent 的数据不能和系统数据混在一起端侧 Agent 访问了大量个人数据这些数据的存储和流转必须做隔离。设计上分三类Agent 自己的数据比如技能包、记忆库、向量索引用户数据的缓存副本比如从相册分析出来的图片向量系统级的敏感数据比如用户的账号信息、支付凭证。三类数据存储位置分开访问路径分开加密密钥也分开。加密这块我用的方案是Agent 的数据默认用设备级密钥加密用户敏感数据换用户级密钥单独加密密钥本身存在系统安全硬件里。有人觉得手机本地端侧没必要加密反正数据不出设备这个想法太天真了——数据不出设备指的是你不主动上传但你的设备可能被别人拿去刷机、ROOT、物理窃取。数据加密的成本不高但能挡住一大票物理攻击场景。合规价值也更扎实。防数据泄漏的另一个重要点是日志。Agent 的日志里往往带着用户数据我遇到过调试日志把用户完整对话内容打印出来的事故。现在项目里的日志库强制做脱敏邮箱、手机号、地址、身份标识自动打码整段明文数据不允许进日志。宁可调试不方便也不能把用户隐私当儿戏。5.3 失败兜底Agent 执行中止了怎么办端侧 Agent 经常遇到执行中止比如模型推理到一半手机内存告急、工具调用卡死、系统杀掉了后台进程。用户侧看到的现象就是“Agent 突然不说话了”或者“执行到一半停了”。这种体验一次两次可以接受次数多了用户就卸载了。兜底方案要分层做。最低层是 harness 级别的 watchdog监控每个工具调用的超时和异常异常时把状态回滚到上一安全点。上一层是会话级别的恢复机制Agent 的每一步决策都记录下来重启后可以恢复继续执行。最上层是用户界面层Agent 中止时给用户一个透明的状态提示是“正在重试”、是“执行成功但部分结果丢失”、还是“需要用户介入决策”。透明永远是第一位的不要让用户对着一个黑屏干等。我做任务状态机的时候吃过一个亏Agent 执行一个多步任务第一步完成后写了状态第二步失败了我直接报错。结果用户重试的时候第一步被重复执行了。后来给每个任务加了幂等 ID 和步骤完成标记重试时直接从断点继续。所以我说 Agent 工程化本质上是一个可靠性工程问题把自己的系统当分布式系统设计幂等、状态持久化、断点续跑这些一个都不能少。6. 工程化远景从 Agent 内核到 Agent Anywhere聊到这里端侧 Agent 工程化的上半场基本讲完了但有一件事我想最后提一嘴工程化做得好收益不只是“你有一个好用的 App 内助手”。好的端侧 Agent 内核天然具备跨端复用的能力。6.1 同一个内核跑在不同设备上的架构红利我见过不少团队做多端 Agent 的方法是手机端一套代码PC 端一套代码车机再一套三个版本互相不认识功能对齐全靠人肉。这种做法的本质问题不是代码重复而是能力没有形成资产。如果在工程化阶段就把 Agent 核心做成一个无所依赖、可移植的事件驱动引擎跑在手机上有手机的形态跑在手表上有手表的形态跑在智能座舱上有座舱的形态那么 Agent 的能力只写一次所有端共用这才是真正的 Agent Anywhere。我的实践是核心层不直接依赖任何 UI 框架和系统 APIUI 适配完全在交互层做掉。核心层只是输入输出事件的搬运工这样移植一个新端基本只要写交互适配代码一周时间足够从零跑通。设备之间的一致性也大幅提升用户在这个设备加了一个技能其他设备同步后立刻可用。6.2 做工程化的人要有一点“造平台”的心态做了几年端侧 Agent我最大的体会是光把功能做出来不算数要能沉淀出别人也能复用的结构才叫工程化。每一次新需求进来先想能不能抽象成通用能力挂到技能层每一次工具调用出问题先想是这一个工具的 bug 还是工具框架的机制漏洞每一个新环境的适配先想是不是核心层没做好环境隔离。工程化是很枯燥的它没有模型算法的光鲜也没有产品交互的亮眼它就是一遍一遍打磨边界、补齐异常、优化资源。但端侧 Agent 时代刚刚开始这波浪潮里真正能把产品做稳的团队一定是工程化底子最好的团队。这篇先写了架构、harness、技能、记忆、并发、安全这六块调试、评测、监控、灰度这些运维侧的工程化内容下篇继续聊。在做端侧 Agent 的朋友如果你们也在架构、框架选型或者资源优化上踩过什么坑欢迎交流各自的解法这个方向值得大家把经验都摊开来看一看。