02 · Harness:把裸模型变成能用的 Agent
读完你会知道:
- 为什么「会聊天」和「能干活」是两件事,Harness 具体补的是哪一段;
- Harness 的四组配置、三个插槽分别控制什么,接口语义是什么;
- 一次请求的真实顺序:历史、上下文提供者、模型、工具循环各在什么位置;
- 工具循环的工程细节------并行调用、异常回填、步数预算、callId 配对;
- 框架自带能力的边界:哪些开关会互相覆盖,哪些「关掉」其实关不掉。
三句话版本
- Harness 不是新东西,就是 1.6 那段 while 循环的工业化:工具执行、历史、上下文注入、步数预算、轨迹记录。
- 它的价值不在省代码,而在把那些「每样都要、每样和业务无关」的分支写对:异常回填成结果、
callId严格配对、
按用户轮次而不是消息条数裁历史、finally里落库。- 它有个反直觉的脾气------配置错了不报错 。设了压缩策略,
MaxContextWindowTokens就被忽略;
Disable...Provider关不掉你自己注入的那一个。读源码,别信开关名字。
概念出处(意译 + 出处) :harness 是个借来的词,本义是马具------把一股力量拢住、并指向要干的活。软件测试里的 test harness 已经用它用了几十年(替身、驱动、记录结果)。
挪到 LLM Agent 上是 2025 年下半年到 2026 年初的事,而且没有单一发明者 ,是几拨人独立收敛到同一个说法:
2025 年 9 月起工程博客已有同题文章(Tian Pan《Anatomy of an Agent Harness》),
2026 年 2 月 Mitchell Hashimoto 把「每次 Agent 犯错就往环境里加一道永久修复」命名为 harness engineering,
同月 OpenAI 一份现场报告(一支小团队五个月产出约百万行、无人工写码)让它扩散,
2026 年 3 月 LangChain 的《The Anatomy of an Agent Harness》把它压成一句
Agent = Model + Harness。一句话定义 :Harness 是模型之外的一切 ------工具派发、状态与记忆、沙箱执行、上下文管理、权限与护栏。
模型是无状态函数,token 进、token 出;把它变成能干活、能连续跑几小时的 Agent,靠的是外面这一层。
MAF 只是其中一个实现,不是定义所在 :Microsoft Agent Framework(开源,把 Semantic Kernel 的企业能力与
AutoGen 的多 Agent 编排并成一套 API)把这层做成
HarnessAgent与HarnessAgentOptions,本篇 2.1--2.4 的配置项、插槽与开关语义都取自它。但要分清这是一种实现的选择 :
换个框架,类名、默认值、开关都会变,
Model + Harness这条分工不变。
一、为什么会有它
1.1 起因:三十行循环,点燃了 2023 年的春天
2022 年 10 月,ReAct 论文给出了一个极简配方:让模型先写一段「想什么」,再输出一个「做什么」,
执行完把结果贴回去,继续下一轮。thought → action → observation,如此往复。
2023 年 3 月底到 4 月初,两个开源项目把这个配方压缩成了几十行 Python:AutoGPT(3 月 30 日)和 BabyAGI(4 月初)。
它们给模型一个目标,然后让它自己拆任务、自己调工具、自己判断「还没做完」。GitHub 星标在几个月内冲到十万级,
无数人第一次看到「AI 自己干活」------虽然它干到第三步就开始重复同一句话。
那是 Agent 的「莱特兄弟时刻」:飞起来了,但只能飞十几秒。
1.2 撞墙:从 demo 到生产,账单有四张
所有人都能跑通 demo,工业界却在同一年撞上四堵墙。它们不是模型不够聪明,而是运行时没长齐:
| 缺口 | demo 里的表现 | 生产里的后果 |
|---|---|---|
| 工具 | 只有搜索和计算器 | 只能「说」,不能真正下单、退款、改库 |
| 循环控制 | 跑 20 步算运气好 | 死循环烧钱;该停的时候不停,该继续的时候提前收工 |
| 历史与上下文 | 一次任务一个会话 | 多轮任务记不住前面;工具返回的长 JSON 一轮就把窗口撑爆 |
| 边界与观测 | 没有审批、没有日志 | 越权操作无人拦;出事只有一句「模型自己决定的」 |
手写 while 循环能补前两个,补到第三个开始难受,补到第四个基本失控:流式事件、并行工具调用、
异常重试、token 统计、上下文压缩、人工审批、可观测性、多 Agent 协作------每一样都要,且每一样都和业务无关。
1.3 转折:function calling 把「猜」变成了「协议」
2023 年 6 月 13 日,OpenAI 在 gpt-3.5-turbo-0613 与 gpt-4-0613 上开放 function calling。
在此之前,让模型调工具靠提示词约定格式 + 正则解析,模型多写一句「好的,我来调用」就解析失败;
在此之后,模型输出的是符合 JSON Schema 的结构化调用,应用层第一次能可靠地接住。
这一步看似只是省了几个正则,实际是把循环从「实验」变成「基础设施」的前提:
只有调用可被可靠解析,框架才敢把重试、并行、压缩、审批这些机制工业化地包在循环外面。
于是 2023 下半年到 2025 年,各家把同一件事做了很多遍:LangChain 的 AgentExecutor、Semantic Kernel、
OpenAI Agents SDK(2025 年 3 月)、Microsoft Agent Framework、Claude Agent SDK。
做法趋同到一个形状:循环由框架写,差异留在插槽里。
1.4 三种做法,三种代价
| 手写 while 循环 | 早期 AgentExecutor | 现代 Harness | |
|---|---|---|---|
| 起步成本 | 最低,几十行 | 低 | 低(配置为主) |
| 补全第八个设施时 | 开始重写自己的框架 | 受框架抽象限制 | 已内置 |
| 流式与并行调用 | 自己拼 | 部分支持 | 原生 |
| 可观测 | 自己打日志 | 需接回调 | 轨迹是一等公民 |
| 换模型 / 换 SDK | 改动集中在调用处 | 常被判例绑死 | 换 ChatClient 即可 |
| 真正的风险 | 越补越像劣质框架 | 抽象泄漏,行为不可控 | 配置错了不报错(见 3.3) |
结论不是「必须用框架」,而是:别把共性设施当业务写。框架提供机制,业务提供策略------这条分工是这一篇的主线。
1.5 三元结构:大脑、身体、地面
把这些缺口归一,会得到一个很朴素的分工:
flowchart LR A"Agent" --> M"Model\
推理 + 决定调用什么" A --> H"Harness\
工具 / 历史 / 步数 / 记录 / 压缩" H --> E"环境\
制度、数据、文档" M -.->|"只有大脑,没有手"| H
- Model 是大脑:会推理、会选工具,但没有手、没有记忆。
- Harness 是身体与边界:给它工具、给它历史、限制步数、记录它做过什么。
- 环境 是它站的地:公司制度、业务数据、知识文档。本篇按狭义口径把它放在 Harness 之外,只决定「够不够得着」;按广义定义(见 2.5),它同样属于 Harness。
把三者混在一起谈,结论只会是「模型不行」------这句话无法指导任何行动。
分开之后,问题立刻变得可处理:模型不行就换模型,够不着就加工具,越界就加护栏。
1.6 Harness 到底替你写了什么
把「工具循环」摊开,一个最小 Harness 的核心只有下面这段伪代码:
python
messages = load_history(session) + [user_message]
for step in range(max_steps):
ctx = inject_context(messages, session) # 技能 / 检索 / 压缩
response = model.chat(ctx, tools=registry) # 一次模型调用
if not response.tool_calls:
save_history(session, messages, response)
return response.text
results = execute_tools(response.tool_calls) # 并行或串行
messages += [response] + results # 工具结果回填
raise StepBudgetExceeded(max_steps)
看起来简单,但每一行在生产里都要长出分支:
load_history要按「用户消息轮次」裁,不能按消息条数裁,否则会把工具链切断;inject_context要在每次模型调用前跑,而不是每轮跑一次;execute_tools要处理异常、超时、并行、幂等,且把错误做成工具结果而不是抛出;results必须带callId与调用一一配对,否则模型会重复调用;save_history要在finally里执行,流式中途断开也要留下已发生的部分。
Harness 的价值不是省掉这个循环,而是把循环里那些「每样都要、每样都和业务无关」的分支写对。
二、它是什么
2.1 四组配置
以 MAF 的 HarnessAgentOptions 为例,几十个属性可以归成四组:
| 组 | 代表配置 | 作用 |
|---|---|---|
| 身份 | Id / Name / Description |
写进 Agent Card,供 A2A 发现 |
| 模型 | ChatOptions(Instructions / Tools / Temperature / MaxOutputTokens) |
真正的模型参数 |
| 上下文 | ChatHistoryProvider、AIContextProviders、HarnessInstructions |
核心:模型每次看到什么 |
| 裁剪与压缩 | 若干 DisableXxx、CompactionStrategy、MaxContextWindowTokens |
框架自带的通用能力,通常默认开启 |
配置项多不是问题,问题是默认值按「研究/编码型长任务」设计 :文件记忆、网页搜索、待办、计划模式默认开。
放到表单/订单场景,它们只会撑爆上下文、增加不可控行为。本项目的做法是显式关掉七项:
json
{
"Harness": {
"MaximumIterationsPerRequest": 8,
"MaxContextWindowTokens": 64000,
"DisableFileMemory": true,
"DisableWebSearch": true,
"DisableTodoProvider": true,
"DisableAgentModeProvider": true,
"DisableAgentSkillsProvider": true,
"DisableOpenTelemetry": true
}
}
这不是「配置洁癖」,而是把「Agent 能做什么」收窄到业务需要的范围。默认能力每多开一项,就多一个
「模型被无关上下文带偏」的机会。
2.2 三个插槽,决定了大部分工作量
任何 harness 都要回答三个位置的问题:历史从哪读、每次调用前补什么、装不下时怎么压 。
MAF 用下面三个接口暴露它们------名字是它的,位置是通用的:
| 插槽 | 框架默认 | 你可以替换成 | 真实接口语义 |
|---|---|---|---|
ChatHistoryProvider |
内存实现 | 数据库、Redis、按会话分片 | 读历史 + 写本轮;分区键决定两个 Agent 会不会串味 |
AIContextProviders |
空(Harness 会往里塞压缩器) | 技能索引、检索结果、用户画像 | 每次模型调用前执行,可增删消息 |
CompactionStrategy |
token 超限时压缩 | 滑动窗口、摘要、组合流水线 | 只作用于本轮运行累积的消息 |
理解这三者的分工,就理解了 Harness 的扩展模型:历史是一条线,上下文是每次调用前的补充,压缩是对这条线的瘦身。
三个插槽最容易混的是「历史」与「上下文」:历史是已经发生过的对话 ,上下文是这次调用前临时补进去的东西 。
把检索结果写进历史,会被当成「用户说过的话」永久保存;只放进上下文,下一次调用就消失。
本项目把技能索引放在 AIContextProviders,把对话放在 ChatHistoryProvider,就是为了让两者的生命周期不同。
2.3 它能做什么,不能做什么
| 能做 | 不做 |
|---|---|
| 工具循环、并行工具调用、最大步数限制 | 替你设计工具(工具边界是业务决策) |
| 历史读写、上下文注入、压缩 | 决定「业务上该不该做这件事」 |
| 流式输出、审批拦截、追踪埋点 | 保证结果正确(正确性要靠幂等与校验) |
| 统一多 Provider 的差异 | 替你写业务策略 |
一句话:Harness 提供机制,不提供策略。业务规则写进提示词与技能文档,硬约束写进工具与服务端校验。
工具从哪来,Harness 并不关心:可以是同进程的 AIFunction、MCP 接进来的外部工具,
也可以是 A2A 委托给另一个 Agent。对工具循环而言它们没有区别------差别在边界与失败怎么兜。
2.4 工具循环的四个工程细节
这一节是「能跑」与「跑得稳」的分水岭:
① 工具异常必须变成结果,不能抛出。
工具抛异常会直接打断循环,用户看到 500;正确做法是 catch 后返回一段结构化错误
({"ok":false,"code":"...","retryable":true}),让模型自己决定重试还是换路。
本项目所有工具都遵循这个约定,A2aEnvelope.Error 就是为此设计的。
② callId 必须配对。
模型一次可能发多个 tool_calls,每个带唯一 id;回填结果时必须带同一个 id。
少了或错了,模型会认为「这个工具没被调用」,于是重复调用------这正是「同一订单被查三次」的常见原因。
③ 步数预算计的是「模型调用轮数」,不是工具次数。
一轮模型调用可以并行发起多个工具。MaximumIterationsPerRequest = 8 意味着最多 8 次模型往返,
不是 8 个工具。把预算当「工具次数」调小,复杂任务会在中途被截断。
④ 并行工具调用要有确定的结果顺序。
模型要求并行时,结果按 callId 回填,不要按完成先后;否则同一批工具的返回顺序每次不同,
模型会把它当成「环境不稳定」。
2.5 广义与狭义:别把两套坐标混着用
同一个词在资料里有两种口径,读混了就会觉得互相打架:
| 口径 | Harness 指什么 | 出处 |
|---|---|---|
| 广义 | 模型之外的一切:提示词、工具、循环、状态、文件系统、沙箱、浏览器、权限 | Tian Pan《Anatomy of an Agent Harness》(2025-09)最早给出定义式表述;LangChain 同题文(2026-03)压成一句话:「如果你不是模型,你就是 Harness」 |
| 狭义 | 框架里那一层控制逻辑:工具循环、历史、上下文注入、压缩、hook、追踪、审批 | MAF 的 HarnessAgentOptions------本篇 2.1--2.4 拆的就是它;换框架,类名与默认值都不同 |
按部署视角,广义 Harness 还能再切三块,因为它们的失败方式与责任人不同:
| 层 | 管什么 | 坏了长什么样 |
|---|---|---|
| Harness(狭义) | 循环、上下文、追踪 | 决策错、上下文撑爆、轨迹重放 |
| Runtime | 进程、会话状态、持久化、超时 | 状态丢失、重启后把历史当新结果 |
| Sandbox | 隔离、权限、资源上限 | 越权写库、凭证泄露、资源跑飞 |
所以 Agent = Model + Harness 与 Agent = Model + Harness + Runtime + Sandbox 不是两个学派:
后者只是把前者的那一个大筐摊开,好让排障时知道该改提示词、改代码还是改部署。
本篇 1.5 的「环境」按狭义口径放在 Harness 之外;换到广义口径,它同样是 Harness 的一部分。
判据:谈设计用二分 (模型能力 vs 外围工程),谈上线用四分(谁运行、在哪运行、炸了归谁)。
三、运行机制
3.1 一次请求的顺序
sequenceDiagram autonumber participant U as 用户消息 participant H as ChatHistoryProvider participant P as AIContextProviders participant C as ChatClient 管线 participant M as 模型 participant T as 工具 U->>H: 读历史(可换成数据库实现) H->>P: 历史进入本轮上下文 P->>P: 技能索引 / 压缩器 / 检索结果 P->>C: 组装完成的消息 C->>M: 调用模型 M-->>C: 文本 或 工具调用 C->>T: 执行工具 T-->>C: 结果 C->>M: 带着工具结果再问(循环,受最大步数限制) C->>H: 本轮结束,落库
两个容易搞反的点:
① 历史先于上下文提供者。 上下文提供者看到的是「已经注入历史之后」的消息集合,所以它能看到历史、也能修改它。压缩器正是挂在 AIContextProviders 上,因此它每次模型调用前都会跑,而不只是每轮跑一次。
② 工具结果是循环内的消息,不是历史。 一轮任务里模型可能调用多次工具,这些中间消息都属于本轮;只有本轮结束才整体落库。这决定了「上下文膨胀」主要发生在工具循环里。
3.2 工具循环的时序(含失败分支)
sequenceDiagram autonumber participant H as Harness participant M as 模型 participant T as 工具注册表 M-->>H: tool_calls call_1, call_2 H->>T: 并行执行(各自带超时) T-->>H: call_1 成功 / call_2 抛异常 H->>H: 异常 → {"ok":false,"code":"TIMEOUT","retryable":true} H->>M: tool 消息(按 callId 配对) M-->>H: 下一轮:重试 call_2,或改用其它工具 H->>H: 超过 max_steps → 返回已完成的最后结果 + 明确错误
关键在最后一行:预算耗尽不是「静默失败」 。Harness 应当把「已经做了什么、卡在哪」交回去,
而不是让接口超时、前端无限转圈。这一步决定了用户看到的是「请稍后重试」还是「订单已创建,但支付未完成」。
3.3 三个典型的「开关陷阱」
这类问题不是某个项目特有,而是框架语义容易误解,值得单独记住:
| 直觉 | 实际 |
|---|---|
设了 MaxContextWindowTokens 就会按它压缩 |
一旦设置了 CompactionStrategy 或 DisableCompaction,该值被忽略 |
DisableAgentSkillsProvider = true 就关掉了技能 |
关的是框架内置那套;自己注入的提供者仍然生效 |
| 压缩会把历史裁短 | 压缩作用于「本轮运行累积的消息」,历史长度由历史窗口决定 |
判断方法只有一个:读源码或做对照实验。文档摘要写的是设计意图,行为取决于实现细节。
本项目的三条实测结论,都是被这三个陷阱打出来的:
- 压缩只管本轮,不裁历史。 连续 9 轮埋词测试,第 9 轮仍能答出第 1 轮埋的词------说明历史窗口没被压缩动过。
- 「记得多久」只由
MemoryOptions.ContextWindowTurns决定。 压缩解决的是「工具循环别撑爆」,不是长期记忆。 DisableAgentSkillsProvider关不掉自己注入的 Provider。 因为AIContextProviders是我们手动加的,框架的开关只管它内置那套。
3.4 上下文窗口到底怎么算
不要把「消息条数」当窗口。一次工具调用至少产生两条消息(assistant 的 tool_call + tool 的结果),
一条工具结果可能有几千 token。按条数裁,等于随机切断工具链。
本项目的 PersistentChatHistoryProvider 按「用户消息」裁轮:
text
历史:user1 assistant1(tool_call) tool1 assistant1'
user2 assistant2
user3 ...
窗口:取最近 N 个「用户消息」及其后的完整工具链
这样既保证「最近 N 轮完整」,又不会出现「只留下 tool 结果、没有对应的 tool_call」这种非法消息序列------
后者会让模型直接返回 400。这条规则在 docs/Harness记忆能力实现详解.md 里有完整的测试反证。
四、最小实践
4.1 场景
从零接一个「查订单」Agent:一个只读工具、一条历史、一个步数预算。先不接审批、不接压缩。
4.2 四步组装
csharp
var agent = chatClient
.AsHarnessAgent(options =>
{
// ① 身份:写进 Agent Card
options.Name = "OrderAgent";
options.Description = "订单业务";
// ② 模型:指令 + 工具 + 输出上限
options.ChatOptions.Instructions = systemPrompt;
options.ChatOptions.Tools = [queryOrder];
options.ChatOptions.MaxOutputTokens = 4000;
// ③ 上下文:历史从哪来、每次补什么
options.ChatHistoryProvider = persistentHistoryProvider;
options.AIContextProviders.Add(skillIndexProvider);
// ④ 边界:步数与压缩
options.MaximumIterationsPerRequest = 8;
options.CompactionStrategy = CompactionStrategy.ContextWindow(64_000);
});
接入顺序建议 :先只开「工具 + 历史」,跑通一条真实任务;再逐步加压缩、审批、追踪。
一次全开的结果是------出问题时不知道是哪一层导致的。
4.3 跑起来并观察
bash
T=$(curl -s --noproxy '*' -X POST http://localhost:5210/api/identity/anonymous \
| python -c "import sys,json;print(json.load(sys.stdin)['ticket'])")
curl -s --noproxy '*' -N -X POST http://localhost:5210/api/chat \
-H 'Content-Type: application/json' \
-d "{\"message\":\"查一下订单 SO202505180001\",\"sessionId\":\"$T\"}" \
--max-time 180 | tail -5
看三处,而不是只看回复:
bash
curl -s --noproxy '*' "http://localhost:5210/api/trace?sessionId=$T" \
| python -m json.tool | head -60
ModelCall:模型调用几次、输入多少条消息、耗时;ToolCall/ToolResult:工具名、参数、结果是否配对;Error/GuardrailBlocked:失败与拦截各几次。
本项目的真实轨迹长这样(正常一轮):
text
用户输入
调用大模型:返回 0 字符|上下文 1 条消息|1200ms
调用工具 query_order:{"orderId":"SO..."}
query_order 返回结果:...
调用大模型:返回 236 字符|上下文 3 条消息|1800ms
「第一次模型调用返回 0 字符」不是故障------它把内容都放在 tool_call 里了。
判断标准是工具是否被调用、第二次模型调用是否拿到结果,而不是第一段文本长度。
4.4 三个真实失败与排查顺序
| 现象 | 根因 | 先查 |
|---|---|---|
| 模型重复调同一个工具 | callId 没配对,模型认为结果没回来 |
ToolResult 的 callId 与 ToolCall 是否一致 |
| 第二轮对话失忆 | 历史 Provider 没落库,或分区键写错 | ConversationTurns 是否有本轮记录;分区名是否一致 |
| 长任务第 5 步突然 400 | 上下文超限,或裁出了「孤立的 tool 消息」 | 窗口按用户消息裁;工具结果大小;压缩是否只在本轮生效 |
| 工具一异常就 500 | 工具把异常抛给了循环 | 工具是否 catch 并返回结构化错误 |
五、边界与取舍
| 取舍 | 说明 |
|---|---|
| 框架默认全开,需要主动裁剪 | 文件记忆、Web 搜索、待办、技能等默认能力会带来额外 token 与不可控行为;不用就显式关掉 |
| 压缩不是「记得更久」 | 它解决的是「别撑爆上下文」,不是长期记忆;记忆要靠历史存储与画像 |
| 步数上限是安全阀,不是性能开关 | 调小会让复杂任务半途而废,调大只是给它更多机会绕圈;配日志才能判断 |
| 不要绕过 Harness 直接调模型 | 绕过就失去工具循环、审批、追踪,后面每加一个能力都要重写一遍 |
| Harness 不保证正确性 | 金额、状态、权限、幂等必须由业务代码兜底;Harness 只保证「循环跑得下去」 |
一个常见的架构误判:把「Agent 答错了」归因于 Harness。实际上要分三层看:
- 模型层:它有没有理解意图、选对工具?------换模型 / 改提示词;
- Harness 层:工具结果有没有回填、历史有没有带上、预算够不够?------看 trace;
- 业务层:工具本身算得对不对、权限有没有校验?------看单测与护栏。
本项目的 run 0e719501 是一个典型:轨迹显示「模型 ×1、工具 ×0、返回 0 字符、11 秒」,
看起来像模型坏了,实际是 LLM 出站被系统代理拦截,请求根本没发出去。先看 trace,再怀疑模型。
六、小结
- Harness 存在的理由:模型只有大脑,工具、循环、历史、边界必须由运行时补上。
- 它的扩展模型是三插槽------历史、上下文、压缩;业务差异不在这三者里,而在工具与策略里。
- 工具循环的稳定性取决于四个细节:异常变结果、callId 配对、预算按轮计、并行结果有序。
- 用框架的前提是知道它到底做了什么:默认值、互斥开关、失效条件,都要以源码或实验为准。
在线体验:http://117.72.72.215:5210
先在左下角「⚙ 设置」里填自己的模型,再让它下一单试试------工具循环、步数预算、审批拦截都能在页面上看到。