Documentation
Yaml Config

YAML Agent Configuration

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 files in the agents/ directory of your Cube project. These files are automatically loaded and validated when your deployment starts.

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

Creating Spaces and Agents

Spaces and agents must first be created through the Cube Cloud UI. YAML configuration is used to override and extend the configuration of existing spaces and agents, not to create them dynamically. When your deployment starts, the system matches YAML entries to UI-created spaces and agents by their name field.

Configuration Override Behavior

When YAML configuration is enabled:

  • Rules: Defined in YAML 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:

  • Semantic Model Selection: Accessible views for each agent are configured through the UI
  • Space and Agent Creation: Initial creation of spaces and agents
  • 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 VariableDescriptionDefault
CUBE_CLOUD_AGENTS_CONFIG_ENABLEDEnables YAML agent configuration. Set to true to activate.false
CUBE_CLOUD_AGENTS_CONFIG_PATHPath to the directory containing agent configuration files, relative to the project root.agents

File Location

Place your agent configuration files in the agents/ directory at the root of your Cube project:

your-cube-project/
├── model/
│   └── cubes/
│       └── orders.yml
├── agents/
│   ├── config.yml           # Main configuration
│   ├── spaces/
│   │   └── sales.yml        # Sales space configuration
│   └── agents/
│       └── assistants.yml   # Agent definitions
└── cube.js

Both .yml and .yaml file extensions are supported. Files can be organized in subdirectories for better organization.

Configuration Schema

Root Structure

The root configuration file can contain two top-level keys:

spaces:
  - # Space definitions...
 
agents:
  - # Agent definitions...

Spaces

Spaces define isolated environments where agents operate and share context.

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

PropertyTypeRequiredDescription
namestringYesUnique identifier for the space
titlestringNoDisplay title for the space
descriptionstringNoHuman-readable description
rulesarrayNoList of agent rules
certified_queriesarrayNoList of certified queries

Rules

Rules provide instructions that guide agent behavior within a space.

spaces:
  - name: sales-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

PropertyTypeRequiredDescription
namestringYesUnique identifier for the rule
descriptionstringNoHuman-readable description
promptstringYesThe instruction text injected into agent context
typestringYesEither 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.

spaces:
  - name: sales-space
    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

PropertyTypeRequiredDescription
namestringYesUnique identifier for the certified query
descriptionstringNoHuman-readable description
user_requeststringYesThe user request pattern this query answers
sql_querystringYesThe SQL query to execute

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

PropertyTypeRequiredDescription
namestringYesUnique identifier for the agent
titlestringNoDisplay title for the agent
descriptionstringNoHuman-readable description
spacestringYesName of the space this agent belongs to
llmstring or objectNoLLM provider configuration
embedding_llmstring or objectNoEmbedding model configuration
runtimestringNoRuntime mode (plain or reasoning)
accessible_viewsarrayNoList of view names the agent can access
memory_modestringNoMemory isolation mode

LLM Providers

You can specify a predefined LLM model:

agents:
  - name: my-agent
    space: my-space
    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:

agents:
  - name: my-agent
    space: my-space
    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

ModeDescription
plainOptimized for speed and cost
reasoningEnables extended thinking mode for complex analysis

Memory Modes

ModeDescription
spaceMemories are shared across all users in the space
userMemories are isolated per user
disabledNo memory is stored

Complete Example

Here's a complete example showing all configuration options:

# agents/config.yml
spaces:
  - name: sales-analytics
    title: "Sales Analytics"
    description: "Space for sales team analytics and reporting"
    rules:
      - name: fiscal-year
        description: "Use fiscal year for date calculations"
        prompt: "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."
        type: always
      
      - name: revenue-definition
        description: "Standard revenue calculation"
        prompt: "Revenue should be calculated as quantity × unit_price, excluding cancelled orders and refunds."
        type: always
      
      - name: efficiency-analysis
        description: "Sales efficiency methodology"
        prompt: "When analyzing sales efficiency, calculate as deal size divided by sales cycle length. Include pipeline velocity metrics for comprehensive analysis."
        type: agent_requested
    
    certified_queries:
      - name: quarterly-revenue
        description: "Get revenue by fiscal quarter"
        user_request: "What is the revenue by quarter?"
        sql_query: |
          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
 
  - 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

Multi-File Configuration

You can split configuration across multiple files for better organization:

# agents/spaces/sales.yml
spaces:
  - name: sales-analytics
    title: "Sales Analytics"
    rules:
      - name: fiscal-year
        prompt: "Use fiscal year starting April 1st"
        type: always
# agents/spaces/marketing.yml
spaces:
  - name: marketing-analytics
    title: "Marketing Analytics"
    rules:
      - name: attribution
        prompt: "Use last-touch attribution"
        type: always
# agents/agents.yml
agents:
  - name: sales-assistant
    space: sales-analytics
    llm: claude_4_sonnet
  
  - name: marketing-assistant
    space: marketing-analytics
    llm: gpt_4o

All files are merged together. The system validates that:

  • Space names are unique across all files
  • Agent names are unique across all files
  • All agent space references point to existing spaces