Multi-tenancy for Cortex Agents¶

How multi-tenancy works¶

When you call the agent:run API, you can include a variables block that defines one or more attributes and variables. The row access policy on your table can be set up to reference these attributes to filter data for the current tenant.

The execution flow is:

1. You call an agent:run API with a variables block that includes tenant-specific values.

2. Before executing any generated SQL, the attributes are set on the Snowflake session.

3. The generated SQL runs in the session where the variables are active.

4. The row access policy on the table evaluates the session attributes and filters rows accordingly.

Mutable vs. immutable session variables¶

The variables block supports both session attributes and session variables.

• Session attributes: Session attributes are immutable and configured using is_immutable_session_attribute: true. Once the value of an attribute is set, it cannot be modified by generated SQL or tool execution during the session.

• Mutable session variables: Session variables are mutable and configured using is_session_variable: true. The value of this variable could be overwritten by other SQL in the session.

Snowflake strongly recommends using immutable session attributes (is_immutable_session_attribute: true) for row access policies. This ensures the tenant context can’t be altered during the agent’s execution.

To configure the properties in the variables block in the agent:run API, use the following parameters:

A single variable can have multiple properties enabled. For example, a username variable can be both a session variable and a session attribute.

Configure variables in agent:run¶

Pass variables in the agent:run API to set tenant context for each invocation:

PUT /api/v2/databases/{database}/schemas/{schema}/agents/{agent_name}:run

{
    "variables": {
        "region": {
            "value": "NORTH",
            "type": "string",
            "is_immutable_session_attribute": true
        },
        "product": {
            "value": "acme",
            "type": "string",
            "is_session_variable": true
        }
    }
}

In this example:

• region is set as an immutable session attribute. The key is region and the value is NORTH. The value is set before query execution, so the row access policy can reference it.

• product is set as a session variable. The key is product and the value is acme. The value is set before query execution, so the row access policy can reference it.

The session variable and session attribute persist for the duration of the interaction. If you set the same variable again in a subsequent agent:run call, the new value overwrites the previous one. Session attributes cannot be overwritten.

Row access policies with session attributes¶

To enforce tenant isolation, Snowflake strongly recommends using a session attribute in a row access policy. The policy filters rows so each tenant sees only their own data.

Create a row access policy

The following example creates a row access policy that filters rows based on the region session attribute:

-- Create a row access policy that filters by the region session attribute
CREATE OR REPLACE ROW ACCESS POLICY rap_region_filter
  AS (region_col STRING) RETURNS BOOLEAN ->
    region_col = SYS_CONTEXT('SNOWFLAKE$SESSION_ATTRIBUTES', 'region');

Apply the policy to your table:

-- Apply the row access policy to the sales table
ALTER TABLE db1.schema1.sales
  ADD ROW ACCESS POLICY rap_region_filter ON (region);

When the agent executes a query against the sales table, the row access policy evaluates the region session attribute and returns only the rows where the region column matches the value set in the agent:run call.

Best practices¶

Follow these recommendations when configuring multi-tenancy with Cortex Agents:

• Use immutable session attributes for row access policies. Set is_immutable_session_attribute: true for any variable referenced by a row access policy. Immutable attributes can’t be modified by generated SQL or tool execution.

• Disable the code sandbox when using mutable session variables. If you can’t use immutable session attributes and must use mutable session variables, disable the code sandbox to prevent code execution from overwriting session variables.

• Restrict custom tools. If you can’t use immutable session attributes and must use mutable session variables, limit custom tools since these could execute SQL and modify session variables.

• Scope variables to the narrowest level. Set only the variables each invocation requires. Don’t pass variables that the agent doesn’t need for the current request.

• Test your row access policies independently. Verify that your row access policies filter correctly by testing them with SET statements outside the agent before deploying.

Access control¶

The following table describes the privileges required for multi-tenancy configuration:

Limitations¶

The following limitations apply to multi-tenancy with Cortex Agents:

• Variable overwrite: Mutable session variables (set with SET statements) can be overwritten by generated SQL, code sandbox execution, or custom tools. Use immutable session attributes for row access policies.

• Session scope: Session variables persist for the duration of the interaction. A subsequent agent:run call with the same variable name overwrites the previous value.

Snowflake provides session variables and row access policies as tools for tenant isolation. You are responsible for configuring these correctly, choosing immutable attributes for sensitive policies, and restricting tools that could modify session state.