# YAML Agent Configuration

<WarningBox>

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

</WarningBox>

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](#multiple-agents-setup).

### 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

<InfoBox>

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

</InfoBox>

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:

```yaml
# 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

```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

```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:

1. **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.
2. **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
```

```yaml
# 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
```

```markdown
<!-- 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.
```

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

```markdown
<!-- 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.

<WarningBox>

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

</WarningBox>

### 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.

<WarningBox>

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.

</WarningBox>

```yaml
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.

```yaml
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.

```markdown
---
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
```

```yaml
# 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
```

```markdown
<!-- 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.
```

```markdown
<!-- 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.
```

```markdown
<!-- 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.

```yaml
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.

```yaml
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](#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:

```yaml
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:

```yaml
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 |
