Introduction
A minimal and extensible agent server for building agent applications.
Brain is a single application you deploy as a service to run the agents behind your products. It's an open-source alternative to Claude Managed Agents and the OpenAI Agents SDK, running on your own infrastructure with the models you choose.
| Approach | What it is | Best for |
|---|---|---|
| Model API | Direct requests to a model provider. You write the agent loop, tool dispatch, and conversation storage. | Single completions, or full control over every model call. |
| Agent library | An agent loop that runs inside your application process, such as the OpenAI Agents SDK. | Agents that one process can run from start to finish. |
| Managed agent service | A hosted agent loop and session service that runs on the provider's infrastructure, such as Claude Managed Agents. | Agent tasks that run in the background, without operating your own infrastructure. |
| Brain | An open-source agent server you deploy yourself. It runs sessions for your applications: the agent loop, the event history, tool calls, and recovery. | Agents that serve many customers and outlast any one process, with tools in your own services and state on your own infrastructure. |
Brain gives you session-oriented primitives for building agents. Your backend creates a session, sends messages, and streams events. Brain runs the harness (the agent loop that calls the model and manages context), records every event, and sends tool calls to services you run. Sessions outlive client connections and server restarts, so you can reconnect to a session, interrupt it, and resume it later.
Quickstart
Sessions
Tools
API reference
Core concepts
| Concept | Description |
|---|---|
| Session | An agent conversation that outlives client connections and server restarts. You choose its harness, model, instructions, and tools, then exchange messages and events with it over time. |
| Turn | The work Brain does for one user message: model calls and tool calls until the harness finishes. A session runs one turn at a time and queues further messages in order. |
| Event | A typed record in a session's stream, such as a message, a tool call, or a status change. Follow events live, or replay the history from the last event you read. |
| Harness | The agent loop that calls the model, manages context, and decides when a turn is done. Brain includes the Pi harness, and you can add your own. |
| Tool | A capability implemented in application code, a client function, or a service. Brain calls it when the model asks, and each session uses exactly the tools you enable for it. |
| Tenant | The isolation boundary for sessions, tokens, and tools. |
| Host config | The JSON file that configures a Brain server: its API tokens, harnesses, model providers, tools, limits, and storage. |
| Checkpoint | Saved session state that Brain records after each completed turn, for recovering a session or moving it to another server. |
How it works
Configure and start Brain
Declare your API tokens, harnesses, model providers, and tools in a host config, then start the server.
Create a session
Choose a harness, a model, instructions, and the tools the agent can use. Brain saves the session and returns its ID.
Send a message
Brain records the message, queues it, and starts a turn. The harness calls the model. When the model calls a tool, Brain sends the call to your tool service together with the session's identity, then returns the result to the harness.
Stream events
Follow the session's events live, or page through its history. The turn keeps running when a client disconnects, and the client can reconnect from the last event it processed.
Interrupt, resume, or close
Stop a running turn, resume an interrupted session from its last completed turn, or close the session. With external storage configured, another server can restore the session from its checkpoints.
When to use Brain
- Background agents: Sessions outlive client connections and server restarts. Clients reconnect and continue from the last event they processed.
- Multi-tenant products: Each tenant's sessions, tokens, and tools stay separate. Tools receive the session's identity from Brain rather than from the model, so they can authorize every call.
- Tools in other systems: Sandboxes, storage, and human approvals run as services that you deploy and scale on their own, in any language.
- State on your infrastructure: You run the open-source server. Sessions stay on your disks and, if you configure it, in your own object storage.
Brain or an embedded agent library?
Use an agent library when one process can run the whole agent: your application owns the loop, the tools, and the conversation state, and nothing else needs to reach the session.
Use Brain when the agent runs as its own service: several clients or customers reach its sessions over an API, tools live in other systems, and sessions outlast client connections and server restarts.
With Brain, your application stays in charge of what each agent is. You choose every session's instructions, model, and tools, and you coordinate any work that spans several agents.
What's included
- Pi harness: Brain includes the Pi harness, an agent loop that works with models from the providers you configure. Every tool is an implementation you control, and the model sees exactly the tools you enable for its session, so you decide everything the agent can do.
- Tool connections: Answer tool calls over HTTP, stream progress with server-sent events, or connect tools from a remote MCP server.
- Tool services: A sandbox service for Modal, E2B, and Daytona; a storage and web service for S3 or R2 storage, Brave or Tavily search, and public web fetch; and an example tool server with an operator approval flow.
- Session storage: Sessions live on local disk and can sync checkpoints to a directory, Amazon S3, Cloudflare R2, or Google Cloud Storage. An optional PostgreSQL index lets servers find each other's sessions.
- SDKs: Compose your service with the Go application SDK, or connect with TypeScript, Python, and the HTTP API.
- Operations: Health checks, structured logs, OpenTelemetry traces and metrics, and a published container image.
Choose your path
| Goal | Start here |
|---|---|
| Start the server and send a message | Quickstart |
| Understand how Brain runs a session | Architecture |
| Connect from your backend | TypeScript SDK or Python SDK |
| Stream, interrupt, and resume sessions | Session lifecycle |
| Inspect routes and event payloads | HTTP API and Events & streaming |
| Configure models and API keys | Models & providers |
| Build a tool service | Distributed tools and Local tools & approvals |
| Connect a remote MCP server | MCP tools |
| Back up sessions and move them between servers | Persistence & recovery |
| Deploy and monitor Brain | Operations & observability |
| Write a harness or storage adapter | Adapter overview and Go interfaces |
| See what's coming next | Roadmap |
Docs for coding agents
These docs are also available as plain text for LLMs and coding agents. /llms.txt lists every page, and /llms-full.txt contains the full text of all pages.