> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Modeling Agent

> Chat with AI while you edit your semantic model in the Model IDE—ask questions, draft YAML, and choose how changes are applied.

The **Modeling Agent** is a chat panel in the [Model IDE](/modeling/develop/guides/model-ide) designed to help you build and maintain your semantic model. Use it to ask questions about your model, get suggestions for fields and relationships, and work through YAML edits.

<Note>
  The Modeling Agent is grounded in your **current model and connection** (topics, views, relationships, and [field-level access controls](/modeling/develop/data-access-control)), not arbitrary SQL against your warehouse. To improve answers across Omni AI, see [Optimize models for Omni AI](/modeling/develop/ai-optimization).
</Note>

## Requirements

To use the Modeling Agent, you need:

* **Omni Agent** enabled in [**Settings > AI**](/ai/settings) for your organization
* Permission to open and edit models in the **Model IDE** for your connection (see [modeling permissions](/modeling/develop/guides/permissions-content-org))

## Open the Modeling Agent

1. Open a model in the **Model IDE**.
2. In the **IDE rail**, click **Show Modeling Agent** (sparkles icon) to open the chat panel.
3. Type in the prompt box. Your conversation stays in the panel while you switch files, save, or change modeling modes.

## Example prompts

You can ask in plain language. You do not need to paste YAML unless you want to point at something specific.

```txt theme={null}
How do the customers and orders views relate in this model?
```

```txt theme={null}
Identify opportunities to improve AI context given this chat prompt: "How is my pipeline doing?"
- conflicting context
- redundant context
- missing context

Make sure to flag if any assumptions are being made so the user can make clarifications,

Update the model with your recommendations:
1. Write `ai_context` mapping business terms to fields
  - **Data nuances** — explain what isn't obvious from field names
2. Add `synonyms` to key dimensions and measures
  - Map alternative names, abbreviations, and domain-specific terminology so the Omni Agent matches user queries to the correct field. Works on both dimensions and measures.
  - **Synonyms vs ai_context**: Use `synonyms` for field-level name mapping. Use `ai_context` for topic-level behavioral guidance, data nuances, and multi-field relationships.
3. Curate `ai_fields` to remove noise
  - Reduce noise for large models
4. Improve field `description` values
  - Good descriptions help both the Omni Agent and human analysts.
```

```txt theme={null}
Read the docs for skills and generate one based on the above prompt.
```

```txt theme={null}
Create a dimension that groups the margin field in order_items into logical bins
```

```txt theme={null}
Create a topic that groups our sales-related tables for self-serve reporting.
```

```txt theme={null}
Fix the model validation errors
```

```txt theme={null}
Update every revenue measure so they are all formatted with currency_2
```

## Built-in skills

The Modeling Agent includes default skills that appear as clickable buttons below the prompt box. These skills guide the agent through specialized tasks without requiring you to write detailed prompts.

### Optimize topic for AI

The **Optimize topic for AI** skill analyzes a topic and its views to identify opportunities for improving AI metadata. When you click this skill, the Modeling Agent asks which topic to analyze, then reviews metadata across four categories:

* **Token efficiency** — Identifies verbose or redundant metadata and flags missing `ai_fields` directives that could reduce token usage
* **Clarity** — Highlights ambiguous fields missing context and non-descriptive labels that may confuse the AI
* **Deduplication** — Finds repeated information between `ai_context` and `description` fields, or between field-level and topic-level metadata
* **Sample queries** — Reviews existing sample queries and recommends additions or improvements, including suggestions for golden datasets

After the analysis, the Modeling Agent provides specific recommendations and can apply changes directly to your model.

<Tip>
  Use this skill regularly when building or updating topics to ensure your AI metadata supports high-quality query generation and reduces unnecessary token consumption. For guidance on AI optimization beyond this skill, see [Optimize models for Omni AI](/modeling/develop/ai-optimization).
</Tip>

### Suggest model from query history

<Note>
  This skill applies to [Snowflake](/connect-data/setup/snowflake) and [Postgres](/connect-data/setup/postgres) connections. Each database has specific requirements:

  * **Snowflake**: The database user must have `IMPORTED PRIVILEGES` on the `SNOWFLAKE` database.
    ```sql theme={null}
    GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE TO ROLE <omni_role>;
    ```

  * **Postgres**: The `pg_stat_statements` extension must be enabled.
    ```sql theme={null}
    CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
    ```
</Note>

The **Suggest model from query history** skill analyzes actual SQL query patterns from your warehouse to help generate semantic models based on real usage. When you click this skill, the Modeling Agent analyzes query history from `ACCOUNT_USAGE.QUERY_HISTORY` (Snowflake) or `pg_stat_statements` (Postgres) and provides insights across several areas:

* **Table usage** — Identifies the most frequently queried tables, with breakdowns showing which tables are used as base tables versus joined tables
* **Column patterns** — Tracks how columns are used in `SELECT`, `WHERE`, `GROUP BY`, and `ORDER BY` clauses, along with aggregation function frequencies
* **Join patterns** — Discovers common join relationships between tables, deduplicated by join type and keys
* **Field classification** — Suggests which fields should be dimensions, measures, or time dimensions based on usage patterns
* **Calculated dimensions** — Identifies scalar transforms and common calculated field patterns that could be defined in your model
* **Query view candidates** — Finds repeated CTE patterns that could be extracted as reusable query views

The agent uses these insights to suggest views, measures (with appropriate `aggregate_type` and symmetric aggregation settings), relationships (with `reversible` semantics), and query views that align with how your team actually queries the data.

## Modeling modes

The panel includes a **mode** menu so you control how proposed model changes are applied. Your selected mode persists between sessions.

| Mode        | How it works                                                                              | Best for                                                                                             |
| ----------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Sandbox** | Proposes all changes at once. You review and accept or reject before anything is written. | Exploring ideas, pressure-testing updates, and reviewing larger changes before they enter the model. |
| **Review**  | Writes changes, then pauses for your approval before continuing.                          | Step-by-step collaboration when you want close oversight as changes are made.                        |
| **Auto**    | Applies changes immediately, including branch creation, without pausing.                  | Fast iteration when you're already working on a [branch](/content/develop/branch-mode).              |

In **Sandbox** mode, all proposed changes are bundled and presented as expandable diffs for each affected file. You make a single **Accept all** or **Reject all** decision before anything is written to the model.

<Note>
  If you edit the **shared** model, your workflow may require a **branch** before the Modeling Agent can write changes. Create a branch from the IDE when prompted, then continue the conversation.
</Note>

## Next steps

* [Model IDE](/modeling/develop/guides/model-ide) — Files, branching, and validation
* [Branch Mode](/content/develop/branch-mode) — Isolate model edits before promotion
* [Content validator](/modeling/develop/content-validator) — Catch issues across workbooks and dashboards
* [AI settings](/ai/settings) — Org-wide AI controls

## Troubleshooting

**I don't see the sparkles / Show Modeling Agent control.**
Confirm **Use Omni Agent** is on in [**Settings > AI**](/ai/settings) and that your role can access the Model IDE for the connection.

**The Modeling Agent won't apply edits.**
On the shared model you may need a **branch** first. Create a branch in the IDE, then ask again.

**Answers feel generic.**
Add richer descriptions, [AI context](/modeling/models/ai-context) on views and topics, and [sample queries](/modeling/models/sample-queries) so Omni's AI has more to work with across the product.

## Getting help

If you're stuck and can't remember how to do something in Omni, just ask Blobby. Questions like *"How do I do \[thing]?"* will prompt Blobby to search the official Omni docs and provide you with an answer, all without leaving your Omni workflow.

You can also directly tell Blobby to search the docs when researching the answer to your question.

<Note>
  **Working in an embedded context?** If you have the **Hide Omni watermark** setting enabled to provide a fully white-labeled experience, the AI doc search feature will respect it. Omni doc links will not be returned in chat, even if explicitly requested.
</Note>