理解OpenHarness核心概念:无状态Agent、事件流与工具循环,5大关键设计深度解析
理解OpenHarness核心概念:无状态Agent、事件流与工具循环,5大关键设计深度解析
OpenHarness 是一个基于 Vercel AI SDK 的开源 AI Agent 框架,用代码即可构建通用的 AI 智能体。对于新手来说,上手 OpenHarness 的关键是理解它的核心概念:无状态 Agent、类型化事件流、多步工具循环、有状态 Session 和可组合 Middleware。本文用通俗的类比和少量示例,带你一次性读懂这 5 大关键设计,帮你快速搭建自己的 Agent 应用。
一图看懂整体架构:谁负责什么?
在深入细节之前,先建立一个整体认知。OpenHarness 把"让 AI 干活"这件事拆成了四层,各层职责清晰、层层组合:
| 层级 | 核心类 | 职责 | 一句话类比 |
|---|---|---|---|
| 执行层 | Agent |
无状态执行器:跑模型、调工具、吐事件 | 一台"不记事"的发动机 |
| 事件层 | AgentEvent |
类型化事件流:文本增量、工具调用、步骤结束 | 发动机运转时的实时仪表盘 |
| 会话层 | Session |
有状态管理:历史、压缩、重试、持久化 | 给发动机装上"记忆 + 保险" |
| 组合层 | Runner / Middleware / Conversation |
中间件自由拼装:只装你需要的能力 | 乐高式积木,随取随用 |
💡 理解了这四层分工,你就理解了 OpenHarness 80% 的设计。下面逐个拆解。
核心概念一:无状态 Agent,为什么"不记事"反而更灵活?
Agent 是 OpenHarness 的核心原语。它把一个语言模型、一组工具和一个多步执行循环封装在一起,但它本身是无状态的——不内部累积任何对话历史。
工作方式非常简洁:
const agent = new Agent({
name: "dev",
model: openai("gpt-5.4"),
tools: { ...fsTools, bash },
maxSteps: 20,
});
// 传入历史 history + 新输入 input,事件流式产出
for await (const event of agent.run(history, "重构 auth 模块")) {
if (event.type === "text.delta") console.log(event.text);
}
run() 是一个异步生成器:你传入历史消息,它边执行边"吐"事件,最后通过 done 事件把更新后的完整历史还给你。下一轮对话时,把这份历史再传进去即可实现多轮交互。
为什么这样设计? 好处有三点:
- 完全掌控历史——你可以随时检查、修改、裁剪,甚至把同一份历史共享给多个 Agent;
- 易于测试和复用——无副作用的执行器,天然适合单元测试(参见 agent.ts 中
Agent类的定义); - 可预测——输入决定输出,没有隐藏的内存状态。
事件类型的完整定义见 AgentEvent,这是整个框架的"通用语言"。
核心概念二:类型化事件流,Agent 干活的"实时仪表盘"
agent.run() 不是一次性返回结果,而是流式产出一系列类型化事件。每一种事件都精确对应 Agent 运转中的一个动作:
| 事件 | 含义 | 典型用途 |
|---|---|---|
text.delta / text.done |
模型文本增量 / 整段完成 | 打字机效果的实时渲染 |
reasoning.delta / reasoning.done |
推理/思考过程增量与完成 | 展示"思考中"面板 |
tool.start / tool.done / tool.error |
工具调用开始 / 成功 / 失败 | 展示"正在读取文件…"状态 |
step.start / step.done |
一个 Agent 步骤的开始 / 结束(含 token 用量) | 进度指示、成本统计 |
error |
执行出错 | 错误提示 |
done |
结束,result 为 complete / stopped / max_steps / error |
拿到最终消息与总用量 |
以 CLI 场景为例,事件流让你能精确呈现每个阶段:
for await (const event of agent.run(messages, "列出所有文件")) {
switch (event.type) {
case "text.delta": process.stdout.write(event.text); break;
case "tool.start": console.log(`正在调用 ${event.toolName}…`); break;
case "tool.done": console.log(`${event.toolName} 完成`); break;
case "done": messages = event.messages; break;
}
}
🎯 这种设计让 UI 层无需关心 Agent 内部实现,只需订阅事件即可渲染任何界面——CLI、React、Vue 通用。
此外,OpenHarness 还提供了 4 个轻量级的流操作符(stream.ts):tap(旁路观察)、filter(过滤事件)、map(转换事件)、takeUntil(提前终止),方便对事件流做管道式加工。
核心概念三:工具循环,让 Agent 真正"动手"干活
"工具循环"(agentic tool loop)是 Agent 与聊天机器人的本质区别:模型不是一次性回答,而是反复执行"思考 → 调工具 → 看结果 → 再思考",直到任务完成或达到上限。
OpenHarness 的工具循环机制包括三个要点:
1. 多步循环由 maxSteps 兜底
每一步(step)模型可能发起多个工具调用。maxSteps(默认 100)限制最大步骤数,防止模型陷入无限循环,超限后 done 事件的 result 会是 max_steps。核心循环逻辑在 Agent.run() 中实现。
2. 内置工具开箱即用
工具基于 Vercel AI SDK 的 tool() 助手 + Zod 校验,内置工厂函数直接可用:
- 文件系统工具:
readFile、writeFile、editFile、listFiles、grep、deleteFile(create-fs-tools.ts) - Bash 工具:执行 shell 命令,支持超时和输出截断(create-bash-tool.ts)
3. approve 审批回调守住安全门
默认所有工具调用都被放行。传入 approve 回调后,每次工具执行前都会询问你——返回 true 放行,false 拒绝。被拒绝的调用会以工具错误形式反馈给模型,让它自行调整策略。这让"读操作自动放行、写操作需人工确认"这类权限策略轻松落地。
const agent = new Agent({
name: "safe-agent",
model: openai("gpt-5.4"),
tools: { ...fsTools, bash },
approve: async ({ toolName }) => {
const readOnly = ["readFile", "listFiles", "grep"];
return readOnly.includes(toolName) || askUser(`允许 ${toolName}?`);
},
});
🔁 工具循环 + 事件流 + 审批回调三者结合,就是 Claude Code 类智能体"自主干活且可控"的秘密。
核心概念四:Session,给无状态 Agent 装上"记忆与保险"
无状态很灵活,但真实的多轮对话需要三样东西:记住历史、上下文爆了能压缩、网络抖动能重试。这正是 Session 存在的意义——它包裹一个 Agent,自动处理这一切:
const session = new Session({ agent, contextWindow: 128_000 });
for await (const event of session.send("列出所有 TypeScript 文件")) {
if (event.type === "text.delta") process.stdout.write(event.text);
}
// 再发一条——Session 自动记得上文
for await (const event of session.send("把最大的那个重构一下")) {
if (event.type === "text.delta") process.stdout.write(event.text);
}
Session(session.ts)内置四大能力:
- 自动压缩(Compaction):对话接近上下文窗口时自动触发,分两阶段——先剪枝旧工具结果(无需调用模型),剪不出来再用模型生成结构化摘要替换整段历史;
- 自动重试(Retry):429/500/502/503 等瞬时错误按指数退避 + 抖动自动重试,且只在尚未产出任何内容前才重试,避免重复副作用;
- 持久化(Persistence):实现
SessionStore接口即可接入任意存储(内存、SQLite、数据库),每轮结束后自动保存; - 生命周期钩子(Hooks):
onBeforeSend/onAfterResponse/onCompaction/onError,在每个节点插桩定制。
session.send() 除产出全部 AgentEvent 外,还额外发出 turn.start、turn.done、compaction.*、retry 等生命周期事件,让你对"幕后操作"也了如指掌。
核心概念五:可组合 Middleware,只装你需要的积木
Session 把压缩、重试、持久化、钩子捆绑成一个类。如果你只想挑其中几样,或想写自定义逻辑,就用 Runner / Middleware / Conversation 这套函数式 API:
Runner:与agent.run()同形的异步生成器函数(runner.ts);Middleware:一个"把 Runner 变成 Runner"的函数,apply()按顺序组合,pipe()打包成可复用管道;Conversation:组合好 Runner 后的轻量有状态封装,自动从done事件更新消息历史(conversation.ts)。
import {
Conversation, toRunner, apply,
withTurnTracking, withCompaction, withRetry,
} from "@openharness/core";
// 只组合你需要的中间件,顺序即包装层次
const runner = apply(
toRunner(agent),
withTurnTracking(),
withCompaction({ contextWindow: 200_000, model: agent.model }),
withRetry({ maxRetries: 5 }),
);
const chat = new Conversation({ runner });
for await (const event of chat.send("修复 auth.ts 的 bug")) {
if (event.type === "text.delta") process.stdout.write(event.text);
}
内置中间件一览:
| 中间件 | 作用 |
|---|---|
withTurnTracking() |
发出 turn.start / turn.done,跨调用维护轮次计数 |
withCompaction(config) |
接近上下文上限时自动压缩历史 |
withRetry(config?) |
瞬时错误指数退避重试 |
withPersistence(config) |
每次 done 后自动保存消息 |
withHooks(hooks) |
挂接 onBeforeSend / onAfterResponse / onError |
写自定义中间件也很简单——就是一个包裹 Runner 的函数,在事件流前后插入你的逻辑(详见 middleware/index.ts)。
动手体验:快速上手步骤
准备好后,按下面三步跑起来:
-
克隆仓库(可选,直接
npm install也行):git clone https://gitcode.com/gh_mirrors/op/open-harness cd open-harness -
安装核心包:
npm install @openharness/core @ai-sdk/openai -
参考官方示例:仓库
examples/下有三个可运行示例——终端 CLI Agent(含工具审批与子 Agent)、Next.js 流式聊天、Nuxt 流式聊天,分别对应不同集成场景。
小结:5 大设计如何协同
| 设计 | 解决的问题 |
|---|---|
无状态 Agent |
历史可控、易测、可复用 |
| 类型化事件流 | UI 与执行解耦,实时可观测 |
工具循环 + maxSteps + approve |
自主干活且有安全边界 |
有状态 Session |
历史管理、压缩、重试、持久化开箱即用 |
| 可组合 Middleware | 能力自由拼装,避免"全有或全无" |
一句话总结:Agent 负责"跑",事件流负责"看得见",工具循环负责"干得完",Session 负责"记得住",Middleware 负责"随便组"。掌握这 5 个概念,你就能在 OpenHarness 上快速构建从 CLI 助手到 Web 聊天应用的完整 Agent 系统。更多细节可查阅仓库内的 agents.mdx、sessions.mdx 和 middleware.mdx 文档。