NOTES · 学习笔记

Harness 工程:通过 Pi Agent 认识 Agent 运行框架

Harness约 6 分钟

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