Agentloops

An agent loop decides when to call the model, use tools, and compact a conversation. One Brain server can run Pi, Codex, OpenCode and custom implementations concurrently. The deployment installs and registers implementations; applications select a name and pass behavior settings when creating a session.

import { pi } from "@aexhq/agentloop-pi";

const session = await brain.sessions.create({
  model,
  tools: [lookupOrder()],
  agentloop: pi({ compaction: { enabled: true, reserveTokens: 8192 } }),
});

pi(options) returns { name: "pi", configuration: options }. The helper does not load or run Pi in your application. A plain selection object works in any language. The chosen name must already be registered by the server; unknown names fail at create. Session requests cannot supply commands, executable code or package paths.

Register implementations

The extension image includes all three upstream runtimes and registers pi, codex and opencode. The base Brain image contains the neutral server and SDK.

docker run --rm -p 127.0.0.1:8080:8080 \
  -e BRAIN_API_TOKEN=quickstart \
  -v brain-agentloops-data:/var/lib/brain ghcr.io/aexhq/brain-agentloops:latest

Override BRAIN_AGENTLOOPS to choose installed commands, deployment defaults and worker capacity. This example runs two Pi workers and one Codex worker:

{
  "pi": { "command": "brain-agentloop-pi", "workers": 2, "max_concurrency": 32 },
  "codex": { "command": "brain-agentloop-codex", "workers": 1, "max_concurrency": 8 }
}

Registrations are fixed for the server lifetime. Different names may use the same executable with different deployment defaults. Use that registered name in the session selection; configuration never changes which executable runs.

Behavior and state

Upstream agents own their loops, compaction and native session files. Extension adapters route model and tool execution through Brain's durable journal barriers. Pi, Codex and OpenCode integration code and runtime dependencies live in the extension packages, outside Brain. See the harness reference for supported settings and runtime requirements.

Each open session stays on its assigned worker and runs one activation at a time. Workers admit concurrent sessions up to max_concurrency; excess activations wait. Idle-session passivation releases native resources. A failed process does not restart or replay its work, and other workers continue serving their sessions.

Back up the entire data directory, including agentloops/. Native state is not a portable checkpoint. Interrupted or failed native activations require a new session. Pre-0.41 data directories are incompatible; retain them separately and start with a new directory.

Provide your own

Implement the public JSON-RPC stdio contract in any language, register its command, and select its name in sessions. Custom implementations have the same callback and lifecycle interface as the official extensions. Write an agentloop starts with a working example.