什么是 Agent Harness
@[toc]
## 从“会回答”到“能完成任务”
假设你让模型修复一个 Python 程序。聊天模型可以给出修改建议，但要把建议变成结果，还需要读取文件、执行修改、运行测试，再根据真实错误继续调整。模型之外负责这些动作、上下文和约束的运行环境，就是本教程要构建的 **Agent Harness**。
Harness 原意可以理解为承载、连接和约束系统的装置。在 Agent 开发中，它为模型提供观察环境与采取行动的接口。模型决定下一步做什么，Harness 负责让动作真正发生，并把结果送回模型。
## 模型、Agent 与 Harness 怎么区分
本专栏把“模型”理解为负责理解任务、推理和选择动作的部分，把“Agent 系统”理解为模型、工具、状态与执行循环组成的整体。Harness 是围绕模型搭建的运行环境，负责提供信息、执行动作并实施约束。
例如模型可以判断“先读配置，再运行测试”，但它不会凭空拥有你的文件和终端。Harness 将读取工具与命令工具提供给它，并负责把真实结果反馈回来。确定性步骤也可以由程序直接控制，实际系统常把工作流与模型决策结合使用。
| 部分 | 负责什么 | 编程场景示例 |
| --- | --- | --- |
| 模型 | 理解目标、分析信息、选择动作 | 决定先读配置还是先运行测试 |
| 工具 | 执行明确的操作 | 读文件、替换文本、运行命令 |
| 知识 | 提供领域方法和资料 | 项目规范、API 文档、Skill |
| 上下文 | 承载当前可见的信息 | 对话历史、工具结果、任务摘要 |
| 持久状态 | 保存跨会话目标和进度 | 任务 JSON、团队名册、事件日志 |
| 权限 | 约束哪些动作可以执行 | 目录边界、沙箱、审批与预算 |
## 最小闭环长什么样
阅读后续代码前，先认识三个常见词：**Schema** 是参数格式说明；**handler** 是接收参数并实际执行操作的函数；**上下文** 是本次模型请求能够看到的提示、消息历史和工具结果。它们分别回答“怎么调用”“谁来执行”“模型现在知道什么”。
下面先展示最小循环的核心片段，帮助理解流程。它用到的 client、MODEL、SYSTEM、TOOLS 和 run_bash 会在下一篇“Agent 循环”中与完整程序一起给出；本篇先理解闭环即可。
```python
def agent_loop(messages: list):
while True:
response = client.messages.create(
model=MODEL, system=SYSTEM, messages=messages,
tools=TOOLS, max_tokens=8000,
)
# Append assistant turn
messages.append({"role": "assistant", "content": response.content})
# If the model didn't call a tool, we're done
if response.stop_reason != "tool_use":
return
# Execute each tool call, collect results
results = []
for block in response.content:
if block.type == "tool_use":
print(f"\033[33m$ {block.input['command']}\033[0m")
output = run_bash(block.input["command"])
print(output[:200])
results.append({"type": "tool_result", "tool_use_id": block.id,
"content": output})
messages.append({"role": "user", "content": results})
```
可以按四个动作读这段代码：
1. 把现有 messages 和工具定义一起发给模型。
2. 保存模型响应，让后续请求能够看到已经发生的工具调用。
3. 如果存在 tool_use，执行工具并用 tool_use_id 关联结果。
4. 把 tool_result 放回消息列表，再调用模型；没有工具调用时退出。
这形成了“观察 → 决策 → 行动 → 反馈”的闭环。它让模型能根据实际输出修改方案，但不会自动保证任务成功。运行测试、检查退出码和确认交付物仍是必要步骤。
## Harness 工程师要解决哪些问题
首先是工具设计。工具名称和参数应明确，失败结果要能帮助模型修正动作。其次是知识组织：让模型先看到简短索引，再按需加载领域说明。然后是上下文管理：把局部调查交给子 Agent，把重复长输出移出活跃历史，将重要目标保存在磁盘。
当任务变大，还需要异步执行、团队消息与目录隔离。后台任务解决等待，团队邮箱解决协作通信，任务系统解决目标与依赖，worktree 解决工作目录分离。这些机制各自处理不同问题，不能用“多开几个 Agent”替代全部工程设计。
权限同样属于 Harness：不应只靠提示词告诉模型“不要越界”。文件路径、命令权限和需要授权的动作，要在执行入口做明确检查。教学代码展示机制，生产系统还需要更完整的保护与恢复能力。
## 专栏学习路线
本专栏共 13 篇：本篇导读，加上 s01 到 s12 的十二个机制。所有文章放在“Agent Harness 教程”目录中，按编号阅读即可。
| 文章 | 核心机制 | 学习结果 |
| --- | --- | --- |
| 01｜Agent 循环：让模型真正动手 | agent_loop | 理解 messages、tool_use、tool_result 和 stop_reason 如何组成最小执行闭环。 |
| 02｜工具调用：设计可扩展的工具层 | tool_use | 掌握工具 Schema、处理函数与分发字典之间的关系，并理解路径校验的边界。 |
| 03｜Todo 规划：让多步任务有进度 | todo_write | 实现带状态校验的 TodoManager，并理解进度提醒怎样进入上下文。 |
| 04｜子 Agent：隔离上下文，拆解复杂任务 | subagent | 理解独立 messages 列表、工具权限差异，以及父子 Agent 之间的结果边界。 |
| 05｜Skill 加载：按需提供领域知识 | skill_loading | 理解 Skill 的两层加载方式，并实现从 SKILL.md 到工具结果的知识通道。 |
| 06｜上下文压缩：为长任务保留关键记忆 | context_compact | 区分微压缩、自动摘要和手动压缩，并理解压缩会带来的信息损失。 |
| 07｜任务系统：持久化目标与依赖关系 | task_system | 掌握任务 JSON 文件、状态流转与 blockedBy 依赖解除机制。 |
| 08｜后台任务：让慢操作与思考并行 | background_tasks | 理解后台任务 ID、执行线程、状态查询与结果通知队列。 |
| 09｜Agent 团队：用异步邮箱协调队友 | agent_teams | 理解团队名册、独立循环和 JSONL 邮箱，区分持久化身份与常驻执行。 |
| 10｜团队协议：让请求与审批形成闭环 | team_protocols | 掌握 request_id 关联机制，以及 pending、approved、rejected 状态机。 |
| 11｜自治 Agent：主动认领任务与恢复工作 | autonomous_agents | 理解 WORK 与 IDLE 两阶段、自动认领条件和身份重注入。 |
| 12｜Worktree 隔离：为任务建立独立工作区 | worktree_task_isolation | 理解任务与 worktree 的双向关联、隔离命令执行，以及保留和删除的生命周期。 |
前六课建立单 Agent 的工具、规划与上下文能力；第七、八课引入持久任务与后台执行；后四课讨论团队、协议、自治和工作区隔离。后续十二篇教程都贴出独立运行所需的完整代码，工具集合不保证逐课累加。
## 开始前需要准备什么
开始学习只需准备两样东西：
1. **Python 3.10 或更高版本。** 用于运行后续教程提供的程序。
2. **可用的 Anthropic 兼容接口。** 准备好 API 密钥、接口支持的模型名称；使用兼容服务时还需要接口地址。接口应支持 Anthropic Messages 协议和工具调用。
后续每篇教程都会直接给出完整的可运行代码、依赖安装命令、配置说明和所需的练习材料。到对应章节时，按步骤创建文件、粘贴代码，填写你自己的接口配置即可运行。
下一篇从最小 Agent 循环开始：用完整程序创建文件、运行命令，再读取真实结果。导读篇先建立概念，不需要先启动任何程序。
## 这套教程能带你走到哪里
学完后，你应能说明一个 Agent 系统怎样调用工具、规划工作、管理记忆、持久保存任务，以及怎样让多个执行者协作。你也应能识别教学实现与生产要求的差距：完整权限治理、可靠消息投递、事务认领、会话恢复与 MCP 运行时并未在这里全部实现。
更换领域时，闭环思路仍然有用。例如客服系统把文件工具换成知识检索与工单接口，研究助手把命令执行换成文献检索与实验工具；工具、知识和授权边界都要随业务变化重新设计。
本教程围绕编程 Agent 的常见机制展开，重点是理解并亲手搭建 Harness。模型能力和环境质量共同决定结果，好的 Harness 能让动作更可控、结果更可验证。