Pi 的 AgentHarness v2：持久化 AI Agent 的革命性设计

前言：为什么需要 AgentHarness？

在 AI 时代，我们面临三个核心问题：

1. 持久化问题

• Agent 崩溃后，上下文丢失
• 重新开始，重复工作
• 无法恢复到崩溃前的状态

2. 并发问题

• 无法并行处理多个任务
• 资源利用率低
• 响应慢

3. 可观察性问题

• 无法追踪 Agent 的执行过程
• 调试困难
• 优化无从下手

AgentHarness v2 是 Pi 对这些问题的革命性解决方案。

---

一、AgentHarness v2 是什么？

一句话定义

AgentHarness v2 是一个持久化的 AI Agent 执行框架。

核心思想：

• 持久化运行（Durable runs）
• 持久化响应（Durable responses）
• 通道并行（Lanes）
• 确定性步进（Deterministic stepping）
• 可观察性（Observability）

架构图

核心组件：

• Harness - 执行引擎
• Lanes - 并行工作通道
• Session - 持久化状态
• Storage - 存储后端
• Observability - 可观察性

---

二、Session 的四大组成部分

1. The Tree（对话树）

定义：对话的完整历史。

特点：

• 只增长，不修改
• 父子链接（parentId）
• 共享、被动

包含：

• 消息（messages）
• 压缩摘要（compaction summaries）
• 分支摘要（branch summaries）
• 自定义条目（custom entries）

价值：

• 完整保留对话历史
• 支持分支和导航
• 轻量级复制（共享前缀）

2. Lanes（工作通道）

定义：工作发生的地方。

特点：

• 每个通道最多一个操作
• 通道并行运行
• 通道拥有自己的叶子节点

示例：

• main - 主通道
• slack:171943... - Slack 线程通道
• email:thread-id - 邮件线程通道

价值：

• 并行处理多个任务
• 隔离不同上下文
• 灵活的扩展性

3. Lane Records（通道记录）

定义：通道的配置和执行历史。

特点：

• 平坦的、按时间顺序的记录序列
• 包含配置和操作记录
• 崩溃后重建的权威来源

包含：

• lane_config - 总配置
• operation_started - 操作开始
• step_started - 步骤开始
• attempt_started - 尝试开始
• tool_batch_planned - 工具批计划
• message_queued - 消息排队
• operation_finished - 操作完成

价值：

• 可追溯的执行历史
• 崩溃后精确恢复
• 调试和审计

4. Global Facts（全局事实）

定义：会话作用域的值。

特点：

• 最新写入获胜
• 追加历史
• 独立命名空间

包含：

• 内置事实（session name、entry labels）
• 自定义事实（custom namespace）

价值：

• 会话级别的元数据
• 扩展机制
• 轻量级状态

---

三、Lanes：并行工作的革命

什么是 Lane？

类比：Lane 就像 Git 分支，有自己的工作树。

核心特性：

• 命名的树位置
• 拥有叶子节点
• 拥有操作日志
• 拥有队列
• 拥有总配置

Lane 的生命周期

状态说明：

• Idle - 空闲，无操作
• Running - 运行中
• Suspended - 挂起（崩溃或延迟）
• Cancelling - 取消中

Lane 的并行规则

规则 1：通道并行运行

• 每个通道独立执行
• 共享序列号
• 单一写入者

规则 2：创建不复制内容

• 只建立指针
• 从种子配置开始
• 原子操作

规则 3：状态依赖线性化

• 验证 → 原子追加 → 内存更新
• 提供者/工具/钩子不占用

规则 4：同叶子不同通道会分叉

• 下一次追加时分叉
• 无需协调

---

四、Operations：持久化工作单位

三种操作类型

1. Run（运行）

• 接受的提示
• 所有自动延续（工具调用、转向、后续、自动压缩）
• 无待处理时结束

2. Compaction（压缩）

• 用摘要条目替换旧上下文
• 减少上下文大小
• 优化性能

3. Navigation（导航）

• 移动通道叶子到现有条目
• 可选分支摘要
• 不重写历史

Runs, Turns, 和 Steps

层次结构：

Run（运行）
  └── Turn（回合）
      └── Step（步骤）
          └── Attempt（尝试）

Step（步骤）：

• 持久化逻辑单位
• 分配稳定的 stepId
• 快照配置和重试策略
• 跨重启持久化

Generation Step（生成步骤）：

• 启动新的 LLM 生成
• 助手响应、压缩摘要、分支摘要

Deferred-Fetch Step（延迟获取步骤）：

• 轮询现有提供者工作
• 稳定的 stepId
• 自包含的轮询

工具批处理

流程：

1. 接受助手响应
2. 创建持久化计划
3. 分配结果条目 ID
4. 工具查找、参数验证、before_tool
5. 执行

特性：

• 源顺序保留
• 并行效果、顺序最终化
• 崩溃后恢复

---

五、Queues 和 Deferred Writes

两种输入机制

Queues（队列）：

• 携带对话意图
• steer - 修正当前工作
• followUp - 添加后续工作
• nextRun - 下次运行的种子

特性：

• 取消时死亡
• 返回给调用者
• 不会持久化

Deferred Writes（延迟写入）：

• 携带树添加请求
• 步骤飞行中请求
• 存活取消

特性：

• 持久化
• 取消时应用
• 模型首次看到

Checkpoints（检查点）

回合之间：

1. 应用待处理的延迟写入
2. 消费排队的转向消息
3. 如果下一个请求不适合则压缩

压缩触发：

• 主动（检查点）
• 反应（响应揭示不适合）

溢出恢复：

• 一次压缩链接到响应和 triggerMessageId
• 第二次相同触发失败
• 新用户消息允许新压缩

---

六、持久化保证

Durable Runs（持久化运行）

承诺：接受的提示是持久化操作。

特性：

• 崩溃后重建
• 从最后持久化边界恢复
• 每个状态可恢复

Durable Responses（持久化响应）

承诺：每个完整响应在分类前追加。

包含：

• 可重试错误
• 溢出
• 延迟
• 中止

No Partial Outcomes（无部分结果）

承诺：任何操作内的崩溃留下两种状态之一。

状态：

• 操作未发生
• 恢复可完成

中间状态：不可观察

---

七、可观察性和可测试性

Observability（可观察性）

承诺：所有执行都可仪器化。

范围：

• 提供者请求和响应内部
• 工具执行
• 钩子执行
• 完整追踪

Deterministic Stepping（确定性步进）

承诺：每个效果跨越一个注入边界。

特性："

• drive: "manual" - 停在每个边界
• 测试逐个调用驱动
• 停止在任何边界
• 注入输入
• 关闭并重新打开模拟崩溃

价值：

• 生产测试相同过程
• 可重复测试
• 完整覆盖

---

八、UI 模型

快照 + 事件流

流程：

1. 客户端获得原子快照
2. 实时事件流
3. 事件不重放
4. 重连意味着新快照

价值：

• 简单的客户端模型
• 一致的状态
• 易于实现

---

九、实际应用

场景 1：Slack 集成

架构：

• 一个 Session = 一个 Slack 频道
• 一个 Lane = 一个线程
• 并行处理多个线程

价值：

• 每个线程独立上下文
• 共享频道历史
• 崩溃后恢复

场景 2：邮件集成

架构：

• 一个 Session = 一个邮件线程
• 一个 Lane = 一个回复线程
• 并行处理多个回复

价值：

• 每个回复独立上下文
• 共享邮件历史
• 持久化草稿

场景 3：交互式 Pi

架构：

• 一个 Session = 一个对话
• 一个隐藏 Lane = 内部操作
• 外部不可见

价值：

• 干净的 UI
• 强大的内部能力
• 持久化状态

---

十、技术实现

存储后端

支持：

• Memory（内存）
• JSONL（文件）
• SQLite（数据库）

特性：

• 可插拔
• 相同接口
• 性能优化

扩展机制

Hooks（钩子）：

• 拦截执行
• 改变上下文、请求、工具
• 自定义逻辑

Events（事件）：

• 观察执行
• 不可改变
• 日志和追踪

Extensions（扩展）：

• 构建在钩子和事件上
• 自定义能力
• 社区贡献

---

十一、对比分析

vs 传统 Agent 框架

维度	传统框架	AgentHarness v2
持久化	无	完整持久化
并发	单线程	多通道并行
可观察性	有限	完整追踪
崩溃恢复	无	自动恢复
可测试性	困难	确定性步进

vs 分布式系统

维度	分布式系统	AgentHarness v2
一致性	CAP 定理	单写入者
持久化	复制	单位置
协调	需要	无需
扩展性	水平	垂直

---

十二、最佳实践

1. 使用 Lanes

场景：

• 多线程对话（Slack、Discord）
• 多任务并行
• 独立上下文

实践：

• 为每个线程创建 Lane
• Lane 名称使用外部 ID
• 共享历史，独立工作

2. 利用持久化

场景：

• 长时间运行的任务
• 崩溃恢复
• 状态重放

实践：

• 依赖持久化保证
• 设计可重放的操作
• 测试崩溃恢复

3. 可观察性

场景：

• 调试
• 性能优化
• 审计

实践：

• 启用完整追踪
• 记录所有事件
• 分析执行路径

4. 测试

场景：

• 单元测试
• 集成测试
• 崩溃测试

实践：

• 使用 drive: "manual"
• 测试每个边界
• 模拟崩溃

---

十三、未来展望

从 v2 到 v3

可能的改进：

• 更多存储后端
• 更好的压缩算法
• 更丰富的钩子系统
• 更强的可观察性

生态系统

可能的扩展：

• 社区贡献的 Hooks
• 共享的 Templates
• 开放的 Plugins
• 标准化的 Extensions

---

十四、总结

核心价值

1. 持久化运行

• 崩溃后恢复
• 无状态丢失
• 可靠性

2. 持久化响应

• 完整保存
• 可追溯
• 可审计

3. 通道并行

• 高效并发
• 独立上下文
• 灵活扩展

4. 确定性步进

• 可测试
• 可重复
• 可调试

5. 可观察性

• 完整追踪
• 性能优化
• 问题诊断

核心思想

AI Agent 不应该是脆弱的。它应该像数据库一样持久化，像分布式系统一样可靠，像微服务一样可观察。

AgentHarness v2 让这一切成为可能。

三个关键点

1. 持久化优先：

• 所有操作都持久化
• 崩溃后自动恢复
• 无状态丢失

2. 通道并行：

• 多个任务并行执行
• 独立上下文
• 高效资源利用

3. 可观察性：

• 完整追踪
• 确定性步进
• 易于测试和调试

记住

AgentHarness v2 不是框架，而是范式。

它重新定义了 AI Agent 的持久化、并发和可观察性。

这就是 Pi 的 AgentHarness v2。

---

参考资源

• Pi：https://github.com/earendil-works/pi
• AgentHarness v2 文档：https://github.com/earendil-works/pi/blob/main/packages/agent/docs/harness-v2.md
• 设计讨论：GitHub Issues

---

声明：本文基于官方设计文档，具体实现请参考源代码。