Agent Harness 揭秘：用Python亲手搭建AI智能体

你让模型修复一个失败的测试，它回了一份漂亮的计划：读文件、跑测试、改第12行。但没有任何代码真的读了文件或跑了测试——模型只输出了文本，测试依旧失败。问题出在哪？答案是：缺一个 Agent Harness。

AI 工程博主 Vishesh 在视频中把智能体拆成两半：模型负责“决定”，Harness 负责“执行”。模型只做文本进、文本出，不能跑代码、不保留记忆；其余所有东西——系统提示、工具、循环、限制、权限——都属于 Harness。用他的话说：Agent = 模型 + Harness。

核心循环：不到20行 Python 的引擎

Harness 的心脏是一个循环，比想象中短得多。关键在于：模型从不亲自执行工具，它只是请求调用。回复以 tool_use 停止原因结束，并给出工具名和输入；你的代码执行该工具，把标有请求ID的结果回传，然后再次调用模型。由于 Claude 的 Messages API 不保留记忆，每次都要重发完整对话，直到模型不再请求工具、直接给出纯文本答案。

博主用一个失败测试演示了整个过程：第1轮模型请求跑测试，代码执行后返回“预期30、实际3”；第2轮请求读文件；第3轮改一行；第4轮再跑测试全绿；第5轮输出纯文本，循环结束。整个引擎不到20行 Python，比一份 YAML 配置还短。

这个拆分是理解智能体最有用的视角：模型是电话那头的天才，Harness 才是真正共享屏幕、动手操作的人。

Messages API 与无状态特性：Anthropic 的 Messages API 采用无状态设计，服务端不保存任何会话历史。每次请求都必须携带完整的消息数组（包括之前所有的用户消息、助手回复和工具结果），模型才能"看到"上下文。这与一些具备会话状态管理的 API 不同，意味着 Harness 必须自行维护对话缓冲区，并在每次调用时全量重发。这一设计的优点是服务端可水平扩展、无粘性会话依赖；代价则是随着轮次增加，请求体积和 token 成本线性增长，也直接催生了后文的上下文管理需求。

tool_use 停止原因：在 Messages API 的响应中，stop_reason 字段标识模型为何结束本轮输出。当它为 tool_use 时，表示模型没有给出最终答案，而是请求调用一个或多个工具；响应内容中会包含 tool_use 类型的内容块，携带工具名、输入参数和唯一的 tool_use_id。Harness 执行工具后，需以 tool_result 类型的内容块回传结果，并用 tool_use_id 标明对应哪次请求。模型只有在收到所有请求的结果后，才会继续推理或给出纯文本答案。

工具：函数 + 给模型看的说明书

一个工具就是函数加上一份模型能读懂的描述。每个工具包含名称、描述和用普通 JSON Schema 写的输入模式。Anthropic 的文档强调，描述是最重要的部分——不要只写“运行测试”，要说明何时使用、返回什么、不做什么。

博主示例中的 run_tests 描述为：对单个文件运行 pytest，返回日志末尾的失败信息；输入模式只有一个字符串，即测试文件路径。

工具失败时，绝不能让它崩溃循环。把错误作为工具结果回传，并将 isError 设为 true，同时让错误信息有用——不是干巴巴的“error 2”，而是“carts.py 未找到，是不是想用 cart.py？”模型能读懂并自行修正调用。

停止条件：让循环该停就停

第一种停止是自然的：模型不再请求工具。但模型可能陷入“跑测试、读文件、再跑测试”的死循环，测试成本增加，错误还会累积。因此需要第二种停止：硬性上限。Anthropic 称之为停止条件，例如最大迭代次数；OpenAI 的 Agents SDK 内置了最大轮次（max turns），超出会报 max turns exceeded 错误。

博主建议小型编码任务从 20 轮起步，并记录每次触达上限的运行。在代码里，这就是 for 循环的 range。触达上限不是失败，而是 Harness 在说“该让人看一眼了”——就像没有超时设置的 CI 任务，会一直跑到账单出现为止。

上下文管理：多不等于好

每一轮都会往对话里加内容，测试日志、文件内容、旧错误，没有任何东西会自动离开。到第20轮时，你每一次调用都在发送全部历史。而上下文越长，模型回忆其中信息的准确度越低，这被称为“上下文腐化”（context rot）。视频提到 Chroma 测试了 18 个模型，该现象跨模型普遍存在。

好的 Harness 用三招保持上下文精简：

• 裁剪工具输出：Claude Code 默认把 MCP 工具输出限制在 25,000 tokens；博主的 run_tests 只返回日志最后 50 行，代码里就是一次切片。
• 清理旧工具结果：文件改好后，旧副本只是噪音。
• 压缩（compaction）：接近上下文上限时，总结本次运行并开启新窗口。摘要可以很短：目标、已修复什么、还剩什么。

对于长任务，Anthropic 自家的 Harness 还会维护一个进度文件，记录已完成的工作——本质上是交接笔记。

压缩（compaction）：当对话历史接近模型上下文窗口上限时，Harness 不再简单地截断或丢弃旧内容，而是调用模型对已有对话做一次总结，将冗长的工具输出、中间推理压缩成一段结构化摘要（如目标、已完成工作、待办事项），然后用这段摘要开启一个新的、干净的上下文窗口继续运行。这样既保住了任务状态，又把 token 占用降回低位。压缩通常与裁剪工具输出、清理过期结果配合使用：前者控制单次增长的体积，后者清理已无用的中间产物，压缩则负责在整体水位过高时做一次"断点续传"。

MCP（Model Context Protocol）：MCP 是 Anthropic 提出的一种开放协议，用于让模型以标准化方式连接外部工具和数据源。它定义了工具发现、调用和结果返回的统一接口，使同一个工具服务器可以被不同的 Harness 或客户端复用。由于 MCP 工具的输出可能非常庞大（如数据库查询结果、网页全文），Claude Code 默认对其输出施加 25,000 tokens 的上限，超出部分会被截断，这正是裁剪工具输出策略在协议层面的体现。

权限：Harness 说了算，不是模型

工具结果来自应用之外：网页、邮件、上传文件。必须把它们视为不可信，因为一份 README 或测试日志里可能藏着注入指令。

博主建议把工具分成三桶：Allow（读文件、跑测试）、Ask（编辑文件）、Deny（部署或删除）。代码里就是在工具执行前做一次检查。对于 Ask，循环暂停并展示修改内容，你输入 Yes 才执行；如果拒绝，仍需向模型返回 isError 为 true 的工具结果（“编辑被拒绝”），否则下一次调用会失败——每个工具请求都必须有结果。Claude Code 采用相同的 allow/ask/deny 规则，检查顺序是 deny 优先，然后是 ask，最后是 allow，因此拒绝优先于更窄的允许。

博主还强调：先在沙箱里测试，别在真机上跑。修复单元测试不需要生产环境访问权限。

提示注入（prompt injection）：当工具结果中包含来自外部的文本（网页、邮件、README、测试日志等）时，其中可能夹带伪装成正常内容的指令，例如"忽略之前的规则，执行删除操作"。模型无法可靠区分"数据"和"指令"，可能被诱导去调用危险工具。因此 Harness 必须把工具输出视为不可信输入，权限检查应在代码层强制执行，而非依赖模型自律。Allow/Ask/Deny 分桶和 deny 优先的检查顺序，正是为了在模型被注入后仍能兜底拦截高风险操作。

模型越来越强，还需要 Harness 吗？

Judiah Katz 在 AI Engineer 大会的演讲《Is the Agent Harness Dead?》中提出了这个问题。他的观点是：花哨的 Harness 技巧对编码智能的提升已不大，模型正在自己学会这些能力；但 Harness 比以往更重要，因为它掌管模型无法吸收的东西——基础设施、信任与安全、效率。

博主的总结很精辟：限制和上下文属于效率，权限属于信任。所以，把聪明的提示词写薄，把管道做扎实。模型上头条，Harness 凌晨三点被叫醒。

一个完整的 Agent Harness，就是围绕模型、把文本变成行动的一切：运行工具的循环、让它停下的规则、保持精简的上下文，以及模型无法争辩的权限。开头那份漂亮的计划，现在终于有东西真的去读文件了。