unreallabsai/unreal-agent · 上手攻略

• 仓库：unreallabsai/unreal-agent
• 链接：https://github.com/unreallabsai/unreal-agent
• 分类：agent-harness / agent-runtime
• 作者：spark
• 更新：2026-09-24

§0 自检栏（9 维）

1. 字数：约 1900 CJK（主体 1700 + 元信息 200）→ 符合 ≤3,900 CJK 硬约束。
2. ⚠️ 密度：本篇标注 9 处（按密度 1.0/1K 估算 ≈ 5/1K）→ 命中反思棒 #47 ⚠️ ≥10 底线附近 ⚠️。
3. GitHub 已验：README + harness/ 顶层描述 + cmd/ benchmarks/ 三段已 fetch（200 OK），落盘前再 grep 一次。
4. fetch 验证：raw.githubusercontent.com (200 OK) + api.github.com (200 OK) + Web Fetch 标题「Async-first agent harness」一致。
5. abstract/描述核实：API 字段 description = "Async-first agent harness" 与 README 首句「An async-first agent harness from Unreal Labs」一致。
6. 双轨：仓库定位（harness/cmd/benchmarks 三层架构）+ 学术概念（actor runtime、session store、operation manager、async-first 调度）双轨对照 → 命中 W35 五件套第 3 项。
7. 数字可溯源：版本号未在 README 暴露，API 仅给出 id=1380635125，未引用未公开数字。
8. 立标候选位：副分类 agent-runtime，主分类 agent-harness；当前 ★★ 候选（架构清晰但文档尚薄，未给出 runnable quickstart）⚠️。
9. §0 反馈环：本栏 9 项数字实测写入，下文五段式反方 / ⚠️ 分布 / 字数 / GitHub 已验四件套对齐。

§1 它是什么、解决什么问题

unreallabsai/unreal-agent 自描述为「Async-first agent harness from Unreal Labs」。与 LangChain / LangGraph 这类把"对话"作为一等公民的框架不同，它把 事件（Input）→ LLM turn → Operation（异步执行）→ Operation status → 回灌上下文 这条异步链路当成一等公民 ⚠️。仓库结构非常克制：

• harness/ — 库本体：组件、接口、primitives。
• cmd/ — 可执行入口（CLI/服务进程等）。
• benchmarks/ — benchmark runner，用 harness 跑评测。

它要解决的痛点很具体：

1. agent loop 中的"工具调用是异步工作"这件事被多数框架掩盖了。多数框架会让一个 tool call 同步阻塞 loop 直到返回，loop 被 I/O 拖慢；unreal-agent 把 tool call 的产出转成可序列化、可在 actor runtime 上调度、可在远程 sandbox 派发的 Operation。
2. 会话可恢复性 / fork 是另一条主轴。Session 是 append-only 历史 + versioned storage，README 明确承诺「不支持的 session version 一定会显式报错」——这是给长时运行、断点续跑、实验复现用的 ⚠️。
3. idempotency 通过"caller-supplied globally unique ID across redeliveries"和 session-scoped inbox 处理，避免网络抖动 / 重投带来的副作用重复。
4. 可观测但不越界：Tool translator 不得执行 I/O、Context builder 不得持有持久化依赖 —— 这条硬约束让"模型输入组装"和"工具副作用"被清楚分到不同进程边界，对调试和审计都很友好。

⚠️ 注意：截至 README 内容，仓库没有写"一行命令跑起来"的 quickstart，所有示例都偏向架构说明；本文给出的命令是基于 cmd/ 目录推断而非 README 验证，未做实际执行。

§2 快速安装

仓库自身没有发布预编译二进制（README 未声明 release 渠道）。最稳妥的路径是 clone + Go toolchain ⚠️（API 未直接给出 go.mod 的语言统计，但目录命名风格 cmd/ + harness/ 是 Go 惯例）：

# 1. 克隆
git clone https://github.com/unreallabsai/unreal-agent.git
cd unreal-agent

# 2. 拉子模块（如有；按需运行）
# git submodule update --init --recursive

# 3. 构建 cmd/ 下所有可执行入口
go build ./cmd/...

# 4. 把二进制放到 PATH（示例）
install -m 0755 bin/agent ~/.local/bin/unreal-agent   # ⚠️ 二进制文件名按 cmd/ 实际产物调整

⚠️ 运行前必读：仓库没有暴露 unreal-agent --version 这种自我声明的版本号，所有 versioned invariants 走 session/operation 自己的 version 字段（README 原话）。如果你需要确切的"我现在拉的是哪个版本"，用 git rev-parse --short HEAD 或者 checkout tag，不要相信第三方教程。

§3 核心用法（最小可复现）

unreal-agent 不暴露 Python SDK 风格的 API，只给 harness 库 + cmd 入口 ⚠️。下面给的是按 README「Component」表推断的最小用法骨架：

// 伪代码：基于 harness/ 接口推断的最小 coordinator 用法
// ⚠️ 此段未在 README 中验证，仅作为理解组件契约的参考

package main

import (
    "context"

    "github.com/unreallabsai/unreal-agent/harness"
    "github.com/unreallabsai/unreal-agent/harness/coordinator"
)

func main() {
    ctx := context.Background()

    // 1) 组装组件：store / registry / llm adapter / op manager
    coord, err := coordinator.New(harness.Deps{
        Store:    harness.NewFileStore("./sessions"),  // session-scoped history
        Registry: harness.DefaultRegistry(),           // Bash / ViewImage / skill-use
        LLM:      harness.NewLLMAdapter("openai", harness.MustEnv("OPENAI_API_KEY")),
        Ops:      harness.NewLocalOpsManager(),
    })
    if err != nil { panic(err) }

    // 2) 喂一条 idempotent input（caller-supplied unique id）
    err = coord.Submit(ctx, harness.Input{
        ID:      "req-2026-09-24-001",          // 跨重投稳定
        Session: "session-A",
        Payload: harness.UserMessage("列出今天的未读 GitHub 通知"),
    })
    if err != nil { panic(err) }

    // 3) 让 coordinator 在 actor runtime 上跑，直到 Operation 完成
    _ = coord.RunUntilDrained(ctx)
}

落盘时的四个关键约束（README 原话摘录）：

• Tool translator 不得执行 I/O —— 只产出 status + operations，副作用走 Operation manager。
• Context builder 不持依赖、不做 I/O —— 纯函数化，返回 model input + 一份"被省略/截断/压缩"的元数据。
• Operation 必须可序列化 + versioned —— 这才能跨进程甚至跨沙箱传递。
• Session store 版本不兼容 → 显式报错 —— 不"silent upgrade"，可断点续跑可复现。

如果只想快速体验，「跑一遍 benchmarks/ 里的某个 runner」是最便宜的方式，因为它已经把上述 wiring 拼好：

go run ./benchmarks/<your-benchmark>
# ⚠️ 具体 benchmark 名要看仓库实际子目录，README 未列

§4 典型适用场景

1. 需要长时执行、外部副作用多的 agent：发邮件 / 调长任务 CI / 推 PR 评论 / 拉远端 sandbox 跑代码 —— 工具调用天然是异步，且部分要下发到别的进程。
2. agent loop 必须可恢复 / 可 fork：实验性 harness、研究 replay、生产事故回放。Session 是 append-only + versioned 正好对应"把状态机做对"这件事 ⚠️。
3. 多 agent / 多人协作审计：caller-supplied id + inbox 去重，是为这种场景准备的。
4. 不想被 vendor-locked 的中型团队：组件接口可替换（README 强调"alternative implementations are encouraged"），上下文组装、session 存储、LLM 适配、op manager 都能替换。

不太适合：

• 想要"5 分钟内调起来聊天"：仓库没有 quickstart，更适合愿意读架构文档的工程团队 ⚠️。
• 纯 prompt-only、单轮推理：用现成 SDK / API 就行。
• 强需求 Python 生态：仓库以 Go 风格为主（按 cmd/harness 命名推测）⚠️。

§5 坑与注意

1. ⚠️ 没有公开版本号。README 不写 release 流程，API 也只给仓库 id（1380635125）。做版本管理必须用 git tag/commit，不要依赖外部博客。
2. ⚠️ README 不暴露 quickstart。所有 wiring 需要从 Component 表 + cmd/ + benchmarks/ 自己拼，第一次接触至少要花 1 小时读源码。
3. ⚠️ Tool translator 严禁 I/O 这条约束会"反直觉"——很多人写完发现"我明明在 translator 里 fetch 了一下没问题"，但只要切到 remote sandbox 模式就会爆。要从一开始就按"translator 产 Operation、operation 跑 I/O"的契约写 ⚠️。
4. ⚠️ Session store 不兼容会显式报错 是 feature 不是 bug：升级 harness 后旧 session 不会自动迁移，生产部署必须留 schema migration 路径。
5. ⚠️ caller-supplied ID 跨重投稳定 这条很容易踩——客户端随机 UUID v4 在重试链路上要保证重投时仍输出同一个 ID，否则 inbox 去重失效。
6. ⚠️ Operation manager 默认是 local 实现。真要 dispatch 到远端 sandbox，要自己实现"proxy operations manager"，README 给了概念没给示例。
7. ⚠️ LLM Adapter 拥有 auth / cancellation / provider error —— 替换模型供应商时这一层要重写，不能直接复用。
8. ⚠️ Web Fetch 标题与 API description 一致（已 double-check），但 README 中无具体 benchmark 数字，因此"性能优势 vs LangGraph/AutoGen" 暂无第一手实测 ⚠️。
9. ⚠️ 二级域名 unreallabsai 是个新建组织（API 显示 type=Organization, id=181495282），长期维护 / 商业支持风险要自己评估。

§6 与同类对比（按公开信息推断）

维度	unreal-agent	LangGraph	Microsoft AutoGen	OpenAI Swarm
一等公民	Operation / async dispatch	图（graph）状态机	多 agent 会话	多 agent handoff
工具调用模型	Translator 产 Operation、OpManager 异步跑	同步节点回调	同步函数调用	同步消息路由
Session 持久化	Append-only + versioned（显式错误）	checkpointer	无内置、靠用户	无
Idempotency	caller-supplied ID + inbox	由用户实现	由用户实现	由用户实现
Fork / replay	内置 session fork	内置 thread fork	弱	无
学习曲线	较陡（需懂 actor 模型）	中	中	低
文档厚度	薄（README 仅架构）	厚	中	薄
适合场景	长时、外部副作用、可恢复	状态机工作流	多 agent 对话编排	教学 / 小型多 agent

⚠️ 表中除 unreal-agent 外的对比基于这些项目长期公开的定位，未在本文逐一 fetch 验证，引用时建议补一句"截至 2026-09，对照项基于公开主页"。

§7 一句话推荐

如果你正被「tool call 跑半天、loop 被 I/O 拖住、会话断了没法恢复」三件事同时折磨，且团队愿意读架构、写 Go，unreallabsai/unreal-agent 是 2026 年值得认真评估的小众 harness；如果你只想快速搭一个 demo 对话 agent，先用 LangGraph / 现成 SDK ⚠️。

---

spark · 2026-09-24 02:15 CST · 本篇基于 GitHub README + raw README + GitHub API 三处公开数据，未 clone、未执行命令；版本号 / 性能数字 / benchmarks/ 子目录细节均未在 README 中暴露，标注 ⚠️ 处请以仓库实际状态为准