Autenticação para agentes de IA

Os agentes de IA geralmente precisam se autenticar em outros recursos para concluir tarefas. Por exemplo, um agente implementado pode precisar de aceder a um índice de Pesquisa Vetorial para consultar dados não estruturados, um endpoint de serviço para chamar um modelo de fundação, ou funções do Unity Catalog para executar lógica personalizada.

Esta página aborda métodos de autenticação para agentes implementados nas aplicações Databricks. Para agentes implementados em endpoints Model Serving, veja Autenticação para agentes de IA (Model Serving).

O Databricks Apps fornece dois métodos de autenticação para agentes. Cada método serve diferentes casos de uso:

Pode combinar ambos os métodos num único agente. Por exemplo, use a autorização da aplicação para aceder a um índice partilhado de Pesquisa Vetorial enquanto usa a autorização do utilizador para consultar tabelas específicas do utilizador.

Configurar autenticação usando a UI do workspace ou pacotes de automação declarativa

Pode configurar todas as definições de autenticação de duas formas:

• Interface do Espaço de Trabalho: Edite a aplicação e gere recursos e escopos a partir do passo Configurar . Recomendado quando estás a iterar numa única aplicação no espaço de trabalho.
• Pacotes de Automação Declarativa: Declare recursos, escopos e variáveis de ambiente num databricks.yml ficheiro e implemente com databricks bundle deploy. Recomendado quando quiseres versionamento baseado em Git, CI/CD, ou para enviar o mesmo agente entre espaços de trabalho. Todos os modelos de agentes são enviados com um databricks.yml.

Ambos os caminhos produzem a mesma configuração em tempo de execução. O resto desta página mostra cada instrução em ambos os formulários para que possas escolher uma e manter a consistência dentro do teu projeto.

Para adicionar um recurso à aplicação por qualquer um dos caminhos, deve ter Can Manage permissão tanto para o recurso como para a aplicação.

Para a referência completa do pacote, veja app resource e app.resources. Para um guia completo de bundles, consulte Gerenciar aplicações Databricks usando Declarative Automation Bundles.

Autorização do aplicativo

Por defeito, as aplicações Databricks autenticam-se usando autorização de aplicação. O Databricks cria automaticamente um principal de serviço quando cria a aplicação, que atua como a identidade da aplicação.

Todos os utilizadores que interagem com a aplicação partilham as mesmas permissões definidas para o principal do serviço. Este modelo funciona bem quando se quer que todos os utilizadores vejam os mesmos dados ou quando a aplicação realiza operações partilhadas que não estão ligadas a controlos de acesso específicos do utilizador.

Para informações detalhadas sobre autorização de aplicações, consulte autorização de aplicação.

Conceder permissões ao experimento MLflow

O seu agente precisa de acesso a uma experiência MLflow para registar traços e resultados de avaliação. Conceda permissão ao principal de serviço Can Edit no experimento.

Interface do usuário do espaço de trabalho

1. Clique em Editar na página inicial da sua aplicação.
2. Vai para a etapa Configurar .
3. Na secção recursos da app, adicione o recurso de experimentação MLflow com Can Edit permissão.

Veja Adicionar um recurso de experiência MLflow a uma aplicação Databricks.

Pacotes de Automação Declarativa

1. Declare o experimento na lista resources da aplicação em databricks.yml. O name que você atribuir ao recurso será referenciado mais tarde quando configurar variáveis de ambiente.

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

2. Redistribuir o pacote:

   databricks bundle deploy
   databricks bundle run my_agent
   

Consulte app.resources.experiment para todas as áreas.

Conceder permissões a outros recursos Databricks

Se o seu agente usar outros recursos Databricks, como espaços Genie, índices de Pesquisa Vetorial ou armazéns SQL, conceda permissões principais ao serviço em cada um deles.

Para aceder ao registro de prompt, conceda as permissões CREATE FUNCTION, EXECUTE e MANAGE no esquema do Catálogo Unity para armazenar prompts.

Ao conceder acesso aos recursos do Unity Catalog, deve também atribuir permissões a todos os recursos dependentes subsequentes. Por exemplo, se conceder acesso a um espaço Genie, também deve conceder acesso às suas tabelas subjacentes, armazéns SQL e funções do Unity Catalog.

Interface do usuário do espaço de trabalho

Adicione recursos à aplicação através da secção de recursos da aplicação quando criar ou editar a aplicação no espaço de trabalho Databricks.

1. Clique em Editar na página inicial da sua aplicação.
2. Vai para a etapa Configurar .
3. Nos recursos da App, clique + Adicionar recurso para cada recurso que o agente utiliza e defina a permissão.

Consulte Adicionar recursos a uma aplicação Databricks para a lista completa de recursos suportados e capturas de ecrã.

Pacotes de Automação Declarativa

1. Declare todos os recursos que o agente usa na lista resources na sua aplicação em databricks.yml. O exemplo abaixo mostra um agente que utiliza um experimento MLflow, um endpoint de serviço, um espaço Genie, um warehouse SQL, um índice de Pesquisa Vetorial, uma função Unity Catalog e uma instância Lakebase. Cada recurso name é referenciado a partir de config.env por meio de value_from para que o agente receba o identificador resolvido em tempo de execução.

   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 value_from valor em config.env deve corresponder a um name campo na resources lista. As incompatibilidades fazem com que a variável de ambiente se resolva para None na aplicação implementada.

2. Lançar e iniciar o pacote:

   databricks bundle validate
   databricks bundle deploy
   databricks bundle run my_agent
   

   bundle deploy carrega a fonte e configura os recursos. bundle run Inicia ou reinicia a aplicação com a fonte mais recente. O argumento para bundle run é a chave YAML em resources.apps (aqui my_agent), não o campo name da aplicação implementada.

Para o esquema completo de cada subtipo de recurso, veja app.resources.

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

Siga o princípio do menor privilégio. Conceda ao principal de serviço apenas as permissões de que o agente precisa e utilize um principal de serviço dedicado por aplicação. Para a lista completa, consulte as melhores práticas de segurança.

Autorização do utilizador

A autorização do utilizador permite que um agente atue com a identidade do utilizador que faz o pedido. Isto prevê:

• Acesso por usuário a dados confidenciais
• Controles de dados refinados impostos pelo Unity Catalog
• Registos de auditoria específicos para o utilizador
• Aplicação automática de filtros ao nível de linha e máscaras de coluna

Use a autorização do utilizador quando o seu agente precisar de aceder a recursos usando a identidade do utilizador solicitante em vez do principal do serviço da aplicação.

Como funciona a autorização do utilizador

Quando configura a autorização do utilizador para o seu agente:

1. Adicione escopos de API à sua aplicação: Defina quais as APIs Databricks que a aplicação pode aceder em nome dos utilizadores. Veja Adicionar telescópios a uma aplicação.
2. As credenciais do utilizador são reduzidas: o Databricks recolhe as credenciais do utilizador e restringe-as apenas aos escopos da API que definiste.
3. Encaminhamento de tokens: O token com escopo reduzido é disponibilizado para a sua aplicação através do x-forwarded-access-token cabeçalho HTTP.
4. O MLflow AgentServer armazena o token: O Agent Server armazena automaticamente este token por pedido para acesso conveniente no código do agente.

Configure a autorização do utilizador adicionando escopos na interface de aplicações do Databricks ao criar ou editar a sua aplicação, ou ao usar programaticamente a API. Consulte Adicionar telescópios a uma aplicação para instruções detalhadas.

Agentes com autorização do utilizador podem aceder aos seguintes recursos Databricks:

• Armazém SQL
• Espaço Genie
• Ficheiros e diretórios
• Ponto de extremidade de serviço de modelo
• Índice de pesquisa vetorial
• Ligações ao Catálogo Unity
• Tabelas do Catálogo Unity

Implementar a autorização do utilizador

Para implementar a autorização do utilizador, deve adicionar escopos de autorização à sua aplicação. Os escopos limitam o que a aplicação pode fazer em nome do utilizador. Para a lista de escopos e semântica de âmbito disponíveis, consulte Segurança baseada em escopo e escalação de privilégios.

Interface do usuário do espaço de trabalho

1. Na interface do Databricks, vá às definições de Autorização da sua aplicação.
2. Em Autorização de Utilizador, clique + Adicionar âmbito e selecione os scopos que a aplicação precisa para aceder aos recursos em nome do utilizador.
3. Guarda as alterações e reinicia a aplicação.

Pacotes de Automação Declarativa

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

   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. Redistribua o pacote e reinicia a aplicação:

   databricks bundle deploy
   databricks bundle run my_agent
   

   Note

   Depois de ativar a autorização do utilizador num espaço de trabalho pela primeira vez, deve reiniciar as aplicações existentes antes que possam usar os scopes. Veja Adicionar telescópios a uma aplicação.

Para configurar a autorização do utilizador no código do seu agente, recupere o cabeçalho deste pedido do AgentServer e construa um cliente de espaço de trabalho com essas credenciais.

1. No seu código de agente, importe a utilidade de autenticação:

   Se estiver a usar um dos modelos fornecidos de databricks/app-templates, importe o utilitário fornecido:

   from databricks_app.utils import get_user_workspace_client
   

   Caso contrário, importa das utilidades do Agent Server:

   from agent_server.utils import get_user_workspace_client
   

   A get_user_workspace_client() função utiliza o Agent Server para capturar o x-forwarded-access-token cabeçalho e constrói um cliente de espaço de trabalho com essas credenciais de utilizador, lidando com a autenticação entre o utilizador, a aplicação e o agente servidor.

2. Inicialize o cliente do espaço de trabalho no momento da consulta, não durante o arranque da aplicação:

   Importante

   Ligue get_user_workspace_client() dentro dos handlers invoke e stream, e não no __init__ ou no arranque da aplicação. As credenciais de utilizador só estão disponíveis no momento da consulta, quando um utilizador faz um pedido. Inicializar durante o arranque da aplicação falha porque ainda não existe contexto do utilizador.

   # 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 compreender a segurança baseada em âmbito, consulte Segurança baseada em âmbito e escalonamento de privilégios. Solicite apenas os escopos mínimos de que o seu agente precisa e registre todas as ações realizadas em nome de um utilizador; consulte Melhores práticas para autorização de utilizador.

Autenticar em servidores MCP Databricks

Os servidores MCP geridos Databricks expõem índices de Pesquisa Vetorial e funções do Catálogo Unity como ferramentas através de URLs da forma https://<workspace>/api/2.0/mcp/vector-search/<catalog>/<schema> e https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema>. Para a lista de servidores disponíveis e os seus padrões de URL, veja Utilizar servidores MCP geridos pela Databricks.

Para autenticar, conceda ao principal de serviço do agente (ou ao utilizador, se estiver a usar autorização de utilizador) acesso a todos os recursos descendentes nesses esquemas.

Por exemplo, se o seu agente usar as 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

Deve conceder acesso a todos os índices de pesquisa vetorial em prod.customer_support e prod.billing, e a todas as funções do Catálogo Unity em prod.billing.

Interface do usuário do espaço de trabalho

Adicione cada índice e funcione como um recurso em Recursos da App. Siga as mesmas etapas que Conceder permissões a outros recursos Databricks.

Pacotes de Automação Declarativa

1. Adicione uma entrada uc_securable por índice e por função na lista resources da sua app:

   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. Redistribuir o pacote:

   databricks bundle deploy
   databricks bundle run my_agent
   

Servidores MCP personalizados alojados como as suas próprias aplicações Databricks (nomes de aplicações prefixados com mcp-) ainda não têm suporte como recursos agrupados. Conceda manualmente o principal Can Use de serviço do agente na aplicação do servidor MCP com databricks apps update-permissions. Veja a competência custom-mcp-server no repositório de modelos de agentes.

Próximos passos

• Crie um agente de IA e implemente-o nas aplicações Databricks
• Gerir aplicações Databricks usando Pacotes de Automação Declarativa
• Configurar a autorização numa aplicação Databricks
• Adicionar recursos a uma aplicação Databricks
• Referência de Recursos da Aplicação