# Unreal Agent

> Async-first coding-agent harness in Go that never blocks the model on a tool call

- Category: AI Coding / Coding-Agent Harnesses & Runtimes
- Language: Go
- Licence: MIT
- Repository: https://github.com/unreallabsai/unreal-agent
- Website: https://unreallabs.ai
- Canonical page: https://ai-tldr.dev/tools/unreal-agent/
- Updated: 2026-09-22

## In short

Unreal Agent is a coding-agent harness: the layer that sits between a language model and the tools it drives, deciding how turns are taken, how tool calls are dispatched and how the session history is kept. It sits in the Coding-Agent Harnesses & Runtimes category of the AI Coding tools and is open-source, written in Go and licensed MIT.

## Overview

Unreal Agent is a coding-agent harness: the layer that sits between a language model and the tools it drives, deciding how turns are taken, how tool calls are dispatched and how the session history is kept. Unreal Labs released it under the MIT License on 22 September 2026 as a Go library, a runner executable and a Harbor-compatible benchmark runner. The company describes its focus as the harness, the runtime an agent acts in and the inference underneath, rather than the models themselves.

The design choice that separates it from most harnesses is asynchrony. A conventional harness issues a tool call and then blocks: the model's turn ends and the next turn cannot start until the command returns, so a long build, a slow test suite or an environment setup costs real turns spent waiting, polling or sending heartbeats. Unreal Agent logs a tool as in-progress the moment it starts and continues the turn, appending the result and calling the model again once the work finishes. Unreal Labs says this leaves the prompt cache intact, lets a user steer the agent without waiting for a pending tool, and lets the model schedule other useful work — exploring code in parallel with an environment that is still installing.

Internally the harness is split into replaceable parts rather than one loop. A session inbox de-duplicates caller-supplied inputs by a globally unique id so a redelivery is not processed twice; a coordinator persists inputs and dispatches operations; a session store keeps the append-only history that makes forking and recovery possible; a context builder assembles model input in memory without performing I/O; tool translators validate a model's request and convert it into an operation, also without I/O; and an operation manager executes the work on an actor runtime. Storage formats are versioned and serializable, and an unsupported version raises an explicit error rather than failing quietly. The README states that alternative implementations of these interfaces are encouraged.

The published benchmark table is a cost table as much as a score table. On Terminal-Bench 4.0 Unreal Agent matches Codex's 57.9% pass rate for $1,428 against $2,350 — about 39% less. On SWE-Atlas QnA it scores 65.8% for $936 against Codex's 63.3% for $1,303, and on DeepSWE 1.1 it reaches 72.4% for $1,367 against 69.0% for $1,633. Unreal Labs summarises the effect as up to 40% cost savings versus Codex on production workloads without a performance penalty.

## What it does

- Tool calls are dispatched asynchronously — the model is never blocked waiting on, polling or heartbeating a long-running command
- Results are appended when work completes, which Unreal Labs says preserves prompt-cache optimization across turns
- Provider-agnostic LLM adapter: openai, openai-codex, openrouter, fireworks and ollama are selectable at runtime
- Append-only session store with forking and recovery from persisted history
- Eight replaceable components (inbox, coordinator, session store, context builder, LLM adapter, tool registry, translators, operation manager) behind documented interfaces
- Versioned, serializable storage formats that raise explicit errors on unsupported versions instead of failing silently
- Ships with a Harbor-compatible benchmark runner under benchmarks/ for reproducing the published results

## Getting started

Unreal Agent is a Go module. The runner executable can be installed straight from the repository with the Go toolchain, or built from a clone with the bundled Makefile.

1. Install the runner

   The runner is published as a Go command in the repository.

```bash
go install github.com/unreallabsai/unreal-agent/cmd/unreal-agent-runner@latest
```

2. Set a key and run a prompt

   With an OpenAI key exported, the runner takes a prompt with -p.

```bash
export OPENAI_API_KEY="..."
unreal-agent-runner -p 'Inspect this project and explain how to run its tests.'
```

3. Point it at a project and keep the transcript

   The -workspace flag chooses the directory the agent works in; the run is emitted as JSON lines on stdout.

```bash
unreal-agent-runner -workspace ./my-project -p 'Summarize this project.' > run.jsonl
```

4. Choose a different provider or model

   Two environment variables pick the backend. The ollama option runs the harness against a model on your own machine.

```bash
export UNREAL_HARNESS_LLM_PROVIDER=openrouter
export UNREAL_HARNESS_LLM_MODEL=...
```

5. Or build from a clone

   The Makefile builds the runner into bin/ and runs the test suite with the race detector.

```bash
make build
make test
```

## When to use it

- Cut the token bill of a coding agent that spends turns waiting on slow builds, installs and test suites
- Run environment setup and code exploration at the same time instead of one after the other
- Steer or interrupt a running agent without first waiting for a pending tool call to return
- Drive a local model through ollama with the same harness used for hosted frontier models
- Reproduce the published Terminal-Bench 4.0, SWE-Atlas and DeepSWE cost comparisons with the bundled benchmark runner
- Build a custom harness by replacing one component — a different session store or tool translator — behind the documented interfaces

## Version history

- 2026-09-22: Unreal Labs published Unreal Agent, an MIT-licensed Go harness that dispatches tool calls asynchronously so the model never blocks on a slow command. It matches Codex's 57.9% on Terminal-Bench 4.0 for $1,428 against $2,350, and beats it on SWE-Atlas QnA and DeepSWE 1.1 at lower cost.