NOTES · 学习笔记
Harness 工程:通过 Pi Agent 认识 Agent 运行框架
Harness 工程是什么?
Harness 原意是“安全带、马具、控制装置”。
在 AI Agent 中,harness 是包围着大模型的一套运行系统。它负责让模型不只是“聊天”,而是能够:
- 理解任务
- 查看上下文
- 选择工具
- 执行操作
- 获取执行结果
- 继续工作
- 保存过程
- 在必要时停止、重试或恢复
因此:Harness 工程,就是设计和实现“如何让大模型稳定、可控、可观测地完成任务”的工程。
它不是单独研究模型本身,而是研究:模型如何被组织、约束、调用和管理。
为什么需要 Harness?
大模型本身主要做一件事:根据输入生成输出。
例如你问:“当前目录有哪些文件?”模型可以生成:“我需要查看当前目录。”
但模型本身通常不能真正访问你的电脑。它需要一个外部系统:
模型:我想调用 bash 查看目录
Harness:好的,我来执行 bash
Harness:执行结果是这些文件
模型:根据结果回答用户所以模型和 Harness 的职责不同:
大模型:理解信息、推理、决定下一步
Harness:提供上下文、执行工具、控制流程、保存状态Harness:运行框架
Harness 是承载 Agent 的运行框架。它负责把模型、工具、上下文、session 和控制逻辑连接起来:
Harness
├── 调用模型
├── 提供上下文
├── 注册工具
├── 执行工具
├── 把工具结果交还给模型
├── 决定是否继续
├── 保存会话
├── 处理错误和重试
└── 提供扩展接口Harness 工程由什么组成
我们把它拆分为 8 个部分。
1. Agent Loop:智能体循环
这是 Harness 的控制核心。基本流程是:
用户输入
↓
组装上下文
↓
请求模型
↓
模型返回文字或工具调用
↓
如果是工具调用:
执行工具
把结果加入上下文
再次请求模型
↓
如果是最终回答:
结束抽象成状态转换:
等待模型
├── 返回工具调用 → 执行工具 → 回到等待模型
└── 返回最终回答 → 结束这就是 Agent Loop。它解决的问题是:模型输出之后,系统下一步该做什么?
2. Context Assembly:上下文组装
模型每次做决定时,都需要输入上下文。上下文可能包括:
- 系统提示
- 用户消息
- 历史对话
- 工具定义
- 工具执行结果
- 项目说明文件
- 技能说明
- 当前工作目录
Harness 需要决定:
- 哪些内容应该发送给模型?
- 按什么顺序发送?
- 内容太长怎么办?
- 哪些内容应该隐藏或压缩?
- 工具结果如何转换成模型能理解的消息?
例如一次模型请求可能被组装成:
System:
你是一个 coding agent
Tools:
bash(command)
read(path)
edit(...)
History:
用户:查看当前目录
模型:调用 bash
工具:发现学习记录.md
Current task:
请总结目录内容模型看到的不是单纯的用户问题,而是 Harness 组装后的完整上下文。
3. Tool System:工具系统
工具是模型与外部世界交互的接口。例如:
read → 读取文件
bash → 执行命令
edit → 修改文件
write → 写入文件
一个工具通常包含:
- 工具名称
- 工具描述
- 参数定义
- 参数校验
- 执行函数
- 执行结果格式
- 错误处理
- 权限控制
4. Session:会话持久化
Harness 不应该只在内存里运行。它通常需要保存:
- 用户消息
- 模型消息
- 工具调用
- 工具结果
- 错误
- 模型切换
- 压缩记录
- 分支关系
这样才能支持:继续上次会话、查看历史、从某一步创建分支、恢复中断的任务、进行上下文压缩。
Pi 的 session 文件就是这种持久化机制。可以理解为:
Session = Agent 工作过程的可恢复记录5. Control and Safety:控制与安全
Agent 可能会执行命令、修改文件、删除内容、访问网络、调用外部服务,所以 Harness 必须控制:
- 哪些工具可用
- 哪些参数允许
- 哪些路径可访问
- 是否需要用户确认
- 命令执行时间限制
- 输出长度限制
- 失败后如何处理
例如:
模型要求执行 rm -rf
↓
Harness 检查权限
↓
拒绝执行或要求确认模型的“想法”不应该自动等于系统的“动作”。
这是非常重要的一句话:模型负责提出行动,Harness 负责决定行动能否真正发生。
6. Error and Retry:错误与恢复
模型请求和工具执行都可能失败:
- 模型 API 超时
- 模型返回格式错误
- 工具参数不合法
- 命令执行失败
- 上下文超过限制
- 网络暂时不可用
Harness 需要决定:
- 是否重试?
- 重试几次?
- 是否等待后重试?
- 是否压缩上下文后重试?
- 是否把错误交给模型处理?
- 是否直接结束?
例如:
工具执行失败
↓
Harness 把错误结果交给模型
↓
模型决定换一种命令重试或者:
API 暂时不可用
↓
Harness 自动等待
↓
重新请求模型7. Observability:可观测性
如果只看到最终回答,我们不知道 Agent 中间发生了什么。Harness 通常需要记录事件:
agent_start
turn_start
模型消息
工具开始
工具结束
工具结果
turn_end
agent_end可观测性让我们能够回答:
- 模型做了什么决定?
- 调用了什么工具?
- 工具花了多长时间?
- 哪一步失败了?
- 为什么 Agent 没有继续?
- 是否发生了重试?
- 最终消耗了多少资源?
没有可观测性,Agent 出问题时很难调试。
8. Extension and SDK:扩展与嵌入
成熟的 Harness 不能把所有功能写死。它通常允许外部扩展:
- 增加新工具
- 监听事件
- 修改上下文
- 增加命令
- 增加模型 provider
- 自定义 UI
- 嵌入到其他程序
在 Pi 中:
- Extension:向运行中的 Pi 注册工具、事件处理器、命令等
- SDK:让其他程序创建和控制 Pi 的 Agent session
- Skill:给模型提供可复用的领域指令和知识
我们拿 Pi Agent 来举例子
你:修复这个 bug
↓
Pi:把任务、项目上下文和工具定义交给模型
↓
模型:读取相关文件
↓
Pi:执行 read 工具
↓
Pi:把文件内容交给模型
↓
模型:提出 edit 操作
↓
Pi:执行 edit 工具
↓
Pi:把修改结果交给模型
↓
模型:运行测试
↓
Pi:执行 bash 工具
↓
模型:根据测试结果总结
↓
Pi:保存完整 session