Admin Dashboard: Schemas

A schema is the workflow that your users talk to. It chooses the entry agent, defines which specialists can be delegated to, and controls whether a product or widget can start chat sessions. Clients address the schema by name instead of selecting an individual agent.

When to create a schema

Create separate schemas for workflows that need different entry agents, delegation graphs, chat exposure, or isolation. Do not create a schema merely to group unrelated configuration.

For example, a customer-support schema can start with a router and permit delegation to billing and technical specialists, while an employee-help schema can expose a different entry agent and relationship graph. The same agent may appear in more than one schema, but the allowed delegation edges come from the schema used for that chat.

Understand the page

The Schemas list separates templates, system schemas, and schemas owned by your workspace. Open a schema to work with:

Canvas: agents and the directed relationships between them;
Settings: schema name, entry agent, and Accept chat requests;
Test Flow: a chat panel that exercises the saved entry agent and relationship graph.

The list is also where you create, open, and remove customer-owned schemas. Protected system schemas may offer reset rather than normal deletion.

Create from a template

Open Schemas and choose New Schema.
Select a template and enter a lowercase name using letters, digits, and hyphens.
Choose Use template.

The fork creates agents and relationships that belong to your workspace and can be edited independently of the template. Review every generated agent before enabling chat: a template provides a starting workflow, not production-ready prompts, credentials, or access rules.

Creating a schema from a template does not create cron jobs, webhooks, or other triggers. SyntheticBrew currently starts schema work through chat requests; use your own scheduler or integration to call the chat API when work must begin from an external event.

Configure and test

Open a schema to use its canvas and tabs:

Set the entry agent.
Add directed relationships from a delegating agent to an allowed specialist.
Configure each agent’s model, prompt, lifecycle, tools, and capabilities.
In Settings, turn Accept chat requests on when the workflow is ready.
Expand the bottom Test Flow panel, send a representative request, and inspect the emitted steps.

The expected result is a chat-enabled schema addressable by name at /api/v1/schemas/{name}/chat. If an agent API response includes can_spawn, treat it as informational; edit delegation on the schema relationship graph.

Relationship direction matters. router -> billing lets the router delegate to billing; it does not let billing delegate back to the router. Nested delegation works only when every required edge is present. A spawn-lifecycle specialist starts with a focused context for each delegated task, while a persistent agent continues in the current session.

Connect a client

After testing, enable Accept chat requests and call the schema name shown in Admin:

curl -N "$SYNTHETICBREW_URL/api/v1/schemas/customer-support/chat" \
  -H "Authorization: Bearer $SYNTHETICBREW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"I need help with an invoice"}'

The response is an SSE stream. When chat is disabled, a new request returns 404; changing the toggle does not interrupt a turn that is already running. Use the returned session ID to continue the same conversation.

Troubleshooting

The intended specialist is never called: confirm the edge starts at the agent making the delegation, then test through this schema rather than an individual agent view.
The entry agent cannot answer: assign a working Chat model or confirm that the workspace has a default Chat model.
A client receives 404: verify the schema name and turn on Accept chat requests.
A changed tool or relationship is missing: save the resource and start a new session; an existing session keeps the tool catalog with which it began.
Deletion is rejected: remove dependent relations and other references deliberately before trying again.

Operational cautions

Avoid cycles and self-relations; the API rejects them.
Deleting a schema may be refused while related resources still depend on it.
A schema without a usable entry-agent model cannot answer unless the deployment supplies a platform default.
Keep chat disabled while changing a production delegation graph.
Treat a schema name as a stable integration handle. To rename one, create and test the replacement, move clients, and then remove the old schema.