Multilocação para Cortex Agents¶

Como funciona a multilocação¶

Quando você chama a API agent:run, você pode incluir um bloco variables que define um ou mais atributos imutáveis da sessão. A política de acesso a linhas em sua tabela faz referência a esses atributos para filtrar dados do locatário atual.

O fluxo de execução é:

1. Você chama uma API agent:run com um bloco variables que inclui valores específicos do locatário.

2. Antes de executar qualquer SQL gerado, os atributos são definidos na sessão do Snowflake.

3. O SQL gerado é executado na sessão em que as variáveis estão ativas.

4. A política de acesso a linhas da tabela avalia os atributos da sessão e filtra as linhas.

Atributos da sessão¶

O bloco variables oferece suporte a atributos de sessão imutáveis, configurados usando is_immutable_session_attribute: true. Depois que o valor de um atributo é definido, ele não pode ser modificado pelo SQL gerado, por execução de códigos ou por invocação de ferramentas durante a sessão. Isso garante que o contexto do locatário não possa ser alterado durante a execução do agente.

Para configurar atributos de sessão no bloco variables na API agent:run, use o seguinte parâmetro:

Configuração de variáveis em agent:run¶

Passe as variáveis na API agent:run para definir o contexto de locatário para cada de invocação:

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

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

Nesse exemplo, region é definido como um atributo de sessão imutável. A chave é region e o valor é NORTH. O valor é definido antes de executar a consulta, para que a política de acesso a linhas possa fazer referência a ele. Os atributos da sessão persistem durante a interação e não podem ser substituídos.

Políticas de acesso a linhas com atributos de sessão¶

Para impor o isolamento de locatário, a Snowflake recomenda fortemente o uso de um atributo de sessão em uma política de acesso a linhas. A política filtra linhas para que cada locatário veja apenas seus próprios dados.

Criação de uma política de acesso a linhas

O exemplo a seguir cria uma política de acesso a linhas que filtra linhas com base no atributo de sessão 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');

Aplique a política à sua tabela:

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

Quando o agente executa uma consulta na tabela sales, a política de acesso a linhas avalia o atributo de sessão region e retorna somente as linhas em que a coluna region corresponde ao valor definido na chamada agent:run.

Práticas recomendadas¶

Siga estas recomendações ao configurar a multilocação com Cortex Agents:

• Use atributos de sessão imutáveis para políticas de acesso a linhas. Defina is_immutable_session_attribute: true para qualquer variável referenciada por uma política de acesso a linhas. Os atributos imutáveis não podem ser modificados pelo SQL gerado nem pela execução de ferramentas.

• Defina o escopo das variáveis para o nível mais restrito. Defina apenas as variáveis exigidas para cada invocação. Não passe variáveis de que o agente não precisa para a solicitação atual.

• Teste suas políticas de acesso a linhas de forma independente. Verifique se suas políticas de acesso a linhas filtram corretamente, testando-as com instruções SET fora do agente antes da implementação.

Controle de acesso¶

A tabela a seguir descreve os privilégios necessários para a configuração de multilocação:

Limitações¶

As seguintes limitações se aplicam à multilocação com Cortex Agents:

• Escopo da sessão: Os atributos da sessão persistem durante a interação e não podem ser substituídos.

O Snowflake fornece atributos de sessão imutáveis e políticas de acesso a linhas para isolar locatários. Você é responsável por configurá-los corretamente para impor os limites de locatários.