> ## 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.

# ai_context

> Sets context for the Omni Agent that is applicable for the entire model.

Free text that provides context to the [Omni Agent](/ai/chat) 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](/modeling/develop/ai-optimization) guide for more information on best practices.

## Syntax

```yaml title="Value is on one line" theme={null}
ai_context: "<value>"
```

```yaml title="Value can contain linebreaks" theme={null}
ai_context: |
  <value>
```

## Properties

<ParamField path="ai_context" type="string">
  Free text that provides context to the Omni Agent. Can include behavioral prompting, instructions for tone, or other guidance to standardize AI outputs across the model.

  You can reference [user attributes](/administration/users/attributes) using `${omni_attributes.<attribute_name>}` syntax to personalize the context for each user. Only user attribute references are allowed — field references and filter conditions are not supported.
</ParamField>

<ParamField path="ai_context_patch" type="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.
</ParamField>

## Layer behavior

<Note>
  The patch-based merging described in this section only applies to model-level `ai_context`.
</Note>

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

<Steps>
  <Step title="Combined mode" noAnchor>
    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.
  </Step>

  <Step title="Model mode" noAnchor>
    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.
  </Step>
</Steps>

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

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

## Examples

```yaml title="Behavioral prompting" theme={null}
ai_context: |
  You are an analyst for an eCommerce retailer called BlobsRUs. After generating a query, always provide a summary of the data both English and Brazilian Portuguese.
```

```yaml title="Personalized context using user attributes" theme={null}
ai_context: |
  You are an analyst for a ${omni_attributes.company_type} company. Focus on metrics relevant to the ${omni_attributes.region} region.
```

```yaml title="Branch layer appending to parent context" theme={null}
# 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.
```

```yaml title="Workbook layer modifying parent context" theme={null}
# 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.
```