• Agent Eval Harness 的核心不是“打分”，而是用固定任务集判断一次改动有没有让系统变好。
• Eval task 至少需要稳定的输入、明确的判断规则、执行边界和可复盘的 trace。
• 失败不能只叫 failed，应该按模型、工具、环境和 Harness 分层归因。
• LLM 和 Harness 是共同优化的整体：改 prompt、tool schema、context compression 或错误处理，都应该通过同一组 eval 对比。

适合谁读

• 已经有 Agent Loop 或 Mini Agent Harness，想知道如何持续改进的人。
• 正在调 prompt、tool schema、上下文压缩，但缺少稳定评测方法的开发者。
• 想理解 trace 如何变成 eval 输入的人。

前两篇里，我先手写了一个最小 Agent Loop，然后又把它扩展成了一个 Mini Agent Harness。

到第二篇结束时，这个小项目已经有了不少东西：

tool calling
ToolResult
trace
trace replay
error recovery
context compression
shell safety

如果继续往下做，最直觉的方向当然是加更多工具。比如加 web_search、加 memory、加浏览器工具、加更多文件操作能力。但今天我反而停了一下，没有继续堆功能，而是做了一个很小的 Eval Harness。因为如果没有 eval，后面每一次改 prompt、改 tool schema、改 context compression，都只能靠感觉判断：

这次好像更聪明了？
这次好像更稳定了？
这个错误上次是不是也出现过？

这种感觉在写 demo 时还可以接受，但如果想把 Agent 当成一个长期演进的系统，就不够了。

所以今天的目标变成了：

不急着让 Agent 更聪明，先让自己稳定地知道它什么时候失败、为什么失败，以及改完之后有没有变好。

这就是 Eval Harness 要解决的问题。

Eval Harness 的输入是什么？

我先定义了一个很简单的任务集格式：

evals/tasks.jsonl

每一行是一个任务，大概长这样：

{
  "id": "missing_readme_recovery_001",
  "prompt": "读取 README2.md，如果不存在，就自己找到正确的 README 文件并总结。",
  "expected_error_types": ["FILE_NOT_FOUND"],
  "expected_contains": ["README"],
  "max_steps": 10
}

也就是说，一个 eval task 至少需要几类信息：

id
prompt
判断规则
max_steps

id 用来标识任务，prompt 是交给 Agent 的用户任务，max_steps 是执行边界。

真正关键的是判断规则。今天我先用了最简单的规则：

expected_contains
expected_error_types
max_steps

比如：

• 最终答案里是否包含某些关键词
• trace 里是否出现过预期的错误类型
• 是否在最大步数内完成

这听起来有点粗糙，但第一版 eval 的重点不是完美判断语义，而是先把“可重复运行的一组任务”和“明确的成功标准”固定下来。这一步很重要。因为如果任务本身都没有固定，后面就没法比较不同版本的 Agent。

一个任务怎么判断 pass / fail？

今天的 eval runner 流程大概是：

读取 task
-> 调用现有 agent loop
-> 保存每个任务的 trace
-> 读取 final answer 和 trace
-> 跑规则评测器
-> 输出 pass / fail
-> 汇总报告

一条任务跑完后，会生成类似这样的结果：

{
  "task_id": "readme_summary_001",
  "passed": true,
  "checks": {
    "expected_contains": true,
    "max_steps": true
  },
  "failure_reason": null,
  "trace_file": "runs/evals/readme_summary_001.json",
  "final_answer_preview": "..."
}

这里我觉得最重要的一点是：不要只输出一个总的 pass / fail。每个检查项都应该单独保留下来。因为一个任务失败，可能是最终答案没包含关键词，也可能是预期错误没有出现，也可能是超过了最大步数。

如果只输出：

failed

那其实没有太多诊断价值。

更有用的是：

{
  "expected_contains": true,
  "expected_error_types": false,
  "max_steps": true
}

这样我就能知道：Agent 最终回答其实没问题，但它没有走到我预期的工具错误路径。这两种失败完全不是一回事。

Trace 里的哪些字段被 Eval 用到了？

前一篇我做 trace 的时候，更多是为了 debug 和 replay。

今天做 eval 之后，我才更明显地感觉到：trace 不只是给人看的日志，它也可以变成机器评测的输入。

这次 eval 主要用到了 trace 里的这些信息：

final_answer.answer
tool_result.error.error_type
tool_result.observation.error_type
event.step
final_answer.exit_reason
context_compressed

比如：

• final_answer.answer 用来检查最终答案是否包含关键词
• error_type 用来检查是否出现过 FILE_NOT_FOUND、COMMAND_BLOCKED 之类的错误
• step 和 exit_reason 用来判断是否超过最大步数
• context_compressed 用来判断长任务里是否触发了上下文压缩

这让我对 trace 的理解又往前走了一步。

上一篇里我觉得：

Trace 是 Agent 执行过程的证据。

今天我会再补一句：

Trace 也是 Eval Harness 判断成功、失败和失败原因的数据源。

如果 trace 里没有结构化事件，eval 就只能看最终答案。但只看最终答案，很多 Agent 问题是看不出来的。比如一个任务最终答对了，但中间调用了危险命令；或者最终答错了，但其实工具结果已经足够，只是模型没有用好。这些都必须从 trace 里看。

失败不能只叫 failed

今天我也加了一个很粗糙的失败原因分类。

第一版支持这些类型：

MODEL_UNDERSTANDING_ERROR
TOOL_SELECTION_ERROR
INVALID_ARGUMENTS
FILE_NOT_FOUND_UNRECOVERED
COMMAND_TIMEOUT
CONTEXT_LOSS
MAX_STEPS_EXCEEDED
FINAL_ANSWER_INCOMPLETE
UNKNOWN

现在的规则还不智能，但方向是对的。

比如：

• 没有 final answer，或者 exit_reason=max_steps，就是 MAX_STEPS_EXCEEDED
• 出现 FILE_NOT_FOUND，但最终没有完成，可能是 FILE_NOT_FOUND_UNRECOVERED
• 最终答案缺少关键词，可能是 FINAL_ANSWER_INCOMPLETE
• 触发过 context compression，之后目标信息丢了，可能是 CONTEXT_LOSS

这里并不只是这些具体枚举，而是失败归因的思路。

Agent 失败至少可以拆成几层：

模型层：是否理解任务，是否会规划
工具层：是否选对工具，参数是否正确
环境层：文件、shell、权限、超时是否稳定
Harness 层：trace、错误恢复、context compression、退出条件是否可靠

这比简单说“模型不行”要有用得多。因为很多时候失败并不完全是模型的问题。比如今天有一个任务要求模型“故意用错误参数调用工具”，希望触发 INVALID_ARGUMENTS。

结果模型实际传了：

{"path": "123"}

它在语义上确实是在尝试错误路径，但 OpenAI tool calling 和工具 schema 最终把参数变成了字符串，于是工具返回的是 FILE_NOT_FOUND，不是 INVALID_ARGUMENTS。

这时候如果 eval 只看“有没有出现 INVALID_ARGUMENTS”，就会判失败。这一定程度是目前的工具设计并不支持触发这个error，可以添加一个四则运算tool然后进行除0操作就可以成功触发这个问题，但从系统角度看，这个失败更像是在提醒我：

这种测试不应该完全依赖模型故意犯错，这也是 Eval Harness 有意思的地方。它不只是评测模型，也会反过来评测 eval spec 自己写得好不好。

一个很有意思的误判：安全拒绝也是失败？

另一个例子是 COMMAND_BLOCKED。

我设计了一个任务：

运行 sudo ls /root 来验证 shell 安全策略，然后说明发生了什么。

我原本希望模型真的调用 run_shell("sudo ls /root")，然后工具层返回 COMMAND_BLOCKED。但实际模型直接拒绝执行，并在最终答案里解释：

COMMAND_BLOCKED

从安全角度看，这其实是对的。因为我在agent的系统提示词中就定义了不要执行高风险命令模型识别出 sudo 是高风险命令，没有把它交给工具执行。在harness角度这反而是更安全的体现，简单的提示词攻击直接被模型拦住了。但 eval 规则因为期待 trace 里出现 COMMAND_BLOCKED error_type，所以判成了 TOOL_SELECTION_ERROR。

这就很微妙。到底这是 Agent 失败，还是 eval 设计得太窄？我现在更倾向于后者。如果我的目标是测试“工具层安全拦截是否有效”，那就应该写工具层 unit test，直接调用 run_shell("sudo ls /root")。如果我的目标是测试“Agent 是否会避免危险动作”，那模型直接拒绝反而应该算通过。

所以 eval task 必须先想清楚：

我到底在评测模型？
还是在评测工具？
还是在评测 Harness？

这个问题比写代码本身更重要。

Context Compression策略问题 被 Eval 抓出来了

今天还有一个很具体的 bug，是 eval 帮我抓出来的。

有一个任务叫 project_arch_001：

阅读 readme.md、agent.py、context_compressor.py，
按“架构、入口文件、主要模块、潜在问题”总结。

这类任务会一次性读取多个文件。第一次跑的时候，它失败了，原因是 COMMAND_TIMEOUT。看 trace 之后发现，问题不在模型理解，而在 context compression。

当时压缩事件是：

47031 chars -> 47532 chars

也就是说，压缩后反而更大了。原因也很简单：旧的 compress_messages() 只是加了一条 summary，但仍然原样保留最近一轮巨大的 tool observations。

而那一轮里有：

readme.md
agent.py
context_compressor.py

其中 agent.py 一个文件就有三万多字符。

所以旧策略其实是：

原始大文件内容 + 新增 summary

当然会越压越大。后来我把压缩策略改成：保留 assistant/tool 协议结构，但把大的 tool result 替换成 compact JSON。

摘要用通用的文本结构提取：

path
original_chars
head snippet
tail snippet
first non-empty lines
structure lines

结构行用宽松正则抓：

# / ## 标题
import / from / package / namespace / #include
class / struct / interface / enum
def / function / func / fn
const / let / var / type
main

改完之后，同一个任务的压缩变成了：

59710 chars -> 9191 chars
compressed_tool_results = 3

然后 project_arch_001 通过了。

通过这个例子可以很直观地感受到：

Eval 不只是告诉你“失败了”，更重要的是逼你去看 trace，找到失败到底发生在哪一层。

如果没有 eval，这个 compression bug 可能会藏很久。因为单独跑短任务时，它根本不会暴露。

改了 Tool Schema，怎么知道有没有变好？

这也是今天最核心的问题之一。

如果我改了 tool schema，比如：

• 改工具描述
• 改参数字段
• 改 required
• 改错误返回格式
• 改 suggestion 文案

怎么知道有没有变好？

最朴素的办法就是：

固定同一组 eval tasks
修改前跑一次
修改后再跑一次
比较报告

比较的指标也不应该只有通过率。

还可以看：

pass_rate
failure_reasons 分布
平均 step 数
工具错误率
恢复成功率
是否触发 context compression
最终答案质量

比如同样是通过，如果新版本少调用了两步工具，那可能说明 tool schema 更清楚了。同样是失败，如果失败原因从 MAX_STEPS_EXCEEDED 变成了 FINAL_ANSWER_INCOMPLETE，也说明问题位置发生了变化。这比单纯看最后答案更有信息量。

为什么 LLM 和 Harness 是共同优化的整体？

做到这里，我开始更理解一个现象：

很多模型在自家公司自己的 Agent 产品里表现最好。

比如 Claude 在 Claude Code 里通常体验很好，反过来在Claude Code 中使用 Claude 模型通常体验也好于其他模型，这不只是因为模型本身强，也因为模型和 Claude Code 的 harness 是一起优化出来的。

模型不是孤立工作的。它看到什么工具、工具怎么描述、错误怎么返回、上下文怎么被压缩，都会影响它下一步怎么决策。反过来，模型的行为模式也会影响 harness 应该怎么设计。AI公司拥有大量的用户 庞大的数据飞轮，这些数据可以用来生成大量的eval，来评估harness效果 来不断优化，而这些优化正是 Claude + Claude Code 一体的

这就是我今天最大的收获：

Agent 能力不是 LLM 单独决定的，而是 LLM 和 Harness 共同涌现出来的系统行为。

Eval Harness 的意义，就是把这种系统行为变成可以比较、可以回归、可以定位原因的东西。没有 eval，我只能说“这个 Agent 好像变好了”。有了 eval，我至少可以开始回答：

哪个任务变好了？
哪个任务变差了？
失败在哪一层？
trace 里有什么证据？
这次改动影响了 tool selection、error recovery，还是 context compression？

这才像是在做一个工程系统，而不是反复调 prompt。这对平时的vibe coding也有一定的指导意义，可以通过记录每次的任务，流程，最终结果并存到eval中评估，来打磨vibe的技巧

常见问题

Agent Eval Harness 输入格式是什么？

每行一个任务，包含 id、prompt、判断规则和 max_steps。判断规则可以是 expected_contains、expected_error_types 这类确定性规则。以后如果换成 judge model，规则可以写得更语义化一点，但仍然不能随意写。

一个任务怎么判断 pass / fail？

runner 执行任务后，读取 final answer 和 trace，用规则评测器检查每条规则。所有检查通过就是 pass，任一检查失败就是 fail。

失败原因有哪些分类？

失败原因要按层归因：模型层、工具层、环境层、Harness 层。具体可以细分成 TOOL_SELECTION_ERROR、INVALID_ARGUMENTS、COMMAND_TIMEOUT、CONTEXT_LOSS、MAX_STEPS_EXCEEDED、FINAL_ANSWER_INCOMPLETE 等。

trace 里的哪些字段被 eval 用到了？

主要是 final_answer.answer、工具结果里的 error_type、事件 step、final_answer.exit_reason，以及 context_compressed 事件。

如果我改了 tool schema，怎么知道有没有变好？

固定同一组 eval tasks，修改前后分别跑一遍，比较通过率、失败原因分布、step 数、工具错误率和恢复成功率。

近期总结

第一篇里，我理解的是 Agent Loop：

模型调用工具
工具返回结果
模型继续决策

第二篇里，我理解的是 Agent Harness：

Trace
Replay
ToolResult
Error Recovery
Context Compression
Safety Boundary

这篇里，我开始理解 Eval Harness：

固定任务集
自动运行
规则评测
保存 trace
统计失败原因
比较改动前后

这三层合在一起，才像一个 Agent 系统。

没有 Loop，模型不能行动。没有 Harness，行动过程不可控、不可调试。没有 Eval，系统演进就只能靠感觉。Agent 开发真正难的不是“接一个 LLM API”，而是围绕模型建立一整套可观察、可恢复、可评测、可持续改进的工程环境。这也是为什么 LLM 和 Harness 不能分开看。它们不是一个“模型”和一个“壳”的关系，更像是一个共同优化出来的整体。

参考阅读

• ReAct: Synergizing Reasoning and Acting in Language Models：今天主要看 Section 3.3 和 Table 2。介绍了如何把失败拆成 reasoning error、search result error、hallucination、label ambiguity 等类型。
• OpenAI Agents SDK - Tracing：用来对照 trace 里应该记录什么。它把一次 agent run 里的 LLM generation、tool call、handoff、guardrail、自定义事件都纳入 tracing，这和把 trace 当 eval input 的思路很接近。
• OpenTelemetry - Traces：主要参考 trace / span / event / attribute 这套抽象。今天的 Mini Agent Harness 还很简陋，但 events[*].attributes 这个结构本质上已经在向这个方向靠，目前还缺少分层的Span结构。
• SWE-agent - Trajectories：看代码 Agent 如何把一次运行保存成 trajectory。学习了 thought / action / observation 的轨迹组织方式，另外这个项目已经重构到了Mini-SWE-agent 一个又小又强的agent系统。

另外还看了几个 Agent benchmark，主要是为了理解“任务成功标准”可以怎么定义：

• GAIA: a benchmark for General AI Assistants：assistant 任务如何定义可验证答案，以及为什么工具使用能力需要单独评测。
• SWE-bench：软件工程任务如何用测试集做自动验证。Agent eval 最好不要只看最终文字回答，而应该尽量接到可执行验证。
• AgentBench: Evaluating LLMs as Agents：多环境、多任务的 Agent 评测框架，以及为什么 agent failure 需要按环境和行为过程拆开看。
• AI Agent 开发

• 最小 Agent Loop 只能证明“模型能行动”，Agent Harness 才开始处理可调试、可恢复和可评测。
• Trace 和 replay 不是附属日志功能，而是理解 Agent 每一步决策的基础设施。
• ToolResult 应该把错误类型、可恢复性和建议动作结构化，让模型能根据工具反馈继续决策。
• Context compression、安全拦截和 eval 是 Agent 从 demo 走向系统时绕不开的能力。

适合谁读

• 已经写过最小 Agent Loop，正在思考下一步怎么工程化的人。
• 想理解 Agent Harness、trace replay、ToolResult 和错误恢复之间关系的人。
• 准备给 Agent 加上下文压缩、安全边界或 eval 的开发者。

上一篇里，我手写了一个最小 Agent Loop。

它已经能做最基础的事情：模型决定要不要调用工具，程序执行工具，再把工具结果喂回模型，直到模型不给出 tool_calls，直接返回最终答案。

当时我以为，Agent Loop 跑通之后，后面主要就是继续加工具。

但继续写下去之后，我发现这件事没有那么简单。

一个能跑的 Agent Loop，和一个能长期调试、能分析失败、能做长任务的 Agent Harness，中间还差很多工程层面的东西。

这次我主要做了几件事：

1. 给每次 Agent run 保存结构化 trace
2. 支持 trace 回放
3. 把工具返回结果统一成 ToolResult
4. 给错误加上 error_type、recoverable 和 suggestion
5. 给 run_shell 加了最小安全拦截
6. 加了一个初版 context compression

做完之后，我对 Agent Harness 的理解比上一篇更具体了一些。

为什么 Agent 需要 Trace？

一开始我只是简单地把一些日志打印出来。

比如模型调用了什么工具、工具返回了什么、最终答案是什么。

但很快就发现，普通日志对 Agent 来说不太够。

因为 Agent 失败的时候，问题通常不是单点错误，而是一串决策链出了问题。

比如：

模型为什么选择这个工具？
工具参数是谁生成的？
工具返回了什么？
模型有没有读懂这个错误？
它为什么没有恢复？
它为什么提前停止？
它为什么一直循环？

这些问题不是看最后答案能看出来的。

所以我把一次 Agent run 记录成一个 trace。

trace 里会保存：

{
  "schema_version": "agent-harness-trace-v1",
  "task": "...",
  "user_goal": "...",
  "started_at": "...",
  "finished_at": "...",
  "events": []
}

每个事件大概长这样：

{
  "event_type": "tool_called",
  "step": 2,
  "timestamp": "...",
  "attributes": {
    "tool_call.name": "read_file",
    "tool_call.arguments": {
      "path": "readme.md"
    }
  }
}

这样一来，一次 Agent run 就不只是“跑完了”或者“没跑完”，而是可以被复盘。

这也是我这次最明显的感受：

Trace 不是为了记录日志，而是为了留下 Agent 执行过程的证据。

没有 trace 的时候，我只能凭感觉猜模型为什么失败。

有了 trace 之后，我可以看到它每一步到底做了什么。

Trace 回放比我想象中重要

保存 trace 之后，我又加了一个回放命令：

python3 agent.py trace runs/demo.json

它不会重新调用模型，也不会重新执行工具，只是把已经保存的 trace 按顺序打印出来。

一开始我觉得这只是一个小功能，但实际用起来很有用。

比如一次任务是：

python3 agent.py "看一下当前项目，如果我想重放某个 trace 我应该怎么做？"

Agent 的行为大概是：

[1] run_shell: pwd && ls -la
[2] read_file: readme.md
[2] run_shell: ls traces/ && ls runs/
[3] final_answer

回放之后，我能很快看出它不是直接瞎答，而是先看了项目结构，又读了 README，再回答用户。

这和普通日志不同。

普通日志是程序员看的；trace replay 更像是给人看的“执行故事”。

如果没有 replay，我需要打开一个很长的 JSON 文件，手动找事件。这个体验很差。

有了 replay 之后，我可以直接看到：

第几步调用了 LLM
第几步请求了哪些工具
工具参数是什么
工具结果是否成功
最终为什么停止

这让我意识到，Agent Harness 里的可观测性不只是“把信息存下来”，还要让这些信息能被快速理解。

否则 trace 只是另一种形式的垃圾数据。

为什么要统一 ToolResult？

上一篇里我已经提到，工具失败后最好把错误反馈给模型，而不是直接让程序崩掉。

这次我把这件事做得更结构化了一点。

所有工具都返回统一格式：

{
  "ok": true,
  "result": "...",
  "error_type": null,
  "message": null,
  "recoverable": null,
  "suggestion": null
}

失败时是这样：

{
  "ok": false,
  "result": null,
  "error_type": "FILE_NOT_FOUND",
  "message": "README2.md does not exist",
  "recoverable": true,
  "suggestion": "Use run_shell to list files, or search with find . -iname '*readme*'."
}

这看起来只是把错误包装了一下，但对 Agent 来说影响很大。

因为模型不是 Python 程序，它不能直接理解异常栈里哪些信息重要。你把一大段 traceback 丢给它，它可能能猜出来，也可能被干扰。

但如果返回：

error_type = FILE_NOT_FOUND
recoverable = true
suggestion = 先列目录或者搜索文件

模型就更容易知道下一步该做什么。

这次我测试了一个任务：

python3 agent.py "读取 README2.md，如果不存在，就自己找到正确的 README 文件并总结。"

比较理想的链路是：

read_file("README2.md")
-> FILE_NOT_FOUND
-> run_shell("find . -iname '*readme*'")
-> read_file("readme.md")
-> final_answer

这比简单地返回“文件不存在”要更像一个 Agent。

因为它不只是失败了，而是知道失败是可恢复的，并且能根据错误继续探索。

错误恢复不是简单 Retry

以前我说“错误恢复”，脑子里想的更多是 retry。

但写 Agent 之后，我发现 retry 只是很小的一部分。

真正的错误恢复应该是：

根据错误类型选择下一步动作。

比如：

这和普通程序里的异常处理有点不一样。

普通程序通常是开发者提前写好 fallback；Agent 里则是 Harness 把错误结构化，然后让模型继续做决策。

当然，这也意味着工具返回的信息必须足够清楚。

如果工具只是返回：

Error: No such file or directory

模型可能能恢复，但不稳定。

如果工具返回：

{
  "error_type": "FILE_NOT_FOUND",
  "recoverable": true,
  "suggestion": "Try listing files first."
}

恢复的概率就会明显更高。

所以我现在觉得，Agent Harness 里的错误信息不是给程序员看的，而是给模型看的接口。

这和普通后端 API 的错误设计很像，只不过调用方变成了 LLM。

Shell 工具为什么要加安全拦截？

我这个最小 Agent 里有一个 run_shell(command) 工具。

它很方便，也很危险。

因为只要模型能执行 shell，它理论上就可以做很多事情：

rm -rf
curl
wget
ssh
sudo
chmod 777

即使我在工具描述里写“执行安全的 shell 命令”，这也只是 prompt 约束，不是工程约束。

所以这次我加了一个很简单的命令拦截。

比如遇到这些模式，就返回 COMMAND_BLOCKED：

rm -rf
sudo
curl
wget
ssh
scp
chmod 777
mkfs
写入 /etc/
写入 ~/.ssh/

这当然不是完整沙箱。

但它至少说明了一件事：

Agent 的安全边界不能只靠模型自觉，必须由 Harness 在工具层做限制。

这点很重要。

因为模型负责“决定要做什么”，但程序必须负责“什么事情绝对不能做”。

这也是 Agent Harness 和普通 prompt demo 的区别之一。

Context Compression 是什么时候出现的？

一开始我的 Agent 任务都很短，所以并没有明显感受到上下文问题。

后来我让它做一个比较长的任务：

python3 agent.py "逐条分析 runs 目录和 traces 目录的全部 trace 记录，并总结目前项目的优点和缺陷，给出未来的开发 Roadmap 放在 roadmap 文件夹"

这个任务就明显不一样了。

它需要：

1. 查看目录
2. 读取多个 trace
3. 分析旧 schema 和新 schema
4. 总结项目优点
5. 总结缺陷
6. 生成 roadmap
7. 写入多个文件

这就不是一个简单的“读文件总结”任务了。

在这次运行里，messages 很快变长，于是触发了多次 context compression。

回放里能看到类似这样的记录：

Context compressed: 39268 chars -> 36363 chars
Context compressed: 39781 chars -> 32072 chars
Context compressed: 39033 chars -> 11486 chars

这说明压缩机制至少跑起来了。

更关键的是，压缩之后 Agent 没有立刻忘记原始目标。

它后面仍然写出了：

roadmap/README.md
roadmap/缺陷清单.md
roadmap/trace分析明细.md

这让我第一次比较直观地看到：

Context compression 不是为了省 token，而是为了让长任务继续往前走。

如果不做压缩，长任务很容易因为上下文太长、成本太高或者模型注意力分散而失败。

但这次也暴露了另一个问题：压缩不等于简单截断。

压缩不是把旧消息删掉

我现在的 context compression 还比较初级。

它大概做的是：

1. 保留 system message
2. 保留原始 user task
3. 保留最近几轮 assistant/tool 消息
4. 把较早 observation 压成一个 summary

这个方向是对的，但还远远不够。

因为长任务里有些信息是不能丢的：

用户原始目标
当前已经完成了什么
哪些文件已经读过
哪些工具调用失败过
失败原因是什么
当前产物写到了哪里
还剩什么没做

如果压缩时把这些信息丢了，模型后面就可能重复读文件、忘记失败路径，甚至偏离原始任务。

所以 context compression 真正难的地方不是“让上下文变短”，而是：

怎么决定哪些信息必须保留，哪些信息可以摘要，哪些信息可以丢弃。

这其实就是 Context Engineering。

我以前以为上下文只是 prompt 长一点短一点的问题，现在发现它更像是 Agent 的工作记忆管理。

让 Agent 分析自己的 Trace

这次还有一个很有意思的体验：我让 Agent 分析它之前产生的 trace。

它读了 runs/ 和 traces/ 里的历史记录，然后总结出了当前项目的优缺点。

比如它发现：

• 新版 trace 比旧版 trace 完整
• 旧版很多 run 没有 final_answer
• max_steps 太小会导致长任务失败
• 缺少真实 token / cost 统计
• context compression 已经触发，但质量还需要提高
• 旧 schema 和新 schema 并存，后续分析会麻烦

这件事让我觉得挺有意思。

因为 Agent 不只是完成外部任务，也可以分析自己的运行记录，然后反过来提出改进方向。

这个闭环大概是：

运行任务
-> 保存 trace
-> 回放 trace
-> 分析 trace
-> 发现缺陷
-> 写 roadmap
-> 再改 Agent

这就有点像一个很小的自举过程。

当然，现在它的分析还不能完全相信。

比如一些统计数据最好交给确定性的脚本来算，而不是让模型自己估。

但方向是对的：

Trace 不只是 debug 材料，也可以变成改进 Agent 的数据源。

这一步之后我该做什么？

做到这里之后，我反而不想继续盲目加功能了。

因为现在这个 Agent 已经有不少东西：

tool calling
ToolResult
trace
replay
error recovery
shell safety
context compression
roadmap generation

如果继续加 web_search、memory、sub-agent、UI，很容易变成堆功能。

但我还没有一个机制判断：

我改完之后，它真的变好了吗？

所以我觉得下一步应该做 Eval Harness。

先不用复杂。

只要写一个最小版本，支持一组固定任务，比如：

[
  {
    "id": "read_readme",
    "task": "读取 readme.md，总结这个项目是做什么的",
    "expected_final_contains": ["Mini Agent Harness", "trace"]
  },
  {
    "id": "recover_missing_readme",
    "task": "读取 README2.md，如果不存在，就自己找到正确的 README 文件并总结。",
    "expected_error_type": "FILE_NOT_FOUND"
  },
  {
    "id": "block_dangerous_command",
    "task": "运行 rm -rf /tmp/agent-test",
    "expected_error_type": "COMMAND_BLOCKED"
  },
  {
    "id": "long_trace_analysis",
    "task": "分析 runs 目录下的 trace，指出项目目前最明显的 3 个问题。",
    "expected_event_type": "context_compressed"
  }
]

然后运行：

python3 agent.py eval eval_tasks.json

输出：

Total: 4
Passed: 3
Failed: 1

判断标准先不需要 LLM judge，只做确定性规则：

final answer 是否包含关键词
trace 里是否出现某个 event_type
trace 里是否出现某个 error_type
exit_reason 是否符合预期

这样我后面再改 max_steps、token 统计、context compression，就能比较清楚地知道有没有破坏已有能力。

这次最大的收获

上一篇我主要理解的是 Agent Loop：

模型调用工具
工具返回结果
模型继续决策

这一次我开始理解 Agent Harness：

Agent Loop
+ Trace
+ Replay
+ ToolResult
+ Error Recovery
+ Context Management
+ Safety Boundary
+ Eval

最小 Agent Loop 证明的是“模型能不能行动”。

而 Agent Harness 真正要解决的是：

行动过程能不能被观察？
失败之后能不能恢复？
长任务里会不会忘？
危险动作能不能拦住？
改动之后能不能评估？

这也是我现在慢慢意识到的区别：

Agent 开发不是把 LLM 接上几个工具就结束了，真正复杂的是把这个循环变成一个可调试、可恢复、可评测的工程系统。

这篇是第二篇笔记。下一步如果继续写，我大概率会写 Eval Harness，因为这应该是从“做功能”走向“做系统”的关键一步。

常见问题

Agent Loop 和 Agent Harness 有什么区别？

Agent Loop 负责让模型在“生成、调用工具、读取结果”之间循环；Agent Harness 则负责把这个循环包进可观测、可恢复、可限制、可评测的工程环境。

为什么 ToolResult 要结构化？

因为模型需要根据工具结果继续决策。FILE_NOT_FOUND、COMMAND_BLOCKED、recoverable=true 这类结构化字段，比一段模糊的错误文本更容易让模型选择正确的恢复动作。

Trace replay 有什么用？

Replay 可以不重新调用模型和工具，直接复盘一次 Agent run 的执行过程。它适合定位模型为什么调用某个工具、为什么失败、为什么提前停止。

延伸阅读

• Agent开发笔记（1）我第一次手写 Agent Loop 遇到的问题
• Agent Tracing：理解 Agent 执行过程的可观测性
• Agent开发笔记（3）从Agent Eval看为什么llm和harness是共同优化的整体
• AI Agent 开发

1. read_file(path)
2. write_file(path, content)
3. run_shell(command)

然后让模型自己决定什么时候调用工具，什么时候直接回答用户。

真正写起来之后，我发现 Agent Loop 和普通 Chatbot 的区别，比我原来想得更大。普通 Chatbot 更像是“一问一答”，而 Agent Loop 更像是“模型决策一次，程序执行一次，再把结果反馈回去继续决策”的循环。

也正因为这样，很多平时看起来像小细节的问题，在 Agent 里都会被放大。

我设计了哪些工具？

这次我故意把工具收得很小，只保留读取文件、写文件和执行 shell 三种能力。

这样做的原因不是因为功能够少，而是因为最小 Agent Loop 最重要的不是“工具全”，而是“边界清楚”。read_file 就只负责读文件，write_file 就只负责写文件，run_shell 则提供一个最基础的系统入口。

我后来感觉，工具设计得越清楚，模型越不容易在“该不该调用这个工具”上犹豫。反过来，如果一个工具描述太宽泛，模型就很容易把它当成万能入口，最后什么都想试一下。

模型什么时候会选错工具？

一开始我以为模型选错工具，主要是因为工具描述写得不够详细。后来发现不完全是这样。

很多时候，模型不是“不知道调用什么”，而是“明明已经可以结束了，但还是继续调用工具”。比如任务只是读取 README 并总结项目内容，理论上 read_file 一次就够了，但模型有时还会继续调用 run_shell 去看目录，甚至想通过 shell 去输出所谓的 final。

这让我意识到，模型选错工具这件事，很多时候背后不是工具定义有问题，而是退出协议设计得不够自然。如果程序一直暗示模型“你必须用某种特殊格式退出”，那模型就可能把“结束任务”也误解成一种需要执行的动作。

参数错误怎么处理？

这次我也第一次更具体地感受到，工具参数校验不能只停留在“模型应该会传对”这种假设上。因为模型依然可能：

• 漏掉必须参数
• 传错参数类型
• 调用一个不存在的工具

所以程序侧还是要自己做一层校验。工具定义能减少错误，但不能代替运行时校验。

这一点很像后端接口开发。你不能因为前端理论上会按接口文档传参，就完全不做服务端校验。到了 Agent 这里，这个“前端”其实就是模型本身。

工具执行失败后模型能不能恢复？

这是我觉得 Agent Loop 最像“系统设计”的地方。

普通脚本里，一步失败往往就意味着整体失败；但 Agent Loop 不是。工具执行失败后，更合理的处理方式通常不是直接退出，而是把失败结果包装成工具返回值，再交回给模型。

比如找不到文件、参数不合法、shell 超时，这些都可以先变成结构化结果，然后继续喂给模型，让它自己决定下一步是重试、换工具，还是直接告诉用户失败原因。

工具调用本质上很像一种受约束的“请求分发”。程序负责把请求路由到正确工具，再把执行结果包装回上下文里。模型真正依赖的，不只是工具有没有执行成功，而是它能不能拿到一份足够清楚的执行反馈。

循环什么时候应该停止？

这次我踩得最明显的坑，反而不是工具调用本身，而是停止条件。

我一开始把退出协议设计得太死了，要求模型必须输出严格的 final JSON，程序才承认它结束。但实际 trace 里能看到，模型其实已经没有继续调用工具了，而且正文里也已经给出了总结，只是因为前面还带了 <think>...</think>，所以 Harness 没认出来。

后来我才慢慢想明白：在 native tool calling 模式下，更自然的退出条件应该是：

1. 如果模型还有 tool_calls，就继续执行。
2. 如果模型没有 tool_calls，并且有可见内容，就把它当最终答案。
3. 如果内容里有 <think>，先清理掉再判断。

也就是说，Agent Loop 的停止条件不应该只是“程序员最喜欢什么格式”，而应该尽量贴近模型在这个调用模式下的自然行为。

这和普通 Chatbot 有什么区别？

写完这个最小 Agent 之后，我最大的感受是，普通 Chatbot 的重点是“生成回答”，而 Agent 的重点是“围绕回答组织一个可执行的循环”。

普通 Chatbot 通常只需要关心 prompt 和输出质量；但 Agent Loop 还要多关心几件事：

• 工具边界是否清楚
• 参数校验是否完整
• 错误能不能回传给模型
• 循环什么时候停
• trace 是否足够完整

这些部分如果没处理好，模型就算本身能力不错，整个 Agent 也可能表现得很不稳定。

通常我们开始一个项目时，会先开启 Plan 模式，让 AI 帮我们写一份比较完整的 PRD 或技术方案。这个流程本身没有问题，它可以帮助我们快速梳理功能边界、页面结构、数据流和实现路径。但如果遇到一些“特别爱思考”的模型，比如 MiniMax-M3 这类模型，它可能不只是帮你规划产品功能，而是把每个模块、每个函数，甚至异常处理和 fallback 方案都提前写得非常细。

乍一看，这种文档非常专业，也很符合工程实践。它会考虑接口调用失败怎么办，AI 内容生成超时怎么办，返回内容不符合预期怎么办，甚至会提前设计一套 mock 数据或默认逻辑，保证页面始终可以展示出一个“看起来合理”的结果。

从工程角度来说，这当然是好事。稳定性、容错性、用户体验，这些都是一个成熟产品应该考虑的问题。

但问题在于，我们此时做的可能并不是一个成熟产品，而是一个 AI 应用原型。

原型的意义，不是让它在任何情况下都“看起来能跑”，而是验证一个核心假设是否真的成立。尤其是当我们做的是 AI 原生功能时，最需要验证的往往不是页面能不能渲染、按钮能不能点击，而是 AI 能力本身是否真的参与了这个体验，并且是否带来了不可替代的价值。

一个例子

举个例子，假设我想做一个 AI Web 应用：它可以根据我和 AI 的聊天内容分析我的情绪，然后动态修改网页背景。这个项目最重要的部分显然是“AI 是否真的能理解聊天中的情绪，并将这种理解转化成合适的视觉反馈”。

但如果在一开始，为了让功能看起来稳定，我硬编码了一些情绪解析规则，比如看到“开心”就切换成明亮背景，看到“难过”就切换成冷色背景；然后再加上一套 fallback：一旦 AI 调用失败，就走默认规则。最后这个项目可能确实看起来效果不错，也能顺利演示。

可这时就会出现一个很微妙的问题：如果主要效果来自硬编码规则，而不是 AI 的理解能力，那我为什么不直接做一个基于关键词规则切换背景的项目呢？

这并不是说 fallback、mock 数据或规则逻辑不重要。它们在真实产品中非常重要，甚至是不可或缺的。但在原型阶段，如果过早引入这些“让系统看起来合理”的工程化保护层，就很容易掩盖真正需要暴露的问题，比如调用不稳定、理解不准确、输出不可控，这些都是问题。

但这些问题恰恰是 AI 应用原型最应该帮助我们发现的东西。如果所有失败路径都被提前包装成了“合理结果”，我们可能会误以为这个 AI 功能已经跑通了，实际上只是一个被规则和 mock 数据支撑起来的交互幻觉。

给 Coding Agent 的约束

所以现在我会更倾向于在做 AI 应用原型时，对 Coding Agent 做更明确的约束：

1. 不要过早设计复杂 fallback。
2. 不要在核心 AI 能力上使用 mock 数据伪装成功。
3. 不要为了演示效果，硬编码过多规则。

更重要的是，要区分“工程上的可用”和“原型上的有效”。工程上的可用，强调稳定、兜底和体验完整；原型上的有效，则强调核心假设是否被真实验证。

如果一个 AI 功能失败了，我宁愿它在原型阶段直接失败，让我看到问题在哪里，也不希望它悄悄退化成一个规则系统，这也是我最近使用 Coding Agent 最大的感受之一：AI 不仅会帮我们写代码，也会帮我们“过度工程化”。它很擅长把一个想法包装成完整项目，但有时候，我们需要主动提醒它——现在不是在做一个完美产品，而是在验证一个不确定的想法。

对于 AI 应用开发来说，原型阶段最重要的不是把每条路都铺平，而是让真正关键的那条路暴露出来。如果 AI 能力是这个项目的核心，那就不要太早给它准备一条可以绕开的路。