端侧 Agent 的讨论这两年很热但大部分文章讲的都是模型多聪明Prompt 怎么设计真正聊怎么把 Agent 做成一个能稳定跑在设备上的产品的内容少得可怜。这个系列前两篇聊了端侧 Agent 的形态和模型选型到了第三篇终于要碰最硬的部分Agent 工程化。为什么说是最硬因为我自己在项目评审里被问住过——对方在开发板上演示语音控制 Agent应答流畅、动作准确但当我问设备只有 1GB 内存上下文窗口满了怎么处理工具调用超时后循环怎么恢复多用户共用设备时 Agent 状态怎么隔离会议室安静了十几秒。这三个问题没有一个跟模型效果有关全是工程问题。Agent 工程化的意义就在这里它不负责让模型更聪明它负责让整个系统在真实设备上活下来。这篇文章是工程化的上篇先讲骨架和循环。1. Demo 与量产之间隔着一整条生产线1.1 为什么能跑和能用是两个物种Demo 阶段的 Agent 长什么样跑在开发机上显存管够网络畅通输入是精心设计的 Prompt输出错了大不了重跑一遍。没人会在 Demo 阶段关心稳定性、内存占用、异常恢复——这些在 Demo 阶段根本不重要也不应该重要。量产端侧的 Agent 长什么样跑在手机、开发板、车载盒子或者机器人控制器上。输入是传感器数据流、用户随时打断的语音、不稳定的本地网络。模型推理比云端慢一个数量级内存少一个数量级而且没有重跑一遍的余地——设备上的 Agent 必须自己把错误消化掉用户不会帮你重启。我判断一个 Agent 项目处在哪个阶段用的标尺很朴素统计100 次完整任务里有多少次不需要人工干预就能跑完。Demo 阶段这个数字可能是 60工程化之后的目标是 99。注意这 39 个百分点的差距不一定来自模型。模型答对了但工具执行没结果、Agent 陷入死循环、上下文溢出、内存泄漏、线程阻塞任何一环出问题都会把成功率拉下来。工程化的本质就是把这些非模型因素逐个消灭把系统从碰运气变成可预期。1.2 端侧特有的三重约束算力、内存、功耗第一是算力。以当前主流端侧部署方式为例量化后的 1B~3B 模型在手机 SoC 或开发板 NPU 上生成速度大概在 10~40 token/s 这个量级。这意味着 Agent 每做一次思考 决策的循环光推理就要等 1~3 秒上下文再长一点首 token 延迟还会往上走。所以端侧 Agent 的每一步都要算 token 账系统提示词占多少、工具描述占多少、历史对话占多少、模型输出预留多少。这不是性能优化是能不能跑起来的问题。第二是内存。一个量化后的 3B 模型权重大约是 1.6GBINT4再加运行时开销、工具执行环境、传感器缓存1GB 内存的设备根本装不下。这里有个常见误区以为模型能加载就万事大吉。实际上 KV cache 才是隐藏的内存杀手。拿一个 1GB 内存的设备来算账典型分配大概是内存项目占用约1B 模型权重INT40.6GB推理引擎 运行时0.15GBKV cache2K 窗口0.1GB工具执行环境 系统开销0.15GB已经贴着天花板了。在这种预算下任何顺手多塞点历史工具返回结果不截断的行为都会直接导致 OOM。内存分配在端侧是硬预算不是软配置。第三是功耗和散热。Agent 不是一次推理是一个持续运行的循环。云端可以为一次推理花 5 秒、100W端侧不行。功耗预算决定了你多久唤醒一次模型、用大模型还是小模型、要不要做轻量模型先判断 重模型兜底的级联。我在车载和机器人项目里都见过因为功耗超限导致整机发热降频、推理速度再掉一半的连锁反应。工程化必须把这段热循环纳入设计而不是等样机烫手了再想办法。1.3 工程化的目标把不确定性关进确定性外壳模型输出天然是概率性的但工程系统必须可预期。我的做法是把端侧 Agent 拆成三层模型层负责推理和决策这一层接受可能出错。执行层工具调用、硬件操作、文件读写这一层必须绝对可靠每个动作都有返回码、超时和校验。编排层循环调度、上下文管理、错误恢复这一层负责在模型层和执行层之间做翻译和兜底。工程化主要做的是后两层。说得直白一点模型这一次会输出什么格式我们不保证但模型输出了垃圾格式之后系统该走哪条分支、给什么错误码、怎么回到正常循环我们必须保证。把这句话反过来就是大多数端侧 Agent 项目翻车的原因——它们把系统级的确定性押在了模型身上。模型一抖整个系统跟着抖这不是工程这是赌博。2. Harness 与 Agent 的边界先把骨架立对再谈聪明2.1 一句话区分 Harness 和 Agentharness 和 agent 区别是搜索热度很高的词也是工程化绕不开的第一课。我的定义很简单Agent 是会思考的那部分——通常是一个 LLM 实例加系统提示词加上它需要读写的记忆接口核心能力是推理和决策。Harness 是保证运行的那部分——负责循环调度、工具注册与执行、上下文管理、安全策略、状态持久化。Agent 只回答下一步做什么Harness 回答怎么让这个下一步安全、可靠、可追踪地被执行。打个比方Agent 是大脑Harness 是身体加神经系统。大脑判断看到红灯要停但真正让腿停下、控制肌肉、感知反馈的是身体。没有身体大脑的决策只是空想没有大脑身体只是僵尸。端侧 Agent 工程化的第一步就是把这两个角色在代码层面彻底分开。这个区分不是学术洁癖它直接决定你后面改模型、换硬件、修 Bug 的时候是动一个文件还是动半个项目。2.2 Harness 该管的四件事我把 Harness 的职责收敛成四块任何端侧 Agent 项目都可以按这个清单自查循环控制谁来触发下一轮推理最大步数是多少单步超时多少模型连续输出非法动作时怎么熔断这层管的是系统永远不会失控。工具执行工具注册、参数校验、执行沙箱、结果回填。工具返回的内容要不要截断、要不要结构化都由 Harness 决定Agent 不直接碰工具。上下文管理系统提示词、历史消息、工具结果、记忆内容的拼接顺序和裁剪策略。窗口满了是丢弃最旧、摘要压缩还是查记忆库这是策略问题不是模型问题。策略与审计工具权限白名单、操作日志、运行时可复现性。端侧 Agent 一旦要控制硬件这层不是可选项是安全底线。2.3 边界划清楚之后的三个工程收益第一可测试性。Harness 和 Agent 分离之后测试时可以 mock 掉 LLM让模型假装返回固定的动作序列专门验证 Harness 的循环逻辑、超时策略和错误恢复。否则每次想测一个边界条件都要等真实模型吐出一段随机文本既慢又没法稳定复现。我见过团队为了复现一个模型输出非法 JSON的 Bug手动构造了几十次 Prompt 才撞上这种成本在边界清晰后几乎可以归零。第二可替换性。端侧硬件迭代快今天用 llama.cpp明天可能换 MNN 或自研 NPU 运行时。只要 Harness 层定义一套统一的模型接口换推理后端就是换一个适配器的事。反面教材我也见过推理逻辑和循环逻辑揉在一个文件里换个模型要改半个项目最后没人敢动。第三可降级。Harness 可以在模型完全不可用的时候给出兜底行为。比如工具执行失败时Harness 可以不经过模型直接返回一个预设的安全动作。这在硬件控制场景里极其重要——模型卡死了系统不能跟着卡死。代码层面最简单的分界是一个接口class Agent: def decide(self, state: AgentState) - Action: 根据当前状态输出一个动作只负责决策。 raise NotImplementedError class Harness: def __init__(self, agent: Agent, tools: ToolRegistry, policies: Policies): self.agent agent self.tools tools self.policies policies def run(self, task: str) - Result: # 循环、工具执行、上下文管理都在这里 ...这个接口看起来简单但它是工程上最重要的一条线Agent 永远不直接碰工具工具永远不直接回复用户所有东西都过 Harness。谁破坏这条线谁就要为后续所有的并发问题、权限问题、审计问题买单。3. 资源约束下的 Agent 循环推理、上下文与记忆的博弈3.1 ReAct 循环在端侧的真正形态大家熟悉的 ReAct 循环是推理 → 行动 → 观察 → 再推理。云端实现很随意observation 随便塞上下文随便长。端侧不行端侧每个 token 都有成本推理时间、KV cache 内存、功耗。所以端侧的 ReAct 循环必须加一堆收费站每轮开始前检查当前 token 预算超了就先把历史压缩。工具返回的 observation 必须截断我通常限制在 500 字以内超过的部分落盘需要时再查。最大步数设硬上限比如 10 步防止 Agent 在设备上无限循环烧电。单步超时也要设模型推理超时和工具执行超时走独立的恢复分支。一个最小循环的骨架长这样生产实现会更细但核心结构不变def run_agent_loop(harness, agent, task, max_steps10, budget2048): state harness.init_state(task) for step in range(max_steps): if harness.context_size(state) budget: state harness.compress_context(state) # 压缩历史 action agent.decide(state) # 模型决策 if action.is_final(): return action.result if not harness.validate(action): # 格式/权限校验 state harness.feed_error(state, invalid_action) continue try: obs harness.execute_tool(action) # 执行工具 state harness.append_observation(state, truncate(obs, 500)) except ToolTimeout as e: state harness.feed_error(state, ftool_timeout: {e.tool}) except ToolError as e: state harness.feed_error(state, ftool_error: {e.code}) return harness.timeout_result()注意一个容易忽略的细节错误信息要喂回给模型。工具执行失败不是循环的终点是下一个推理轮次的输入。模型需要知道刚才那个工具超时了你可以换一个工具或者换一种做法——这才是 Agent 行为而不是脚本行为。如果没有这一步Agent 遇到失败只会重试同一个动作陷入死循环。3.2 上下文窗口的预算管理上下文管理在端侧是硬约束不是调参问题。拿 KV cache 算一笔账。KV cache 每 token 的字节数约等于2 × 层数 × KV头数 × head_dim × 数据类型字节数假设用一个 3B 模型32 层Grouped Query Attention 下 4 个 KV 头head_dim 128FP16 推理下每 token 大约是2 × 32 × 4 × 128 × 2 65536 字节 ≈ 64KB4K 上下文就是约 256MB。而模型权重在 INT4 下才 1.6GB 左右——一个 4K 窗口的 KV cache 几乎占掉权重五分之一的额外内存推理时的内存峰值还更高。面对 1GB 内存的设备这个窗口根本开不满。所以我强烈建议端侧 Agent 采用预算式上下文管理而不是尽力式固定预算给上下文定一个硬上限比如 2K token。这不是建议值是内存算出来的天花板。三级压缩窗口满了先丢弃最旧的历史截断还不够就把前面多轮对话做摘要摘要再不够才查外部记忆检索。摘要触发时机不建议每轮都摘要太浪费推理。我的经验是设一个水位线比如上下文用到 80% 时触发一次摘要既不会频繁压缩也不会让窗口溢出。另外提一下前缀缓存prefix caching。端侧 Agent 的系统提示词和工具 schema 是固定的它们对应的 KV 可以预计算缓存模型首批 token 的延迟能明显降下来。很多推理框架原生支持前缀缓存接入时留个心眼可以把首 token 延迟省 20%~50%。这个收益是白捡的前提是你没有把系统提示词写成一团随机拼接的字符串。3.3 记忆分层的廉价方案端侧 Agent 的记忆是典型的需求很大、资源很少问题。我的方案是三层工作记忆就是当前上下文窗口放正在执行任务的信息由 Harness 的上下文管理负责。任务记忆一个任务结束后把关键决策、工具执行结果、结论写入本地文件JSONL 或 SQLite。下次同类任务可以直接用摘要初始化上下文不用从零开始。长期记忆需要跨任务检索的知识用轻量向量库。端侧不用上重量级方案SQLite 浮点向量 暴力检索就够用。设备上几万条向量暴力检索毫秒级完成根本不需要建索引。记忆写回的时机也要控制。我见过一个项目每轮对话都往记忆文件里写结果 flash 写入放大寿命和性能双双受损。正确的做法是任务级写回——整个任务结束或者达到明确里程碑时才做一次记忆持久化。频繁写回不是更聪明是给自己埋坑。3.4 推理侧的量化与缓存模型量化是端侧 Agent 绕不开的一步。INT4 量化通常能把模型权重压缩到 FP16 的四分之一推理速度在多数 NPU 上明显提升。但量化不是免费的语言能力会下降工具调用的 JSON 输出格式错误率会上升。所以量化之后一定要做专门的回归测试重点看工具调用的 schema 是否符合、参数值是否准确而不是只看问答对不对——问答错一个字无所谓工具调用的参数错一个数值设备就干出离谱的事。还有一个容易被忽略的点量化感知训练QAT比训练后量化PTQ在工具调用场景下优势明显。如果端侧模型是自家微调的建议在微调阶段就引入量化模拟避免推理时格式崩坏。PTQ 对纯文本生成够用但工具调用对输出格式的敏感度高得多QAT 多花的那点训练成本通常能在推理稳定性上赚回来。流式输出在端侧 Agent 里也很重要但它的价值不只是给用户打字机效果。对 Agent 循环来说流式输出的核心价值是提前判断——模型正在输出工具调用 JSON 时Harness 可以边收边解析一旦拿到完整的 action 字段就准备执行省掉等全部生成完的时间。前提是解析器要够健壮半截 JSON 也能正确处理、能等待、能丢弃重来。4. Skill 与工具调用的端侧落地让 Agent 真正能干事4.1 工具不是越多越好是越窄越好很多团队做 Agent 的第一反应是把所有能力塞成工具函数列表一大串。端侧不是云端模型参数学到的工具调用能力有限工具越多schema 越长上下文占用越大模型选错工具的概率也越高。我的原则是每个工具只做一件事接口尽量窄。以文件操作为例宁可拆成 read_file、write_file、list_dir 三个工具也不要做一个万能 file_operation 带十几个参数。工具描述要写清楚什么时候该用它而不是长篇大论讲实现。我统计过工具描述超过 100 字之后模型在端侧的调用准确率明显下降——模型看 description 是来找触发条件的不是来学习 API 文档的。工具 schema 的另一个要点是参数要少。超过 5 个参数的工具模型很容易漏填或填错。如果确实需要复杂参数让 Agent 先调用查询状态工具拿到信息再决定而不是让它一次猜完所有参数。这一步牺牲一点循环轮次换来的是稳定性和可调试性值。4.2 工具执行的沙箱与权限层端侧 Agent 的工具往往会触达硬件读传感器、控制 GPIO、写文件、发消息、调电机。这些动作一旦执行错轻则数据损坏重则设备故障。所以 Harness 必须有一个硬性的权限层。我的做法是工具注册时声明权限等级read只读操作默认允许记录日志。control状态修改类操作改配置、开关设备需要策略校验比如要求任务描述里明确包含目标否则拒绝。admin高危操作格式化、固件升级、重启需要额外确认或者根本不允许 Agent 自动执行。Harness 在每次执行工具前检查权限不因为模型输出了工具名就信任它。这个检查与模型本身无关——即使模型被恶意 Prompt 诱导输出一个危险工具调用权限层也会拦住。这是工程兜底不是对模型的道德要求。工具执行的沙箱化同样重要。端侧常见做法是把工具放进子进程执行加上超时强杀。有人提到 docker 容器里的 ROS2 humble 配合 micro-ros agent这是典型的隔离形态Agent 本体和硬件抽象层分离Agent 只能通过服务接口间接控制硬件不能直接访问底层驱动。这种中间件隔离在机器人场景几乎是标配。端侧资源紧张时子进程加 timeout 是性价比最高的沙箱重量级容器留给真正需要强隔离的场景。4.3 工具错误如何优雅地回到循环里工具执行失败是常态不是异常。端侧尤其如此串口可能没数据、网络可能断、传感器可能被遮挡、文件可能已存在。Agent 循环必须优雅处理这些失败。我给工具调用定义了一个统一的返回结构class ToolResult: ok: bool code: str # 机器可读的错误码 message: str # 人/模型可读的描述 data: dict | None # 结构化结果 truncated: bool错误码体系要稳定不能让模型去猜这个报错到底是什么意思。例如code含义Agent 的建议动作TIMEOUT工具执行超时报告超时建议重试或换工具PERMISSION_DENIED权限不足说明原因建议改用只读方案INVALID_ARGS参数校验失败重新生成正确参数HW_UNAVAILABLE硬件无响应建议检查连接稍后重试重试策略要分情况幂等工具读状态、查询可以自动重试一次非幂等工具发消息、写文件绝对不能自动重试要交给模型判断否则可能重复执行副作用。这个区分是我吃过亏才学乖的——有一次自动重试把一条指令发了两遍现场同事差点拆设备。4.4 硬件资源如何封装成工具端侧 Agent 的感知靠的是工具感知工具的质量决定了 Agent 对世界的理解。最常见的坑是阻塞轮询——工具执行卡在等待上把整个循环拖慢。我的做法是事件驱动传感器数据由独立线程或中断收集写入环形队列Agent 调用读取事件工具时直接从队列取不阻塞。硬件状态查询类工具统一走快照 时间戳模式返回的是某个时刻的状态避免 Agent 拿陈旧数据做决策。在机器人场景硬件抽象层通常已经是 ROS2 节点Agent 不需要直接碰串口和电机驱动。Harness 层的工具只是把 ROS2 的服务和 topic 包装成 LLM 能理解的动作接口。这也是我强调工具层要做窄接口的原因——Agent 不需要知道电机的 PWM 怎么算它只需要知道 move_to(x, y) 这个动作成功了没有。复杂控制交给中间件Agent 只做高级决策这是端侧 Agent 最合理的分工方式。5. 一个最小可用的端侧 Agent 工程骨架5.1 目录结构与模块划分前面四节的原理落到工程上就是一个清晰的目录结构。我推荐一个最小化的 Python 骨架足够支撑原型验证和小规模量产edge-agent/ ├── agent/ │ ├── core.py # Agent 接口与提示词组装 │ ├── memory.py # 三层记忆的读写 │ └── llm_backend.py # 推理后端适配llama.cpp/MNN/ONNX ├── harness/ │ ├── loop.py # Agent 主循环与超时控制 │ ├── context.py # 上下文预算、截断、摘要 │ ├── policy.py # 权限策略与审计日志 │ └── errors.py # 统一错误码 ├── tools/ │ ├── registry.py # 工具注册与参数校验 │ ├── builtin/ # 文件、时间、查询等基础工具 │ └── device/ # 传感器、硬件相关工具 ├── configs/ │ └── agent.yaml # 模型、工具、策略配置 ├── tests/ │ ├── test_loop.py # 脱模循环测试 │ └── replay_tests/ # 真实对话回放测试数据 └── main.py # 入口加载配置、启动循环这个骨架的关键点agent 目录不 import toolsharness 目录不 import 具体模型tools 目录不感知循环。三个目录之间唯一的联系是接口定义。这样任何一层都能独立替换、独立测试。不要小看这条约束我见过太多项目到后期变成牵一发动全身的泥潭就是因为目录之间相互 import接口边界形同虚设。5.2 核心循环与语言选型循环代码前面已经给了骨架。这里补充一个端侧开发必然纠结的问题用 Python 还是 Rust如果模型推理本身跑在 C 推理引擎里llama.cpp 之类Agent 骨架用 Python 完全可行开发效率高接推理引擎的绑定库也方便。但 Python 在端侧有两个硬伤内存开销解释器本身几十 MB和 GC 停顿实时控制场景不可接受。如果是机器人实时控制或者内存极小的场景用 Rust 重写 Harness 值得考虑——内存可控、无 GC、交叉编译到各种架构都很成熟。我的建议是原型用 Python 跑通产线用 Rust 或 C 固化中间留好接口不要一开始就锁死语言。热词里基于 Rust 语言 AI Agent搜索热度不低我确实见过不少端侧团队今年开始把 Harness 用 Rust 落一遍把 Python 留给原型验证。这不是赶时髦是端侧内存和实时性的现实要求。5.3 配置驱动的适配层端侧硬件型号杂、推理后端多配置驱动是必须的。一个 agent.yaml 大概长这样model: path: /data/models/qwen2.5-3b-int4.gguf backend: llama.cpp context_budget: 2048 temperature: 0.1 prefix_cache: true harness: max_steps: 10 step_timeout_ms: 8000 compress_watermark: 0.8 observation_truncate: 500 tools: allow_read: true allow_control: true allow_admin: false timeout_ms: file: 2000 sensor: 1000 network: 5000 memory: task_log: /data/agent/tasks.jsonl vector_db: /data/agent/mem.db write_back: task_end注意 temperature 我默认给了 0.1。工具调用场景下低温度能显著降低 JSON 格式出错的概率。这不是玄学是大量实验的结论Agent 决策追求稳定不需要创意。高温度留给闲聊类应用工具调用类 Agent 用高温度就是在给自己制造异常分支。5.4 测试与回归端侧 Agent 最容易翻车的地方端侧 Agent 的测试是我最想强调的部分十个项目里有九个在这上面偷懒。至少要建三类测试脱模测试mock 掉 LLM让 agent 返回固定的 action 序列专门验证 Harness 的循环逻辑、超时、权限拦截。这类测试要秒级跑完每次改 Harness 都跑。回放测试把真实运行时的对话、动作、工具结果录制成 JSONL改动之后回放对比动作序列和最终结果有没有回归。换模型、调量化参数之后这是最快的验证手段。压力冒烟跑 20~50 轮随机工具调用重点监控内存峰值和泄漏。端侧 Agent 最常见的内存泄漏来自 KV cache 分块没释放、工具返回的原始数据没清理。冒烟测试必须在目标设备上跑不能只在开发机上跑。另外类似agent execution terminated due to error的运行时错误最常见的根源是工具返回了模型无法解析的内容二进制数据、超长日志或者 JSON 解析半路崩掉。统一错误码 所有外部输入都走结构化校验能消灭大部分这类问题。这类错误之所以难查是因为它往往在跑了很久之后随机出现没有日志和回放在场你根本定位不到是哪一步把状态搞坏的。5.5 踩坑清单最后列一份我这几年在端侧 Agent 项目里踩过、见过的坑按出现频率排序坑表现对策上下文膨胀跑几轮后每步推理时间翻倍预算管理 水位线摘要工具结果过大窗口瞬间打满、模型被噪声淹没统一截断到 500 字关键信息落盘模型幻觉工具名调用不存在的工具错误喂回去也没用schema 校验 Prompt 白名单推理线程和工具线程抢资源工具 I/O 阻塞导致模型推理变慢线程分离工具执行放独立线程/进程温度过高工具调用 JSON 频繁格式错误temperature 压到 0.1~0.3自动重试非幂等工具指令重复发送、副作用放大只对幂等工具自动重试我知道这篇文章信息量不小而且很多内容看起来不性感——没有讲酷炫的 Agent 新能力全在讲循环、预算、权限、错误码这些苦活累活。但这就是端侧 Agent 工程化的真相模型能力决定 Agent 的天花板工程化决定一个团队能摸到多高。我个人做过最失败的项目恰恰是把最多精力花在换更大模型上而不是把 Harness 骨架立稳。如果你正在做端侧 Agent我的建议是先把循环跑稳把上下文预算算清楚把工具权限立起来再去追模型效果。这篇是Agent 工程化的上篇下一篇我会接着聊并发、状态隔离、可观测性和产线部署这些更偏下半场的问题到时候见。
端侧 Agent 的讨论这两年很热但大部分文章讲的都是模型多聪明Prompt 怎么设计真正聊怎么把 Agent 做成一个能稳定跑在设备上的产品的内容少得可怜。这个系列前两篇聊了端侧 Agent 的形态和模型选型到了第三篇终于要碰最硬的部分Agent 工程化。为什么说是最硬因为我自己在项目评审里被问住过——对方在开发板上演示语音控制 Agent应答流畅、动作准确但当我问设备只有 1GB 内存上下文窗口满了怎么处理工具调用超时后循环怎么恢复多用户共用设备时 Agent 状态怎么隔离会议室安静了十几秒。这三个问题没有一个跟模型效果有关全是工程问题。Agent 工程化的意义就在这里它不负责让模型更聪明它负责让整个系统在真实设备上活下来。这篇文章是工程化的上篇先讲骨架和循环。1. Demo 与量产之间隔着一整条生产线1.1 为什么能跑和能用是两个物种Demo 阶段的 Agent 长什么样跑在开发机上显存管够网络畅通输入是精心设计的 Prompt输出错了大不了重跑一遍。没人会在 Demo 阶段关心稳定性、内存占用、异常恢复——这些在 Demo 阶段根本不重要也不应该重要。量产端侧的 Agent 长什么样跑在手机、开发板、车载盒子或者机器人控制器上。输入是传感器数据流、用户随时打断的语音、不稳定的本地网络。模型推理比云端慢一个数量级内存少一个数量级而且没有重跑一遍的余地——设备上的 Agent 必须自己把错误消化掉用户不会帮你重启。我判断一个 Agent 项目处在哪个阶段用的标尺很朴素统计100 次完整任务里有多少次不需要人工干预就能跑完。Demo 阶段这个数字可能是 60工程化之后的目标是 99。注意这 39 个百分点的差距不一定来自模型。模型答对了但工具执行没结果、Agent 陷入死循环、上下文溢出、内存泄漏、线程阻塞任何一环出问题都会把成功率拉下来。工程化的本质就是把这些非模型因素逐个消灭把系统从碰运气变成可预期。1.2 端侧特有的三重约束算力、内存、功耗第一是算力。以当前主流端侧部署方式为例量化后的 1B~3B 模型在手机 SoC 或开发板 NPU 上生成速度大概在 10~40 token/s 这个量级。这意味着 Agent 每做一次思考 决策的循环光推理就要等 1~3 秒上下文再长一点首 token 延迟还会往上走。所以端侧 Agent 的每一步都要算 token 账系统提示词占多少、工具描述占多少、历史对话占多少、模型输出预留多少。这不是性能优化是能不能跑起来的问题。第二是内存。一个量化后的 3B 模型权重大约是 1.6GBINT4再加运行时开销、工具执行环境、传感器缓存1GB 内存的设备根本装不下。这里有个常见误区以为模型能加载就万事大吉。实际上 KV cache 才是隐藏的内存杀手。拿一个 1GB 内存的设备来算账典型分配大概是内存项目占用约1B 模型权重INT40.6GB推理引擎 运行时0.15GBKV cache2K 窗口0.1GB工具执行环境 系统开销0.15GB已经贴着天花板了。在这种预算下任何顺手多塞点历史工具返回结果不截断的行为都会直接导致 OOM。内存分配在端侧是硬预算不是软配置。第三是功耗和散热。Agent 不是一次推理是一个持续运行的循环。云端可以为一次推理花 5 秒、100W端侧不行。功耗预算决定了你多久唤醒一次模型、用大模型还是小模型、要不要做轻量模型先判断 重模型兜底的级联。我在车载和机器人项目里都见过因为功耗超限导致整机发热降频、推理速度再掉一半的连锁反应。工程化必须把这段热循环纳入设计而不是等样机烫手了再想办法。1.3 工程化的目标把不确定性关进确定性外壳模型输出天然是概率性的但工程系统必须可预期。我的做法是把端侧 Agent 拆成三层模型层负责推理和决策这一层接受可能出错。执行层工具调用、硬件操作、文件读写这一层必须绝对可靠每个动作都有返回码、超时和校验。编排层循环调度、上下文管理、错误恢复这一层负责在模型层和执行层之间做翻译和兜底。工程化主要做的是后两层。说得直白一点模型这一次会输出什么格式我们不保证但模型输出了垃圾格式之后系统该走哪条分支、给什么错误码、怎么回到正常循环我们必须保证。把这句话反过来就是大多数端侧 Agent 项目翻车的原因——它们把系统级的确定性押在了模型身上。模型一抖整个系统跟着抖这不是工程这是赌博。2. Harness 与 Agent 的边界先把骨架立对再谈聪明2.1 一句话区分 Harness 和 Agentharness 和 agent 区别是搜索热度很高的词也是工程化绕不开的第一课。我的定义很简单Agent 是会思考的那部分——通常是一个 LLM 实例加系统提示词加上它需要读写的记忆接口核心能力是推理和决策。Harness 是保证运行的那部分——负责循环调度、工具注册与执行、上下文管理、安全策略、状态持久化。Agent 只回答下一步做什么Harness 回答怎么让这个下一步安全、可靠、可追踪地被执行。打个比方Agent 是大脑Harness 是身体加神经系统。大脑判断看到红灯要停但真正让腿停下、控制肌肉、感知反馈的是身体。没有身体大脑的决策只是空想没有大脑身体只是僵尸。端侧 Agent 工程化的第一步就是把这两个角色在代码层面彻底分开。这个区分不是学术洁癖它直接决定你后面改模型、换硬件、修 Bug 的时候是动一个文件还是动半个项目。2.2 Harness 该管的四件事我把 Harness 的职责收敛成四块任何端侧 Agent 项目都可以按这个清单自查循环控制谁来触发下一轮推理最大步数是多少单步超时多少模型连续输出非法动作时怎么熔断这层管的是系统永远不会失控。工具执行工具注册、参数校验、执行沙箱、结果回填。工具返回的内容要不要截断、要不要结构化都由 Harness 决定Agent 不直接碰工具。上下文管理系统提示词、历史消息、工具结果、记忆内容的拼接顺序和裁剪策略。窗口满了是丢弃最旧、摘要压缩还是查记忆库这是策略问题不是模型问题。策略与审计工具权限白名单、操作日志、运行时可复现性。端侧 Agent 一旦要控制硬件这层不是可选项是安全底线。2.3 边界划清楚之后的三个工程收益第一可测试性。Harness 和 Agent 分离之后测试时可以 mock 掉 LLM让模型假装返回固定的动作序列专门验证 Harness 的循环逻辑、超时策略和错误恢复。否则每次想测一个边界条件都要等真实模型吐出一段随机文本既慢又没法稳定复现。我见过团队为了复现一个模型输出非法 JSON的 Bug手动构造了几十次 Prompt 才撞上这种成本在边界清晰后几乎可以归零。第二可替换性。端侧硬件迭代快今天用 llama.cpp明天可能换 MNN 或自研 NPU 运行时。只要 Harness 层定义一套统一的模型接口换推理后端就是换一个适配器的事。反面教材我也见过推理逻辑和循环逻辑揉在一个文件里换个模型要改半个项目最后没人敢动。第三可降级。Harness 可以在模型完全不可用的时候给出兜底行为。比如工具执行失败时Harness 可以不经过模型直接返回一个预设的安全动作。这在硬件控制场景里极其重要——模型卡死了系统不能跟着卡死。代码层面最简单的分界是一个接口class Agent: def decide(self, state: AgentState) - Action: 根据当前状态输出一个动作只负责决策。 raise NotImplementedError class Harness: def __init__(self, agent: Agent, tools: ToolRegistry, policies: Policies): self.agent agent self.tools tools self.policies policies def run(self, task: str) - Result: # 循环、工具执行、上下文管理都在这里 ...这个接口看起来简单但它是工程上最重要的一条线Agent 永远不直接碰工具工具永远不直接回复用户所有东西都过 Harness。谁破坏这条线谁就要为后续所有的并发问题、权限问题、审计问题买单。3. 资源约束下的 Agent 循环推理、上下文与记忆的博弈3.1 ReAct 循环在端侧的真正形态大家熟悉的 ReAct 循环是推理 → 行动 → 观察 → 再推理。云端实现很随意observation 随便塞上下文随便长。端侧不行端侧每个 token 都有成本推理时间、KV cache 内存、功耗。所以端侧的 ReAct 循环必须加一堆收费站每轮开始前检查当前 token 预算超了就先把历史压缩。工具返回的 observation 必须截断我通常限制在 500 字以内超过的部分落盘需要时再查。最大步数设硬上限比如 10 步防止 Agent 在设备上无限循环烧电。单步超时也要设模型推理超时和工具执行超时走独立的恢复分支。一个最小循环的骨架长这样生产实现会更细但核心结构不变def run_agent_loop(harness, agent, task, max_steps10, budget2048): state harness.init_state(task) for step in range(max_steps): if harness.context_size(state) budget: state harness.compress_context(state) # 压缩历史 action agent.decide(state) # 模型决策 if action.is_final(): return action.result if not harness.validate(action): # 格式/权限校验 state harness.feed_error(state, invalid_action) continue try: obs harness.execute_tool(action) # 执行工具 state harness.append_observation(state, truncate(obs, 500)) except ToolTimeout as e: state harness.feed_error(state, ftool_timeout: {e.tool}) except ToolError as e: state harness.feed_error(state, ftool_error: {e.code}) return harness.timeout_result()注意一个容易忽略的细节错误信息要喂回给模型。工具执行失败不是循环的终点是下一个推理轮次的输入。模型需要知道刚才那个工具超时了你可以换一个工具或者换一种做法——这才是 Agent 行为而不是脚本行为。如果没有这一步Agent 遇到失败只会重试同一个动作陷入死循环。3.2 上下文窗口的预算管理上下文管理在端侧是硬约束不是调参问题。拿 KV cache 算一笔账。KV cache 每 token 的字节数约等于2 × 层数 × KV头数 × head_dim × 数据类型字节数假设用一个 3B 模型32 层Grouped Query Attention 下 4 个 KV 头head_dim 128FP16 推理下每 token 大约是2 × 32 × 4 × 128 × 2 65536 字节 ≈ 64KB4K 上下文就是约 256MB。而模型权重在 INT4 下才 1.6GB 左右——一个 4K 窗口的 KV cache 几乎占掉权重五分之一的额外内存推理时的内存峰值还更高。面对 1GB 内存的设备这个窗口根本开不满。所以我强烈建议端侧 Agent 采用预算式上下文管理而不是尽力式固定预算给上下文定一个硬上限比如 2K token。这不是建议值是内存算出来的天花板。三级压缩窗口满了先丢弃最旧的历史截断还不够就把前面多轮对话做摘要摘要再不够才查外部记忆检索。摘要触发时机不建议每轮都摘要太浪费推理。我的经验是设一个水位线比如上下文用到 80% 时触发一次摘要既不会频繁压缩也不会让窗口溢出。另外提一下前缀缓存prefix caching。端侧 Agent 的系统提示词和工具 schema 是固定的它们对应的 KV 可以预计算缓存模型首批 token 的延迟能明显降下来。很多推理框架原生支持前缀缓存接入时留个心眼可以把首 token 延迟省 20%~50%。这个收益是白捡的前提是你没有把系统提示词写成一团随机拼接的字符串。3.3 记忆分层的廉价方案端侧 Agent 的记忆是典型的需求很大、资源很少问题。我的方案是三层工作记忆就是当前上下文窗口放正在执行任务的信息由 Harness 的上下文管理负责。任务记忆一个任务结束后把关键决策、工具执行结果、结论写入本地文件JSONL 或 SQLite。下次同类任务可以直接用摘要初始化上下文不用从零开始。长期记忆需要跨任务检索的知识用轻量向量库。端侧不用上重量级方案SQLite 浮点向量 暴力检索就够用。设备上几万条向量暴力检索毫秒级完成根本不需要建索引。记忆写回的时机也要控制。我见过一个项目每轮对话都往记忆文件里写结果 flash 写入放大寿命和性能双双受损。正确的做法是任务级写回——整个任务结束或者达到明确里程碑时才做一次记忆持久化。频繁写回不是更聪明是给自己埋坑。3.4 推理侧的量化与缓存模型量化是端侧 Agent 绕不开的一步。INT4 量化通常能把模型权重压缩到 FP16 的四分之一推理速度在多数 NPU 上明显提升。但量化不是免费的语言能力会下降工具调用的 JSON 输出格式错误率会上升。所以量化之后一定要做专门的回归测试重点看工具调用的 schema 是否符合、参数值是否准确而不是只看问答对不对——问答错一个字无所谓工具调用的参数错一个数值设备就干出离谱的事。还有一个容易被忽略的点量化感知训练QAT比训练后量化PTQ在工具调用场景下优势明显。如果端侧模型是自家微调的建议在微调阶段就引入量化模拟避免推理时格式崩坏。PTQ 对纯文本生成够用但工具调用对输出格式的敏感度高得多QAT 多花的那点训练成本通常能在推理稳定性上赚回来。流式输出在端侧 Agent 里也很重要但它的价值不只是给用户打字机效果。对 Agent 循环来说流式输出的核心价值是提前判断——模型正在输出工具调用 JSON 时Harness 可以边收边解析一旦拿到完整的 action 字段就准备执行省掉等全部生成完的时间。前提是解析器要够健壮半截 JSON 也能正确处理、能等待、能丢弃重来。4. Skill 与工具调用的端侧落地让 Agent 真正能干事4.1 工具不是越多越好是越窄越好很多团队做 Agent 的第一反应是把所有能力塞成工具函数列表一大串。端侧不是云端模型参数学到的工具调用能力有限工具越多schema 越长上下文占用越大模型选错工具的概率也越高。我的原则是每个工具只做一件事接口尽量窄。以文件操作为例宁可拆成 read_file、write_file、list_dir 三个工具也不要做一个万能 file_operation 带十几个参数。工具描述要写清楚什么时候该用它而不是长篇大论讲实现。我统计过工具描述超过 100 字之后模型在端侧的调用准确率明显下降——模型看 description 是来找触发条件的不是来学习 API 文档的。工具 schema 的另一个要点是参数要少。超过 5 个参数的工具模型很容易漏填或填错。如果确实需要复杂参数让 Agent 先调用查询状态工具拿到信息再决定而不是让它一次猜完所有参数。这一步牺牲一点循环轮次换来的是稳定性和可调试性值。4.2 工具执行的沙箱与权限层端侧 Agent 的工具往往会触达硬件读传感器、控制 GPIO、写文件、发消息、调电机。这些动作一旦执行错轻则数据损坏重则设备故障。所以 Harness 必须有一个硬性的权限层。我的做法是工具注册时声明权限等级read只读操作默认允许记录日志。control状态修改类操作改配置、开关设备需要策略校验比如要求任务描述里明确包含目标否则拒绝。admin高危操作格式化、固件升级、重启需要额外确认或者根本不允许 Agent 自动执行。Harness 在每次执行工具前检查权限不因为模型输出了工具名就信任它。这个检查与模型本身无关——即使模型被恶意 Prompt 诱导输出一个危险工具调用权限层也会拦住。这是工程兜底不是对模型的道德要求。工具执行的沙箱化同样重要。端侧常见做法是把工具放进子进程执行加上超时强杀。有人提到 docker 容器里的 ROS2 humble 配合 micro-ros agent这是典型的隔离形态Agent 本体和硬件抽象层分离Agent 只能通过服务接口间接控制硬件不能直接访问底层驱动。这种中间件隔离在机器人场景几乎是标配。端侧资源紧张时子进程加 timeout 是性价比最高的沙箱重量级容器留给真正需要强隔离的场景。4.3 工具错误如何优雅地回到循环里工具执行失败是常态不是异常。端侧尤其如此串口可能没数据、网络可能断、传感器可能被遮挡、文件可能已存在。Agent 循环必须优雅处理这些失败。我给工具调用定义了一个统一的返回结构class ToolResult: ok: bool code: str # 机器可读的错误码 message: str # 人/模型可读的描述 data: dict | None # 结构化结果 truncated: bool错误码体系要稳定不能让模型去猜这个报错到底是什么意思。例如code含义Agent 的建议动作TIMEOUT工具执行超时报告超时建议重试或换工具PERMISSION_DENIED权限不足说明原因建议改用只读方案INVALID_ARGS参数校验失败重新生成正确参数HW_UNAVAILABLE硬件无响应建议检查连接稍后重试重试策略要分情况幂等工具读状态、查询可以自动重试一次非幂等工具发消息、写文件绝对不能自动重试要交给模型判断否则可能重复执行副作用。这个区分是我吃过亏才学乖的——有一次自动重试把一条指令发了两遍现场同事差点拆设备。4.4 硬件资源如何封装成工具端侧 Agent 的感知靠的是工具感知工具的质量决定了 Agent 对世界的理解。最常见的坑是阻塞轮询——工具执行卡在等待上把整个循环拖慢。我的做法是事件驱动传感器数据由独立线程或中断收集写入环形队列Agent 调用读取事件工具时直接从队列取不阻塞。硬件状态查询类工具统一走快照 时间戳模式返回的是某个时刻的状态避免 Agent 拿陈旧数据做决策。在机器人场景硬件抽象层通常已经是 ROS2 节点Agent 不需要直接碰串口和电机驱动。Harness 层的工具只是把 ROS2 的服务和 topic 包装成 LLM 能理解的动作接口。这也是我强调工具层要做窄接口的原因——Agent 不需要知道电机的 PWM 怎么算它只需要知道 move_to(x, y) 这个动作成功了没有。复杂控制交给中间件Agent 只做高级决策这是端侧 Agent 最合理的分工方式。5. 一个最小可用的端侧 Agent 工程骨架5.1 目录结构与模块划分前面四节的原理落到工程上就是一个清晰的目录结构。我推荐一个最小化的 Python 骨架足够支撑原型验证和小规模量产edge-agent/ ├── agent/ │ ├── core.py # Agent 接口与提示词组装 │ ├── memory.py # 三层记忆的读写 │ └── llm_backend.py # 推理后端适配llama.cpp/MNN/ONNX ├── harness/ │ ├── loop.py # Agent 主循环与超时控制 │ ├── context.py # 上下文预算、截断、摘要 │ ├── policy.py # 权限策略与审计日志 │ └── errors.py # 统一错误码 ├── tools/ │ ├── registry.py # 工具注册与参数校验 │ ├── builtin/ # 文件、时间、查询等基础工具 │ └── device/ # 传感器、硬件相关工具 ├── configs/ │ └── agent.yaml # 模型、工具、策略配置 ├── tests/ │ ├── test_loop.py # 脱模循环测试 │ └── replay_tests/ # 真实对话回放测试数据 └── main.py # 入口加载配置、启动循环这个骨架的关键点agent 目录不 import toolsharness 目录不 import 具体模型tools 目录不感知循环。三个目录之间唯一的联系是接口定义。这样任何一层都能独立替换、独立测试。不要小看这条约束我见过太多项目到后期变成牵一发动全身的泥潭就是因为目录之间相互 import接口边界形同虚设。5.2 核心循环与语言选型循环代码前面已经给了骨架。这里补充一个端侧开发必然纠结的问题用 Python 还是 Rust如果模型推理本身跑在 C 推理引擎里llama.cpp 之类Agent 骨架用 Python 完全可行开发效率高接推理引擎的绑定库也方便。但 Python 在端侧有两个硬伤内存开销解释器本身几十 MB和 GC 停顿实时控制场景不可接受。如果是机器人实时控制或者内存极小的场景用 Rust 重写 Harness 值得考虑——内存可控、无 GC、交叉编译到各种架构都很成熟。我的建议是原型用 Python 跑通产线用 Rust 或 C 固化中间留好接口不要一开始就锁死语言。热词里基于 Rust 语言 AI Agent搜索热度不低我确实见过不少端侧团队今年开始把 Harness 用 Rust 落一遍把 Python 留给原型验证。这不是赶时髦是端侧内存和实时性的现实要求。5.3 配置驱动的适配层端侧硬件型号杂、推理后端多配置驱动是必须的。一个 agent.yaml 大概长这样model: path: /data/models/qwen2.5-3b-int4.gguf backend: llama.cpp context_budget: 2048 temperature: 0.1 prefix_cache: true harness: max_steps: 10 step_timeout_ms: 8000 compress_watermark: 0.8 observation_truncate: 500 tools: allow_read: true allow_control: true allow_admin: false timeout_ms: file: 2000 sensor: 1000 network: 5000 memory: task_log: /data/agent/tasks.jsonl vector_db: /data/agent/mem.db write_back: task_end注意 temperature 我默认给了 0.1。工具调用场景下低温度能显著降低 JSON 格式出错的概率。这不是玄学是大量实验的结论Agent 决策追求稳定不需要创意。高温度留给闲聊类应用工具调用类 Agent 用高温度就是在给自己制造异常分支。5.4 测试与回归端侧 Agent 最容易翻车的地方端侧 Agent 的测试是我最想强调的部分十个项目里有九个在这上面偷懒。至少要建三类测试脱模测试mock 掉 LLM让 agent 返回固定的 action 序列专门验证 Harness 的循环逻辑、超时、权限拦截。这类测试要秒级跑完每次改 Harness 都跑。回放测试把真实运行时的对话、动作、工具结果录制成 JSONL改动之后回放对比动作序列和最终结果有没有回归。换模型、调量化参数之后这是最快的验证手段。压力冒烟跑 20~50 轮随机工具调用重点监控内存峰值和泄漏。端侧 Agent 最常见的内存泄漏来自 KV cache 分块没释放、工具返回的原始数据没清理。冒烟测试必须在目标设备上跑不能只在开发机上跑。另外类似agent execution terminated due to error的运行时错误最常见的根源是工具返回了模型无法解析的内容二进制数据、超长日志或者 JSON 解析半路崩掉。统一错误码 所有外部输入都走结构化校验能消灭大部分这类问题。这类错误之所以难查是因为它往往在跑了很久之后随机出现没有日志和回放在场你根本定位不到是哪一步把状态搞坏的。5.5 踩坑清单最后列一份我这几年在端侧 Agent 项目里踩过、见过的坑按出现频率排序坑表现对策上下文膨胀跑几轮后每步推理时间翻倍预算管理 水位线摘要工具结果过大窗口瞬间打满、模型被噪声淹没统一截断到 500 字关键信息落盘模型幻觉工具名调用不存在的工具错误喂回去也没用schema 校验 Prompt 白名单推理线程和工具线程抢资源工具 I/O 阻塞导致模型推理变慢线程分离工具执行放独立线程/进程温度过高工具调用 JSON 频繁格式错误temperature 压到 0.1~0.3自动重试非幂等工具指令重复发送、副作用放大只对幂等工具自动重试我知道这篇文章信息量不小而且很多内容看起来不性感——没有讲酷炫的 Agent 新能力全在讲循环、预算、权限、错误码这些苦活累活。但这就是端侧 Agent 工程化的真相模型能力决定 Agent 的天花板工程化决定一个团队能摸到多高。我个人做过最失败的项目恰恰是把最多精力花在换更大模型上而不是把 Harness 骨架立稳。如果你正在做端侧 Agent我的建议是先把循环跑稳把上下文预算算清楚把工具权限立起来再去追模型效果。这篇是Agent 工程化的上篇下一篇我会接着聊并发、状态隔离、可观测性和产线部署这些更偏下半场的问题到时候见。
