Overview

Every Cube deployment ships with an agent that powers AI features such as Analytics Chat. You can customize the agent’s behavior with rules, certified queries, accessible views, model selection, and memory configuration.

Configuring the agent in the UI is deprecated in favor of code-first configuration. Cube version 1.6.5 or above is required.Deployments created after April 30, 2026 have code-first agent configuration enabled by default. Existing deployments need to opt in by setting CUBE_CLOUD_AGENTS_CONFIG_ENABLED=true. The directory path defaults to agents and can be overridden with CUBE_CLOUD_AGENTS_CONFIG_PATH.

Agent configuration

Agent configuration lives in your Cube data model repository, alongside your cubes and views. Configuration is defined as YAML and Markdown files under an agents/ directory in your project:

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

Storing configuration as code in your repository enables version control, code review, and consistent behavior across environments.

Configure the agent

Place agent properties at the root of agents/config.yml:

# agents/config.yml
llm: claude_4_sonnet
runtime: plain
accessible_views:
  - orders_view
  - customers_view
memory_mode: user

Properties

Property	Type	Default	Description
`llm`	string or object	`auto`	LLM provider — `auto`, a predefined model name, or a BYOM reference.
`embedding_llm`	string or object	`text-embedding-3-large`	Embedding model — a predefined name or a BYOM reference.
`runtime`	string	`plain`	Runtime mode — `plain` or `reasoning`.
`accessible_views`	array	all views	List of view names exposed to the agent as context guidance for which views to query. This is not a security control — if omitted or empty, all views are exposed. Use access policies to enforce actual access restrictions.
`memory_mode`	string	`space`	Memory isolation mode — `space`, `user`, or `disabled`.

Rules and certified queries have their own dedicated pages:

Rules — instructions that guide the agent’s behavior
Certified queries — a library of trusted SQL examples for the agent
Skills — reusable, named agent workflows users can run on demand from chat

LLM

The default value is auto — Cube picks a recommended model on your behalf and may change it as better models become available. Use auto unless you have a reason to pin a specific model. To pin a specific model, set the llm property to one of the predefined models: Anthropic Claude:

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
claude_4_6_sonnet
claude_4_6_opus
claude_4_7_opus

OpenAI GPT:

gpt_4o
gpt_4_1
gpt_4_1_mini
gpt_5
gpt_5_mini
gpt_5_3
gpt_5_4
o3
o4_mini

To use your own model, see Bring your own model.

Embedding models

Predefined embedding models for the embedding_llm property:

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

BYOM is also supported for embedding models.

Runtime

The runtime property controls how the agent processes requests:

Mode	Description
`plain`	Default. Optimized for speed and cost. Recommended for most use cases.
`reasoning`	Enables extended thinking for complex analysis.

reasoning is experimental. It may be unstable and is not yet feature-complete. Stick with plain unless you have a specific need for extended reasoning.

Memory

The memory_mode property controls how the agent persists context across conversations:

Mode	Description
`space`	Default. Memories are shared across all users — useful when the agent serves a single team.
`user`	Memories are isolated per user — useful when each user has private context.
`disabled`	The agent does not persist memory between conversations.

See Memories for details on how memories are stored and used.

Customize the agent

Rules

Define instructions that guide how the agent responds and analyzes data.

Certified queries

Provide a library of trusted SQL queries for the agent to reference.

Skills

Package reusable, named agent workflows that users can run on demand from chat.

Bring your own model

Configure the agent to use your own LLM provider or model.

Memories

Control how the agent persists context across conversations and users.

Connect to data

Users & Permissions

SSO & Identity Providers

Deployment

Monitoring

AI

Account

Agent configuration

Configure the agent

Properties

LLM

Embedding models

Runtime

Memory

Customize the agent

Rules

Certified queries

Skills

Bring your own model

Memories

​Agent configuration

​Configure the agent

​Properties

​LLM

​Embedding models

​Runtime

​Memory

​Customize the agent

Rules

Certified queries

Skills

Bring your own model

Memories

Agent configuration

Configure the agent

Properties

LLM

Embedding models

Runtime

Memory

Customize the agent