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
Autorização do aplicativo	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.
Autorização do usuário	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.

Configure a autenticação com a interface do usuário workspace ou com os Pacotes de Automação Declarativa.

Você pode configurar todas as definições de autenticação de duas maneiras:

• Interface do usuário do espaço de trabalho : Edite o aplicativo e gerencie recursos e escopos a partir da opção Configurar o passo. Recomendado quando você estiver iterando em um único aplicativo no workspace.
• Bundles de Automação Declarativa : Declare recurso, escopos e variável de ambiente em um arquivo databricks.yml e implantado com databricks bundle deploy. Recomendado quando você deseja versionamento baseado em Git , CI/CD ou para distribuir o mesmo agente em diferentes espaços de trabalho. Todos os agentes padrão são enviados com um databricks.yml.

Ambos os caminhos produzem a mesma configuração de tempo de execução. O restante desta página mostra cada instrução em ambos os formatos para que você possa selecionar um e manter a consistência em todo o seu projeto.

Para adicionar um recurso ao aplicativo por qualquer um dos caminhos, você deve ter permissão Can Manage tanto no recurso quanto no aplicativo.

Para obter a referência completa do pacote, consulte app recurso e app.recurso. Para um passo a passo completo do pacote, consulte Gerenciar aplicativos Databricks usando pacotes de automação declarativa.

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 para o experimento.

Workspace UI

1. Clique em Editar na página inicial do seu aplicativo.
2. Vá para Configurar o passo.
3. Na seção de recursos do aplicativo , adicione o recurso de experimento MLflow com permissão Can Edit .

Consulte Adicionar um recurso de experimento do MLflow a um aplicativo Databricks.

Declarative Automation Bundles

1. Declare o experimento na lista resources do seu aplicativo em databricks.yml. O name que você atribui ao recurso é referenciado posteriormente quando você conecta a variável de ambiente.

   YAML

   resources:
     apps:
       my_agent:
         name: 'my-agent'
         source_code_path: ./
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'

2. Reimplemente o pacote:

   Bash

   databricks bundle deploy
   databricks bundle run my_agent

Consulte app.recurso.experiment para obter todos os campos.

Conceder permissões a outros recursos Databricks

Se o seu agente utiliza outros recursos Databricks , como Genie Spaces, índices do Vector Search ou SQL Warehouse, conceda permissões à entidade de serviço em cada um deles.

Para acessar o registro de prompts, conceda permissões CREATE FUNCTION, EXECUTE e MANAGE no esquema do Unity Catalog para armazenar prompts.

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 suas tabelas subjacentes, ao banco de dados SQL e às funções Unity Catalog .

Workspace UI

Adicione recursos ao aplicativo por meio da seção "Recursos do aplicativo" ao criar ou editar o aplicativo no workspace Databricks .

1. Clique em Editar na página inicial do seu aplicativo.
2. Vá para Configurar o passo.
3. Em Recursos do aplicativo , clique em + Adicionar recurso para cada recurso que o agente utiliza e defina a permissão.

Consulte Adicionar recurso a um aplicativo Databricks para obter a lista completa de recursos compatíveis e capturas de tela.

Declarative Automation Bundles

1. Declare todos os recursos que o agente usa na lista resources sob seu aplicativo em databricks.yml. O exemplo abaixo mostra um agente que utiliza um experimento MLflow , um endpoint de serviço, um Genie Space, um SQL warehouse, um índice Vector Search, uma função Unity Catalog e uma instância Lakebase . Cada recurso name é referenciado de config.env até value_from , de modo que o agente recebe o identificador resolvido em tempo de execução.

   YAML

   bundle:
     name: my_agent
   
   resources:
     apps:
       my_agent:
         name: 'my-agent'
         description: 'Custom agent deployed on Databricks Apps'
         source_code_path: ./
         config:
           command: ['uv', 'run', 'start-app']
           env:
             - name: MLFLOW_EXPERIMENT_ID
               value_from: 'experiment'
             - name: LAKEBASE_INSTANCE_NAME
               value_from: 'database'
   
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'
   
           - name: 'llm'
             serving_endpoint:
               name: 'databricks-claude-sonnet-4-5'
               permission: 'CAN_QUERY'
   
           - name: 'sales-genie'
             genie_space:
               space_id: '<genie-space-id>'
               permission: 'CAN_RUN'
   
           - name: 'warehouse'
             sql_warehouse:
               id: '<warehouse-id>'
               permission: 'CAN_USE'
   
           - name: 'docs-index'
             uc_securable:
               securable_full_name: 'main.docs.chunks_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'lookup-function'
             uc_securable:
               securable_full_name: 'main.tools.order_lookup'
               securable_type: 'FUNCTION'
               permission: 'EXECUTE'
   
           - name: 'database'
             database:
               instance_name: '<lakebase-instance-name>'
               database_name: 'databricks_postgres'
               permission: 'CAN_CONNECT_AND_CREATE'
   
   targets:
     dev:
       mode: development
       default: true

importante

Cada valor value_from em config.env deve corresponder a um campo name na lista resources . Incompatibilidades fazem com que a variável de ambiente seja resolvida como None no aplicativo implantado.

2. implantar e começar o pacote:

   Bash

   databricks bundle validate
   databricks bundle deploy
   databricks bundle run my_agent

   bundle deploy Carrega a fonte e configura o recurso. bundle run inicia ou reinicia o aplicativo com a fonte mais recente. O argumento para bundle run é a key YAML em resources.apps (aqui my_agent), não o campo name do aplicativo de implante.

Para o esquema completo de cada subtipo de recurso, consulte app.recurso.

A tabela a seguir lista as permissões mínimas usadas nos exemplos acima e o valor equivalente em Pacotes de Automação Declarativa para cada tipo de recurso:

Tipo de recurso	permissão da interface do usuário do espaço de trabalho	Pacotes de Automação Declarativa: recurso e permissão
SQL Warehouse	Can Use	sql_warehouse com CAN_USE
Modelo de ponto de extremidade de serviço	Can Query	serving_endpoint com CAN_QUERY
Unity Catalog Função	Can Execute	uc_securable com securable_type: FUNCTION e EXECUTE
Espaço Genie	Can Run	genie_space com CAN_RUN
Índice de pesquisa vetorial	Can Select	uc_securable com securable_type: TABLE e SELECT
Unity Catalog Tabela	SELECT	uc_securable com securable_type: TABLE e SELECT
Unity Catalog Conexão	Use Connection	uc_securable com securable_type: CONNECTION e USE_CONNECTION
Volume Unity Catalog	Can Read ou Can Read and Write	uc_securable com securable_type: VOLUME e READ_VOLUME ou WRITE_VOLUME
Lakebase (provisionamento)	Can Connect and Create	database com CAN_CONNECT_AND_CREATE
Lakebase (autoscale)	Can Connect and Create	postgres com CAN_CONNECT_AND_CREATE

Siga o princípio do menor privilégio. Conceda à entidade de serviço apenas as permissões necessárias ao agente e utilize uma entidade de serviço dedicada para cada aplicativo. Para obter a lista completa, consulte as Melhores práticas de segurança.

Autorização do usuário

info

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:

1. 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.
2. 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ê.
3. encaminhamento de tokens : Os tokens com escopo reduzido são disponibilizados para seu aplicativo por meio do cabeçalho HTTP x-forwarded-access-token .
4. 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. Para obter a lista de escopos disponíveis e a semântica de escopo, consulte Segurança baseada em escopo e escalonamento de privilégios.

Workspace UI

1. Na interface do Databricks, acesse as configurações de autorização do seu aplicativo.
2. Em Autorização do usuário , clique em + Adicionar escopo e selecione os escopos que o aplicativo precisa para acessar o recurso em nome do usuário.
3. Salve as alterações e reinicie o aplicativo.

Declarative Automation Bundles

1. Declare os escopos em user_api_scopes no recurso do aplicativo em databricks.yml:

   YAML

   resources:
     apps:
       my_agent:
         name: 'my-agent'
         source_code_path: ./
         user_api_scopes:
           - sql
           - dashboards.genie
           - serving.serving-endpoints
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'

2. Reimplante o pacote e reinicie o aplicativo:

   Bash

   databricks bundle deploy
   databricks bundle run my_agent

nota

Após habilitar a autorização de usuário em um workspace pela primeira vez, você deve reiniciar os aplicativos existentes para que eles possam usar escopos. Consulte Adicionar escopos a um aplicativo.

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.

1. 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:

   Python

   from databricks_app.utils import get_user_workspace_client

   Caso contrário, importe as utilidades do servidor do agente:

   Python

   from agent_server.utils import get_user_workspace_client

   A função get_user_workspace_client() usa o servidor de agentes para capturar o cabeçalho x-forwarded-access-token e 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.

2. Inicialize o cliente workspace no momento da consulta, não durante startup do aplicativo:

importante

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.

Python

# 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. Solicite apenas os escopos mínimos necessários para o seu agente e log todas as ações realizadas em nome de um usuário; consulte Práticas recomendadas para autorização de usuários.

Autentique-se nos servidores Databricks MCP.

Os servidores Databricks gerenciam MCP, expõem índices de pesquisa vetorial e funções Unity Catalog como ferramentas por meio de URLs do formato https://<workspace>/api/2.0/mcp/vector-search/<catalog>/<schema> e https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema>. Para obter a lista de servidores disponíveis e seus padrões de URL, consulte Usar Databricks para gerenciar servidores MCP.

Para autenticar, conceda à entidade de serviço do agente (ou ao usuário, se estiver usando autorização de usuário) acesso a todos os recursos subsequentes nesses esquemas.

Por exemplo, se o seu agente usar os seguintes URLs de servidor MCP:

• https://<your-workspace>/api/2.0/mcp/vector-search/prod/customer_support
• https://<your-workspace>/api/2.0/mcp/vector-search/prod/billing
• https://<your-workspace>/api/2.0/mcp/functions/prod/billing

Você deve conceder acesso a todos os índices de pesquisa vetorial em prod.customer_support e prod.billing e a todas as funções Unity Catalog em prod.billing.

Workspace UI

Adicione cada índice e função como um recurso em Recursos do aplicativo . Siga os mesmos passos que em Conceder permissões a outros recursos Databricks.

Declarative Automation Bundles

1. Adicione uma entrada uc_securable por índice e por função na lista resources do seu aplicativo:

   YAML

   resources:
     apps:
       my_agent:
         resources:
           - name: 'support-index'
             uc_securable:
               securable_full_name: 'prod.customer_support.tickets_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'billing-index'
             uc_securable:
               securable_full_name: 'prod.billing.invoices_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'refund-function'
             uc_securable:
               securable_full_name: 'prod.billing.process_refund'
               securable_type: 'FUNCTION'
               permission: 'EXECUTE'

2. Reimplemente o pacote:

   Bash

   databricks bundle deploy
   databricks bundle run my_agent

Servidores MCP personalizados hospedados como seus próprios aplicativos Databricks (nomes de aplicativos com prefixo mcp-) ainda não são suportados como recurso de pacote. Conceda a entidade de serviço do agente Can Use no aplicativo do servidor MCP manualmente com databricks apps update-permissions. Consulte a habilidade custom-mcp-server no repositório padrão do agente.

Próximos passos

• Crie um agente AI e implemente-o no Databricks Apps
• Gerenciar aplicativos Databricks usando pacotes de automação declarativa
• Configure a autorização em um aplicativo Databricks.
• Adicionar recurso a um aplicativo Databricks
• recurso do aplicativo referência