Multi-agent

Configure multiple agents within a single deployment, each with its own model, accessible views, rules, and certified queries.

Every Cube deployment ships with a single agent by default — see the Overview for the standard configuration. For more advanced setups, you can configure multiple agents within the same deployment, each with its own model, accessible views, rules, and certified queries.

Multi-agent is useful when:

• Different teams need agents tuned to their own domain (e.g., a Sales Assistant and a Marketing Analyst).
• You want specialized agents with distinct instructions or tool access in the same deployment.
• You need to isolate context (rules, certified queries, memories) between user groups.

Spaces and agents must first be created through the Cube Cloud UI before they can be configured via YAML. The system matches YAML entries to UI-created spaces and agents by their name field.

Architecture

A multi-agent setup introduces one new concept on top of the single-agent model: spaces.

• A space belongs to the account and is used by one or more deployments — see Space scope.
• A space is an isolated context. It owns its rules, certified queries, and memories — they are not shared across spaces.
• Each agent belongs to exactly one space and inherits everything that space owns. Multiple agents can live in the same space and share the same rules, certified queries, and memories.

This means you choose a space’s boundary based on what context should be shared. Two agents serving the same team usually live in one space; agents serving different domains (Sales vs. Marketing) live in different spaces so their context stays separate.

In the single-agent setup, there is an implicit auto space that holds all rules, certified queries, and memories — you don’t need to think about it. In a multi-agent setup, you define spaces explicitly and attach rules and certified queries to specific spaces.

What changes from the single-agent setup

The agents/ file structure is the same. What’s different is how agents/config.yml is shaped:

1. Agents are defined as an array. Each agent gets a unique name and an optional description, in addition to the standard agent properties (llm, runtime, accessible_views, memory_mode, etc.).
2. Spaces are introduced. A spaces array defines the contexts agents operate in. Each space gets a unique name.
3. Rules and certified queries attach to spaces. Use the space property in the frontmatter of each rule or certified query Markdown file to attach it to a specific space.

You cannot mix flat root-level properties (the single-agent style) with spaces or agents arrays in the same file. Use one style per file.

Agents

Replace the flat root-level agent properties with an agents array:

# agents/config.yml
agents:
  - name: sales-assistant                   # Required
    description: "AI assistant for sales analytics"
    space: sales-analytics                  # Required: reference to a space
    llm: claude_4_6_sonnet
    accessible_views:
      - orders_view
      - customers_view
    memory_mode: user

  - name: marketing-analyst                 # Required
    description: "AI assistant for marketing analytics"
    space: marketing-analytics              # Required
    llm: gpt_5

The properties available on each agent are the same as in the single-agent setup, plus:

Property	Type	Required	Description
name	string	Yes	Unique identifier for the agent.
description	string	No	Human-readable description.
space	string	Yes	Name of the space this agent belongs to.

Spaces

A space is the context an agent operates in. Spaces own the rules, certified queries, and memories that the agents inside them share. Define spaces alongside agents:

# agents/config.yml
spaces:
  - name: sales-analytics                   # Required
    description: "Space for sales team analytics and reporting"

  - name: marketing-analytics               # Required
    description: "Space for marketing team analytics"

Property	Type	Required	Description
name	string	Yes	Unique identifier for the space.
description	string	No	Human-readable description.

Each agent must reference exactly one space via its space property. Multiple agents can share the same space and inherit its rules, certified queries, and memories.

Space scope

Spaces live at the account level, so one space can be used by agents in more than one deployment. When a space is created, you choose its scope:

• Global — one space that agents in every deployment can use.
• Per deployment — the space is available to a single deployment only.

You pick the scope on the Agents → Spaces page, in two places:

• Create space, when you create a space by hand.
• The Create All panel, shown for spaces and agents declared in agents/config.yml that don’t exist yet. Its Create Spaces control offers Global and Per deployment.

Spaces created per deployment are named after the deployment, for example Product (production) and Product (staging). Only the displayed name changes — the space stays linked to the space name declared in agents/config.yml, so the YAML entry keeps matching. You can change the scope of an existing space later on the space’s page.

Choose per-deployment scope when the same spaces: entry is declared in several deployments — typically development, staging, and production fed from branches of one data model — and you don’t want them sharing what the space stores.

Creating the spaces again does not split a space that was created as global: it already counts as created for every deployment, so Create All creates nothing new. To split one, re-scope it to a deployment on its space page, then run Create All for the other deployments.

Spaces created before this option existed have no scope stored. Cube infers the deployment they belong to from the agents linked to them, and the Spaces list shows them as Not scoped. Set the scope explicitly on the space page to make it definite.

Scope affects storage, not configuration

Scope never changes where configuration comes from. Agents always belong to a single deployment, and the spaces: and agents: entries, rules, and certified queries that shape an agent are read from the agents/ directory of the data model of that deployment, on that deployment’s branch. A global space does not merge the configuration of the deployments that use it.

What a global space shares is storage: the space itself and the data held against it — memories in particular. Two deployments using the same global space read and write the same memories, while each of them still applies its own agents/ configuration.

Attaching rules and certified queries to a space

In the single-agent setup, rules and certified queries belong to the implicit auto space. In a multi-agent setup, you must attach each rule and certified query to a specific space using the space property in the Markdown frontmatter:

<!-- agents/rules/fiscal-year.md -->
---
space: sales-analytics
type: always
---
Always use fiscal year starting April 1st when analyzing dates.

<!-- agents/certified_queries/quarterly-revenue.md -->
---
space: sales-analytics
description: "Apply when the user asks about quarterly revenue"
user_request: "What is the revenue by quarter?"
---
SELECT
  DATE_TRUNC('quarter', order_date) AS quarter,
  SUM(amount) AS revenue
FROM orders
WHERE status != 'cancelled'
GROUP BY 1
ORDER BY 1

You can also organize rules and certified queries into space-named subdirectories. Files placed under agents/rules/<space-name>/ or agents/certified_queries/<space-name>/ are attached to that space automatically — no space frontmatter required.

Complete example

# agents/config.yml
spaces:
  - name: sales-analytics
    description: "Space for sales team analytics and reporting"

  - name: marketing-analytics
    description: "Space for marketing team analytics"

agents:
  - name: sales-assistant
    description: "AI assistant for sales analytics and reporting"
    space: sales-analytics
    llm: claude_4_6_sonnet
    accessible_views:
      - orders_view
      - customers_view
      - products_view
    memory_mode: user

  - name: marketing-analyst
    description: "AI assistant for marketing analytics"
    space: marketing-analytics
    llm: gpt_5
    memory_mode: user