Cortex Agentsのマルチテナンシー¶

マルチテナンシーにより、単一のCortex Agentは複数のテナントを提供しながら、それらのテナント間でデータ分離を実施できます。agent:run API の variables ブロックでセッション属性を構成し、Snowflakeテーブルでそれらを行アクセスポリシー（ RAP ）と組み合わせて、テナント分離を達成します。エージェントが生成された SQL を実行する前に、Snowflakeは指定したセッション属性を設定し、行アクセスポリシーはそれらの値に基づいて行をフィルタリングします。

このアプローチは、共有責任モデルに従います。Snowflakeはツール（セッション属性および行アクセスポリシー）を提供し、ユーザーはテナントの境界を適用するためにそれらを正しく構成する責任があります。

マルチテナンシーの仕組み¶

agent:run API を呼び出すと、1つ以上の不変セッション属性を定義する 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は、テナント分離のツールとして、不変のセッション属性と行アクセスポリシーを提供します。ユーザーは、テナントの境界を適用するために、これらを正しく構成する責任があります。