Gerenciar permissões para armazenamento de memória e sessão do agente

info

Beta

Este recurso está na Beta. Para usá-lo, um administrador do workspace deve ativar as Sessões de Memória do Agente na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

O armazenamento de memória do agente e o armazenamento de sessão usam o mesmo modelo de permissão de nível de armazenamento. Uma permissão se aplica ao conteúdo do armazenamento: cada entrada de memória em um armazenamento de memória, ou cada sessão e item de sessão em um armazenamento de sessão.

Você pode conceder acesso a um usuário ou service principal do Databricks. Identifique um usuário pelo email e um service principal pelo seu ID de aplicativo (cliente). As permissões de armazenamento não oferecem suporte a grupos.

Requisitos

• Um armazenamento de memória ou armazenamento de sessão existente.
• Para os exemplos da CLI do Agent Bricks ou do SDK do AgentKit, Python 3.10 ou acima e databricks-agentbricks 0.8.0 ou acima.

Modelo de acesso nível da loja

O store é o limite de segurança. Campos como actor_id, session_id, path e metadata organizam e filtram dados, mas não restringem o acesso. Uma entidade principal com acesso ao store pode acessar dados de todos os atores no store. Para isolar dados entre tenants ou usuários, crie um store separado para cada limite de segurança.

As permissões de armazenamento têm os seguintes níveis:

Permissão	Ler dados de loja	Gravar dados de loja
READ	Sim	Não
WRITE	Sim	Sim. WRITE inclui READ.
Sem acesso	Não	N.º Você não pode conceder este estado. Para remover o acesso explícito de uma entidade de serviço, use a operação Revogar. A operação Get relata este estado como PERMISSION_LEVEL_UNSPECIFIED.

Permissão	Ler dados de loja	Gravar dados de loja
READ	Sim	Não
WRITE	Sim	Sim. WRITE inclui READ.
Sem acesso	Não	N.º Você não pode conceder este estado. Para remover o acesso explícito de uma entidade de serviço, use a operação Revogar. A operação Get relata este estado como PERMISSION_LEVEL_UNSPECIFIED.

Apenas o criador do store e os administradores do workspace podem gerenciar permissões:

• O criador do armazenamento tem acesso WRITE implícito e pode conceder, listar e revogar permissões. Você não pode revogar a propriedade do criador.
• Um administrador do workspace pode conceder, listar e revogar permissões em qualquer repositório no workspace. Ser um administrador de workspace não concede acesso a dados por si só. Um administrador sem acesso aos dados existente deve conceder a si mesmo READ ou WRITE para usar o armazenamento.
• Um usuário ou service principal com READ ou WRITE pode usar o repositório, mas não pode gerenciar suas permissões.

O acesso herdado vem da participação em uma função Postgres no projeto Lakebase de suporte, como databricks_superuser. As operações de permissão de armazenamento não alteram essas participações de função. Consulte Gerenciar permissões para funções Postgres.

Operações de permissão

As permissões de armazenamento suportam quatro operações:

Operação	Comportamento
Conceder	Concede READ ou WRITE a um usuário ou service principal. A operação é idempotente. Conceder READ a um principal que tem WRITE não reduz a concessão existente.
Get	Qualquer chamador autenticado pode execução Get. Ele retorna apenas a permissão efetiva do chamador, incluindo acesso implícito ao criador e acesso herdado. Ele retorna PERMISSION_LEVEL_UNSPECIFIED quando o chamador não tem acesso.
Lista	Retorna concessões explícitas a usuários e Service Principal. Ele exclui o acesso implícito do criador, a autoridade de gerenciamento de administrador do workspace e o acesso herdado. Um resultado vazio não prova que nenhum principal pode acessar o armazenamento.
Revogar	Remove concessões explícitas de READ e WRITE de um principal. A operação é idempotente. Ela não remove a propriedade ou acesso herdado.

Operação	Comportamento
Conceder	Concede READ ou WRITE a um usuário ou service principal. A operação é idempotente. Conceder READ a um principal que tem WRITE não reduz a concessão existente.
Get	Qualquer chamador autenticado pode execução Get. Ele retorna apenas a permissão efetiva do chamador, incluindo acesso implícito ao criador e acesso herdado. Ele retorna PERMISSION_LEVEL_UNSPECIFIED quando o chamador não tem acesso.
Lista	Retorna concessões explícitas a usuários e Service Principal. Ele exclui o acesso implícito do criador, a autoridade de gerenciamento de administrador do workspace e o acesso herdado. Um resultado vazio não prova que nenhum principal pode acessar o armazenamento.
Revogar	Remove concessões explícitas de READ e WRITE de um principal. A operação é idempotente. Ela não remove a propriedade ou acesso herdado.

A API REST List usa um tamanho de página default de 100 concessões e oferece suporte a até 1.000 concessões por página. O SDK AgentKit segue todas as páginas automaticamente. Com a CLI do Agent Bricks, use --all para retornar todas as páginas.

Para rebaixar um principal de WRITE para READ, revogue a concessão existente e depois conceda READ. Essas operações não são atômicas, portanto, o principal não tem acesso explícito entre as duas chamadas.

Gerenciar permissões de armazenamento

Os exemplos a seguir gerenciam permissões em um armazenamento de memória. Para um armazenamento de sessão, use sessions stores em vez de memory stores na CLI do Agent Bricks, client.session_stores.get("<store-name>") no SDK do AgentKit ou session-stores/<store-name> no caminho da API REST.

Agent Bricks CLI

Os comandos de permissão aceitam os mesmos identificadores de store que os outros comandos de store. Os stores de memória aceitam um ID de store, nome de recurso ou nome de exibição inequívoco. Os stores de sessão aceitam um nome de store ou nome de recurso.

Para conceder acesso de leitura a um usuário, execução o seguinte:

Bash

agentbricks memory stores permissions grant <store-id> \
  --user teammate@example.com --permission READ

Para conceder acesso de gravação a um Service Principal, faça a execução do seguinte. Passe o ID do aplicativo do service principal:

Bash

agentbricks memory stores permissions grant <store-id> \
  --service-principal <application-id> --permission WRITE

Para obter a sua própria permissão efetiva, execução o seguinte:

Bash

agentbricks memory stores permissions get <store-id>

Para listar todas as concessões explícitas, execute o seguinte como criador da loja ou administrador do workspace:

Bash

agentbricks memory stores permissions list <store-id> --all

Para revogar o acesso explícito de um usuário, execução o seguinte. A opção --yes pula o prompt de confirmação:

Bash

agentbricks memory stores permissions revoke <store-id> \
  --user teammate@example.com --yes

AgentKit SDK

Os métodos de permissão estão disponíveis em objetos MemoryStore e SessionStore. O exemplo a seguir passa explicitamente o nível de permissão e o tipo de principal:

Python

from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

client = AgentKitClient(WorkspaceClient())
store = client.memory_stores.get("<store-id>")

# Grant a user read access.
store.grant_permission(
    "teammate@example.com",
    principal_type="USER",
    permission="READ",
)

# Return the authenticated caller's effective permission.
permission = store.get_permission()
print(permission.principal.name, permission.permission)

# List every explicit grant.
for grant in store.list_permissions(page_size=100):
    print(grant.principal.name, grant.principal.principal_type, grant.permission)

# Remove the user's explicit READ and WRITE grants.
store.revoke_permission("teammate@example.com", principal_type="USER")

grant_permission() e revoke_permission() usar SERVICE_PRINCIPAL como o tipo de principal default. grant_permission() usa WRITE como a permissão default. Passe ambos os argumentos explicitamente ao conceder acesso ao usuário ou acesso somente leitura.

REST API

Os Endpoint de permissão estão em /api/2.0/agents/memory-stores/<store-id>/permissions. O corpo da solicitação identifica um usuário com USER e um service principal com SERVICE_PRINCIPAL.

Defina DATABRICKS_HOST como a URL do seu workspace, incluindo https://, e DATABRICKS_TOKEN como seu access token.

Para conceder a um usuário acesso de leitura, chame a operação Grant:

Bash

curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions:grant" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": {"principal_type": "USER", "name": "teammate@example.com"},
    "permission": "READ"
  }'

Para obter a permissão efetiva do chamador autenticado, chame a operação Get:

Bash

curl "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions/self" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Para listar concessões explícitas, chame a operação Listar como criador da loja ou administrador do workspace:

Bash

curl "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions?page_size=100" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Para revogar o acesso explícito do usuário, chame a operação Revogar:

Bash

curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions:revoke" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": {"principal_type": "USER", "name": "teammate@example.com"}
  }'

As operações Grant e Revoke não retornam um objeto de permissão. Para verificar uma alteração, faça a execução de List como o criador da store ou administrador de Workspace. Para verificar o acesso efetivo, autentique-se como o principal afetado e execução Get.

Permissões gerenciadas por implantação de agente

Quando um projeto de agente declara um armazenamento de memória ou sessão, agentbricks deploy concede ao service principal do aplicativo implantado acesso a esse armazenamento. Uma implantação posterior pode restaurar o acesso que você revogou manualmente.

Desvincular um repositório remove a vinculação do projeto do agente. Isso não revoga o acesso que já foi concedido ao service principal do aplicativo. Use a operação Revogar para remover esse acesso.

Outros recursos

• • Memória do agente
  • Dê aos agentes uma memória de longo prazo que persiste em diferentes conversas.
• • Sessões de agente
  • Armazene a história de conversas de um agente para que ele possa retomar uma interação entre turnos.