Agent Harness 是甚麼：模型外層執行框架為何影響效果上限
Agent Harness 是什么：模型外层的执行框架为什么决定效果上限
Agent Harness 是模型外層的執行框架，由執行循環、工具集、記憶、權限控制及可觀測性組成，影響模型能力能否落地。權限需要透過工具白名單、參數校驗和操作確認落在執行層，不能只依賴提示詞。記錄每步輸入輸出、耗時和 token 用量，則可用於定位故障環節及配額消耗。
2026-11-06 3
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
简介： 本文深度解析AI Agent的“外层执行框架”（Harness），涵盖执行循环、工具集、记忆管理、权限控制与可观测性五大核心模块，揭示同一模型在不同Harness下效果差异巨大的根本原因——模型定上限，Harness决落地。
谈 AI 应用效果，大家习惯比较模型本身——参数、版本、跑分。但同样一个模型，套在不同框架里表现能差出很多。
这个"外层框架"有个专门叫法：Harness（挽具）。它指的是模型之外、负责把模型能力落地的整套工程结构。
这篇拆一下 Harness 的技术构成。
一、Harness 管什么
模型本身只会一件事：给定输入，输出下一个 token。它不会自己查资料、不会自己执行代码、不会自己记住上次对话。
把这些能力补给模型的，就是 Harness：
Harness = 执行循环 + 工具集 + 记忆 + 权限控制 + 可观测
| 组成 | 作用 | 缺失的后果 |
|---|---|---|
| 执行循环 | 驱动多步推理与工具调用 | 只能单轮问答 |
| 工具集 | 扩展模型的动作能力 | 只能说话，不能做事 |
| 记忆 | 跨轮次保留上下文 | 无状态，每次从零开始 |
| 权限控制 | 限制可执行的操作范围 | 误操作风险无边界 |
| 可观测 | 追踪每一步输入输出 | 出问题无法定位 |
同一模型 + 好的 Harness，能完成"读代码→定位 bug→修改→跑测试→提交"的完整任务；同一模型 + 裸调用，只能给你一段大概正确的代码片段。
二、执行循环：Agent 的心脏
核心是一个 while 循环：
while 未完成:
1. 把当前状态（用户请求 + 历史 + 工具结果）拼成上下文
2. 调模型，得到下一步决策（调用某工具 / 输出最终答案）
3. 如果是工具调用：执行工具，把结果加入上下文，回到 1
4. 如果是最终答案：结束
技术上要处理的问题：
终止判定。 什么时候算"完成"？模型说完成就算，还是需要验证？前者容易假完成，后者需要验证器。
最大轮次。 必须设上限，否则死循环会烧光配额。
上下文增长。 每轮都追加内容，上下文会越来越长。到上限前要做压缩（摘要、丢弃旧内容、只保留关键结果）。
错误恢复。 工具调用失败后，模型需要看到错误信息并重新决策，而不是整个流程崩溃。
三、工具集：能力边界的来源
工具是模型能"做事"的接口。设计工具集的技术要点：
描述质量决定选择准确率。 工具名和描述是模型唯一的判断依据，含糊的描述会导致误选。
粒度匹配任务。 一个工具对应一个完整的业务动作，太粗太细都不好。
只读与写入分离。 只读工具可以放心让模型多调，写操作要加确认。
结果要结构化。 工具返回的结果格式要清晰，模型才能正确解读。返回一大段非结构化文本会让模型抓不住重点。
错误信息要可读。 工具失败时返回"参数 userId 格式错误，应为 16 位数字"，比返回"500 Internal Error"有用得多——模型能据此修正。
四、记忆：从无状态到有状态
模型本身无状态，记忆是 Harness 补的。
短期记忆：当前会话的对话历史。技术上就是拼进上下文的消息列表。
长期记忆：跨会话的知识。实现方式通常是存储 + 检索——把信息写入向量库或数据库，需要时检索相关片段拼回上下文。
工作记忆：当前任务的中间结果。比如执行到第 5 步时，前 4 步的产出要能拿到。这类通常存在文件或状态对象里，按需读取。
技术难点在什么时候写、什么时候读。全量写入会污染记忆，全量读取会爆上下文。好的实现是按重要性筛选。
五、权限控制：不能只靠提示词
这是最容易被忽略的一环。很多人以为在系统提示词里写"不要删除文件"就够了——不够。
模型可能误解、可能被诱导、可能产生幻觉。权限必须落在执行层：
- 工具白名单：这个 Agent 只能用这几个工具
- 参数校验：文件路径必须在指定目录内，命令必须在白名单内
- 操作确认：写操作前要求人工确认
- 资源配额：单任务最多调用多少次工具、最长跑多久
- 审计日志：每次调用记录谁、何时、做了什么
执行层的限制是硬约束，提示词是软约束。两者都要有，但硬约束是底线。
六、可观测：为什么重要
一个 Agent 任务可能调用模型二十次、工具十次。出了问题要能回答：
- 在哪一步失败的？
- 当时模型看到的是什么上下文？
- 工具返回了什么？
- 重试了几次？
没有链路追踪，这些问题只能靠猜。技术上要记录每步的输入输出（注意脱敏敏感信息）、耗时、token 用量。
token 用量统计的实际价值：能看出哪个环节在消耗配额。很多时候不是模型调用贵，而是上下文塞太多（每次把全部历史都带上）。
七、Harness 决定体验的几个具体表现
| 体验问题 | Harness 层面的原因 |
|---|---|
| 总选错工具 | 工具描述质量差、粒度不对 |
| 反复调同一个工具 | 缺终止判定、缺上下文中的"已完成"信息 |
| 长任务中途失忆 | 上下文压缩策略差、状态没落盘 |
| 回答越来越慢 | 上下文无控制地增长 |
| 偶尔做出危险操作 | 缺执行层权限约束 |
| 出错后无法排查 | 缺可观测 |
八、写在最后
模型决定能力上限，Harness 决定能不能接近这个上限。评估一个 AI 应用，不只看它用什么模型，更要看它的执行循环、工具设计、状态管理、权限边界做得怎么样。
当前 AI 生产力订阅方案中包含的 Harness 相关权益可以看官方页面——查看 AI 权益与 Token Plan 订阅方案的技术能力。具体权益内容与价格以页面实际展示为准。
你在做 Agent 时，最花时间的是哪一环——提示词、工具，还是权限和观测？评论区聊聊。
來源：阿里雲開發者社區 AI · developer.aliyun.com