Multi-Agent Orchestration

Multi-agent orchestration lets you build teams of specialized agents that collaborate on complex tasks. A supervisor agent coordinates the team, delegating subtasks to specialist agents that each have their own tools and expertise.

How it works

The orchestration model is simple but powerful:

A delegation relation in the schema (source → target) defines which agents a supervisor can delegate to. You draw these edges on the schema canvas or create them via POST /api/v1/schemas/{name}/agent-relations.
For each relation, SyntheticBrew generates a spawn_<target> tool on the source agent.
The LLM decides when to spawn based on reasoning. The config limits what is possible.
The target agent’s lifecycle controls its context. Use spawn for a fresh context on every delegation, or persistent when that specialist should continue the same session.
When the sub-agent completes, its summary is returned to the supervisor.
The supervisor integrates the result and continues its own reasoning.

Spawn tree architecture

In a multi-agent system, agents form a tree structure. The supervisor sits at the root and delegates to specialists. Specialists can even spawn their own sub-agents:

# Spawn tree visualization:
#
#   supervisor (persistent)
#   |-- sales-agent (spawn)
#   |   |-- inventory-checker (spawn)
#   |-- support-agent (spawn)
#   |-- researcher (spawn)
#
# Each spawn agent gets a fresh context focused solely on its task.
# Results flow back up the tree to the supervisor.

When to use multi-agent

Complex workflows — a single agent cannot handle all aspects of a task (e.g., sales requires product lookup, inventory check, and order creation).
Specialized models — use a powerful model for the supervisor (reasoning) and cheaper models for specialists (data retrieval).
Tool isolation — a researcher should not have access to order creation tools, and vice versa.
Parallel processing — set the supervisor’s tool execution mode to Parallel when independent specialist calls may run at the same time. Keep Sequential when order matters or a tool needs user input.

Full example

A sales team with a supervisor that delegates to a sales consultant and a support agent:

This config-import example assumes the named models and MCP/custom tools already exist. It creates the agents, schema, and delegation relations; it does not create model credentials, MCP authentication, or capability bindings. Bind Knowledge to an agent separately in Admin or through the capability API.

agents:
  supervisor:
    model: glm-5                  # Powerful model for coordination
    lifecycle: persistent         # Continues within the current chat session
    system: |
      You lead a sales team. When a customer asks about products,
      delegate to the sales-agent. When they need research on
      a topic, delegate to the researcher.

      After receiving results from sub-agents, synthesize
      a final response for the customer.

  sales-agent:
    model: qwen-3-32b             # Cheaper model for data lookup
    lifecycle: spawn              # Fresh context per delegation
    tools:
      - search_products
      - check_inventory
      - create_order
    system: |
      You are a sales consultant. Find products matching
      the customer's needs, check availability, and
      create orders when the customer is ready.

  researcher:
    model: claude-sonnet-4
    lifecycle: spawn
    mcp_servers: [web-search]   # Web search via MCP (Tavily, Brave, etc.)
    system: |
      Research the given topic thoroughly.
      Return a structured report with:
      - Key findings
      - Supporting data
      - Sources

schemas:
  - name: sales-desk
    entry_agent: supervisor       # Receives the user's first message
    chat_enabled: true
    relations:                    # Delegation edges — who may spawn whom
      - from: supervisor          # Creates the spawn_sales_agent tool
        to: sales-agent
      - from: supervisor          # Creates the spawn_researcher tool
        to: researcher

The delegation graph lives in the schemas: section, not on the agents. Each from → to relation generates a spawn_<to> tool on the source agent. Over the REST API the same edge is POST /api/v1/schemas/sales-desk/agent-relations with {"source": "supervisor", "target": "sales-agent"}.

Expected result: a chat sent to sales-desk starts with supervisor. The supervisor can delegate only to the two agents connected from it, and each specialist returns its result to the supervisor. Persistent context lasts within the active session; add and enable the Memory capability if information must be recalled in later sessions.