Unreal Agent 核心概念图解：Input、Inbox、Session 与 Operation 完整指南

Unreal Agent 核心概念图解Input、Inbox、Session 与 Operation 完整指南【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agentUnreal Agent是 Unreal Labs 推出的「异步优先Async-first」AI 智能体框架agent harness它用四个核心概念——Input、Inbox、Session、Operation——把「模型思考」和「真正干活」彻底解耦。本文带你一图读懂这套设计帮你快速上手这个 Go 语言写的智能体运行时。 为什么需要异步优先的智能体框架普通聊天机器人是「你问一句、它答一句」的同步模式。而智能体Agent不同它可能要执行一条跑 10 分钟的 Shell 命令、生成一张图、调用外部 API……如果整个进程为等待这些活儿卡死体验必然很差。Unreal Agent 的解法很直白模型调用和工具执行走两条独立流水线所有工作都被描述成可序列化、可恢复的Operation所有消息都带全局唯一 ID天然支持去重和崩溃恢复。一句话总结输入走 Inbox历史存 Session干活靠 Operation协调交给 Coordinator。官方在 README.md 的术语表Glossary中对这四个概念做了权威定义下面的每个小节都能对应到源码目录。 Input带唯一 ID 的事件信封Input是进入系统的一切外部消息定义在 harness/inbox/inbox.go 中。它长这样概念上Input 全局唯一 ID 类型Kind 负载Payload它的关键特性有两条ID 全局唯一且跨重投递保持稳定——同一条消息重发 10 次ID 也只有一个分三种类型对应三类来源类型含义典型场景external外部用户输入用户发来的新指令control控制消息停止、心跳、更新设置crash崩溃恢复输入进程重启后补投的消息其中控制消息支持 4 种模式见 harness/inbox/inbox.gohard立即硬停、when_idle空闲时停、heartbeat心跳探测、settings动态调整推理强度。给新手的直觉把 Input 想象成一封盖了唯一编号邮戳的信——编号让邮局系统能识别这封信我已经处理过了。 Inbox会话级的去重收件箱Inbox是 Input 的收件处作用域限定在单个会话内实现位于 harness/inbox/local.go。它本质上是一个内存态去重器提交 Input ──► 校验ID 非空、类型合法 ──► 查已见 ID 集合 ──► 重复 直接丢弃 ✅ ──► 新消息 入队 → 顺序输出给协调器两个值得注意的设计细节会话内有效Inbox 本身不持久化但重启时会从会话历史中恢复「已见 ID 列表」seenIDs保证崩溃重投的消息依然会被正确去重顺序保真内部用队列串行化输出消息按到达顺序被协调器消费不会乱序。类比Inbox 就像你家门口的信箱——投递员任何调用方把信塞进来你协调器按顺序取贴重号码的信管家直接扔回收站。 Session只追加、可分叉的历史账本Session是持久化的会话历史身份定义见 harness/session/session.go而真正落盘的账本接口在 harness/sessionstore/sessionstore.go。它的三个核心特质1️⃣ 只追加Append-only历史条目按序列号Sequence单调递增五种条目类型依次记录全过程条目类型记录内容fork分叉点从哪个父会话、哪一轮分出来input被接受的 Inputturn一次 LLM 逻辑轮次的开始model_response模型的完整响应tool_call_status工具调用结果 关联的 Operation 快照2️⃣ 可分叉ForkFork方法harness/sessionstore/sessionstore.go允许从某个历史轮次剪出一个新会话——想换个思路重做分叉即可原历史毫发无损。3️⃣ 可恢复ResumeResume会返回完整恢复状态会话快照、所有未完成的 Operation、以及待处理的外部输入 ID见 harness/sessionstore/sessionstore.go。这意味着 进程崩了重启后 Unreal Agent 能从账本里读出我干到哪了接着干而不是从零开始。测试数据目录 harness/sessionstore/localfile/testdata/ 里的golden-fork.session.jsonl、soft-stop-session.session.jsonl就是真实的恢复/分叉场景样例想深入可翻一翻。️ Operation可序列化的异步工作单Operation是整篇文章最重要的概念定义在 harness/operation/operation.go。当模型说帮我跑make build时系统不会立刻执行而是先生成一张工作单Operation ID 类型Type 版本Version 状态Status 状态数据State 幂等键Idempotency它有完整生命周期状态机ready就绪──► awaiting等待中──► completed完成 │ ├──► canceling取消中──► canceled已取消 └─────────────────────► failed失败三个设计亮点版本化 永远可序列化任何一张工作单都能完整落盘恢复时精确复现幂等键Idempotency同一张单子重放不会造成副作用比如不会把文件写两遍执行交给 Primitives工作单最终被拆解为原语动作分发执行全部原语清单见 harness/primitives/primitive_dispatch.go——进程启停、文件读写、定时器、计算、远程请求一应俱全。类比Operation 就像外卖平台的订单——下单提交、接单就绪、配送中awaiting、送达completed。订单本身是数据结构骑手执行器是谁都可以换。 四个概念如何协同工作把所有零件拼起来Unreal Agent 一次完整的回合是这样流动的① Input 从 Inbox 按序进入 │ ② 协调器Coordinator持久化 Input 到 Session 账本 │ ③ Context Builder 在内存中组装模型输入纯计算、零 I/O │ ④ LLM Adapter 把请求发给模型拿回统一格式响应 │ ⑤ 模型产生 Tool Call → 翻译器同步校验生成 Operation │ 状态与操作一起原子写入 Session 账本 │ ⑥ Operation Manager 异步执行工作单进度持续回写 │ ⑦ 结果翻译回模型语言 → 进入下一轮直到收到 stop 控制其中协调器是中央事件循环的拥有者依赖注入清单一目了然harness/coordinator/coordinator.goInbox、会话存储、上下文构建器、LLM 适配器、工具注册表、操作管理器——每个部件都是接口可替换。两条重要的职责边界也是面试/源码阅读的好问题组件能做什么绝对不能做什么工具翻译器校验调用、生成 Operation做任何 I/O、阻塞事件循环上下文构建器内存中组装模型输入任何 I/O、依赖持久层操作管理器执行持久化操作——本地实现可整体替换正因为干活被隔离在 Operation 后面官方才敢于承诺一个高级玩法用代理操作管理器把序列化后的工作单发给远端沙箱进程去执行工具代码就跑在沙箱里了见 README.md 的 Extending the harness 一节。✅ 小结一张表带走四个概念概念一句话理解源码位置Input带全局唯一 ID 的消息信封harness/inbox/inbox.goInbox会话级内存去重防重投harness/inbox/local.goSession只追加、可分叉的持久化历史账本harness/sessionstore/sessionstore.goOperation可序列化、有状态机的异步工作单harness/operation/operation.go掌握这四个词你就拿到了 Unreal Agent 源码的地图。想动手验证入口程序在 cmd/unreal-agent-runner/测试数据里有可直接打开的会话快照harness/sessionstore/localfile/testdata/配合go test ./...跑一遍测试比读十篇教程都管用 【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考