Agent harness：让一次模型决策变成可运行的任务
围绕一个会中断、会重试的资料整理任务，拆解 harness 的执行环境、工具边界、预算、运行记录与恢复职责，并说明它与 loop、graph 的关系。
延伸分析 · 从项目场景展开的原理与方案讨论。
- AI 学习
- Harness
- Agent 工程
- 任务恢复
同一个模型，在网页聊天框里可以给出建议，在编程工具里却能读文件、执行命令和检查产物。模型能力之外，还需要一层程序，把输出连接到实际环境，并管理整段任务。讨论 agent 时，这一层经常被称为 harness。
用整理资料来打比方：模型负责提出“下一步查什么”，harness 负责让这一步真正跑起来，并处理执行过程。 它需要能找到资料、保存草稿，还要知道任务停在哪里。只有建议而没有这些程序，助手就不能实际交付文件。
这个词没有一套在所有项目中都一致的模块清单。阅读资料时，先看作者把哪些职责放进了 harness，再比较不同实现。
loop、graph 和 harness 可以同时存在
本文把 harness 理解为支撑 agent 运行的程序层。Anthropic 在 Managed Agents 的架构介绍中，把调用模型并分派工具的 harness，与记录历史的 session、执行代码的 sandbox 分开。另一些讨论会用更宽泛的 harness 指代周围的整套支撑设施。
为了学习，可以按要回答的问题来划分：
| 概念 | 主要问题 |
|---|---|
| Loop | 模型和工具如何反复交互，何时停止？ |
| Graph | 当前状态对应哪个节点，下一条路径是什么？ |
| Harness | 这些动作在哪里运行，允许做什么，失败后留下什么？ |
它们不是三款只能选一个的框架。一个 harness 可以运行一个简单 loop，也可以驱动带分支的 graph；图中的节点还可以再包含一个 loop。
从“整理并保存笔记”列出实际依赖
假设任务要求读取用户给定的资料，生成 notes/agent-runtime.md。把它交给模型之前，需要落实几个具体问题：
- 搜索和读文件的工具是否可用，返回值是否有稳定结构？
- 工作目录是哪一个，保存路径如何解析？
- 用户只要求保存草稿，还是也允许发布？
- 工具等待过久、进程退出或额度耗尽时，任务怎样呈现？
- 最后由什么证据判断笔记确实生成？
这些约定可以体现在代码、工具注册表、配置和执行记录中。提示词负责解释任务，执行器仍要实际检查路径与权限；给提示词写一句“请只修改 notes 目录”，不会自动形成文件系统隔离。
下面的清单是教学用自定义格式，不是可直接交给某个产品的配置文件：
{
"runId": "research-042",
"workspace": "/workspace/research-042",
"allowedTools": ["read_source", "save_note"],
"outputPath": "notes/agent-runtime.md",
"limits": {"modelCalls": 12, "toolCalls": 20},
"completionChecks": ["file_exists", "required_sections", "source_support"]
}数字只是演示预算，并非推荐的通用配额。真正的边界取决于工具实现：例如写文件前解析规范化路径，处理符号链接，确认结果仍在允许的目录中；仅检查字符串是否以 notes/ 开头不够。
恢复任务，需要一份能接手的记录
运行到一半退出后，下一次执行不能只看到“继续努力”。它至少需要知道目标、已经完成的操作、产物位置、未解问题和下一步。
目标：整理执行方式，保存草稿，不发布
已完成：读完两份资料；草稿保存到 notes/agent-runtime.md
已验证：文件存在，包含 Loop 和 Graph 两节
未验证：第三节引用是否支持结论
下一步：核查第三节引用，再执行完整验收这是一份自拟的交接记录。它保留了“已完成”和“已验证”的区别。恢复时先检查文件当前状态，避免把旧记录当成实时事实；文件可能被人修改，也可能上次保存根本没有完成。
Anthropic 的长任务 harness 实验展示过初始化环境与后续增量工作配合、用工件连接不同会话的做法。这是一种设计参考，不能推导出任何任务只要写了进度文件就能可靠恢复。
超时与重试需要执行记录配合
假设保存操作实际上已经成功，但客户端没有收到响应。若只记“失败，待重试”，下一轮可能重复创建笔记；若直接记“完成”，又可能漏掉真正未写入的情况。
执行记录可以保留操作标识、输入摘要和 unknown 状态，恢复时先核对目标文件或服务端状态。具体去重和幂等约定见工具重试。harness 把这些步骤组织起来，不会让外部系统的限制消失。
这里的“幂等”可以先理解成：同一次操作重复提交，不会重复产生业务结果。例如保存同一份草稿的请求重发一次，不应凭空多创建一份笔记。具体怎样保证，需要接收请求的一方配合。
不必一次搭出完整平台
做第一个学习版本时，可以只有一个工作目录、一个只读工具、一段受限循环和一份运行日志。等到明确出现跨进程恢复、并发任务或外部写操作，再为这些问题补相应机制。
一个有用的练习是：保存草稿后主动结束进程，重新启动并读取交接记录。新运行能否找到同一份草稿，指出尚未验证的部分，而不是从头生成或直接宣布成功？这个问题比工具列表有多长更能检验 harness 的实际作用。
继续阅读：上下文、执行状态与长期记忆，以及怎样验证最终结果。