Harness:把裸模型变成能用的 Agent

02 · Harness:把裸模型变成能用的 Agent

读完你会知道:

  1. 为什么「会聊天」和「能干活」是两件事,Harness 具体补的是哪一段;
  2. Harness 的四组配置、三个插槽分别控制什么,接口语义是什么;
  3. 一次请求的真实顺序:历史、上下文提供者、模型、工具循环各在什么位置;
  4. 工具循环的工程细节------并行调用、异常回填、步数预算、callId 配对;
  5. 框架自带能力的边界:哪些开关会互相覆盖,哪些「关掉」其实关不掉。
    三句话版本
  • 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 就关掉了技能 关的是框架内置那套;自己注入的提供者仍然生效
压缩会把历史裁短 压缩作用于「本轮运行累积的消息」,历史长度由历史窗口决定

判断方法只有一个:读源码或做对照实验。文档摘要写的是设计意图,行为取决于实现细节。

本项目的三条实测结论,都是被这三个陷阱打出来的:

  1. 压缩只管本轮,不裁历史。 连续 9 轮埋词测试,第 9 轮仍能答出第 1 轮埋的词------说明历史窗口没被压缩动过。
  2. 「记得多久」只由 MemoryOptions.ContextWindowTurns 决定。 压缩解决的是「工具循环别撑爆」,不是长期记忆。
  3. 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。实际上要分三层看:

  1. 模型层:它有没有理解意图、选对工具?------换模型 / 改提示词;
  2. Harness 层:工具结果有没有回填、历史有没有带上、预算够不够?------看 trace;
  3. 业务层:工具本身算得对不对、权限有没有校验?------看单测与护栏。

本项目的 run 0e719501 是一个典型:轨迹显示「模型 ×1、工具 ×0、返回 0 字符、11 秒」,

看起来像模型坏了,实际是 LLM 出站被系统代理拦截,请求根本没发出去。先看 trace,再怀疑模型。


六、小结

  • Harness 存在的理由:模型只有大脑,工具、循环、历史、边界必须由运行时补上。
  • 它的扩展模型是三插槽------历史、上下文、压缩;业务差异不在这三者里,而在工具与策略里。
  • 工具循环的稳定性取决于四个细节:异常变结果、callId 配对、预算按轮计、并行结果有序。
  • 用框架的前提是知道它到底做了什么:默认值、互斥开关、失效条件,都要以源码或实验为准。

在线体验:http://117.72.72.215:5210

先在左下角「⚙ 设置」里填自己的模型,再让它下一单试试------工具循环、步数预算、审批拦截都能在页面上看到。

相关推荐
学无止境小袁同学13 小时前
LangGraph 深度指南
语言模型·框架·agent·并发·上下文·langgraph·长期记忆
Cosolar14 小时前
2026 年 Java AI Agent 生态全景盘点:50+ Java 开源项目的分类、实测与选型判断
人工智能·架构·agent
张一凡9316 小时前
你的 AGENTS.md,真的管到模型写代码了吗?
前端·后端·agent
qinglongcn16 小时前
怎么让 200 轮的长任务不崩——三层保全策略
agent·ai编程
数字工作台16 小时前
给 LangGraph 加一道可审计记忆:替换默认 Checkpointer,实现防篡改 + 崩溃不丢数据
python·agent
阿里云大数据AI技术16 小时前
如何用 STAROps Elasticsearch 智能助手看穿“搜索变慢”
人工智能·agent
小七-七牛开发者17 小时前
Anthropic:Agent 不必一直运行,也能持续工作
agent·claude·deepseek·anthropic·alwaysonagent
xyphf_和派孔明19 小时前
第十章: Agent Skill的调用机制解读
langchain·llm·agent
Csvn20 小时前
所有问题都喂最贵的模型?规则路由实测:30 个问题里 16 个能交给便宜模型(C03)
人工智能·aigc·agent