Schemas

A Schema is the top-level unit you deploy and expose to users. It binds together a set of agents, designates which agent receives the user’s first message (the entry agent), and controls whether the schema accepts chat requests.

Every chat session is associated with a schema — not directly with an individual agent.

What a schema contains

Element	Description
Entry agent	The agent that receives the user’s first message. It can spawn other agents from there.
Agent relations	Connections that define the delegation tree — which agent can spawn which.
Chat Enabled	A boolean toggle. When `true`, the schema accepts `POST /api/v1/schemas/{name}/chat`.

Why schemas exist

Schemas let you expose a multi-agent workflow as a single chat endpoint. Instead of talking to individual agents, a client talks to a schema — the entry agent routes and delegates as needed.

This separation lets one agent participate in multiple workflows without receiving the same authority everywhere. A specialist may be reachable from one schema and deliberately absent from another. The schema also gives clients a stable integration boundary while models, prompts, and internal agent composition evolve behind it.

Schema: "Customer Support"
├── Entry agent: router (receives all user messages)
├── Agent relations:
│   ├── router → billing-agent (via spawn)
│   └── router → technical-agent (via spawn)
└── Chat Enabled: true

Enabling chat

Toggle Chat Enabled in Admin Dashboard → Schemas → select schema → Settings. Once enabled, the schema accepts requests at:

POST /api/v1/schemas/{name}/chat

The {name} is the schema name. Find it in the Admin Dashboard or via GET /api/v1/schemas.

When chat is disabled, new chat requests return 404 so the endpoint does not reveal whether the schema exists. An already-running turn is not interrupted by changing the toggle.

Chat API

curl -N "$SYNTHETICBREW_URL/api/v1/schemas/support-handbook/chat" \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, I need help with my order"}'

Pass session_id to continue an existing conversation:

curl -N "$SYNTHETICBREW_URL/api/v1/schemas/support-handbook/chat" \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -d '{"message": "Follow-up question", "session_id": "67b592d5-a76f-4d83-9090-1ff0342ee2c3"}'

The response streams as Server-Sent Events. See REST API Chat for the full event reference.

Design the relationship graph

Each relation is directional. A relation from router to billing-agent produces a delegation tool for the router; it does not authorize the billing agent to call the router. Add the reverse edge only when that behavior is genuinely required.

Start with the smallest graph that completes the workflow:

Choose the agent that should receive every new request.
Give that entry agent outgoing edges only to relevant specialists.
Give specialists their own outgoing edges only when nested delegation is required.
Test direct, ambiguous, and mixed requests before enabling chat.

Use spawn lifecycle for a specialist that should receive a fresh, task-focused context on each delegation. Use persistent when the agent should continue within the active session. Cross-session recall requires the Memory capability; lifecycle alone is not long-term memory.

Operational boundaries

Schemas do not schedule themselves. An external service may invoke the chat endpoint, but there is no built-in cron or webhook trigger resource.
Agent can_spawn output is derived from schema relations and cannot be edited directly.
A chat-disabled schema returns 404 for new requests so callers cannot use the endpoint to discover private schema names.
Existing sessions retain the catalog with which they started. Start a new session when validating relation or tool changes.

Bootstrap and GitOps

Schemas, agents, models, MCP servers, and capabilities are configured through standard REST endpoints. To reconcile a Cloud workspace or Enterprise deployment from reviewed version-controlled configuration, see the Configuration as Code guide.

Chat and background work

A chat-enabled schema accepts POST /api/v1/schemas/{name}/chat. Work created outside an interactive chat can be tracked in Tasks; current task records do not persist reliable source or agent attribution.