Autenticação para agentes de IA

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

Esta página aborda os métodos de autenticação para agentes implantados nos Aplicativos do Databricks. Para agentes implantados em endpoints de Model Serving, consulte Autenticação para agentes de IA (Model Serving).

Os Aplicativos do Databricks fornecem dois métodos de autenticação para agentes. Cada método atende a diferentes casos de uso:

Você pode combinar ambos os métodos em um único agente. Por exemplo, utilize a autorização do app para acessar um índice compartilhado de Vector Search, enquanto usa a autorização do usuário para consultar tabelas específicas do usuário.

Configurar a autenticação com a interface do usuário do workspace ou pacotes de automação declarativa

Você pode definir todas as configurações de autenticação de duas maneiras:

• Interface do usuário do workspace: edite o aplicativo e gerencie recursos e escopos na etapa Configurar. Recomendado quando se está iterando em um único aplicativo no espaço de trabalho.
• Pacotes de Automação Declarativa: declarar recursos, escopos e variáveis de ambiente em um databricks.yml arquivo e implantar com databricks bundle deploy. Recomendado quando você deseja controle de versão baseado em Git, CI/CD, ou distribuir o mesmo agente entre diferentes workspaces. Todos os modelos de agente vêm com um databricks.yml.

Ambos os caminhos produzem a mesma configuração de runtime. O restante desta página mostra cada instrução em ambos os formulários para que você possa selecionar uma e permanecer consistente em seu projeto.

Para adicionar um recurso ao aplicativo por meio de qualquer caminho, você deve ter Can Manage permissão no recurso e no aplicativo.

Para obter a referência completa do pacote, consulte app resource e app.resources. Para obter um passo a passo completo do pacote, consulte Gerenciar Aplicativos do Databricks usando Pacotes de Automação Declarativa.

Autorização de aplicativo

Por padrão, os Aplicativos do Databricks são autenticados usando a autorização do aplicativo. O Databricks cria automaticamente um principal de serviço quando você cria o aplicativo, e este age como a identidade do aplicativo.

Todos os usuários que interagem com o aplicativo compartilham as mesmas permissões definidas para o principal do 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 não vinculadas a controles de acesso específicos do usuário.

Para obter informações detalhadas sobre a autorização do aplicativo, consulte a autorização do aplicativo.

Conceder permissões ao experimento do MLflow

Seu agente precisa de acesso a um experimento do MLflow para registrar os rastreamentos e os resultados da avaliação. Conceda permissão ao principal de serviço Can Edit no experimento.

Interface do usuário do workspace

1. Clique em Editar na home page do aplicativo.
2. Vá para a etapa Configurar .
3. Na seção Recursos do aplicativo, adicione o recurso de teste do MLflow com Can Edit permissão.

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

Pacotes de Automação Declarativa

1. Declare o experimento na lista resources do seu aplicativo em databricks.yml. A name que você atribui ao recurso é referenciada posteriormente quando você conecta as 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. Reimplantar o pacote:

   databricks bundle deploy
   databricks bundle run my_agent
   

Consulte app.resources.experiment para todos os campos.

Conceder permissões a outros recursos do Databricks

Se o agente usar outros recursos do Databricks, como espaços Genie, índices de Pesquisa Vetorial ou Armazéns SQL, conceda permissões à Entidade de Serviço em cada um deles.

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

Ao conceder acesso aos recursos do Catálogo do Unity, você também deve conceder permissões a todos os recursos dependentes downstream. Por exemplo, se você conceder acesso a um espaço do Genie, também deverá conceder acesso a suas tabelas subjacentes, SQL Warehouses e funções do Catálogo Unity.

Interface do usuário do workspace

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

1. Clique em Editar na home page do aplicativo.
2. Vá para a etapa Configurar .
3. Em recursos de aplicativo, clique em + Adicionar recurso para cada recurso que o agente usa e defina a permissão.

Consulte Adicionar recursos a um aplicativo do Databricks para obter a lista completa de recursos e capturas de tela com suporte.

Pacotes de Automação Declarativa

1. Declare todos os recursos que o agente usa na lista resources sob seu aplicativo em databricks.yml. O exemplo a seguir mostra um agente que usa um experimento do MLflow, um endpoint de serviço, um espaço Genie, um SQL Warehouse, um índice Vector Search, uma função do Unity Catalog e uma instância do Lakebase. Cada recurso name é referenciado de config.env através 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 valor em value_from deve corresponder a um campo name na lista resources. Os desajustes fazem com que a variável de ambiente seja avaliada como None no aplicativo implantado.

2. Implante e inicie o pacote:

   databricks bundle validate
   databricks bundle deploy
   databricks bundle run my_agent
   

   bundle deploy carrega a origem e configura recursos. bundle run inicia ou reinicia o aplicativo com a fonte mais recente. O argumento para bundle run é a chave YAML sob resources.apps (aqui my_agent), não o campo name do aplicativo implantado.

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

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

Siga o princípio dos privilégios mínimos. Conceda ao service principal apenas as permissões que o agente precisa e use um service principal dedicado por aplicativo. Para obter a lista completa, consulte as práticas recomendadas de segurança.

Autorização do usuário

A autorização do usuário permite que um agente atue com a identidade do usuário que está fazendo a solicitação. Isso fornece:

• Acesso por usuário a dados confidenciais
• Controles de dados refinados impostos pelo Catálogo do Unity
• Trilhas de auditoria específicas do usuário
• Imposição automática de filtros de nível de linha e máscaras de coluna

Use a autorização do usuário quando o agente precisar acessar recursos usando a identidade do usuário solicitante em vez da entidade de serviço do aplicativo.

Como funciona a autorização do usuário

Ao configurar a autorização do usuário para seu agente:

1. Adicionar 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 são limitadas: Databricks usa as credenciais do usuário e as restringe apenas aos escopos de API definidos.
3. Encaminhamento de token: o token downscoped é disponibilizado para seu aplicativo por meio do x-forwarded-access-token cabeçalho HTTP.
4. O MLflow AgentServer armazena o token: O Servidor do Agente armazena automaticamente esse token por solicitação para acesso conveniente 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 do usuário podem acessar os seguintes recursos do Databricks:

• SQL Warehouse
• Espaço do Gênio
• Ficheiros e diretórios
• Ponto de extremidade do Serviço de Modelo
• Índice de busca em vetores
• Conexões de catálogo do Unity
• Tabelas do catálogo do Unity

Implementar autorização do usuário

Para implementar a autorização do usuário, você deve 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 semântica de escopo, consulte a segurança baseada em escopo e o escalonamento de privilégios.

Interface do usuário do workspace

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

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. Reimplante o pacote e reinicie o aplicativo:

   databricks bundle deploy
   databricks bundle run my_agent
   

   Note

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

Para configurar a autorização do usuário no código do agente, recupere o cabeçalho dessa solicitação do AgentServer e construa um cliente de workspace com essas credenciais.

1. No código do agente, importe o utilitário de autenticação:

   Se estiver usando um dos modelos fornecidos do databricks/app-templates, importe o utilitário fornecido:

   from databricks_app.utils import get_user_workspace_client
   

   Caso contrário, importe dos utilitários do Servidor de Agentes:

   from agent_server.utils import get_user_workspace_client
   

   A get_user_workspace_client() função usa o Servidor do Agente para capturar o x-forwarded-access-token cabeçalho e constrói um cliente de workspace com essas credenciais de usuário, tratando a autenticação entre o usuário, o aplicativo e o servidor do agente.

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

   Importante

   Chame get_user_workspace_client() dentro dos manipuladores invoke ou stream, não em __init__ ou na inicialização do aplicativo. As credenciais do usuário só estão disponíveis no momento da consulta quando um usuário faz uma solicitação. A inicialização durante a inicialização do aplicativo falhará porque ainda não existe nenhum 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 obter um guia completo sobre como adicionar escopos e entender a segurança baseada em escopo, consulte a segurança baseada em escopo e o escalonamento de privilégios. Solicite apenas os escopos mínimos de que seu agente precisa e registre todas as ações executadas em nome de um usuário; consulte as práticas recomendadas para autorização do usuário.

Autentique-se em servidores MCP do Databricks

Os servidores MCP gerenciados pelo Databricks expõem índices de Pesquisa Vetorial e funções do Catálogo Unity como ferramentas por meio de URLs no 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 servidores MCP gerenciados pelo Databricks.

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

Por exemplo, se seu agente usar os seguintes URLs dos servidores 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 cada índice de pesquisa de vetor em prod.customer_support e prod.billing, e a cada função do Catálogo Unity em prod.billing.

Interface do usuário do workspace

Adicione cada índice e função como um recurso em recursos de aplicativo. Siga as mesmas etapas que conceder permissões a outros recursos do Databricks.

Pacotes de Automação Declarativa

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

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

   databricks bundle deploy
   databricks bundle run my_agent
   

Os servidores MCP personalizados hospedados como seus próprios aplicativos do Databricks (nomes de aplicativos prefixados com mcp-) ainda não têm suporte como recursos de pacote. Conceda manualmente a principal de serviço do agente no aplicativo do servidor MCP Can Use usando databricks apps update-permissions. Consulte a habilidade de servidor mcp personalizado no repositório de modelos de agente.

Próximas etapas

• Criar um agente de IA e implantá-lo em Aplicativos do Databricks
• Gerenciar aplicativos do Databricks usando Pacotes de Automação Declarativa
• Configurar a autorização em um aplicativo do Databricks
• Adicionar recursos a um aplicativo do Databricks
• referência de recurso do aplicativo