unreallabsai/unreal-agent

Async-first agent harness

Summary

Unreal Agent is an async-first agent harness written in Go from Unreal Labs, designed for building LLM-driven agents with durable, forking session state. It separates model interaction (LLM turns), tool translation, and asynchronous operation execution into composable interfaces with explicit contracts. The repository ships a library, runnable executables, and benchmark runners across three top-level directories.

What it is useful for

The README targets engineers building agent systems that need reliable execution semantics rather than simple request/response chat. Concrete situations where it fits:

• Building agents whose state must survive restarts, using append-only sessions that the README says can be forked and resumed
• Validating tool requests deterministically before any side effects happen, since tool translators are required to run synchronously on the coordinator's event loop with no I/O
• Dispatching long-running or side-effecting work as serializable operations that can be tracked independently from the tool-call status
• Isolating tool execution, because a proxy operations manager can forward serialized operations to a local manager running inside a remote sandbox
• Swapping concrete components (LLM adapters, session stores, operation managers) without rewriting the harness, since each component is defined by an interface

How engineers can use it

The README organizes the project as harness/ (the library), cmd/ (executables that wire the harness together), and benchmarks/ (benchmark runners). The Glossary and Components table in the README are the right entry documentation, since they define the input → inbox → coordinator → tool translator → operation flow and the responsibilities of each component.

A typical integration path described by the README looks like:

1. Implement an LLM Adapter for the target provider. The README notes the adapter owns authentication, cancellation, and provider errors.
2. Register tool definitions and translators with the Tool registry. Only Bash, ViewImage, and skill-use are listed as the host-selected built-in tools.
3. Provide a Session store and an Operation manager, or plug into the local implementations. The README encourages using harness/primitives/ when implementing operations.
4. Compose the pieces in a cmd/ binary that drives the Coordinator.

Documented limitations to plan for: the session storage format is versioned and an unsupported version will cause an explicit error on resume; tool translators must perform no I/O and must not suspend the event loop; and the context builder is required to perform no I/O and accept no persistence dependencies. The README does not document install or run commands, so readers should consult cmd/ and harness/ directly for current entry points.