Autenticação para agentes AI
Os agentes AI frequentemente precisam se autenticar em outros recursos para concluir tarefas. Por exemplo, um agente implantado pode precisar acessar um índice do Vector Search para consultar dados não estruturados, um endpoint de serviço para chamar um modelo básico ou funções do Unity Catalog para executar lógica personalizada.
Esta página aborda os métodos de autenticação para agentes implantados em Databricks Apps. Para agentes implantados no endpoint do modelo, consulte Autenticação para agentes AI (servindo modelo).
O Databricks Apps oferece dois métodos de autenticação para agentes. Cada método serve a diferentes casos de uso:
Método | Descrição | Quando usar |
|---|---|---|
O agente se autentica usando uma entidade de serviço criada automaticamente com permissões consistentes. Anteriormente chamada de autenticação de entidade de serviço. | Caso de uso mais comum. Utilize quando todos os usuários devem ter o mesmo acesso ao recurso. | |
O agente se autentica usando a identidade do usuário que faz a solicitação. Anteriormente chamada de autenticação "Em nome de" (OBO). | Utilize quando precisar de permissões específicas do usuário, trilhas de auditoria ou controle de acesso refinado com o Unity Catalog. |
Você pode combinar ambos os métodos em um único agente. Por exemplo, use a autorização de aplicativo para acessar um índice de pesquisa vetorial compartilhado e a autorização de usuário para consultar tabelas específicas do usuário.
Autorização do aplicativo
Por default, Databricks Apps autenticam-se usando a autorização do aplicativo. O Databricks cria automaticamente uma entidade de serviço quando você cria o aplicativo, e ela funciona como a identidade do aplicativo.
Todos os usuários que interagem com o aplicativo compartilham as mesmas permissões definidas para a entidade de serviço. Esse modelo funciona bem quando você deseja que todos os usuários vejam os mesmos dados ou quando o aplicativo executa operações compartilhadas que não estão vinculadas a controles de acesso específicos do usuário.
Para obter informações detalhadas sobre a autorização de aplicativos, consulte Autorização de aplicativos.
Conceda permissões ao experimento MLflow.
Seu agente precisa ter acesso a um experimento MLflow para log rastreamentos e resultados de avaliação.
Conceda permissão à entidade de serviço Can Edit no experimento MLflow :
- Clique em Editar na página inicial do seu aplicativo.
- Acesse a opção Configurar o passo.
- Na seção de recursos do aplicativo , adicione o recurso do experimento MLflow .
Consulte Adicionar um recurso de experimento do MLflow a um aplicativo Databricks.
Conceder permissões a outros recursos Databricks
Se o seu agente utiliza outros recursos Databricks , como Genie spaces, índices de pesquisa vetorial ou o data warehouse SQL , conceda as permissões à entidade de serviço através da interface de usuário Databricks Apps . Consulte Adicionar recurso a um aplicativo Databricks para obter a lista completa de recursos compatíveis e instruções de configuração.
Para acessar o registro de prompts, conceda permissões CREATE FUNCTION, EXECUTE e MANAGE no esquema do Unity Catalog para armazenar prompts.
A tabela a seguir lista as permissões mínimas necessárias para que os agentes acessem recursos comuns Databricks :
Tipo de recurso | Permissão |
|---|---|
SQL Warehouse |
|
Modelo de ponto de extremidade de serviço |
|
Unity Catalog Função |
|
Espaço Genie |
|
Índice de pesquisa vetorial |
|
Unity Catalog Tabela |
|
Unity Catalog Conexão |
|
Volume Unity Catalog |
|
Lakebase |
|
Ao conceder acesso a um recurso Unity Catalog , você também deve conceder permissões a todos os recursos dependentes subsequentes. Por exemplo, se você conceder acesso a um espaço Genie , também deverá conceder acesso às tabelas subjacentes, ao banco de dados SQL e às funções Unity Catalog .
O usuário que adiciona o recurso deve ter a permissão Can Manage tanto no recurso quanto no aplicativo. Para obter a lista completa de recursos suportados e todas as permissões disponíveis, consulte Tipos de recursos suportados.
Para obter as melhores práticas sobre como gerenciar a autorização de aplicativos com segurança, incluindo o gerenciamento de credenciais e os princípios de privilégio mínimo, consulte Autorização de aplicativos.
Autorização do usuário
Visualização
A autorização de usuários está em versão prévia pública. O administrador do seu workspace precisa habilitá-lo antes que você possa usar a autorização de usuário.
A autorização do usuário permite que um agente aja com a identidade do usuário que fez a solicitação. Isto proporciona:
- Acesso por usuário a dados confidenciais
- Controles de dados refinados aplicados pelo Unity Catalog
- Trilhas de auditoria específicas do usuário
- Aplicação automática de filtros em nível de linha e máscaras de coluna.
Utilize a autorização de usuário quando seu agente precisar acessar o recurso usando a identidade do usuário solicitante em vez da entidade de serviço do aplicativo.
Como funciona a autorização de usuários
Ao configurar a autorização de usuário para seu agente:
- Adicione escopos de API ao seu aplicativo : defina quais APIs do Databricks o aplicativo pode acessar em nome dos usuários. Consulte Adicionar escopos a um aplicativo.
- As credenciais do usuário têm seu escopo reduzido : o Databricks utiliza as credenciais do usuário e as restringe apenas aos escopos de API definidos por você.
- encaminhamento de tokens : Os tokens com escopo reduzido são disponibilizados para seu aplicativo por meio do cabeçalho HTTP
x-forwarded-access-token. - O AgentServerMLflow armazena os tokens : O Agent Server armazena automaticamente esses tokens por solicitação para facilitar o acesso no código do agente.
Configure a autorização do usuário adicionando escopos na interface do usuário do Databricks Apps ao criar ou editar seu aplicativo, ou programaticamente usando a API. Consulte Adicionar escopos a um aplicativo para obter instruções detalhadas.
Agentes com autorização de usuário podem acessar o seguinte recurso Databricks :
- SQL Warehouse
- Espaço Genie
- Arquivos e diretórios
- Endpoint do serviço de modelos
- Índice de pesquisa vetorial
- Conexões Unity Catalog
- Tabelas Unity Catalog
Implementar autorização de usuário
Para implementar a autorização de usuários, você precisa adicionar escopos de autorização ao seu aplicativo. Os escopos restringem o que o aplicativo pode fazer em nome do usuário.
- Na interface Databricks , acesse as configurações de autorização dos seus Databricks Apps .
- Clique em +Adicionar escopo e selecione os escopos aos quais você deseja acessar o recurso em nome do usuário.
- Salve as alterações.
Para configurar a autorização do usuário no código do seu agente, recupere o cabeçalho desta solicitação do AgentServer e construa um cliente workspace com essas credenciais.
-
No código do seu agente, importe as utilidades de autenticação:
Se estiver usando um dos padrões fornecidos em databricks/app-padrão, importe as russias fornecidas:
Pythonfrom databricks_app.utils import get_user_workspace_clientCaso contrário, importe as utilidades do servidor do agente:
Pythonfrom agent_server.utils import get_user_workspace_clientA função
get_user_workspace_client()usa o servidor de agentes para capturar o cabeçalhox-forwarded-access-tokene constrói um cliente workspace com essas credenciais de usuário, lidando com a autenticação entre o usuário, o aplicativo e o servidor de agentes. -
Inicialize o cliente workspace no momento da consulta, não durante startup do aplicativo:
Chame get_user_workspace_client() dentro dos manipuladores invoke e stream , não em __init__ ou na startup do aplicativo. As credenciais do usuário só ficam disponíveis no momento da consulta, quando o usuário faz uma solicitação. A inicialização durante startup do aplicativo falhará porque ainda não existe um contexto de usuário.
# In your agent code (inside invoke or stream handler)
user_client = get_user_workspace_client()
# Use user_client to access Databricks resources with user permissions
response = user_client.serving_endpoints.query(name="my-endpoint", inputs=inputs)
Para um guia completo sobre como adicionar escopos e entender a segurança baseada em escopo, consulte Segurança baseada em escopo e escalonamento de privilégios.
Autentique-se nos servidores Databricks MCP.
Para autenticar nos servidores Databricks MCP, especifique todos os recursos que seu agente precisa em seu arquivo databricks.yaml . Conceda à entidade de serviço do aplicativo (ou aos usuários, se estiver usando autorização de usuário) acesso a todos os recursos subsequentes.
Por exemplo, se o seu agente usar os URLs do servidor MCP listados abaixo, você deverá conceder acesso a todos os índices de pesquisa vetorial nos esquemas prod.customer_support e prod.billing e a todas as funções Unity Catalog em prod.billing:
https://<your-workspace-hostname>/api/2.0/mcp/vector-search/prod/customer_supporthttps://<your-workspace-hostname>/api/2.0/mcp/vector-search/prod/billinghttps://<your-workspace-hostname>/api/2.0/mcp/functions/prod/billing
Configure a autenticação com os Bundles Databricks Ativo.
Você pode configurar todas as definições de autenticação programaticamente usando Databricks Ativo Bundles em vez da interface de utilizador Databricks Apps . Esta página mostra a configuração baseada em interface do usuário para ilustrar quais recursos e permissões são necessários, mas a mesma configuração pode ser definida nos seus arquivos YAML do pacote. Consulte a seção Aplicativos em pacotes para obter a referência completa da configuração do pacote.