YAML Agent Configuration - Cube Documentation

This feature is available by request only. Please contact your Cube representative to enable YAML agent configuration for your deployment.

YAML Agent Configuration allows you to define and manage your AI agents, spaces, rules, and certified queries as code. This approach enables version control, code review workflows, and programmatic management of your agent configuration.

Overview

Instead of configuring agents through the Cube Cloud UI, you can create YAML and Markdown files in the agents/ directory of your Cube project. These files are automatically loaded and validated when your deployment starts. An auto space and auto agent are always provisioned by default, so you can get started with just a few lines of configuration. For more complex setups, you can define multiple spaces and agents.

Key Benefits

Version Control: Track changes to agent configuration in Git
Code Review: Review agent configuration changes through pull requests
Infrastructure as Code: Manage agent configuration alongside your data model
Multi-file Support: Split configuration across multiple YAML and Markdown files for better organization
Validation: Automatic schema validation with helpful error messages

UI and YAML Interplay

Understanding how YAML configuration interacts with the Cube Cloud UI is important for effective management.

Configuration Override Behavior

When YAML configuration is enabled:

Rules: Defined in YAML files or Markdown files for the corresponding space
Certified Queries: When YAML config is enabled, only YAML is used for certified queries. UI-based certified query management is disabled to ensure a single source of truth.
Agent Settings: LLM provider, runtime mode, and memory mode can be overridden via YAML

UI-Only Settings

The following settings are still managed exclusively through the Cube Cloud UI:

Agent Embedding: Embedding configuration and deployment settings

Environment Variables

Cube version 1.6.5 or above is required to enable this feature.

The following environment variables control the YAML agent configuration feature:

Environment Variable	Description	Default
`CUBE_CLOUD_AGENTS_CONFIG_ENABLED`	Enables YAML agent configuration. Set to `true` to activate.	`false`
`CUBE_CLOUD_AGENTS_CONFIG_PATH`	Path to the directory containing agent configuration files, relative to the project root.	`agents`

Auto Agent Setup

When YAML agent configuration is enabled, an auto space and auto agent are always provisioned automatically. This is the simplest way to get started — you can customize the default agent without defining any spaces or agents explicitly.

File Structure

your-cube-project/
├── model/
│   └── cubes/
│       └── orders.yml
├── agents/
│   ├── config.yml                  # Agent configuration
│   ├── rules/
│   │   ├── fiscal-year.md          # Rule as Markdown
│   │   └── revenue-definition.md
│   └── certified_queries/
│       └── quarterly-revenue.md    # Certified query as Markdown
└── cube.js

The following file types are supported:

YAML (.yml, .yaml): Define agent settings, rules, and certified queries
Markdown (.md, .markdown): Define individual rules or certified queries with YAML frontmatter

YAML Configuration

Place agent and space properties directly at the root of your YAML file. This configures the default auto agent and auto space:

# agents/config.yml
title: "Sales Assistant"
description: "AI assistant for sales analytics"
llm: claude_4_sonnet
runtime: reasoning
accessible_views:
  - orders_view
  - customers_view
memory_mode: user
rules:
  - name: fiscal-year
    prompt: "Always use fiscal year starting April 1st"
    type: always
certified_queries:
  - name: total-revenue
    user_request: "What is the total revenue?"
    sql_query: "SELECT SUM(amount) FROM orders WHERE status = 'completed'"

The flat configuration automatically creates:

A space named auto with the specified title, description, rules, and certified_queries
An agent named auto in that space with the specified title, description, llm, embedding_llm, runtime, accessible_views, and memory_mode

The auto name is fixed and cannot be overridden.

Properties

Property	Type	Applies to	Description
`title`	string	Space and Agent	Display title
`description`	string	Space and Agent	Human-readable description
`llm`	string or object	Agent	LLM provider configuration
`embedding_llm`	string or object	Agent	Embedding model configuration
`runtime`	string	Agent	Runtime mode (`plain` or `reasoning`)
`accessible_views`	array	Agent	List of view names the agent can access
`memory_mode`	string	Agent	Memory isolation mode
`rules`	array	Space	List of agent rules
`certified_queries`	array	Space	List of certified queries

Markdown Files

In addition to YAML, you can define rules and certified queries as individual Markdown files. Each file uses YAML frontmatter for metadata and the body for content. Since everything targets the auto space by default, you don’t need to specify a space property.

Rules as Markdown

---
description: "Use fiscal year for date calculations"
type: always
---
Always use fiscal year starting April 1st when analyzing dates.
Q1 is April-June, Q2 is July-September, Q3 is October-December, Q4 is January-March.

The Markdown body is used as the rule prompt. If prompt is specified in the frontmatter, the frontmatter value takes precedence over the body.

Certified Queries as Markdown

---
description: "Get revenue by fiscal quarter"
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

The Markdown body is used as the sql_query. If sql_query is specified in the frontmatter, the frontmatter value takes precedence over the body.

Kind Inference

When the kind property is not specified in the frontmatter, it is determined automatically:

Directory path: Files under a rules/ directory are treated as rules. Files under certified_queries/, certified-queries/, or queries/ directories are treated as certified queries.
Frontmatter shape: If the frontmatter contains type or prompt, it is treated as a rule. If it contains user_request or sql_query, it is treated as a certified query.

If kind cannot be determined from either the path or the frontmatter shape, an error is raised.

Name Inference

When the name property is not specified in the frontmatter, it is inferred from the file name by taking the basename without the extension. For example, fiscal-year.md produces the name fiscal-year.

Complete Auto Agent Example

agents/
├── config.yml
├── rules/
│   ├── fiscal-year.md
│   └── revenue-definition.md
└── certified_queries/
    └── quarterly-revenue.md

# agents/config.yml
title: "Sales Assistant"
description: "AI assistant for sales analytics"
llm: claude_4_sonnet
runtime: reasoning
accessible_views:
  - orders_view
  - customers_view
memory_mode: user

<!-- agents/rules/fiscal-year.md -->
---
description: "Use fiscal year for date calculations"
type: always
---
Always use fiscal year starting April 1st when analyzing dates.
Q1 is April-June, Q2 is July-September, Q3 is October-December, Q4 is January-March.

<!-- agents/rules/revenue-definition.md -->
---
description: "Standard revenue calculation"
type: always
---
Revenue should be calculated as quantity × unit_price, excluding cancelled orders and refunds.

<!-- agents/certified_queries/quarterly-revenue.md -->
---
description: "Get revenue by fiscal quarter"
user_request: "What is the revenue by quarter?"
---
SELECT 
  CASE 
    WHEN MONTH(order_date) BETWEEN 4 AND 6 THEN 'Q1'
    WHEN MONTH(order_date) BETWEEN 7 AND 9 THEN 'Q2'
    WHEN MONTH(order_date) BETWEEN 10 AND 12 THEN 'Q3'
    ELSE 'Q4'
  END as fiscal_quarter,
  SUM(quantity * unit_price) as revenue
FROM orders
WHERE status != 'cancelled'
GROUP BY 1
ORDER BY 1

Multiple Agents Setup

When you need multiple agents with separate spaces, you can use the explicit configuration style with spaces and agents arrays. This gives you full control over how agents, rules, and certified queries are organized.

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

File Structure

your-cube-project/
├── model/
│   └── cubes/
│       └── orders.yml
├── agents/
│   ├── config.yml                      # Spaces and agents
│   ├── rules/
│   │   └── sales/
│   │       ├── fiscal-year.md          # Rule for sales-analytics space
│   │       └── revenue-definition.md
│   └── certified_queries/
│       └── sales/
│           └── quarterly-revenue.md    # Certified query for sales-analytics space
└── cube.js

You can also split YAML configuration across multiple files for better organization:

agents/
├── spaces/
│   ├── sales.yml
│   └── marketing.yml
└── agents/
    └── assistants.yml

All YAML and Markdown files are merged together. The system validates that space names and agent names are unique across all files.

Spaces

Spaces define isolated environments where agents operate and share context.

Spaces and agents must first be created through the Cube Cloud UI before they can be configured via YAML. A space discovers available deployments based on its assigned agents, so you must create at least one agent in the UI and assign it to the space before YAML configuration from that deployment becomes visible. When selecting a YAML-configured agent in the UI, the system matches it to the corresponding space and agent by the name field.

spaces:
  - name: analytics-space          # Required: unique identifier
    title: "Analytics Space"       # Optional: display name
    description: "Space for analytics agents"
    rules:
      - # Rule definitions...
    certified_queries:
      - # Certified query definitions...

Space Properties

Property	Type	Required	Description
`name`	string	Yes	Unique identifier for the space
`title`	string	No	Display title for the space
`description`	string	No	Human-readable description
`rules`	array	No	List of agent rules
`certified_queries`	array	No	List of certified queries

Agents

Agents are AI-powered assistants that operate within spaces.

agents:
  - name: sales-assistant           # Required: unique identifier
    title: "Sales Assistant"        # Optional: display name
    description: "AI assistant for sales analytics"
    space: sales-space              # Required: reference to a space
    llm: claude_4_sonnet            # Optional: LLM provider
    embedding_llm: text-embedding-3-large  # Optional: embedding model
    runtime: reasoning              # Optional: runtime mode
    accessible_views:               # Optional: list of accessible views
      - orders_view
      - customers_view
    memory_mode: user               # Optional: memory isolation mode

Agent Properties

Property	Type	Required	Description
`name`	string	Yes	Unique identifier for the agent
`title`	string	No	Display title for the agent
`description`	string	No	Human-readable description
`space`	string	Yes	Name of the space this agent belongs to
`llm`	string or object	No	LLM provider configuration
`embedding_llm`	string or object	No	Embedding model configuration
`runtime`	string	No	Runtime mode (`plain` or `reasoning`)
`accessible_views`	array	No	List of view names the agent can access
`memory_mode`	string	No	Memory isolation mode

Additional spaces and agents can also be created through the Cube Cloud UI. When your deployment starts, the system matches YAML entries to UI-created spaces and agents by their name field.

Markdown Files with Space Targeting

When using multiple spaces, set the space property in your Markdown frontmatter to target the correct space. If space is omitted, the rule or certified query is added to the auto space.

---
space: sales-analytics
description: "Use fiscal year for date calculations"
type: always
---
Always use fiscal year starting April 1st when analyzing dates.

Complete Multiple Agents Example

agents/
├── config.yml
├── rules/
│   ├── fiscal-year.md
│   └── revenue-definition.md
└── certified_queries/
    └── quarterly-revenue.md

# agents/config.yml
spaces:
  - name: sales-analytics
    title: "Sales Analytics"
    description: "Space for sales team analytics and reporting"
    rules:
      - name: efficiency-analysis
        description: "Sales efficiency methodology"
        prompt: "When analyzing sales efficiency, calculate as deal size divided by sales cycle length."
        type: agent_requested

  - name: marketing-analytics
    title: "Marketing Analytics"
    description: "Space for marketing team analytics"
    rules:
      - name: attribution-model
        description: "Default attribution model"
        prompt: "Use last-touch attribution model by default for campaign analysis unless otherwise specified."
        type: always

agents:
  - name: sales-assistant
    title: "Sales Assistant"
    description: "AI assistant for sales analytics and reporting"
    space: sales-analytics
    llm: claude_4_sonnet
    embedding_llm: text-embedding-3-large
    runtime: reasoning
    accessible_views:
      - orders_view
      - customers_view
      - products_view
    memory_mode: user

  - name: sales-report-builder
    title: "Sales Report Builder"
    description: "Specialized agent for building sales reports"
    space: sales-analytics
    llm: gpt_4o
    runtime: plain
    accessible_views:
      - orders_view
    memory_mode: space

  - name: marketing-analyst
    title: "Marketing Analyst"
    description: "AI assistant for marketing analytics"
    space: marketing-analytics
    llm:
      byom:
        name: custom-marketing-model
    runtime: reasoning
    memory_mode: user

<!-- agents/rules/fiscal-year.md -->
---
space: sales-analytics
description: "Use fiscal year for date calculations"
type: always
---
Always use fiscal year starting April 1st when analyzing dates.
Q1 is April-June, Q2 is July-September, Q3 is October-December, Q4 is January-March.

<!-- agents/rules/revenue-definition.md -->
---
space: sales-analytics
description: "Standard revenue calculation"
type: always
---
Revenue should be calculated as quantity × unit_price, excluding cancelled orders and refunds.

<!-- agents/certified_queries/quarterly-revenue.md -->
---
space: sales-analytics
description: "Get revenue by fiscal quarter"
user_request: "What is the revenue by quarter?"
---
SELECT 
  CASE 
    WHEN MONTH(order_date) BETWEEN 4 AND 6 THEN 'Q1'
    WHEN MONTH(order_date) BETWEEN 7 AND 9 THEN 'Q2'
    WHEN MONTH(order_date) BETWEEN 10 AND 12 THEN 'Q3'
    ELSE 'Q4'
  END as fiscal_quarter,
  SUM(quantity * unit_price) as revenue
FROM orders
WHERE status != 'cancelled'
GROUP BY 1
ORDER BY 1

Rules

Rules provide instructions that guide agent behavior within a space.

rules:
  - name: fiscal-year-rule
    description: "Use fiscal year for date calculations"
    prompt: "Always use fiscal year starting April 1st when analyzing dates"
    type: always
  
  - name: efficiency-analysis
    description: "Sales efficiency calculation guidance"
    prompt: "When analyzing sales efficiency, calculate as deal size divided by sales cycle length"
    type: agent_requested

Rule Properties

Property	Type	Required	Description
`name`	string	Yes	Unique identifier for the rule
`description`	string	No	Human-readable description
`prompt`	string	Yes	The instruction text injected into agent context
`type`	string	Yes	Either `always` or `agent_requested`

Rule Types

always: Applied to every agent interaction within the space
agent_requested: Applied only when the agent determines the rule is relevant

Certified Queries

Certified queries are pre-approved SQL queries that agents can use for specific user requests.

certified_queries:
  - name: total-revenue
    description: "Calculate total revenue"
    user_request: "What is the total revenue?"
    sql_query: "SELECT SUM(amount) as total_revenue FROM orders WHERE status = 'completed'"
  
  - name: monthly-sales
    description: "Monthly sales breakdown"
    user_request: "Show me sales by month"
    sql_query: |
      SELECT 
        DATE_TRUNC('month', order_date) as month,
        SUM(amount) as total_sales
      FROM orders
      GROUP BY 1
      ORDER BY 1

Certified Query Properties

Property	Type	Required	Description
`name`	string	Yes	Unique identifier for the certified query
`description`	string	No	Human-readable description
`user_request`	string	Yes	The user request pattern this query answers
`sql_query`	string	Yes	The SQL query to execute

Markdown Frontmatter Reference

Common Properties

Property	Type	Required	Description
`name`	string	No	Unique identifier. Inferred from the file name if omitted.
`kind`	string	No	Either `rule` or `certified_query`. Inferred from directory path or frontmatter shape if omitted.
`space`	string	No	Target space name. Defaults to the `auto` space if omitted. Only needed in multiple agents setup.

Rule-Specific Properties

Property	Type	Required	Description
`description`	string	No	Human-readable description
`type`	string	Yes	Either `always` or `agent_requested`
`prompt`	string	No	Rule prompt. Falls back to the Markdown body if omitted.

Certified Query-Specific Properties

Property	Type	Required	Description
`description`	string	No	Human-readable description
`user_request`	string	Yes	The user request pattern this query answers
`sql_query`	string	No	The SQL query. Falls back to the Markdown body if omitted.

LLM Providers

You can specify a predefined LLM model:

llm: claude_4_sonnet

Available predefined models:

claude_3_5_sonnetv2
claude_3_7_sonnet
claude_3_7_sonnet_thinking
claude_4_sonnet
claude_4_5_sonnet
claude_4_5_haiku
claude_4_5_opus
gpt_4o
gpt_4_1
gpt_4_1_mini
gpt_5
gpt_5_mini
o3
o4_mini

Or use a Bring Your Own Model (BYOM) configuration:

llm:
  byom:
    name: my-custom-model
# Or reference by ID:
# llm:
#   byom:
#     id: 123

Embedding Models

Available predefined embedding models:

text-embedding-3-large
text-embedding-3-small

BYOM is also supported for embedding models using the same syntax as LLM providers.

Runtime Modes

Mode	Description
`plain`	Optimized for speed and cost
`reasoning`	Enables extended thinking mode for complex analysis

Memory Modes

Mode	Description
`space`	Memories are shared across all users in the space
`user`	Memories are isolated per user
`disabled`	No memory is stored

Connect to data

Users & Permissions

SSO & Identity Providers

Deployment

Monitoring

AI

Account & Billing

​Overview

​Key Benefits

​UI and YAML Interplay

​Configuration Override Behavior

​UI-Only Settings

​Environment Variables

​Auto Agent Setup

​File Structure

​YAML Configuration

​Properties

​Markdown Files

​Rules as Markdown

​Certified Queries as Markdown

​Kind Inference

​Name Inference

​Complete Auto Agent Example

​Multiple Agents Setup

​File Structure

​Spaces

​Space Properties

​Agents

​Agent Properties

​Markdown Files with Space Targeting

​Complete Multiple Agents Example

​Rules

​Rule Properties

​Rule Types

​Certified Queries

​Certified Query Properties

​Markdown Frontmatter Reference

​Common Properties

​Rule-Specific Properties

​Certified Query-Specific Properties

​LLM Providers

​Embedding Models

​Runtime Modes

​Memory Modes

Overview

Key Benefits

UI and YAML Interplay

Configuration Override Behavior

UI-Only Settings

Environment Variables

Auto Agent Setup

File Structure

YAML Configuration

Properties

Markdown Files

Rules as Markdown

Certified Queries as Markdown

Kind Inference

Name Inference

Complete Auto Agent Example

Multiple Agents Setup

File Structure

Spaces

Space Properties

Agents

Agent Properties

Markdown Files with Space Targeting

Complete Multiple Agents Example

Rules

Rule Properties

Rule Types

Certified Queries

Certified Query Properties

Markdown Frontmatter Reference

Common Properties

Rule-Specific Properties

Certified Query-Specific Properties

LLM Providers

Embedding Models

Runtime Modes

Memory Modes