1. 拆开 AI Agent 的“驾驶舱”：Harness 到底管什么
很多人第一次听到 Harness 这个词，脑子里浮现的是汽车线束或者测试框架。放在 AI Agent 的语境里，它其实更接近“驾驶舱”或者“总装线”——模型是发动机，工具是车轮，记忆是油箱，而 Harness 是把这些东西串起来、让 Agent 真正跑起来的那套骨架。你单独拿一个 LLM 出来，它只能聊天；你给它挂上工具、加上循环、塞进上下文管理，它才开始“干活”。这中间的胶水层、调度层、状态层，合起来就是我理解的 Harness。
我接触过不少团队做 Agent，早期都容易犯一个错：把注意力全放在 Prompt 调优和模型选型上，结果 Demo 很惊艳，一上真实任务就崩。问题往往不出在模型，而出在 Harness 没搭好。模型再强，如果循环控制写死、工具返回没做归一化、上下文无限膨胀，跑三轮就开始胡言乱语。所以这篇文章我想把 Harness 拆成 7 个子系统来讲，每个子系统解决什么问题、为什么这么切、实操中怎么落地，尽量说透。
这 7 个子系统不是某个框架的官方定义，而是我在多个 Agent 项目里反复验证后总结出的一套分层方式。它覆盖了从“模型怎么被调用”到“任务怎么被拆解”再到“结果怎么被验证”的完整链路。适合正在从 0 到 1 搭建 Agent 的开发者，也适合已经有一个能跑的 Demo、但想把它做成稳定产品的团队。读完你至少能判断：自己手头的 Agent 缺的是哪一块，以及补这块大概要花多少功夫。
2. 七个核心子系统逐个拆解
2.1 Agent Loop：整个 Harness 的心跳
Agent Loop 是 Harness 里最核心的子系统，没有之一。它决定了 Agent 是“一问一答”还是“持续行动”。最简单的 Loop 长这样：接收用户输入，拼上下文，调模型，解析输出，如果输出里有工具调用就执行工具，把结果塞回上下文，再调模型，直到模型输出最终答案或者达到最大轮次。
听起来简单，但坑非常多。第一个坑是终止条件。我见过太多 Agent 因为终止条件写得太松，陷入无限循环，烧掉大量 token 还出不来。常见的做法是设最大轮次，比如 10 轮或 15 轮，超过就强制中断并返回当前状态。但光有轮次限制不够，还要有“无进展检测”——如果连续两轮工具调用返回的结果高度相似，或者模型输出开始重复，就应该主动打断。
第二个坑是错误处理。工具执行失败时，是把错误信息原样塞回上下文，还是包装成结构化错误？我的经验是包装成结构化错误，包含错误类型、错误信息、建议的重试方式。这样模型下一轮能更好地决策，而不是被一堆堆栈信息搞晕。第三个坑是并发。有些任务可以并行调多个工具，但 Loop 本身如果是串行的，就会浪费大量时间。可以在 Loop 内部加一个并发调度层，把无依赖的工具调用并行化，但要注意结果合并的顺序和一致性。
# 一个简化但可用的 Agent Loop 骨架 def agent_loop(task, max_turns=12): context = build_initial_context(task) for turn in range(max_turns): response = llm_call(context) if response.is_final: return response.content tool_calls = parse_tool_calls(response) if not tool_calls: context.append(response.content) continue results = execute_tools(tool_calls) context.append(format_tool_results(results)) if no_progress(context): return "任务未完成，已中断" return "达到最大轮次"注意：最大轮次不是越大越好。我实测下来，大部分任务 8 到 12 轮足够，超过 15 轮还没结果，基本是任务定义或工具设计有问题，继续跑只是烧钱。
2.2 LLM Integration：别把模型当黑盒
LLM Integration 这个子系统管的是“怎么跟模型说话”。很多人以为这就是调个 API，其实远不止。首先是模型选择，不同任务适合不同模型。推理密集型任务用强推理模型，格式转换类任务用轻量模型就够。我通常会在 Harness 里做一个模型路由层，根据任务类型、上下文长度、成本预算动态选模型。
其次是 Prompt 组装。System Prompt、历史消息、工具定义、当前任务，这几块怎么拼、顺序如何、各自占多少 token，都会影响效果。我的经验是把工具定义放在 System Prompt 之后、历史消息之前，这样模型在生成时能优先看到可用工具。历史消息要做截断或摘要，不能无限堆。上下文窗口再大也有上限，而且越长越贵、越慢、越容易丢关键信息。
第三个点是输出解析。模型返回的文本要解析成结构化动作，比如工具调用、最终答案、追问。解析器要足够鲁棒，能处理模型偶尔的格式偏差。我一般会要求模型输出 JSON，但同时在解析层做容错，比如用正则兜底、用 JSON 修复库处理不完整 JSON。还有一个细节是流式输出，如果前端需要实时展示，Harness 要支持流式解析，不能等整个响应结束再处理。
# 模型路由的简化逻辑 def select_model(task_type, context_length, budget): if task_type == "reasoning" and budget > 0.5: return "strong-reasoning-model" if context_length > 8000: return "long-context-model" return "lightweight-model"2.3 Tool Registry：工具不是越多越好
Tool Registry 管的是“Agent 能用哪些工具、怎么用”。我见过最夸张的一个项目，给 Agent 挂了 40 多个工具，结果模型选择困难，经常调错。工具数量超过 15 个之后，选择准确率会明显下降。所以我的建议是分层：核心工具常驻，扩展工具按需加载。
每个工具的定义要包含名称、描述、参数 schema、返回值格式、错误码。描述要写得像给新人看的文档，说清楚“什么时候用这个工具”“输入什么”“输出什么”。参数 schema 用 JSON Schema 定义，方便模型理解，也方便做校验。返回值格式要统一，比如都返回{status, data, error}结构，这样 Loop 层处理起来一致。
工具执行层要做超时控制、重试、熔断。外部 API 不稳定是常态，不能让一个工具卡死整个 Agent。我通常给每个工具设 10 到 30 秒超时，失败重试 1 到 2 次，连续失败就熔断并返回结构化错误。还有一个容易被忽略的点是工具权限，有些工具只能读、有些能写、有些能删，Harness 要在执行前做权限校验，避免 Agent 误操作。
| 工具类型 | 典型数量 | 加载方式 | 超时建议 |
|---|---|---|---|
| 核心工具 | 5-8 个 | 常驻 | 10-15 秒 |
| 扩展工具 | 10-20 个 | 按需 | 20-30 秒 |
| 危险工具 | 1-3 个 | 二次确认 | 30 秒以上 |
2.4 Memory & Context：让 Agent 记住该记的
Memory 子系统解决的是“Agent 怎么记住东西”。短期记忆就是当前会话的上下文，长期记忆是跨会话的知识。短期记忆的管理核心是“什么该留、什么该丢”。我的做法是分层：最近 N 轮完整保留，更早的做摘要，再早的只保留关键实体和结论。
摘要不是简单截断，而是用模型生成一段压缩后的上下文。比如把前 10 轮对话压缩成 200 字的关键信息。这样既保留了语义，又控制了 token。长期记忆可以用向量库存储，检索时按相似度召回。但要注意，召回的内容要经过相关性过滤，不能一股脑塞进上下文，否则会干扰模型判断。
还有一个实践是“工作记忆”和“情景记忆”分开。工作记忆是当前任务的临时状态，任务结束就清空；情景记忆是历史任务的记录，可以跨任务复用。我通常会在 Harness 里维护一个任务状态对象，记录当前目标、已完成步骤、待办事项、关键发现。这个对象每轮更新，作为上下文的一部分传给模型。
提示：上下文不是越长越好。我实测发现，超过 6000 token 的上下文，模型对中间部分的注意力会明显下降。关键信息要放在开头或结尾，中间放次要内容。
2.5 Planning & Decomposition：把大任务拆成小步骤
Planning 子系统管的是“Agent 怎么把复杂任务拆开”。没有 Planning 的 Agent 就像无头苍蝇，东一榔头西一棒子。常见的 Planning 方式有三种：一次性规划、逐步规划、混合规划。
一次性规划是让模型先输出完整步骤列表，然后按步骤执行。优点是全局清晰，缺点是如果第一步就错了，后面全错。逐步规划是每轮只决定下一步做什么，灵活但容易迷失方向。混合规划是我最常用的：先让模型输出一个粗粒度计划，比如 3 到 5 个大步骤，然后每个大步骤内部再逐步细化。
拆解的时候要注意粒度。太粗了执行不了，太细了效率低。我的经验是每个子任务应该能在 1 到 3 轮内完成，超过 3 轮就继续拆。子任务之间要有明确的依赖关系，能并行的并行，不能并行的串行。还要有回退机制，如果某个子任务失败，能回到上一步重新规划。
# 混合规划的简化实现 def plan_task(task): coarse_plan = llm_call(f"把任务拆成3-5个大步骤：{task}") steps = parse_steps(coarse_plan) for step in steps: fine_plan = llm_call(f"细化这个步骤：{step}") execute_step(fine_plan) if step_failed(): replan()2.6 Execution & Sandbox：让 Agent 安全地动手
Execution 子系统管的是“Agent 怎么真正执行动作”。这包括代码执行、文件操作、API 调用、浏览器操作等。核心问题是安全。Agent 执行代码时，不能让它直接跑在宿主机上，必须放在沙箱里。沙箱要限制网络访问、文件系统访问、CPU 和内存使用。
我通常用容器做沙箱，每个任务一个独立容器，任务结束就销毁。容器内预装常用依赖，但禁止访问宿主机文件系统。网络访问要白名单控制，只允许访问必要的 API。执行结果要捕获 stdout、stderr、退出码，结构化返回给 Loop 层。
文件操作也要小心。Agent 写文件时，要限制在指定工作目录内，不能越界。删除操作要二次确认，或者先移到回收站。API 调用要加限流和重试，避免把外部服务打挂。还有一个细节是执行日志，每一步操作都要记录，方便排查问题和审计。
| 执行类型 | 沙箱方案 | 限制项 | 日志级别 |
|---|---|---|---|
| 代码执行 | 容器 | CPU/内存/网络 | DEBUG |
| 文件操作 | 工作目录隔离 | 路径白名单 | INFO |
| API 调用 | 代理层 | 限流/重试 | INFO |
| 浏览器操作 | 无头浏览器 | 域名白名单 | DEBUG |
2.7 Evaluation & Feedback：让 Agent 知道自己干得怎么样
Evaluation 子系统管的是“怎么判断 Agent 干得好不好”。没有评估的 Agent 就像没有考试的学校，不知道学生学没学会。评估分两层：过程评估和结果评估。
过程评估看每一步是否合理，比如工具选择对不对、参数传得对不对、有没有绕弯路。结果评估看最终输出是否满足要求，比如任务完成度、准确性、格式合规性。我通常会用规则加模型的方式做评估：能用规则判断的用规则，比如格式校验、关键词匹配；规则判断不了的用模型，比如语义正确性、逻辑一致性。
反馈要能影响后续行为。如果评估发现某一步错了，要能触发重试或重新规划。如果整体结果不达标，要能给出改进建议。评估结果还要记录下来，用于后续优化 Prompt、调整工具、改进规划策略。我一般会维护一个评估日志，记录每次任务的成功率、平均轮次、常见错误类型，定期复盘。
# 简单的评估逻辑 def evaluate(task, result, trace): format_ok = check_format(result) semantic_ok = llm_judge(task, result) efficiency = len(trace) / expected_turns return { "format": format_ok, "semantic": semantic_ok, "efficiency": efficiency, "passed": format_ok and semantic_ok }3. 从零搭一个最小可用 Harness 的实操路径
3.1 环境准备与依赖选型
搭 Harness 不需要一开始就上重型框架。我的建议是先用手写 Python 把核心 Loop 跑通，再逐步引入组件。Python 版本用 3.10 以上，依赖主要几个：openai或对应模型 SDK、pydantic做数据校验、httpx做异步 HTTP、dockerSDK 做沙箱、chromadb或qdrant做向量存储。
目录结构我习惯这样分：core/放 Loop 和调度，llm/放模型集成，tools/放工具定义和执行，memory/放记忆管理，planning/放规划逻辑，sandbox/放沙箱，eval/放评估。每个模块对外暴露清晰接口，模块之间通过事件或消息传递，降低耦合。
配置管理用 YAML 或环境变量，把模型密钥、超时时间、最大轮次、沙箱镜像这些可调参数外置。这样换模型、调参数不用改代码。日志用结构化日志，每条记录包含时间戳、模块、级别、任务 ID、轮次、耗时，方便后续分析。
# config.yaml 示例 llm: default_model: "lightweight-model" reasoning_model: "strong-reasoning-model" max_tokens: 4096 loop: max_turns: 12 no_progress_threshold: 2 sandbox: image: "agent-sandbox:latest" timeout: 30 memory_limit: "512m"3.2 核心 Loop 的编码与调试
先写一个最简 Loop，只支持文本输入输出，不挂工具。跑通之后，加一个 echo 工具，测试工具调用链路。再加一个计算器工具，测试参数解析和结果回传。每加一个功能，都写一个对应的测试用例，确保回归时不会破坏已有功能。
调试的时候，把每轮的上下文、模型输出、工具调用、工具结果都打印出来。我通常会写一个 trace 查看器，把整个执行链路可视化。这样出问题时能快速定位是哪一轮、哪个环节出的错。常见问题包括：模型不按格式输出、工具参数解析失败、上下文超长、循环不终止。
# 最小 Loop 的调试版本 def debug_loop(task): context = [{"role": "user", "content": task}] for turn in range(5): print(f"--- Turn {turn} ---") print(f"Context length: {len(str(context))}") response = llm_call(context) print(f"Response: {response}") context.append({"role": "assistant", "content": response}) if "FINAL" in response: break return context3.3 工具接入与沙箱配置
工具接入从最简单的开始：一个读文件的工具、一个写文件的工具、一个执行 shell 命令的工具。每个工具定义好 schema，写好执行函数，注册到 Tool Registry。执行函数里加超时和异常捕获，返回统一格式。
沙箱用 Docker 起一个容器，把工作目录挂载进去，限制网络和资源。执行命令时通过 Docker API 发送，捕获输出。容器可以复用，但每个任务结束后要清理临时文件。如果任务涉及敏感操作，可以每个任务起一个新容器，用完即销毁。
# 工具注册示例 def register_tool(name, description, schema, func): TOOLS[name] = { "description": description, "schema": schema, "func": func } register_tool( "read_file", "读取指定路径的文件内容", {"path": {"type": "string"}}, lambda path: open(path).read() )3.4 记忆与规划模块的集成
记忆模块先做短期记忆，用列表存消息，超过阈值就做摘要。摘要用模型生成，把最早的一批消息压缩成一段话。长期记忆可以后面再加，先用文件或 SQLite 存任务记录。
规划模块先做一次性规划，让模型输出步骤列表，然后按步骤执行。执行过程中如果某步失败，记录失败原因，继续下一步或中断。等一次性规划跑稳了，再升级到混合规划。
集成的时候注意模块之间的数据流。Loop 从 Memory 拿上下文，从 Planning 拿下一步动作，从 Tool Registry 拿工具定义，从 Sandbox 拿执行结果，从 Evaluation 拿反馈。每个模块只做自己的事，通过清晰的接口交互。
4. 实操中最容易踩的坑与排查手册
4.1 循环不终止的三种典型场景
第一种是模型一直调用工具但不给最终答案。这通常是因为 Prompt 里没明确要求“完成后输出 FINAL”，或者工具返回的结果让模型觉得还需要继续查。解决办法是在 System Prompt 里强调终止条件，并在 Loop 层加轮次限制。
第二种是工具调用失败后模型反复重试同一个工具。这通常是因为错误信息没给够，模型不知道该怎么改。解决办法是把错误信息结构化，包含错误类型和建议，让模型能调整参数或换工具。
第三种是模型输出格式不对，解析器一直解析失败。这通常是因为 Prompt 里的格式要求不够明确，或者模型能力不够。解决办法是加 few-shot 示例，或者在解析层做容错，实在解析不了就当作普通文本处理。
| 现象 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| 一直调工具 | 终止条件不明确 | 看 System Prompt | 加 FINAL 要求 |
| 反复重试 | 错误信息不足 | 看工具返回 | 结构化错误 |
| 解析失败 | 格式要求模糊 | 看模型输出 | 加示例/容错 |
| 上下文超长 | 记忆没压缩 | 看 token 数 | 加摘要层 |
4.2 工具调用失败的排查思路
工具调用失败分几种：参数解析失败、执行超时、执行报错、权限不足。参数解析失败通常是 schema 定义和模型输出不匹配，检查 schema 是否太复杂，或者模型是否理解不了。执行超时看工具本身耗时，加超时或优化工具实现。执行报错看错误日志，定位是工具代码问题还是外部依赖问题。权限不足检查沙箱配置和工具权限设置。
我一般会做一个工具调用日志，记录每次调用的输入、输出、耗时、状态。出问题时按任务 ID 查日志，能快速定位。还有一个技巧是给工具加 dry-run 模式，先不真正执行，只校验参数，确认没问题再实际执行。
4.3 上下文爆炸的预防与处理
上下文爆炸是 Agent 跑长任务时的常见问题。预防手段有几个：一是每轮结束后检查 token 数，超过阈值就触发摘要；二是工具返回结果做截断，只保留关键信息；三是历史消息分层，最近几轮完整保留，更早的摘要，再早的只留实体。
处理已经爆炸的上下文，可以用模型做一次压缩，把整个上下文压缩成一段简短描述，然后重新开始。但这样会丢失细节，所以最好还是预防为主。我通常会在 Harness 里设一个 token 预算，比如 8000 token，超过就自动触发压缩。
注意：压缩上下文时，任务目标、当前状态、关键发现这三类信息必须保留，其他可以丢。丢了这三类，Agent 会迷失方向。
4.4 评估结果不稳定的应对
评估结果不稳定通常是因为评估标准模糊，或者模型评估本身有波动。解决办法是把评估标准量化，能用规则判断的不用模型。比如格式校验用正则，关键词匹配用字符串包含，只有语义判断才用模型。模型评估时加多次采样取多数，或者用更强的模型做评估。
还有一个问题是评估和实际需求脱节。评估通过了但用户不满意，说明评估指标没覆盖真实需求。这时候要回头调整评估标准，把用户反馈纳入评估体系。我一般会定期人工抽检评估结果，校准评估标准。
5. 关于 Harness 设计的一些个人体会
Harness 这个东西，说到底是把 Agent 从“玩具”变成“工具”的关键。模型能力再强，没有好的 Harness，也只能做 Demo。我见过太多团队在模型上砸钱，却在 Harness 上省功夫，结果产品化阶段寸步难行。
七个子系统里，我觉得最重要的是 Agent Loop 和 Evaluation。Loop 是骨架，Evaluation 是眼睛。没有 Loop，Agent 动不起来；没有 Evaluation，Agent 不知道自己动得对不对。其他子系统可以逐步完善，但这两个必须一开始就设计好。
还有一个体会是，Harness 的设计要“可观测”。每一步在做什么、为什么这么做、结果如何，都要能追踪。这样出问题能排查，优化有依据。我通常会把 trace 做成可视化，任务执行完能回放整个链路，像看录像一样。
最后说一个细节：Harness 的配置要外置，不要硬编码。模型、超时、轮次、沙箱参数这些，都要能通过配置文件或环境变量调整。这样换环境、调参数不用改代码，部署和实验都方便。我踩过这个坑，早期把参数写死在代码里，后来调一次参数就要重新部署，效率极低。
