Multi-Agent Configuration

Use a multi-agent schema when one entry agent should delegate bounded work to specialists. The schema relation graph is the authority for delegation: each directed source to target edge gives the source agent a generated spawn_<target> tool.

Before you begin

Create and verify the model records the agents will use. Config import does not persist model API keys, kind, embedding dimension, default state, API version, or cache-control settings.
Configure any external MCP servers and their credentials before assigning them to agents.
Decide which agent receives chat requests and which specialists should use the spawn lifecycle.
Use a key with agents:write and schemas:write for REST, or config for config import.

Choose the delegation graph

A common hub-and-spoke design has one persistent supervisor and several spawn-lifecycle specialists:

supervisor (entry agent, persistent)
├── researcher (spawn)
├── writer (spawn)
└── reviewer (spawn)

Use persistent for an agent that continues within the current chat session. Use spawn for a delegated, single-use run that starts with fresh context and returns a summary. Cross-session memory is separate and requires the Memory capability.

Relations may form a deeper tree. An agent can be the target of one relation and the source of another. Avoid cycles and self-relations; the schema API rejects them.

Import the agents and schema

The following body uses the config-import snapshot format. primary-model and worker-model must already exist with their credentials configured through Admin, REST, or brewctl. web-search must already be a configured MCP server.

agents:
  - name: supervisor
    model_name: primary-model
    lifecycle: persistent
    system_prompt: |
      Break the request into bounded work. Delegate research and drafting,
      then review the result before answering the user.
    tools: [manage_tasks]

  - name: researcher
    model_name: worker-model
    lifecycle: spawn
    system_prompt: Search approved sources and return a concise brief.
    mcp_servers: [web-search]

  - name: writer
    model_name: worker-model
    lifecycle: spawn
    system_prompt: Draft an answer from the supplied research brief.

schemas:
  - name: content-team
    description: Delegated content workflow
    entry_agent: supervisor
    chat_enabled: true
    relations:
      - from: supervisor
        to: researcher
      - from: supervisor
        to: writer

Apply the file:

curl -X POST "$SYNTHETICBREW_URL/api/v1/config/import" \
  -H "Authorization: Bearer $SYNTHETICBREW_TOKEN" \
  -H "Content-Type: application/x-yaml" \
  --data-binary @content-team.yaml

Config import accepts model as an alias for model_name and system as an alias for system_prompt, but the canonical names above make the format easier to distinguish from brewctl resources. Do not add can_spawn; imported values do not change delegation.

Create relations through REST

When the agents and schema already exist, create each edge separately:

curl -X POST "$SYNTHETICBREW_URL/api/v1/schemas/content-team/agent-relations" \
  -H "Authorization: Bearer $SYNTHETICBREW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source":"supervisor","target":"researcher"}'

The expected result is a relation record and a generated spawn_researcher tool on supervisor. If GET /api/v1/agents/supervisor reports can_spawn, treat it as informational; agent create, update, and patch cannot set delegation.

Isolate models and tools

Assign the strongest model where coordination quality matters and a smaller or local model where a narrow specialist can be evaluated reliably. Model names in agent configuration are tenant-local SyntheticBrew records, not raw provider model IDs.

An agent sees only its configured built-in tools, assigned MCP servers, injected capability tools, and generated delegation tools:

manage_tasks and show_structured_output are core built-ins;
MCP tools appear only when their server is assigned to the agent;
Memory, Knowledge, and Knowledge Graph tools are injected by their capability bindings;
spawn_<target> appears only for an outgoing schema relation;
custom HTTP tools added by an Enterprise administrator are deployment-specific and are not part of config import/export.

Create capability bindings separately after the agent exists. For example, give the researcher persistent memory:

curl -X POST "$SYNTHETICBREW_URL/api/v1/agents/researcher/capabilities" \
  -H "Authorization: Bearer $SYNTHETICBREW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"memory","enabled":true,"config":{}}'

Confirmation and interactive input

confirm_before gates a named tool inside the running process. The REST stream emits confirmation, but REST has no route that approves it; without an in-process responder the call is denied after 60 seconds.

For a web or API client that must collect user input, enable show_structured_output instead. It emits a persisted interrupt_request that the client can resume on the same schema chat endpoint. See Resume a human-in-the-loop interrupt.

Test the workflow

curl -N "$SYNTHETICBREW_URL/api/v1/schemas/content-team/chat" \
  -H "Authorization: Bearer $SYNTHETICBREW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Research the topic and prepare a reviewed briefing."}'

Confirm that the stream shows the expected spawn_researcher or spawn_writer tool call and that the final response returns through the supervisor. If no delegation tool appears, inspect the relation on content-team, not the agent’s read-only can_spawn value.

Operational cautions

Keep specialist prompts narrow and state what their returned summary must contain.
Do not give every agent every MCP server; assignment is an authorization boundary.
Use parallel tool execution only when calls are independent and downstream systems tolerate concurrency.
Set step, context, turn-duration, and step-duration limits proportionate to the model and task.
Test nested delegation for depth, latency, and token cost before production use.