ai_context - Model files

Free text that provides context to the Omni Agent for all topics in the model. When a branch or workbook layer extends a model with ai_context, Omni uses patch-based merging to preserve parent context while allowing layer-specific modifications. This prevents child layers from overwriting parent context when making edits. Refer to the Optimizing models for AI guide for more information on best practices.

Syntax

Value is on one line

ai_context: "<value>"

Value can contain linebreaks

ai_context: |
  <value>

Properties

string

Free text that provides context to the Omni Agent. Can include behavioral prompting, instructions for tone, or other guidance to .The following references are supported for this field:

User attributes, referenced with {{omni_attributes.<attribute_name>}}. This allows you to personalize the context for each user.
Model constants, referenced using @{constant_name} syntax. This allows you to maintain reusable instruction blocks such as tone, privacy guidance, and domain context instead of duplicating them.
omni_llm namespace, which allows you to tailor context to specific AI model tiers:
- {{ omni_llm.model }} — Substitutes the active model’s family name, which will be one of: smartest, standard, or fastest
- {{# omni_llm.<family> }}...{{/ omni_llm.<family> }} — Conditional sections for specific model tiers. <family> must be one of smartest, standard, or fastest
- {{^ omni_llm.<family> }}...{{/ omni_llm.<family> }} — Inverse sections, which apply when the specified tier is not used. <family> must be one of smartest, standard, or fastest
See the Examples section for more information.
omni_agent namespace, which allows you to scope context to specific AI agents:
- {{ omni_agent.name }} — Substitutes the active agent’s name, which will be one of: analyze, build, or simple_summarize
- {{# omni_agent.<agent> }}...{{/ omni_agent.<agent> }} — Conditional sections for specific agents. <agent> must be one of analyze, build, or simple_summarize
- {{^ omni_agent.<agent> }}...{{/ omni_agent.<agent> }} — Inverse sections, which apply when the specified agent is not used. <agent> must be one of analyze, build, or simple_summarize
See the Examples section for more information.

object

Server-managed field that stores how a branch or workbook layer modifies its parent’s ai_context. Omni automatically generates patches when you edit ai_context in a non-base layer.You can delete a patch by omitting the ai_context_patch: field from your YAML in Model mode, but you cannot manually create or edit patch contents. Omni automatically chooses the appropriate patch type.The literal ai_context is always persisted alongside the patch as the source of truth and fallback.

Layer behavior

The patch-based merging described in this section only applies to model-level ai_context.

When you edit the model-level ai_context in a branch or workbook layer in:

Combined mode

Omni compares your edited context to the resolved parent context and automatically generates an ai_context_patch. Both the literal ai_context and the patch are stored.

Model mode

You see only the patch content (your layer’s contribution) when a patch exists. The literal ai_context is hidden but still persisted in the background.

When Omni resolves a model across layers (Shared > Branch > Workbook):

If a layer has an ai_context_patch, Omni attempts to apply it against the resolved parent context
If the patch applies successfully, the result becomes the resolved context for that layer
If a diff patch cannot apply cleanly, such as due to parent changes, Omni falls back to the layer’s literal ai_context
Append patches always apply successfully, making them ideal for layers that only add context

Examples

Behavioral prompting

ai_context: |
  You are an analyst for an eCommerce retailer called BlobsRUs. After generating a query, always provide a summary of the data in both English and Brazilian Portuguese.

Personalized context using user attributes

ai_context: |
  You are an analyst for a {{omni_attributes.company_type}} company. Focus on metrics relevant to the {{omni_attributes.region}} region.

Model-specific instructions

The following context will apply when the model tier is smartest.

Applies when the model tier is smartest

ai_context: |
  {{# omni_llm.smartest }}
  Before calling 'GenerateQuery', explain your reasoning for field selection in detail (9-10 sentences) under "Reasoning for field selection", then provide 3-4 sentences on alternative approaches under "Alternative approaches considered".

  You are running on {{ omni_llm.model }}.
  {{/ omni_llm.smartest }}

The following context will apply when the model tier is not smartest.

ai_context: |
  {{^ omni_llm.smartest }}
  Proceed directly to generating the query without intermediate explanation steps.

  You are running on {{ omni_llm.model }}.
  {{/ omni_llm.smartest }}

Agent-specific instructions

The following context provides detailed modeling conventions to the build_configuration agent while keeping the context concise for other agents.

Agent-specific modeling conventions

ai_context: |
  {{# omni_agent.build }}
  Modeling conventions for this model:
  - Always define primary keys for all base tables
  - Use snake_case for all field names
  - Prefix measures with aggregation type (e.g., total_revenue, count_orders)
  - Document all custom SQL with inline comments
  {{/ omni_agent.build }}

  {{^ omni_agent.build }}
  Standard modeling conventions apply.
  {{/ omni_agent.build }}

  You are the {{ omni_agent.name }} agent.

Using constant references

You can reference constants to maintain reusable AI instruction blocks instead of duplicating them:

Model file with constants

constants:
  tone:
    value: "Keep responses concise and professional."
  privacy_high:
    value: "Never show individual customer names or emails."
  domain_finance:
    value: "This is a financial analytics model. Use monetary values with precision."

ai_context: |
  @{tone} @{privacy_high}
  @{domain_finance}
  You are analyzing company financial data.

Branch layer appending to parent context

# In the SHARED layer:
ai_context: |
  You are an analyst for BlobsRUs eCommerce.

# In a BRANCH layer, adding region-specific context:
ai_context: |
  You are an analyst for BlobsRUs eCommerce.
  
  Focus on the European market and use metric names in euros.
ai_context_patch:
  append: |
    
    Focus on the European market and use metric names in euros.

Workbook layer modifying parent context

# In the SHARED layer:
ai_context: |
  You are an analyst for BlobsRUs. Provide detailed explanations.

# In a WORKBOOK layer, changing tone:
ai_context: |
  You are an analyst for BlobsRUs. Keep responses concise.
ai_context_patch:
  diff: |
    @@ -1 +1 @@
    -You are an analyst for BlobsRUs. Provide detailed explanations.
    +You are an analyst for BlobsRUs. Keep responses concise.

Getting started

Manage content

Analyze & build

Visualize & present

Deliver content

Model data

Manage integrations

ai_context - Model files

Syntax

Properties

Layer behavior

Examples

Behavioral prompting

Personalized context using user attributes

Model-specific instructions

Agent-specific instructions

Using constant references

Branch layer appending to parent context

Workbook layer modifying parent context

​Syntax

​Properties

​Layer behavior

​Examples

​Behavioral prompting

​Personalized context using user attributes

​Model-specific instructions

​Agent-specific instructions

​Using constant references

​Branch layer appending to parent context

​Workbook layer modifying parent context

Syntax

Properties

Layer behavior

Examples

Behavioral prompting

Personalized context using user attributes

Model-specific instructions

Agent-specific instructions

Using constant references

Branch layer appending to parent context

Workbook layer modifying parent context