Unreal Agent

Unreal Agent 快速入门

Unreal Agent（unreallabsai/unreal-agent）是 Unreal Labs 开源的 async-first agent harness：每次工具调用立即返回「进行中」事件、实际执行放后台，工具真正完成后才把结果追加进会话并触发下一次模型调用。官方基准（GPT-6 Astra xhigh）显示它与 Codex 通过率相当、总成本最多省 40%（Terminal-Bench 4.0：57.9% 通过、$1,428 vs Codex $2,350）。MIT + Go。2026-10-02 核验（GitHub API + 官方博客）：2,049★ / 118 fork，创建于 2026-09-21、最近 push 2026-09-23，官网 unreallabs.ai 在线（Sequoia & First Round 背景团队）。

这是什么？适合谁？

Unreal Agent 解决的是「生产环境 agent 的工具调用管理开销」：传统 harness 里模型要花大量 token 管理等待、轮询和心跳；Unreal Agent 把这一切交给 harness 异步处理——模型发出工具调用后立刻收到「in-progress」状态继续干别的，用户插话（steering）永远不用等工具跑完。

核心概念（官方 glossary）：

• Input：带调用方全局唯一 ID 的事件，跨重投递保持稳定——这是幂等的基础
• Inbox：session 级内存去重，外部输入/控制输入/崩溃恢复输入都过这里
• Session：只追加（append-only）持久化历史，可 fork
• LLM turn：由协调器统一管理的一次逻辑模型请求
• Tool translator：校验工具调用并翻译成可执行操作，同步运行、不做 I/O
• Operation：translator 产出的可序列化异步工作单元，由 Operation manager（actor 运行时）执行

适合人群：要在生产环境跑 agent 产品的后端/平台工程师；对 token 成本敏感、想复现官方基准结果的评测工程师；研究 harness 设计本身的研究者（作者明说「harness 设计本身是一个研究领域」）。

不适合谁：想要 GUI 聊天界面的终端用户（这是库和命令行 runner，不是产品）；纯 Python 技术栈且不想碰 Go 的团队。

准备工作

1. Go 开发环境（harness 是 Go 库；只跑 runner 的话按仓库 README 装预构建可执行文件即可）
2. 一个模型 provider 的 API key（官方基准用 GPT-6 Astra xhigh；LLM Adapter 层Owns 认证与取消，换 provider 不改业务代码）
3. 时间预算：跑通 runner 首任务 30 分钟内；读懂 harness 组件并自定义一个工具 translator 约半天
4. 成本：MIT 免费开源；主要成本是模型 API 调用——异步架构省的正是这部分（更少模型轮次、更少输入 token）
5. 替代参考：如果只要 CLI agent 不要生产架构，Claude Agent SDK / Codex CLI 上手更快；Unreal Agent 的价值在生产级异步与成本效率

核心用法：四步上手

第 1 步：克隆仓库，认清三层结构

git clone https://github.com/unreallabsai/unreal-agent.git
cd unreal-agent

仓库分三层：harness/（库本体）、cmd/（使用库的可执行文件，含类似 claude -p / codex exec 的 runner）、benchmarks/（兼容 Harbor 框架的基准 runner）。

第 2 步：配置模型 key 并跑 runner

按仓库 README 配置 provider 凭证，然后运行 cmd/ 下的 runner 给它一个编码任务。观察日志里的会话事件流：你会看到工具调用发出后立即记录「in-progress」事件，模型继续其他工作，工具完成时结果才追加进 session log 并触发下一次 LLM 调用。

第 3 步：理解协调器循环

读 harness/ 的 Coordinator：它持久化被接受的输入、运行 LLM turn、通过 registry 解析 tool translator、派发已提交的 operation。这是整个异步模型的中枢——translator 同步校验并产出 operation，operation 异步执行，两者解耦。

第 4 步（进阶）：自定义一个工具

实现自己的 tool：用 schema 描述能力、绑定 translator（记住 translator 不能做 I/O），把耗时工作作为 operation 提交。官方鼓励替换各组件实现（如把 operation manager 换成代理模式，把操作发到远端沙箱里执行）。

常见踩坑

1. 症状：在 tool translator 里做网络请求或文件 I/O，死锁或阻塞。 根因：translator 契约明确要求同步运行且不得阻塞协调器事件循环。解决：translator 只做校验和翻译，实际 I/O 全部作为 operation 提交异步执行。
2. 症状：同一输入被处理两次。 根因：你的 Input 没有带全局唯一且跨重投递稳定的 ID。解决：给每个外部事件生成稳定唯一 ID，Inbox 的 session 级去重依赖它。
3. 症状：fork 出来的会话行为怪异。 根因：session 存储格式有版本号，不支持的版本会在 resume 时显式报错（这是设计行为，不是 bug）。解决：确认 fork/恢复用同一 harness 版本，或按仓库迁移说明处理版本差异。
4. 症状：复现官方基准对不上成本数字。 根因：官方结果绑定 GPT-6 Astra xhigh 与特定基准集（Terminal-Bench 4.0 / SWE-Atlas / DeepSWE 1.1 / ALE-CLI），且 Harbor 任务 ID 公开可查。解决：用官方给出的 Harbor job 链接核对配置细节再跑，模型或推理档位不同数字自然不同。
5. 症状：把「省 40%」当成对你 workload 的保证。 根因：官方口径是「与 Codex 相比，在生产工作负载与编码/科学基准上最多 40%」。解决：把它当作基准集上的实测数据看，自己的场景自己测。

常见问题 FAQ

Q1: 它和 Claude Agent SDK 这类框架的本质区别是什么？

A: 官方博客直接说了动机：CLI 向 SDK（如 Claude Agent SDK）内置本地会话、子进程、资源限制的假设，搬到生产环境要自己包一层生命周期管理；多 provider 兼容常要重写集成。Unreal Agent 从第一天按生产异步设计：用户可随时插话、工具调用零轮询 token 税、组件可替换。

Q2: 「最多省 40% 成本」具体怎么来的？

A: 两个因素：极简 harness 占用（简单提示词、token 优化的工具输出、无子 agent 无工作流编排）+ 每个模型轮次塞进更多有效工具调用（不用花 token 等待/轮询）。Terminal-Bench 4.0 实测 $1,428 vs Codex $2,350（约 39%），SWE-Atlas QnA $936 vs $1,303（约 28%）。

Q3: 内置了哪些工具？

A: Tool registry 固定持有 Bash、ViewImage 和 skill-use 的定义与 translator，宿主选择开放哪一组；自定义工具通过 schema + translator 加入。

Q4: 能把工具执行放到远端沙箱吗？

A: 能。Operation 是可序列化的，官方明示可以做代理型 operation manager：把序列化操作发给远端沙箱里的本地 operation manager 执行。

Q5: 中文生态怎么样？

A: 项目是英文的（README/博客），无中文文档；但它是库不是终端产品，使用门槛在 Go 与 harness 概念而非语言。

参考链接

• 官方仓库 unreallabsai/unreal-agent
• 官方博客：Unreal Agent 发布文（含完整基准表）
• 官网 Unreal Labs
• Harbor 基准框架

本文章基于公开资料整理，AI 辅助生成，独立实测与数据核验日期 2026-10-02（GitHub API 实时抓取 stars/fork/pushed/license；官网与官方博客在线核验；未在本机做 Go 环境部署实测）。