docs-mintlify/admin/ai/index.mdx
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.
<Warning> 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.
</Warning>
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.
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
| 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:
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_sonnetv2claude_3_7_sonnetclaude_3_7_sonnet_thinkingclaude_4_sonnetclaude_4_5_sonnetclaude_4_5_haikuclaude_4_5_opusclaude_4_6_sonnetclaude_4_6_opusclaude_4_7_opusOpenAI GPT:
gpt_4ogpt_4_1gpt_4_1_minigpt_5gpt_5_minigpt_5_3gpt_5_4o3o4_miniTo use your own model, see Bring your own model.
Predefined embedding models for the embedding_llm property:
text-embedding-3-largetext-embedding-3-smallBYOM is also supported for embedding models.
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. |
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.