Introduction

big-brain is a Go library, not a service you configure. You write a small Go program that imports pkg/bb, assembles your brain as a tree of flows and agents, and calls one function to serve it. What comes out the other end speaks the exact wire protocol of an OpenAI or Anthropic model — so every chat UI, IDE plugin, and SDK you already have is a free client.

bb.Serve(ctx, brain) // OpenAI + Anthropic-compatible, at :8080

The core idea

An agent that disguises itself as a model. From the outside, a big-brain deployment is indistinguishable from a model endpoint: point curl, the OpenAI SDK, or your IDE's assistant panel at it and it just answers. Inside, a request runs through a brain — model calls, memory, tools, routing, and background work — that makes it far more capable than a single model call.

The disguise extends to cost, honestly: the usage block big-brain reports is the real sum of every upstream call the brain made to answer you, not a mirror of your own prompt size. A brain that made five model calls really did spend five calls' worth of tokens, and bb tells you that plainly — see Telemetry & cost.

Why a library, not a platform

This codebase is vLLM, not OpenAI. A running process is one deployment owned by one author, not a multi-tenant provider. There's no first-class multi-tenancy, no per-tenant billing, no isolated memories — because that's somebody else's product, built around this one, using the embeddable pkg/ and an externalized store. What one process can do is serve several named flows behind one endpoint, each its own "model" id, chosen by the request's model field — a routing convenience for one owner (a chat brain, a coding brain, a summarizer, from a single binary), not a tenancy model.

The authoring model, in one sentence

A brain is a tree of flows, and control flow is Go. A flow runs one or more agents over a chat and hands the result to the next flow; flows compose (a group of flows is itself a flow) and chain with Next. An agent's OnMessage handler is a plain Go function: it branches, calls tools, reads memory, and Selects which flow runs next. There is no graph DSL, no Vars map[string]any, no node vocabulary to grow — if is if.

Continue to the quick start for a complete, runnable brain, or jump straight to the mental model for the vocabulary (flow, agent, turn) used throughout the rest of these docs.

What the engine actually sells

A brain author could hand-write the model calls, the prompt templates, the routing, and the database wiring, and get exactly what a reference brain does. The engine earns its place by owning the parts an author would get wrong or forget:

• Composition — agents, flows, Select routing, and the concurrency strategies (All/One/Group, Checkpoint); you write handlers and wiring, the engine runs the tree and resolves selection.
• Durable, resumable execution — with a store configured, each flow's result is checkpointed; a client that retries a crashed run (same run id) resumes from the flow that was interrupted, not from the start.
• Observability, free from the same boundaries — every flow start/end, select, response, and cached-resume is a timed trace event, with what that flow actually spent attached. Debugging is a byproduct of running the tree.
• The boring boundary — OpenAI/Anthropic-compatible serving, /v1/models, startup validation of the whole wiring, faithful passthrough of the chat protocol including a caller's own tools.
• Faculties — model roles, structured extraction, typed prompt templates, a Notify outgoing flow — the common machinery, abstracted so it adds value without getting in the way of your business logic.

What it does not promise (v1)

• Streaming is terminal-only per stage, buffered everywhere else. See Streaming for exactly where a client gets live tokens and why.
• At-least-once, not exactly-once. A resumed durable run replays already-delivered response stages so the client sees the complete answer again; side effects that must not double are the author's responsibility. See Durability.
• Voice/vision/realtime endpoints, a graph file format, a generic plugin system, server-side transcripts, and multi-tenancy are explicitly out of scope for v1 — later, when a real slice demands them, not speculatively now.