How Cereal fits into your app

What Cereal runs, what your application runs, and how the HTTP API and TypeScript SDK connect them.

Cereal runs the agent loop and stores durable sessions. Your application authenticates users and serves your custom tools. Your browser sends messages through your application and reads a scoped event stream from Cereal.

Browser ── messages and decisions ──> Your app (server or serverless)
Your app (server or serverless) ── authenticated API calls ──> Cereal
Cereal ── signed tool calls and hooks ──> Your app (server or serverless)
Cereal <── model requests and responses ──> Model provider
Browser <── session event stream ── Cereal

Your database stays in your application. Tool results return through Cereal to the model and can appear in session events and traces. Provider-executed tools run with the model provider; sandbox tools run in a Cereal-managed sandbox.

Use your existing hosting

Your app can run on serverless functions or an existing server. Cereal continues the agent session after the initiating request returns. Your tool and hook handlers run when Cereal calls them; their work still has to fit your host's request limits.

The HTTP API works from any language. The TypeScript SDK offers handlers for Web Request/Response runtimes and a Node adapter. You keep your authentication and database. Cereal calls your registered model provider using the credential you supply.

Choose an interface

Interface	Use it for	What it adds
HTTP API	Configure and run agents from any language	JSON operations and an SSE stream
TypeScript client	Call Cereal from TypeScript	Typed inputs, return values, errors, and streaming helpers
TypeScript authoring	Define an agent alongside its tools	`defineAgent`, handlers, and configuration sync
Browser helpers	Display a session in your app	Token renewal, stream reconnection, and UI adapters
CLI	Sign in, develop tools, and create environment-bound keys	Terminal commands for the same hosted service

The TypeScript SDK is optional. Using the client does not require defineAgent, and using HTTP does not require TypeScript. See the API/SDK map for exact relationships.

An agent definition is configuration

An agent is a versioned document describing its model, instructions, tools, and policies. A session pins one version of that definition and records its conversation and turns.

defineAgent combines the definition and your tool handlers in an application object. It does not run the model loop in your process. agent.definition() produces the JSON; agent.fetch(request) serves the callbacks; agent.init() registers the definition and connection with Cereal. agent.sessions.start() creates a session for that agent.

Development and deployment

During local development, NODE_ENV=development automatically opens an outbound channel on first use so Cereal can call your tools on your laptop. Cereal still runs the session. You need no public callback URL while developing.

For production, deploy your application to a public HTTPS origin and register its callbacks. Syncing configuration does not deploy your application. A pinned agent version also does not freeze the code behind a shared callback URL. Keep older tool contracts compatible, or use versioned callback URLs when changing them.

Credentials have different jobs

Your app (server or serverless) holds a Cereal API key. The browser receives a short-lived token that can read one session; messages and approval decisions go through your server. Your server must authorize which customer may access that session before issuing a token. An asserted Cereal identity is not a login system for your application.

An environment isolates your agents, providers, connections, and sessions. A single-environment key selects that environment. A key bound to multiple environments must also send x-cereal-environment. Credentials explains scopes and personal tokens; identity explains the user your session acts for.

Continue with a quickstart or the research-agent tutorial.