你的 Agent 在一次查询上刷了 38 美元账单——不是因为完成了多复杂的活儿，而是把同一份文档来回总结了 47 次。没有报错，没有告警，只是陷入了空转循环，账单一路走高。

你翻模型日志，发现模型表现符合预期。问题根本不在模型，而在包裹它的那一层：没有状态，没有停止条件，没有“我们来过这儿了”的记忆。这正是漂亮 demo 与可用生产之间的巨大缝隙。

下面这份实操指南，讲清楚把 AI Agent 从“能跑一次”变成“长期可靠”的 7 个关键 Harness 组件。

没人提前告诉你的鸿沟

做一个能跑通一次的 Agent，很容易：调个 LLM，挂几把工具，写个循环，二十来行 Python，录个演示，干净利落。

一上到生产，问题才开始真实发生：

• 用户输入超出预期；某个 tool 返回空；40 分钟后上下文塞满；两个子 Agent 相互打架；模型对某一步无限重试……
• 这些在 demo 里不可见的坑，在生产里都会变成事故。

问题多半不在模型质量，而在 Harness 质量。没有 Harness 的模型像没有神经系统的大脑：会“想”，但动不了，或者动错。

Agent = Model + Harness

Agent = Model + Harness

• Model → 推理、语言、决策
• Harness → 让模型可靠行动所需的一切

如果你没在训练模型，那你就在做 Harness。Harness 是包裹模型的所有代码、配置与执行钩子，它把“文本生成器”变成“能完成工作”的系统：模型决定做什么，Harness 确保它安全、可复现、可扩展地做到。

大多数工程师把 90% 时间花在“换提示词、换模型、加示例”上，而生产失败几乎都来自他们忽略的那 10%。那 10% 是 Harness。

7 个真正重要的组件

1. 控制循环（Control Loop）

循环是 Agent 的心跳。没有循环，你只有一次调用和一次回复——那是 Chatbot，不是 Agent。控制循环要负责：

• 运行模型 → 读取结果 → 执行工具 → 把结果回灌 → 重复
• 直到模型给出最终答案，或触发步数上限

while agent_is_running:
    response = call_model(context)

    if response.has_tool_calls:
        results = execute_tools(response.tool_calls)
        append_to_context(results)
        continue

    if response.is_final_answer:
        return response.content

    if step_count >= MAX_STEPS:
        return "Task incomplete. Max steps reached."

MAX_STEPS 不是可选项。它是“乖巧 Agent”与“38 美元事故”之间的分界线——在写任何一个 tool 之前就加上它。

一个糟糕的循环比没有循环更糟：没有停止条件、没有状态跟踪、不能识别重复工具调用，模型就可能在已完成的任务上无限自转。

2. 状态管理（State Management）

模型天生无状态，每次 API 调用都是从零开始。如果 Harness 不显式跟踪，Agent 就不会记得“做过什么、哪里成功、停在哪”。你需要两类 state：

• Session state：会话内的历史、工具结果、当前 step 编号
• Persistent state：跨会话保留的进度、完成的子任务、已处理文件

最简单可用的生产级 state 存储：一个 JSON 文件。可读、可调试、进程重启不丢，还不依赖额外基础设施。

{
  "task_id": "refactor-auth-module",
  "completed_files": ["auth.py", "middleware.py"],
  "pending_files": ["routes.py", "tests/test_auth.py"],
  "current_step": 3
}

对跨大型代码库作业的 Coding Agent，这个文件决定它能否持续向前——没有它，Agent 每一轮都可能反复改同一个文件。再叠加 Git 的版本化：跟踪进度、回滚错误、分支实验。

3. 记忆（Memory）

State 记录“这次会话做了什么”；Memory 记录“它跨会话知道什么”。

• 短期记忆：对话历史 + 工具调用及其结果。实现便宜，但不管理成本极高——历史增长会推高 token 费用，性能在撞上硬上限前就开始下滑。
• 长期记忆：比如 Coding Agent 记得你偏好显式错误处理，客服 Agent 记得某客户上周有账单问题。常用做法是向量库语义检索，或在事实具体时用结构化存储。

一个实用的生产流程：

1. 会话开始：加载 AGENTS.md 或项目记忆文件 → 注入 system prompt
2. 会话开始：按当前任务检索相关记忆 → 作为上下文补充
3. 会话中：维护滚动的对话历史
4. 会话结束：总结关键学习 → 写入记忆库

这些动作由 Harness 负责（1、2、4）。模型不会自行管理记忆。没有长期记忆，Agent 每次都要从头学习上下文，用户会感觉它“忘记人”，信任会流失——这不是模型问题，是 Harness 问题。

注：system prompt 指系统级指令；context 和 context window 指传给模型的可见信息及其窗口大小。

4. 工具与 bash 应急通道（Tools & the Bash Escape Hatch）

工具让语言变成行动。工具数量不如工具设计重要：每多一个工具描述，就多占上下文，还增加误用概率。三个描述清晰的工具，胜过十五个模糊的。

优秀工具描述要回答这三件事：

• 它到底做什么？
• 什么情况下必须用它（不只是“可以用”）？
• 它会产出什么样的输出，以便判断是否成功？

bash 应急通道是能力版图的拐点。与其穷举所有工具，不如给 Agent 受限访问 bash 的能力，让它临时写出需要的工具——这正是 Claude Code 处理开放式任务的思路。代价是安全性，因此一旦引入 bash，沙箱隔离不可妥协。

在宿主机直接跑 Agent 生成的代码有风险且不可扩展。沙箱提供隔离的执行环境：运行代码、装依赖、查文件，不触碰主机；按需拉起、并行扩展、完事即销毁。配置良好的沙箱应内置常用默认项：语言运行时、git CLI、测试跑器、浏览器等，让 Agent 能自证：写代码、跑测试、看日志、修失败。Harness 搭环境，Model 来用。

5. 上下文管理（Context Management）

“上下文腐烂”是最隐蔽的生产故障之一：前 40 分钟好好的，随后模型开始无视 system prompt。没有报错，只是窗口被填满，关键指令被埋，注意力自然滑走。

Harness 决定模型能看到什么——模型自己做不到。三种在生产里好用的模式：

• Compaction：窗口趋满时，压缩较早历史而不是直接丢弃。硬性约束：永远不要压缩最初的任务定义或 system prompt。
• Tool 输出截断：禁止庞大工具输出淹没上下文。比如抓取的 50 页文档，只保留开头与结尾的 N 个 tokens，完整内容落盘，给模型一个指针。
• 按需披露技能（progressive disclosure）：会话伊始不要把所有 Tool 描述一股脑塞进来。需要哪个再懒加载哪个。常常是“懒加载 50 个技能”的 Agent，比“一开始就加载 10 个工具”的更轻盈。

生产铁律：system prompt 与任务定义必须始终可见。先压缩历史，再动它们。

6. 规划（Planning）

没有规划的模型只会挑“看起来下一步”，未必通向目标。简单任务还行，复杂多步骤就会乱序、重复、或漏掉隐蔽环节。Agent 很强，也会因为缺乏结构而失败。

Plan file 是行之有效的极简修复：

task: Migrate database schema from v1 to v2
steps:
  - Backup current schema           [ ]
  - Generate migration script       [ ]
  - Run migration on staging        [x]
  - Verify data integrity           [ ]
  - Run migration on production     [ ]
  - Update documentation            [ ]
current_step: 4

Harness 在每轮循环开始前把 plan 注入上下文；Agent 完成一步就勾选；会话结束持久化；恢复时精准续上。

自我验证（self-verification）闭合回路：每步后先验证，再继续。Harness 可通过跑测试并回传失败来强制。能在 staging 上立刻验证迁移脚本的 Agent，比“写完就当对了”的可靠太多。

The Ralph Loop 值得记住。当长任务把上下文窗口耗尽还没完成时，用钩子拦截这次退出，把原始目标注入全新窗口，强制继续。借助文件系统，每个新窗口都能从上轮迭代读取 state，从而跨多个窗口实现真正的长视程自治。

7. 错误处理（Error Handling）

现实不会配合你：工具会挂、接口会限流、文件会缺、模型偶尔吐出不可解析输出。没有明确错误处理，Agent 只有两条烂路：崩溃，或装作没看见继续编造——在生产里都不行。

• Tool 失败：可重试？（超时、限流）→ 指数退避；数据问题？→ 换路子；权限错误？→ 升级给人类
• 模型输出畸形：带格式提醒重试；三连败 → 启用结构化输出强制
• Agent 循环：步数上限触发强停；检测到重复相同工具调用 → 打断并重定向
• 置信度低：标记异步人工复核；在等待时不阻塞用户

升级路径（escalation path）是多数 Harness 最缺的一环。会在合适时刻“叫人”的 Agent，比死磕到底的 Agent 更有用。上线前设定置信度阈值；每个工具要定义清晰失败行为：返回空做 X、报错做 Y、超时做 Z。

一次真实 Trace：生产级 Agent 里发生了什么

用户请求：“总结上个月关于欧盟 AI 监管的新闻报道中的关键论点。”

1. 规划：制定计划：检索最近 30 天欧盟监管新闻 → 读前 5 条 → 聚类论点 → 结构化总结
2. 状态检查：无历史进度，步数计数器置 0
3. Search 工具：返回 8 篇文章；Harness 将每篇摘要截断至 500 tokens → 加入上下文
4. fetch_url()：抓取前 5 篇全文；全文写入文件系统，Agent 获得摘要 + 文件指针
5. 上下文检查：窗口占用 60%，暂不压缩
6. 综合：识别出 3 个主要论点簇 → 写入上下文
7. 验证：检查文章日期，发现两篇超 45 天；收紧时间筛选再检索 → 补充 2 篇
8. 最终输出：给出带引文的结构化总结
9. 状态更新：Plan 全部完成；关键发现写入记忆库；Step counter = 9，MAX_STEPS = 20

模型负责写总结；Harness 负责状态追踪、上下文治理、验证、步数上限和记忆落库。九个步骤，无需人工介入，输出正确——这就是 Harness 的价值：不花哨，但决定“偶尔有效”还是“稳定可用”。

会绊倒你的边界情况

• 有工具仍然幻觉：明明有搜索工具，模型却按旧印象回答。修复：在工具描述里明确哪些问题必须先用工具再作答。
• 无限循环：拿到空结果后以微调参数重复同一调用，把“空”当“再试”。修复：检测重复相同工具调用，用重定向 prompt 打断。
• 上下文溢出：运行 30 分钟后开始无视指令。修复：引入压缩策略，并强制规则——任务定义与 system prompt 必须始终出现在上下文开头与结尾。
• 工具误用：先写后读、用删代归档等。修复：在描述中加“什么时候不该用”。
• 时延爆炸：一串合理的串行工具调用拖成 45 秒。修复：能并行的并行；先量化 Harness 决策的延迟，再动模型。

关于 Model–Harness 的耦合，很多团队并不知道

像 Claude Code 这样的现代 Coding Agent，是在模型与 Harness 同时运行的条件下进行后训练的。模型之所以会“文件系统操作 / bash 执行 / 规划”，部分是因为在那个 Harness 里被奖励过。

这带来一个有趣后果：改变工具逻辑，常会让模型变差，哪怕功能等价。比如模型在特定 patching 格式上学过，你一改格式（即便逻辑等价），表现就打折。这是一种对 Harness 的“过拟合”。

实际影响：同一个模型，不同 Harness，结果可量化不同。在 Terminal Bench 2.0 上，放在 Claude Code 的 Opus 4.6，分数显著低于放在自定义调优 Harness 的 Opus 4.6。多数团队从未真正做过 Harness 优化，而真正的性能潜力就藏在这里。

什么时候不该用 Agents

• 流程确定：同输入 → 同步骤 → 同输出，用确定性 pipeline。硬编码更快、更便宜、更可靠。
• 后果不可逆：可能删生产数据或误发邮件，务必设人为关卡。把“建议”与“执行”分离。
• 输入结构化、处理基于规则：别上 Agent。往表单提交流程里塞 Agent 是过度工程，不是优化。

“Agent 不是 Workflow 的升级版，它是解决另一类问题的工具。”最明显的过度工程信号：每一步只有唯一正确动作，路径完全确定，而你用 Agent 的主要原因只是——它看起来很酷。

从零开始该怎么搭

按这个顺序叠层，每一步都对应最常见的失败源：

1. 控制循环 + 步数上限：在有任何工具之前就上。默认 MAX_STEPS = 10，先止血再扩展。
2. 状态文件：一个 JSON 跟踪已发生和接下来要做的事；每轮循环开头读取。
3. 工具集：先 3–5 个，描述写好。只在发现明确缺口时再加。
4. 错误处理：每个工具在上线前明确失败行为。
5. 上下文压缩：只有当你观察到长会话性能劣化时再加，别太早。
6. 记忆：当用户开始抱怨“它怎么老忘”时再上。
7. 规划：当任务跨多会话或超过单个窗口时补上。

别跳步。没做第 2 步就上第 6 步，你会在错误的地方调试。

最后的想法

一个好 Agent 的高光，不在一切顺利时它做了什么，而在出问题时它怎么自救。模型会持续进步，部分今天由 Harness 承担的能力会被模型原生吸收，规划和自验证所需的提示负担会降低。

但围绕模型智能的工程——合理工具、持久状态、上下文管理、验证回路——无论模型多强，都会让任何模型更有效。这不是“给缺陷打补丁”，而是系统设计。

模型每隔几个月会变好，Harness 则只能靠你打造。

“Model 不是你的 Agent，Harness 才是。把投入用在刀刃上。”