Cortex Agents 的多租户¶

多租户使单个 Cortex Agent 能够服务多个租户，同时在它们之间强制实现数据隔离。您可以通过在 agent:run API 的 variables 块中配置会话属性，并将其与 Snowflake 表上的行访问策略 (RAP) 配合使用来实现租户隔离。在代理执行任何生成的 SQL 之前，Snowflake 会设置您提供的会话属性，行访问策略会根据这些值筛选行。

此方法遵循责任共担模型。Snowflake 提供这些工具（会话属性和行访问策略），而您负责正确配置这些工具以强制执行租户边界。

多租户的工作原理¶

当您调用 agent:run API 时，可以包含一个 variables 块，用于定义一个或多个不可变的会话属性。表上的行访问策略会引用这些属性，以筛选当前租户的数据。

执行流程如下：

您调用一个带有 variables 块的 agent:run API，该变量块包含租户特有的数值。
在执行任何生成的 SQL 之前，这些属性会设置到 Snowflake 会话中。
生成的 SQL 在变量处于活动状态的会话中运行。
表上的行访问策略会评估会话属性，并据此筛选行。

会话属性¶

variables 块支持不可变的会话属性，使用 is_immutable_session_attribute: true 进行配置。一旦属性值被设置，在会话期间无法通过生成的 SQL、代码执行或工具调用进行修改。这可确保在代理执行期间无法更改租户上下文。

要在 agent:run API 的 variables 块中配置会话属性，请使用以下参数：


属性	类型	描述
`is_immutable_session_attribute`	布尔	将变量设置为不可变的会话属性，在会话期间无法修改。

在 agent:run 中配置变量¶

在 agent:run API 中传递变量，为每次调用设置租户上下文：

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

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

在此示例中，region 被设置为不可变的会话属性。键为 region，值为 NORTH。该值在查询执行之前设置，因此行访问策略可以引用它。会话属性在交互期间始终持续有效，且无法被覆盖。

具有会话属性的行访问策略¶

为了强制实施租户隔离，Snowflake 强烈建议在行访问策略中使用会话属性。该策略会筛选行，使每个租户只能看到自己的数据。

创建行访问策略

以下示例创建了一个基于 region 会话属性筛选行的行访问策略：

-- 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 row access policy to the sales table
ALTER TABLE db1.schema1.sales
  ADD ROW ACCESS POLICY rap_region_filter ON (region);

当代理对 sales 表执行查询时，行访问策略会评估 region 会话属性，并仅返回 region 列与 agent:run 调用中设置的值匹配的行。

最佳实践¶

在使用 Cortex Agents 配置多租户时，请遵循以下建议：

为行访问策略使用不可变会话属性。 对于行访问策略引用的任何变量，请设置 is_immutable_session_attribute: true。不可变属性不能通过生成的 SQL 或工具执行修改。
将变量范围限定在最小粒度。 仅设置每次调用所需的变量。不要传递代理在当前请求中不需要的变量。
独立测试行访问策略。 在部署前，通过在代理外部使用 SET 语句测试您的行访问策略，以验证其筛选功能是否正确。

访问控制¶

下表描述了多租户配置所需的权限：


权限	对象	适用场景
MODIFY	代理	使用提示变量配置代理指令
USAGE	代理	使用会话属性调用代理
CREATE ROW ACCESS POLICY	架构	创建行访问策略
ADD ROW ACCESS POLICY	表	将行访问策略应用到表
OWNERSHIP	代理	对代理配置的完全控制

限制¶

Cortex Agents 的多租户机制存在以下限制：

会话范围：会话属性在交互期间始终持续有效，且无法被覆盖。

Snowflake 提供不可变会话属性和行访问策略作为实现租户隔离的工具。您负责正确配置这些项，以强制执行租户边界。