端侧 Agent 工程化和云侧 Agent 工程化完全是两种打法。模型能不能在设备上跑起来这只是第一关真正让 Agent 能被用户日常使用是第二关——运行时的调度、记忆、工具边界、权限、可观测性缺哪一个都会让你从 Demo 回退成“玩具”。这篇是《深入理解端侧 Agent》系列的第四篇也就是工程化的下半场重点讲端侧 Agent 从“能推理”到“能干活”要跨过的那些工程坎。适合正在做端侧 AI 硬件部署、Agent 产品化、或者纠结 Agent 框架怎么选的工程师也适合准备入行 Agent 开发的人当一份全局地图看。1. 先看清全景Agent 工程化下到底在补哪些模块1.1 从上篇到这篇交付路径还差哪几块上篇花了不少篇幅讲模型层的事选型、量化、NPU 适配、单次推理的性能评估。那部分解决的是“模型能不能在设备上跑”这篇要解决的是“Agent 能不能在设备上长期、稳定、安全地干活”。我在实际项目里看到最典型的翻车场景是这样模型量化好了首次推理延迟测出来 50 毫秒团队很高兴觉得已经成了。结果一接入真实对话流程Agent 本地要加载系统提示词、注入用户画像、调一个工具去读文件、再把工具结果塞回上下文重新推理一次整套链路跑下来用户等了 40 秒。中间还出现过一次 Agent 在工具执行完以后没保存状态设备重启对话断线全部丢失的故障。所以工程化下半场要补的不是某一个点而是一整条“可信运行链”。按我的拆解主要七块进程与生命周期管理、并发与请求调度、记忆与状态持久化、工具与 Skills 插件机制、安全沙箱与权限模型、可观测性与日志、失败恢复与降级。云侧这些东西很多都能靠 Kubernetes、Redis、Prometheus 一套组合拳解决但端侧设备没有这些基础设施。端侧更像一台没有运维人员的微型服务器你得把那些能力以轻代码的方式全部内嵌到 Agent 运行时里。1.2 Agent 框架与 Harness 的区别以及为什么端侧更依赖后者最近在社区里看到一个高频问题Harness 和 Agent 框架到底什么关系。很多人把 LangChain、Dify、CrewAI 这类框架当成 Agent 的全部这其实是理解偏差。框架解决的是“Agent 循环怎么描述”怎么让模型做计划、调用工具、观察结果、再决定下一步。它给你的是编排层本质是一个相对通用的控制流模板。而 Harness 解决的是“这个循环怎么被安全地装进一个生产环境”。Harness 要管循环启动条件、单步超时、总预算上限、工具执行隔离、状态持久化、失败重试、事件日志。你甚至可以理解为框架是发动机Harness 是整车电子电气架构。在端侧你更需要 Harness因为设备环境的资源边界和不可控性太强。你在 GitHub 上能看到一些叫 agent-harness、Hermes Agent 的开源项目它们的核心思路基本一致把 Agent 循环封装在一个可观测、可限流、可重启的执行环境里。用 Rust 写的这类运行时尤其多因为 Rust 的内存控制和无 GC 行为在端侧太合适了。后面讲并发和安全时很多设计也都是从 Harness 的视角出发的。1.3 端侧工程化的四个约束条件做端侧 Agent 工程化之前先把这几个约束刻在脑子里。第一算力不是无限的推理原则上应该串行并行多路意味着成倍的内存。第二设备可以被随时打断来电、息屏、重启、断电你不做状态持久化用户就会骂娘。第三端侧的最大价值是隐私数据留在本地那你就要把这个承诺在架构上立住不能被一个权限漏洞打穿。第四设备往往处于弱网环境一旦工具调用依赖云端服务就要有明确的超时和降级策略。这四个约束是后面所有设计决策的出发点。理解了它们你再看网上那些“端侧 Agent 扛并发”“端侧多 Agent 编排”的方案就能分辨出哪些是工程现实哪些只是 PPT。2. 并发怎么处理端侧 Agent 的资源调度策略2.1 别把云侧的“扛并发”直接搬到端侧先说明一个容易误入的概念“Agent 怎么扛并发”在端侧和云侧是两件事。云侧扛并发是解决多个独立用户请求同时打进来办法是水平扩容。端侧通常是单用户设备真正的问题是一个用户同时触发了多个 Agent 任务或者一个 Agent 任务内部同时并发调用多个工具这时候模型资源严重不够。举一个实际数字一个 1B 到 7B 参数量级的端侧模型量化以后权重占用通常在 1GB 到 4GB推理过程中还有 KV Cache 占用。设备总内存如果只有 8GB你想同时保持两个 Agent 会话活跃很快就会发现系统开始频繁换页推理速度掉到不可接受的水平。我见过一个团队试过在同一个手机上同时跑两个 Agent 实例结果模型加载内存接近 6GB后台直接被系统杀掉。所以端侧并发的设计目标不是“同时跑”而是“排队跑得好”。你要保证优先级高的交互请求快速响应同时不让后台批量任务饿死也不让它们把内存挤爆。Singul 我们在路由侧做到的最优策略本质上就是一个带优先级的任务队列让推理引擎始终单例运行。2.2 单引擎加队列把多路请求排成一条可控的流你可以在 Agent 运行时里维护一个任务队列任务有优先级推理引擎只关心从队列头拿任务。举个例子class AgentExecutor: def __init__(self): self.priority_queue PriorityQueue() self.engine EngineLoader.get_shared() async def submit(self, request, priority): task AgentTask(request, priority) self.priority_queue.put(task) async def run(self): while True: task await self.priority_queue.get() async with self.engine.acquire_context(): await self.engine.invoke(task.stream_context) self.priority_queue.task_done()代码是示意重点在结构。请求按两到三级优先级划分用户正在看的交互式请求放最高后台预加载和摘要任务放中等级批量数据整理放最低级。如果最高优先级任务到达而当前正在跑一个低优先级任务你可以选择立即取消低优先级任务把推理资源让出来或者让它最多跑到一个安全断点再让位。这里我建议优先采用“可中断点”而不是强杀因为推理中途硬切可能让 KV Cache 和上下文状态不一致。2.3 共享引擎与会话状态隔离既然推理引擎必须单例那多会话的关键就是“共享但不串味”。模型权重可以共享因为推理引擎加载一次就够了每个会话只保留独立的上下文状态、工具调用历史和记忆索引。工程上要把这两者分清楚全局引擎是只读的会话上下文是可变的。最容易踩的坑是把“会话独占一个 Agent 实例”写成“为每个会话加载一份模型”。我在一个项目里见过这样的代码理由是并行度高结果模型加载两回直接把设备内存打穿。正确做法是会话只持有自己那份 SessionState里面包含当前上下文缓存的引用、变量表、任务进度。当请求进入时运行时从队列把它调度到共享引擎上执行执行完把增量状态写回 SessionState。会话状态最好加事务性避免工具调用写了一半设备突然被杀下次恢复出一份坏数据。状态更新的最小单位是事件而不是直接覆盖快照。2.4 端侧并发和响应速度的取舍再来一个实操层面的计算逻辑。用户感受到的 Agent 响应延迟大致是排队等待时间 模型推理时间 工具执行时间。模型推理时间取决于当前上下文长度和设备算力工具执行时间取决于外部服务或本地文件 IO排队等待时间就是你调度策略的结果。假设设备推理速度是每秒 30 token当前上下文 4000 token一次完整生成 500 token那模型层就要 150 秒左右这显然太慢你根本不可能让用户干等。如果上下文短一点 1500 token生成 200 token那就是大约 57 秒还是偏慢。这意味着三件事一是 Agent 要让对话上下文尽量精简二是长任务必须主动降级为“后台执行 完成通知”三是流式输出必须从一开始就把首 token 快点返回给用户不要让用户面对空白窗口。并发调度在端侧不是追求同时做的任务数而是保证主任务永远不被阻塞。永远记住这句端侧 Agent 的并发设计本质是选择什么任务可以被牺牲。3. 记忆与状态端侧 Agent 的上下文不动产管理3.1 三层记忆模型的端侧落地社区里讨论 Agent 记忆时经常吵“记忆是不是伪需求”我的看法是工程上先把记忆拆层再判断。端侧 Agent 的记忆至少分三层。短期记忆就是当前对话的最近片断一般放在内存里工作记忆是当前任务进行到哪一步了正在执行的子任务、已经完成的清单这种状态必须持久化否则任务中断就断片了长期记忆是用户的偏好、历史事实、领域知识这些要落到本地数据库里按需检索。做端侧记忆存储选型不需要大上向量数据库。SQLite 加一个本地向量索引完全够用。你甚至可以用更轻的思维方式把长期记忆拆成结构化条目按用户 ID、时间、类型存表需要时用关键词和向量混合召回。端侧数据量级一般不会大到需要专用向量数据库重点是建立可增删改查的记忆索引并且一定要给用户一条“删除全部记忆”的路径这是合规底线。3.2 上下文预算把 Token 当作真正的内存容量很多刚接触的开发者会问“AI Agent Token 是什么意思”。往浅了说Token 就是模型处理文本的基本单位往深了说Token 窗口就是模型这个“打工人”一次能摆在桌面上的便签总数。端侧模型上下文往往只有 4K 到 32K比云上动辄 200K 小得多。所以 token 在端侧不是计费概念它是内存容量是硬预算。上下文预算就是问一个问题一份 8K 的上下文系统提示词占 1500工具定义占 1500当前用户请求占 500那留给历史记忆的只剩 4500。记忆放不下怎么办压缩。老的对话要摘要化而不是原封不动全塞进去。下面是一个很粗糙但实用的预算函数def build_context(system, tool_schemas, recent_history, retrieved_memory, query, max_tokens8000): used count_tokens(system) count_tokens(tool_schemas) count_tokens(query) available max_tokens - used if count_tokens(recent_history) count_tokens(retrieved_memory) available: return system tool_schemas recent_history retrieved_memory query # 优先保最近的对话再用摘要压缩更老的部分 recent recent_history[-8:] memory_summary summarize(retrieved_memory, budgetavailable - count_tokens(recent)) return system tool_schemas recent memory_summary query这个函数的核心思想是长期记忆永远只取 top-k老对话永远做摘要压缩系统提示词和工具说明尽量精简。你还可以把摘要结果缓存下来避免每次请求都重新压缩。3.3 状态持久化与崩溃恢复Event Sourcing 的思路Agent 执行到一半被系统杀掉是端侧必然遇到的问题。单纯把 Agent 当前上下文存储成一个 JSON 快照是不够的因为可能刚写到一半设备断电留下一个半新半旧的文件。我在端侧 Agent 里比较推荐 Event Sourcing 的思路每次交互都落一条结构化事件记录包括用户消息、Agent 的中间思考、工具调用、工具返回值、生成的回复、记忆更新操作。恢复流程很简单从事件日志里重放把 SessionState 重建出来如果最后一条事件是不完整的工具调用就标记为失败并允许重试。比如一个 Agent 正在执行网页转 Markdown 的工具突然系统被强杀。重启后你翻事件记录发现 ToolCall 已经发出但 ToolResult 没回来那你可以直接恢复会话提示用户“刚才的任务被打断了是否重试”。这比把错误原样抛给用户要好得多。3.4 记忆治理过期、遗忘与隐私删除长期记忆如果不治理最后会成为垃圾场。用户的旧偏好可能已经变化老任务的历史此前可能还有用但半年后就是噪声。工程上要给每条记忆加时间戳、来源、置信度定期做汇总和过期清理。隐私删除更关键。用户说“忘记关于我的所有数据”你要能做到数据真正删除而不是把向量库文件翻出来还能找到残留。这就回到前面说的设备本地的记忆存储建议用加密数据库删除时直接销毁密钥让历史数据彻底不可恢复。4. 把能力做成 Skills工具、多 Agent 与编排模式4.1 为什么 Skills 比 Tools 更适合端侧 AgentTools 是单个函数调用Skills 是一整套可独立加载的能力包。它的差别在于一个 Skill 包含触发描述、参数结构、实现代码、依赖清单、测试用例和示例调用。你可以把 Skill 想象成系统里的一个 APPTools 只是 APP 里的一个按钮。端侧尤其需要 Skill 机制原因有三。一是设备上的工具不能无限加载每个工具定义都会占系统提示词 token所以你必须按场景动态挂载二是端侧 Agent 不一定预先知道自己要面对什么任务动态发现 Skill 列表、按描述匹配能力是很好的扩展方式三是 Skill 单独开发和测试不像 Tools 那样全都绞在 Agent 主代码里。工程上Skill 描述写得好不好直接影响 Agent 能不能正确调用它。描述里不能只写“抓取网页”要写明适用场景、输入输出限制、使用注意、可能的失败模式。4.2 一个可落地的 Skill 案例把网页保存成 Markdown有一个在端侧很典型的 Agent 技能用户给一个链接Agent 把网页正文转成 Markdown存到本地笔记。这个任务看似简单落地时有不少细节。Skill 描述可以这样定义{ name: web_to_markdown, description: Fetch a URL and convert main content into Markdown., parameters: { type: object, properties: { url: { type: string, format: uri } } }, allowed_domains: [*.example.com, *.wikipedia.org], timeout_sec: 12, max_bytes: 2097152 }执行流程是网页请求、HTML 编码检测、正文抽取、HTML 转 Markdown、大小截断。这里必须加 允许域名白名单否则 Agent 拿到一个恶意链接就去请求内网地址会激起 SSRF 风险。超时和安全限制也一样要写进参数。工具执行完以后返回给模型的不应该是整篇 Markdown 原文而是摘要和存储路径否则又白白烧掉一大截上下文 token。测试这个 Skill 时要准备干净的 HTML、乱码编码页面、超时页面、极大网页四类用例。工具测试层面很容易跑通真正的问题往往在真实网络环境里所以端侧 Skill 还要加一个“离线缓存优先”的选项避免在弱网下卡死。4.3 多 Agent 编排在端侧的正确姿势社区里多 Agent 概念炒得很热但端侧设备上别秀肌肉。你不能在设备内存里同时跑“主管 Agent”“研究员 Agent”“写作者 Agent”三份模型实例那不叫编排那叫内存爆炸。端侧多 Agent 的正确姿势是共享同一个推理引擎用不同 System Prompt 和不同 Skills 组合模拟多个角色。它们之间通过内存中的消息总线通信消息就是普通的 JSON 事件而不是各自独立的推理循环。严格说这不是多个 Agent而是同一个大脑在不同角色间的切换调度。如果你确实需要并行处理多个任务建议用计划者-执行者模式一个调度 Agent 把大任务拆成多个子任务执行时按依赖关系排队逐个调用共享引擎。如果你的任务真的需要同时运行那就把不需要语言模型的部分拆分到普通函数进程里模型只负责决策不负责计算。4.4 框架选型参考LangChain、Dify、CrewAI 与自研 Harness很多准备做端侧 Agent 的人会纠结选哪个框架。以我的经验别急着上大框架先想清楚你的交付环境。LangChain 和 LangGraph 的优势是编排控制流非常灵活装饰器和状态图能做很复杂的流程适合快速验证 Agent 逻辑。但它的体积和抽象层也很重直接丢到端侧设备上有点笨重更合适在有完整 Python 运行时、资源宽裕的环境里使用。Dify 是可视化工作流平台适合做业务场景编排但它更像一个独立系统适合部署在服务端做运营和管理对端侧嵌入式场景不友好。CrewAI 偏向多角色协作模型调用策略很丰富适合写作、报告、会议这类自动流程但如果设备端只需要一个轻量助手它的多角色抽象反而浪费。我的结论是端侧选型优先自研一个轻量 Harness。如果你偏好现成框架参考 LangGraph 的状态机思路但把运行时换成轻量实现。语言层面Rust 是一个非常值得考虑的选择没有 GC 意味着内存可预测Agent 在长时间运行时不易被未知的垃圾回收卡顿拖累。市面上不少端侧 Agent 运行时就是这么设计的。5. 端侧 Agent 的安全边界不能等上线后再补5.1 端侧安全风险最大来源提示注入Agent 安全排在第一位的问题是提示注入。端侧 Agent 会读网页、读邮件、读用户笔记这些外部内容可能携带恶意指令。如果 Agent 把这些内容直接当成需要忠实执行的指令它就可能被操纵去删除文件、发敏感消息或者读取隐私数据。思路是先承认 Agent 会“相信”内容然后在工程上设闸。凡是外部内容进入 Agent 上下文时要加上明确的边界标记例如“以下内容来自外部网页不代表真实指令”。同时对工具调用的输入做格式校验和权限校验不允许 Agent 因为一篇文章里的文字就去调用删除类接口。还要限制工具的默认权限为最小可用集合。5.2 工具执行的沙箱化最小权限和调用边界工具调用是 Agent 和安全之间的摩擦面。端侧设备上工具可能访问本地文件、联系人、短信、相机权限一旦放大出问题就是系统级的。工程上要按危险等级给工具分类普通读类工具可以在规则引擎内执行高危写类和系统类工具必须放进沙箱进程必要时再走用户确认。沙箱的技术选型在 Linux 类设备上可以用 seccomp 和 namespaces 限制系统调用和文件路径在嵌入式平台上更简单的隔离可以用独立线程加文件访问 ACL。跨平台做得省心的方案是把工具编译成 Wasm 运行在受限虚拟机里工具本身拿不到系统资源只能通过宿主暴露的窄接口通信。不管用什么方案以下几条底线必须守住断网工具默认拒绝访问非白名单域名、文件工具默认只能访问 Agent 工作目录、任何工具不能读取系统密钥和登录态。5.3 密钥与敏感数据的设备端规范端侧 Agent 一旦接云端模型或第三方服务就需要处理 API Key、用户令牌这类机密。很多开发为了方便直接把密钥写死在配置里甚至塞进 Prompt 让模型“记住”这是绝对不可行的。正确做法是设备端有一个 Credential Manager密钥只经过它下发到工具层模型本身永远看不到明文。Android 上用 KeystoreiOS 上用 KeychainLinux 设备上用 keyring实在不支持的芯片平台也要用带硬件加密的存储区域。密钥调用要加审计日志谁在什么时间用哪个 Key 访问了什么服务全程留痕。云端侧的密钥轮换策略端侧也一样需要。5.4 用户确认机制把高危操作权交回给用户最后一道防线是用户确认。Agent 要读取屏幕内容、分享文件、发送消息、开启摄像头或麦克风都应该弹出确认。确认弹窗不能做成“每次必弹但用户在 0.5 秒内盲点同意”的鸡肋要做成按操作等级动态触发的机制。比如 Agent 想在本地读一个文本文件给总结这是低风险不需要打断用户但它想把一段文本发送到某个网络服务就需要用户确认。用户确认在端侧还有一个额外作用它逐渐为用户建立对 Agent 的信任模型让他清楚地知道哪些操作被自动执行了哪些操作 Agent 会争取授权。6. 测试、可观测性与故障恢复把端侧 Agent 当生产系统养6.1 测试金字塔从函数单元到设备真机端侧 Agent 的测试不能只测“模型输出像不像样”要测的是 Agent 的决策轨迹是否符合预期。我建议分三层。第一层是单元测试覆盖工具函数和 Skill 本身比如网页转 Markdown 技能在各种输入下的表现。第二层是轨迹回归测试拿一批固定的历史对话记录回放 Agent 循环断言每次工具调用顺序、参数、错误处理是否符合预期。第三层是设备端到端测试在真实手机上跑完整流程看内存峰值、耗电、首次响应时间和崩溃率。轨迹回归测试是 Agent 特有的环节因为你不能断言模型回复的文本一模一样但你可以断言它是否选择了正确的工具、是否合理处理了输入、有没有在超时后给出降级响应。这样做最值得花时间。6.2 可观测性事件日志比指标更重要云服务习惯看吞吐量、延迟、错误率端侧 Agent 更需要看事件轨迹。你要能精确知道某一个会话里模型被调用了多少次每次用了多少 token、耗时多少工具被调用了哪些哪个超时记忆检索命中了哪几条最后是谁终结了循环。实现上不复杂用结构化 JSON Lines 日志即可每个事件带 session_id、trace_id、时间戳。每次模型调用、工具调用、记忆更新、错误捕获都是一条事件。日志写到本地文件偶然上传或由用户主动导出。有了事件轨迹线上问题就不再是黑盒。6.3 失败恢复把“Agent execution terminated due to error”翻译成人话端侧 Agent 上线后最常见的报错就是一句冷冰冰的英文错误。用户不懂模型为何终止开发也难排查两边都很痛苦。工程上要把错误分类处理。瞬时错误如模型服务超时、NPU 资源暂时不可用可以做有限次指数退避重试。永久错误如非法输入、疑似注入、用户取消直接终止并返回可读原因。还有一类降级错误比如端侧模型内存不足这时可以回退到预先缓存的多轮应对模板至少不让用户面对空白。错误码要暴露在日志里但展示给用户的必须是行动提示例如“网络超时请重试”或“该操作未被允许已停止”。6.4 给开发者的四步学习路径如果你刚开始接触 Agent 工程化不要一上来就研究多 Agent 编排和复杂记忆机制。我的建议是走一条递进路径。第一步用一个现成框架把单 Agent 跑通搞懂“模型调用-工具调用-观察结果”这个循环。第二步研究一个 Harness 实现自己写一个极简版只做超时、重试、事件日志三件事。第三步给 Agent 加一个 Skills 机制和本地记忆做一个能跨重启恢复会话的小项目。第四步给系统加安全边界和测试模拟各种坏输入把错误恢复补齐。走完这四步你对端侧 Agent 工程化的理解会远远超过只读框架文档的人。最后说一个我自己在端侧 Agent 项目里比较实际的体会不要一上来就贪多多 Agent、超长记忆、复杂工具链这些都先放一放。把一个最小闭环做到极致——一个模型、三个按需加载的 Skills、一套可靠的状态持久化、一份干净的事件日志——端侧产品的稳定性就能超过大多数热闹的 Demo。先把“不崩、可恢复、知道为什么失败”这三件事做扎实再谈更多能力扩展这是我踩过很多次坑之后最想分享的一条经验。