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.

Schema names (engine 1.1.0+)

Schema URLs are keyed by the operator-declared name (e.g., support-handbook), not the internal UUID. The name is the stable handle you declare in configApply.config — UUID remains an internal storage detail. Names follow DNS-label format (^[a-z0-9]([-a-z0-9]*[a-z0-9])?$), are immutable post-create, and cannot be UUIDs or reserved tokens. To rename a schema, create a new one and migrate consumers, then delete the old one.

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.

Disabling a schema returns 403 for all new requests while active sessions drain normally.

Chat API

curl -N http://localhost:8443/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 http://localhost:8443/api/v1/schemas/support-handbook/chat \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -d '{"message": "Follow-up question", "session_id": "sess_abc123"}'

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

Bootstrap and GitOps

Schemas, agents, models, MCP servers, and capabilities are configured through standard REST endpoints. To deploy a fully-configured ByteBrew installation from a git repository (GitOps-friendly), see the Bootstrap and GitOps guide.

Scheduled and event-driven triggers (V3 roadmap)

Cron and webhook triggers are planned for V3 and not yet available. In the current release, schemas are activated only via the REST chat API (POST /api/v1/schemas/{id}/chat).

Planned V3 features:

• Cron triggers — run agents on a schedule (e.g., 0 9 * * 1-5 — weekdays at 9 AM)
• Webhook triggers — fire an agent from an external HTTP event (order created, deployment finished)
• on_complete callbacks — notify downstream systems when a triggered task finishes

Follow the changelog for updates.

---

What’s next

• Agents & Lifecycle
• REST API Chat
• Admin: Schemas
• Bootstrap & GitOps