最近半年，我接手的项目里有好几个都与 Agent 相关。和很多人一样，第一次做出单轮 Agent demo 的时候是真的很兴奋，效果惊艳，但一旦进入多工具、多步骤的真实任务就开始翻车：prompt 从 2K 膨胀到 20K，模型却越来越"笨"；任务循环偶尔卡死，日志里只有一句"正在思考…"；工具调用链一断，整个任务白跑。折腾了几个月，我终于慢慢想明白一件事：高效 Agents 的尽头，确实是 Harness——一个能把模型放对位置、让执行过程变得稳定的框架。这篇文章就聊聊我踩过的坑，以及我最终是怎么把一个"裸写 Agent"一步一步改造出 Harness 的。
1. 先聊清楚：Agent 到底在解决什么问题
很多人上来就写 Agent，但从来没认真想过"Agent 是什么、为什么需要它"。不把这个想清楚，后面写 Harness 也只是套模板。
1.1 一个 Agent 的"第一性原理"拆解
我习惯把 Agent 拆成四部分来看：
- 决策器：也就是大模型本体，负责理解目标、选择下一步动作。
- 执行器：工具/函数，负责真正干活，比如查数据库、调接口、发消息。
- 记忆体：上下文窗口，负责装下用户目标、历史对话、工具返回结果。
- 控制流：循环逻辑，负责决定"什么时候再想、什么时候再干、什么时候结束"。
这四个部分合在一起，形成一个闭环：拿到目标 -> 读取记忆 -> 模型决策 -> 调用工具 -> 观察结果 -> 更新记忆 -> 再决策……直到判定完成。
你可以把模型当成"脑子"，工具当成"手"，上下文当成"工作台"，控制流当成"行动节奏"。缺了任何一个，都不能叫 Agent，只能叫"接口调用"或者"聊天机器人"。
单轮问答为什么简单？因为它只用到了决策器和记忆体，一次决策就结束了。多步任务为什么难？因为控制流和执行器一旦参与进来，整个系统的复杂度和出错概率就指数级上升。
1.2 为什么真实任务必须用 Agent，而不是"多写几个 if else"
有人说，传统程序也能编排工具，为什么非要让模型来决策？这个问题的答案，恰恰是 Agent 存在的价值。
真实任务有一个特点：非结构化。比如用户说"帮我查一下上周的订单，如果有超时的就发个提醒，再统计一下超时率"。你没法提前用 if else 把所有分支写死，因为订单数量、超时状态、提醒方式都可能变化，甚至用户的语言本身就有歧义。
Agent 做的事是把"决策权"交给模型：让模型根据实际情况，动态拼装出"查订单 -> 过滤超时 -> 发提醒 -> 算统计"这样一条执行链。模型的灵活性强，但代价是"失控风险"也来了——模型规划可能不合理，工具可能超时，返回的数据可能不符合预期。
所以你会发现，真正难的不是让模型"想出来"，而是让这套"想法"可靠地变成"行动"。这就需要一个壳来兜底，也就是 Harness 出场的必然性。
1.3 "会写模型调用"不等于"会写 Agent"
我见过太多人（包括最初的我），写的第一版 Agent 大概是这个套路：
def run(user_input): messages = [system_prompt, {"role": "user", "content": user_input}] while True: resp = llm.chat(messages, tools=tool_schemas) if resp.tool_call: result = execute_tool(resp.tool_call) messages.append(resp.message) messages.append({"role": "tool", "content": result}) continue return resp.content这段代码 demo 完全能跑，但它只能叫"模型交互脚本"，不叫 Agent 系统。
差别在于：脚本假设一切顺利，系统假设一切会出错。脚本没有最大步数，模型反复调用同一个工具也不会被中断；脚本没有状态保存，进程一崩就前功尽弃；脚本没有错误恢复，工具返回异常数据模型照样把它当前提；脚本没有上下文管理，跑十几轮之后 token 直接爆掉。
所以"会写模型调用"只是入门，真正的 Agent 工程是在模型外面搭建一个完整的执行环境。这个环境，就是 Harness。
2. 为什么说"高效 Agents 的尽头是 Harness"
如果你去翻社区里各种 Agent 项目，会发现一个很有意思的现象：做得越久的人，越强调框架和执行壳；刚上手的人，则更关注模型选型和 prompt 技巧。原因很简单——模型选型和 prompt 只能帮你"想得更好"，但真正决定 Agent 能不能稳定跑完任务的，是执行层。
2.1 Harness 到底是个什么东西
Harness 这个词，直译是"马具、挽具"，在 Agent 语境里我更愿意把它理解成"装配壳"或"执行框架"。它的核心职责是围绕模型推理循环，搭建一套运行时的控制层。
具体到我自己的实践，Harness 至少要做这些事：
- 定义循环的节奏：什么时候让模型思考，什么时候调用工具，什么时候收尾。
- 管理状态：记录 Agent 当前走到哪一步、已完成什么、还差什么。
- 维护工具注册表：所有工具统一登记、校验、调用，不允许模型"凭空发明工具"。
- 控制上下文预算：让模型始终看到该看的信息，而不是被历史淹没。
- 处理异常与恢复：重试、降级、回退、中断，不让单点故障毁掉整个任务。
- 输出可观测日志：每步都留痕，方便回放和定位问题。
把模型比作引擎，Harness 就是底盘和变速箱。引擎再猛，没有底盘和变速箱，车也只能原地打转。现实就是：模型能力已经很强了，大多数 Agent 项目效果不行，问题都出在"底盘"上。
2.2 不写 Harness，裸写循环的四个灾难
我第一版裸写 Agent 跑了一个月，总结出四个最典型的灾难，几乎每个都遇到过。
第一，prompt 膨胀。工具描述、历史对话、任务规则、中间结果全塞在一个超长字符串里。token 成本翻倍先不说，关键是模型根本"看不过来"：工具列表太长的时候，排在后面的工具会被模型无意识忽略；历史太长的时候，最新的工具返回也被稀释。我用过一个 16K 上下文的模型跑任务，塞到 12K 之后，它开始频繁忘记调用最后注册的两个工具。
第二，循环失控。没有最大步数上限的裸循环，会出现很滑稽的情况：模型认为"需要调用库存接口"，接口返回了库存不足，它还是坚持再调一次库存接口，连续调了十几次，没有终止策略，最后还是我手动 kill 掉的。模型不是故意偷懒，是它的决策逻辑里缺少"放弃当前策略、换个思路"的触发条件。
第三，上下文污染。工具的一次错误返回被 append 进 messages 之后，后续所有轮次都把这个错误数据当成事实。比如某个订单查询接口临时返回了空列表，模型就基于"没有订单"继续规划，整个任务方向直接跑偏，而且越偏越远，很难回溯。
第四，失败不可恢复。网络超时、模型返回非法 JSON、工具抛异常，任何一个小问题都让整个任务白跑。没有检查点、没有状态快照，用户只能重新发起一次任务。这在真实场景里是完全不可接受的。
这四个问题，用 Harness 都能在结构上解决掉，而不是靠"再写几句 prompt 提示一下"糊弄过去。
2.3 为什么说"回归 Harness"是大方向
我自己的感受是，当出现下面几个信号时，你就该上 Harness 了：
- 优化 prompt 已经解决不了稳定性问题；
- 你开始频繁在日志里搜"为什么模型又调了 xxx 工具"；
- 上下文 token 用量按天翻倍；
- 线上任务时不时卡死，但本地复现不出来。
这些事情背后的共同本质是：你试图用"模型自身的智能"去兜住"执行过程的混乱"，而模型根本不擅长兜底。它的强项是生成，不是纪律。
所以"尽头是 Harness"不是说必须用某一个特定的框架，而是说"把执行过程框架化"这件事，是所有高效 Agent 的必由之路。你可以自己写，也可以用社区方案，但那份控制逻辑必须存在。
3. 我的 Harness 设计：六个核心模块与取舍
下面这部分是我自己踩坑踩出来的设计，不一定适合所有场景，但大方向我认为是通用的。我按"任务循环 -> 状态机 -> 工具注册表 -> 上下文管理 -> 错误恢复 -> 可观测性"的顺序逐个说。
3.1 任务循环：给 Agent 一个明确的"下班"判断
任务循环是整个 Harness 的心脏。不用设计得很花哨，但三要素必须有：起点、步进、终点。
def run_agent(harness, user_request): state = harness.create_initial_state(user_request) while not state.is_finished(): action = harness.decide(state) # 模型决策 if action.is_final_answer(): state.finish(action.answer) break observation = harness.invoke_tool(action) # 执行工具 state.record(action, observation) # 更新状态 harness.checkpoint(state) # 落检查点 return state.final_answer()这个循环看起来简单，真正要注意的是终点的设置。我一般会设四种终点：
- 模型给出最终答案，正常完成；
- 达到最大步数，强制结束并提示"任务未完成"；
- 用户主动中断；
- 发生不可恢复异常，进入人工处理通道。
最大步数怎么定？我踩过的经验是：纯对话型任务给 5 步，工具型任务给 10-15 步，涉及时序编排的复杂任务最多给 25 步。定太小容易误伤正常任务，定太大又会让错误任务浪费大量 token。先给一个宽松值，然后根据日志里的步数分布逐步收紧，这样最稳。
3.2 状态机：让每一步都有"户口"
Agent 在任务执行中会经历多个阶段，如果没有状态机，整个执行过程就像一匹没戴笼头的马。我用一个简单的枚举来定义状态：
from enum import Enum class AgentState(Enum): START = "start" PLANNING = "planning" TOOL_CALL = "tool_call" OBSERVING = "observing" INTERRUPTED = "interrupted" FINISHED = "finished"然后定义允许的状态转移，比如：
- START 只能进入 PLANNING；
- PLANNING 可以进入 TOOL_CALL 或者 FINISHED；
- TOOL_CALL 执行失败且无法恢复时进入 INTERRUPTED；
- OBSERVING 收集完结果之后回到 PLANNING。
状态机的价值在于：模型仍然输出它想输出的内容，但 Harness 只允许在合法转移路径上推进。一旦模型试图做非法转移，比如在 TOOL_CALL 阶段突然给出最终答案，框架可以选择拦下来，要求模型先完成工具调用。这就是"可控性"的来源。
有人觉得状态机是多余的约束，会限制模型的灵活性。实际不是。状态机约束的是"执行框架的流程"，而不是"模型的思考内容"。模型依然可以在 PLANNING 状态自由思考策略，只是它不能跳过工具调用直接编结果。
3.3 工具注册表：给 Agent 装上"白名单"
裸写 Agent 有个很大的隐患：模型可能会输出一个并不存在的工具名，或者给已有的工具传一个完全不合法的参数。我用一个工具注册表来解决这个问题。
class ToolRegistry: def __init__(self): self._tools = {} def register(self, name, fn, schema): self._tools[name] = {"fn": fn, "schema": schema} def list_schemas(self): return [t["schema"] for t in self._tools.values()] def call(self, name, args): if name not in self._tools: raise ValueError(f"unknown tool: {name}") validate_args(args, self._tools[name]["schema"]) return self._tools[name]["fn"](**args)注册表里每个工具存储这些信息：函数名、函数本体、参数 JSON Schema、返回类型、副作用级别（只读/写操作/高权限）。模型能看到的是 schema 列表，但实际调用会经过注册表校验。
这里有两个容易忽略的细节。第一，参数校验一定要做。模型偶尔会把字符串数字传成 int，或者漏传必填字段，如果直接让这些参数传到业务接口，会引发很难排查的线上问题。第二，工具列表要控制数量。我试过一次性注册 20 个工具，模型决策质量明显下降；后来通过合并相似工具、精简描述，把数量控制在 8-10 个，效果立刻提升。
3.4 上下文管理：控制模型看的"窗口"
这是 Harness 里性价比最高、也最容易被忽略的模块。模型不是读得越多越聪明，而是读得越乱越糊涂。
我用的策略是"预算 + 压缩 + 保护"三层配合。
预算是给不同内容分配上下文份额。一个参考配置：
| 内容类型 | 预算占比 | 说明 |
|---|---|---|
| 系统指令与用户目标 | 20% | 不可压缩，始终完整保留 |
| 工具描述 | 25% | 可做 LRU 缓存，高频工具优先保留 |
| 最近对话与执行过程 | 40% | 完整的原始细节 |
| 历史摘要 | 15% | 只保留压缩后的摘要 |
压缩策略我试过两种，一种是滑窗截断，简单但会丢失关键中间结果；另一种是摘要压缩，让模型把旧过程压缩成几条事实，但压缩本身也有 token 成本和失真风险。最终我采用的是"混合式"：最近两轮对话完整保留，更早的内容一律摘要化，每轮摘要只保留"动作、结论、残余风险"三要素。
关键的保护字段包括：用户原始目标、已经完成的关键操作列表、当前待办事项。这三个字段我会单独存到 state 里，每次模型决策前拼到系统消息头部。这样即使历史压缩得再狠，Agent 也不会忘记自己为什么在这儿、已经干了什么、还差什么。
3.5 错误恢复与重试：让任务"经得起折腾"
任务跑着跑着，一定会遇到错误。Harness 的价值在于把错误分门别类处理，而不是一棍子打死。
我整理了一个分层策略：
- 瞬时网络错误：指数退避重试，最多 3 次，退避间隔 1 秒、2 秒、4 秒。
- 工具业务异常：把异常信息作为观测结果反馈给模型，让它重新规划，最多允许 2 次修正。
- 模型输出格式非法：重新引导，提示"请严格按 JSON 格式输出"，最多 2 次。
- 业务规则冲突：不自动重试，直接进入"等待人工确认"的中间状态。
代码上最核心的一点：重试逻辑要统一放在 Harness 层，而不是散落在各个工具函数里。因为如果每个工具自己都做重试，一个上游接口超时会收到来自多个工具的并发重试请求，流量直接放大。统一管理之后，我能在 Harness 入口处做全局熔断和限流，从根上避免这个问题。
3.6 可观测性：没有日志，一切都是玄学
排过 Agent 故障的人应该都有这种绝望感：Agent 跑错了，但说不清它是从哪一步开始错的。所以 Harness 必须输出结构化日志。
我的做法是：每一步决策都记录一条 JSON Line，字段包括 step_id、当前状态、模型输出原始文本、解析后的 action、工具名、工具参数、观测结果摘要、token 消耗、耗时、是否有异常。
{ "step_id": 7, "state": "tool_call", "model_output": "{\"action\": \"query_order\", \"args\": {\"order_id\": \"A123\"}}", "tool_name": "query_order", "tool_args": {"order_id": "A123"}, "observation_summary": "order found, status=delayed", "token_cost": 1250, "latency_ms": 830, "error": null }这些日志不仅是排障工具，还是优化依据。我经常通过日志统计发现："模型总是第 4 步绕一次弯路"或者"某工具描述导致模型在 3 个相似工具间反复横跳"，然后针对性改进工具描述或状态转移规则。没有日志，这些优化全凭玄学。
4. 实操记录：把一个裸写 Agent 改造成 Harness
理论说了这么多，落地的过程反而最值得写。我拿一个实际项目来复盘：一个工单处理 Agent，需要完成查订单、查库存、计算超时、发提醒、生成总结这个链路。我经历了三版改造。
4.1 第一版：那个"能跑但不敢用"的 Demo
第一版代码特别简单，逻辑就是裸的 while 循环加 function calling，和前面贴的 demo 几乎一样。跑单轮演示没问题，但放到真实环境里跑了几天，问题全冒出来了。
最典型的一个场景：模型为了判断订单是否超时，需要先调"查订单"工具拿到订单列表，再逐个调"查订单详情"。但模型经常在拿到列表之后，不调详情，直接开始生成"超时分析总结"，数字全靠编。原因就是工具返回列表太长，塞进上下文中后，模型被大量干扰信息淹没，忽略了"还需要查详情"这个关键步骤。
这一版还出现过一次严重事故：模型调用"发提醒"工具时传错了消息模板编号，给用户发了一条风马牛不相及的通知。因为没有参数校验，这个错误直接传到了业务层。从那以后我下定决心，必须上完整的 Harness。
4.2 第二版：先上状态机和工具注册表
第二版改造不追求一步到位，先把状态机和工具注册表接进来。
class Harness: def __init__(self, registry, llm): self.registry = registry self.llm = llm self.state = AgentState.START self.steps = [] self.max_steps = 15 def decide(self, messages): return self.llm.chat(messages, tools=self.registry.list_schemas()) def step(self, user_input): if self.state == AgentState.START: self.state = AgentState.PLANNING action = self.decide(self.build_messages(user_input)) if action.is_final_answer(): self.state = AgentState.FINISHED return action.answer if self.state in (AgentState.PLANNING, AgentState.OBSERVING): self.state = AgentState.TOOL_CALL observation = self.registry.call(action.tool, action.args) self.state = AgentState.OBSERVING self.steps.append((action, observation)) if len(self.steps) >= self.max_steps: self.state = AgentState.INTERRUPTED return "max steps reached" return None这一版上线后，最直接的变化是：工具调用不能再"随意发明"了，所有参数都经过 schema 校验，非法调用会在 Harness 层被拦下，并给模型反馈一条错误提示。之前那种"模型传错消息模板编号"的事故，从产品侧彻底消失了。
但因为状态机只做了大阶段划分，上下文还是裸奔的，所以任务跑到七八步之后，token 依然会爆，模型依然会迷失。
4.3 第三版：上下文压缩与回溯恢复
第三版做了两个关键升级：一是上下文预算和摘要压缩，二是检查点与回溯恢复。
上下文压缩的核心代码如下：
def build_messages(self, state): system = state.system_prompt() # 系统指令+用户目标，20% tool_desc = self._tool_desc_budget() # 工具描述，25% recent = state.recent_steps(2) # 最近两轮完整内容 summary = state.history_summary() # 更早过程的摘要 messages = [ {"role": "system", "content": system}, {"role": "system", "content": tool_desc}, ] messages += recent messages.insert(-1, {"role": "system", "content": f"早期过程摘要：{summary}"}) return messages摘要不是每次都重新生成，而是每新增 5 步才触发一次摘要更新，然后把旧的原始步骤从状态列表里移除。我之前试过每步都压缩，token 省了一点，但压缩成本反而让总延迟变高，得不偿失。
检查点与回溯的方式是：每次工具调用完成后，把状态序列化到本地文件。
class Checkpoint: def __init__(self, path): self.path = path def save(self, state): payload = { "state": state.name, "steps": state.steps, "user_goal": state.user_goal, "pending_action": state.pending_action, } with open(self.path, "w", encoding="utf-8") as f: json.dump(payload, f, ensure_ascii=False, indent=2) def load(self): with open(self.path, "r", encoding="utf-8") as f: return json.load(f)这里有一个我踩过的坑：检查点只保存 messages 是不够的，必须把状态机阶段、用户目标、待执行动作都存下来。否则进程恢复后，Agent 虽然记着历史对话，但不知道自己该从哪个状态继续，只能从头开始跑，检查点等于白设。
4.4 改造前后的实测数据对比
模拟项目 X 里，我用相同的 120 条测试任务，分别跑了三个版本，记录的数据如下：
| 指标 | 第一版裸写 | 第二版状态机 | 第三版完整 Harness |
|---|---|---|---|
| 任务成功率 | 52% | 71% | 94% |
| 平均完成步数 | 12.3 | 9.6 | 7.8 |
| 峰值上下文 token | 28.6K | 22.4K | 11.2K |
| 单任务平均耗时 | 210s | 145s | 96s |
| 排障平均耗时 | 约 2 小时 | 约 40 分钟 | 约 15 分钟 |
数据本身不惊人，但它验证了一个朴素的结论：大部分收益不是来自模型变聪明，而是来自执行框架把无效浪费和错误决策拦截掉了。任务成功率从 52% 到 94%，靠的不是换更好的模型，而是让模型在正确的时间看到正确的信息，并且在出错时能被拉回来。
5. 常见问题与排查技巧实录
Harness 不是装上就万事大吉，运行过程中还是会遇到一堆奇怪的问题。这一节把我印象最深的几个案例和排查思路整理出来。
5.1 典型问题速查表
| 现象 | 可能根因 | 建议解法 |
|---|---|---|
| Agent 不调用工具，直接编答案 | 工具描述过于抽象，或工具列表太长被忽略 | 精简工具数量，每个工具补充"适用场景"和"不适用场景" |
| 循环卡在同一个工具调用上 | 缺少结果去重和步数上限 | 增加结果指纹判断，重复输出时打断并引导换策略 |
| 上下文 token 爆炸 | 历史没有压缩，中间结果全部堆积 | 引入摘要压缩和预算管理 |
| 恢复检查点后状态对不上 | 检查点只存了消息没存状态机 | 检查点必须包含状态枚举、用户目标、待执行动作 |
| 模型传参格式错误 | 缺少 schema 校验 | 增加参数校验，错误时向模型返回明确提示 |
| 重试导致上游接口被打爆 | 工具内部各自重试，流量放大 | 重试统一收敛到 Harness 层，加指数退避和熔断 |
5.2 三个印象深刻的翻车现场
案例一：工具描述太"花"，模型反复调错工具。我的 Agent 里有一个"查询订单状态"和"查询订单历史"两个工具，描述写得差不多，模型经常在应该查"历史"的时候去调"状态"，然后得到错误字段，再绕一大圈。后来我给每个工具补了一段"适用场景"说明，并附上典型调用示例，问题立刻缓解。工具描述写清楚使用边界，比让模型"多想一下"靠谱得多。
案例二：摘要压缩把任务目标给弄丢了。有一版压缩逻辑把用户最初的目标"退款订单处理"压成了一行平淡的事实，导致 Agent 在后续步骤里开始自发地做"重新下单"而不是"退款"。排查了很久才发现是摘要模块把关键目标给扭曲了。后来我把"用户目标"单独拿出来，作为保护字段每轮都拼进系统消息，绝不让它进入压缩池。这是很重要的经验：压缩可以压过程，但不能压目标。
案例三：重试逻辑把上游接口打爆。库存服务偶尔超时，我在工具函数内部加了重试，加上 Harness 层的异常反馈重试，结果一次超时引发了 6 次甚至 12 次请求，把上游系统压得直接雪崩。后来我把所有重试逻辑统一收编到 Harness 的调度层，同一工具调用最多重试 2 次，并且使用指数退避，问题彻底解决。教训是：重试是全局策略问题，不是单个工具的内部实现问题。
最后分享一点个人体会
折腾了大半年 Harness，我的结论不是在推崇某个具体框架，而是想清楚了一个优先级：做高效 Agents，先求稳，再求省，最后求快。模型的能力决定 Agent 的能力上限，但 Harness 决定你能不能稳定地够到这个上限。模型再强，执行过程一团糟，最终产出依然不可用。
再分享一个小技巧：如果你每天要跑大量 Agent 任务，建议把每次运行的完整轨迹都保存下来。等模型升级之后，把历史轨迹批量回放一遍，成本很低，收获却很大——你会清楚地看到，哪些步骤其实根本不需要模型"思考"那么多次，哪些工具描述可以进一步收敛。这种基于真实轨道的优化，比凭感觉调 prompt 高效太多。
)
