unreal-agent — 常见问题

Question 1

这是什么？

Accepted Answer

Unreal Agent 是一个用 Go 编写的、以异步为先（async-first）的智能体框架（agent harness）——一套用于运行 LLM 智能体的工具包，支持可持久化、可分支的会话、工具调用以及可靠的后台任务。

Question 2

这是一个供我构建的库，还是一个可以直接运行的应用？

Accepted Answer

它是一个 Go 库：也就是你在其上构建智能体的 harness/ 包。仓库还附带了使用该库的 cmd/ 可执行程序，以及 benchmarks/ 基准测试运行器。

Question 3

我怎么把它跑起来？

Accepted Answer

没有给出具体的安装步骤。作为一个 Go 库，第一步是把 harness/ 导入你的 Go 项目；cmd/ 目录里有一些可执行文件，展示了实际使用方法。

Question 4

使用它需要在某个特定的 LLM 提供商注册账号吗？

Accepted Answer

没有指明任何提供商。LLM Adapter（适配器）组件负责身份验证并返回标准化后的响应，所以你接入哪个提供商的实现就用哪个。

Question 5

如果对话进行到一半进程崩溃了会怎样？

Accepted Answer

会话和操作状态都会持久化并支持恢复，所以崩溃并不是致命的。但输入去重只保存在内存中，而且一旦会话版本不受支持，恢复时一定会明确报错。

Question 6

'async-first'（以异步为先）实际是什么意思？

Accepted Answer

工具的工作不是内联执行的：转换器把模型请求转成可序列化的操作，交给一个独立的 actor 运行时可靠地执行，同时协调器会持续推动 LLM 的轮次向前进行。

Question 7

智能体开箱自带哪些工具？

Accepted Answer

一个固定的注册表，包含 Bash、ViewImage 和一个技能使用工具，每个工具都配有带校验的转换器。宿主可以选择智能体会话实际能看到其中哪些工具。

Question 8

会话（session）到底是什么？

Accepted Answer

是智能体一次对话的只追加、持久化的历史记录。会话可以被分支（fork），工具调用的状态会与产生它们的操作原子性地一并记录。

Question 9

工具可以在别的地方执行吗，比如远程沙箱？

Accepted Answer

可以——操作都是带版本号且始终可序列化的，所以一个代理操作管理器可以把它们转发给运行在远程沙箱内的操作管理器，让工具在那里执行。

Component	Responsibility
Session inbox	Volatile, session-scoped input idempotency.
Coordinator	Persist accepted inputs, run LLM turns, resolve tool translators through the registry, and dispatch committed operations.
Session store	Persist canonical session history and operation state; support recovery and forks; atomically record tool-call status with operations.
Context builder	Statefully assemble model input in memory. Return the model input together with a record of anything omitted, truncated, or compacted. Perform no I/O and accept no persistence dependencies.
LLM Adapter	Send prepared model input to a provider and return a normalized completed response. Own authentication, cancellation, and provider errors.
Tool registry	Own the fixed Bash, ViewImage, and skill-use definitions and their translators; expose the host-selected set.
Tool translator	Validate a tool call and produce its status and operations. Format a recorded call status and prepared operation output into model results. Perform no I/O.
Operation manager	Actor runtime for durable operations. The local implementation is swappable.

unreal-agent README