Unreal Agent
An async-first agent harness from Unreal Labs.
- harness/ — the library.
- cmd/ — executables that use the library.
- cmd/unreal-agent-runner - cloud agent runner.
- cmd/unreal-agent-tui - cozy TUI.
- benchmarks/ — benchmark runners.
Glossary
- Input: an event with a caller-supplied globally unique ID that remains stable across redeliveries.
- Inbox: session-scoped, in-memory deduplication of external, control, and crash inputs.
- Session: append-only persisted history that can be forked.
- LLM turn: the coordinator-managed sequence around one logical LLM request.
- Tool: a capability described by a schema and bound to a translator.
- Tool call: a model-produced request to use a tool.
- Tool translator: validates a tool call and translates it into one or more operations. It runs synchronously on the coordinator's event loop and must not perform I/O or suspend the loop.
- Tool call status: the translation outcome: a validation error or references to submitted operations. Operation execution state is tracked separately; the translator formats these into a model-facing result.
- Operation: a serializable description of work produced by a tool translator for asynchronous execution. Implementations are encouraged to use the available primitives.
Components
| 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. |
Extending the harness
Harness components are composable, and alternative implementations of their interfaces are encouraged.
We intend to preserve these invariants:
- Session-store items are serializable, and the storage format is versioned.
- We'll do our best to maintain backwards compatibility for sessions. An unsupported session version will always cause an explicit error on resume.
- Operations are versioned and always serializable.
For example, a proxy operations manager can send serialized operations to a local operations manager running in a process inside a remote sandbox, allowing tools to execute there.