Agent · 框架

我们的 Agent Harness：为什么智能体不能只靠一个 Prompt

把大模型接进业务，真正的工程量不在 Prompt，而在 Harness——运行循环、工具协议、上下文管理、权限边界和失败恢复。渤溢云拓 CTO 曹昕拆解 Agent Harness 的四层结构与六个工程决定。

过去两年，几乎所有企业都试过同一件事：写一段很长的 Prompt，把业务规则、输出格式、示例全塞进去，然后期待模型变成业务专家。

Demo 阶段效果不错。上线三个月后，问题全出来了：上下文越来越长、回答开始漂移、工具调用偶尔失败就整轮崩掉、出了错没人知道是哪一步错的。

结论很简单：Prompt 是脚本，Harness 才是系统。

一、Agent Harness 到底解决什么问题

Harness 是套在模型外面的一层运行时。它不负责“想”，负责让“想”这件事变得可控：

• 决定每一轮给模型看什么上下文；
• 决定模型能调用哪些工具、以什么协议调用；
• 决定一次工具失败之后是重试、降级还是终止；
• 决定这次运行留下了什么可审计的痕迹。

换句话说，模型是发动机，Harness 是变速箱、底盘和刹车。没有后者，马力再大也上不了路。

二、我们的四层结构

我们把 Harness 拆成四层，每层只做一件事。

1. 运行循环层

负责一轮一轮地推：读上下文 → 调模型 → 解析回复 → 执行工具 → 回填结果 → 判断是否继续。

这里最容易犯的错是没有迭代上限。早期我们没设死上限，遇到模型反复调用同一个工具时会空转，一次请求能烧掉几十轮 token。现在的规则很硬：最大迭代次数显式配置，不依赖 SDK 默认值；超限直接返回已获得的最好结果，而不是报错。

2. 工具协议层

工具不是“函数列表”，是契约。我们的约定是：

• 参数必须强类型、有 schema，拒绝“什么都能填”的自由文本参数；
• 工具的返回必须是结构化结果，失败也要返回结构化错误，而不是抛异常让模型去猜；
• 工具描述里写清楚什么时候不该调用，这比写“什么时候调用”更重要。

一个真实例子：我们的记忆检索工具，描述里专门加了一句“搜索失败或未命中，不代表用户没有相关信息，不要据此编造”。加这一句之前，模型搜不到就开始臆测；加了之后，同一批用例的答案质量明显稳定。

3. 上下文层

上下文不是越多越好。我们的做法是分层装配：

关键是最后一条：工具结果不应该无限累积。我们只保留最近一次的完整结果，更早的压缩成一行摘要。不做这件事，长任务跑到第 20 轮时上下文就废了。

4. 边界与审计层

这一层决定系统能不能进生产：

• 身份参数绝不交给模型填。决定“查谁的数据”的参数只能来自服务端可信上下文，读不到就失败关闭，不给默认值。
• 每一次运行留痕：用了哪个模型、调了哪些工具、命中哪些检索结果、耗时多少、失败在哪一步。
• 失败要显式。宁可告诉用户“本次未能完成核验”，也不要静默降级成一个看起来正常的回答——后者是最难排查的线上问题。

三、我们踩过的三个坑

坑一：把 Prompt 当配置中心

第一版把所有业务规则写进 Prompt，改一条规则要发版。现在规则拆成两类：稳定约束进代码，可变口径进配置或知识库。改口径不需要发版，改约束必须走评审。

坑二：工具越加越多

工具从 5 个加到 25 个之后，模型选错工具的概率明显上升。后来做了两件事：按场景分组挂载（不是所有工具都全局可见），以及给每个工具写“反例说明”。工具的可发现性，比数量重要。

坑三：没有区分“模型错了”和“系统错了”

早期所有异常都归为“模型不稳定”。加上分步留痕之后才发现，大约一半的“模型出错”其实是工具返回格式变化、超时、上游接口限流导致的。没有观测，就没有优化。

四、什么时候不需要 Harness

说句公道话：如果你的场景是单轮问答、无工具、无状态，直接用模型 API 就够了，上 Harness 是过度设计。

需要 Harness 的信号有三个：

1. 任务需要多步完成，且中间结果要回填；
2. 需要调用真实业务系统，出错要能回滚或降级；
3. 需要可审计——出了问题要能说清楚是哪一步、为什么。

满足两条以上，就值得投入。

五、最后

模型会一直被替换。今天用 A 家，明天换 B 家，参数和价格都在变。

但 Harness 里的东西——工具契约、上下文装配策略、权限边界、失败处理、审计留痕——是你自己的工程资产，换模型不用重写。

所以我对团队的要求一直是：别把聪明押在 Prompt 上，把可靠做进 Harness 里。