Autenticação para agentes de IA

Agentes de AI frequentemente precisam autenticar-se em outros recursos para concluir tarefas. Por exemplo, um agente implantado pode precisar acessar um índice de pesquisa de AI para query dados não estruturados, um Endpoint de serviço para chamar um modelo base ou funções do Unity Catalog para executar lógica personalizada.

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

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

Método	Descrição	Quando usar
Autorização do aplicativo	O Agente se autentica usando um Service Principal criado automaticamente com permissões consistentes. Anteriormente chamada autenticação de Service Principal.	Caso de uso mais comum. Use quando todos os usuários tiverem o mesmo acesso a recursos.
Autorização do usuário	O agente autentica-se usando a identidade do usuário que faz a solicitação. Anteriormente chamada autenticação On-Behalf-Of (OBO).	Use quando você precisar de permissões específicas do usuário, trilhas de auditoria ou controle de acesso granular com o Unity Catalog.

Método	Descrição	Quando usar
Autorização do aplicativo	O Agente se autentica usando um Service Principal criado automaticamente com permissões consistentes. Anteriormente chamada autenticação de Service Principal.	Caso de uso mais comum. Use quando todos os usuários tiverem o mesmo acesso a recursos.
Autorização do usuário	O agente autentica-se usando a identidade do usuário que faz a solicitação. Anteriormente chamada autenticação On-Behalf-Of (OBO).	Use quando você precisar de permissões específicas do usuário, trilhas de auditoria ou controle de acesso granular com o Unity Catalog.

Você pode combinar ambos os métodos em um único agente. Por exemplo, use a autorização do aplicativo para acessar um índice compartilhado da Pesquisa de AI enquanto usa a autorização do usuário para query tabelas específicas do usuário.

Configure a autenticação com a UI do workspace ou os Pacotes de Automação Declarativa

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

• Workspace UI: edite o aplicativo e gerencie recursos e escopos no passo Configurar. É recomendado ao iterar em um único aplicativo no workspace.
• Pacotes de Automação Declarativa : Declare recursos, escopos e variáveis de ambiente em um arquivo databricks.yml e implante com databricks bundle deploy. Recomendado quando você quer versionamento baseado em Git, CI/CD ou para enviar o mesmo agente entre Workspaces. Todos os padrões de agente são implantados com um databricks.yml.

Ambos os caminhos produzem a mesma configuração de runtime. O restante desta página mostra cada instrução nas duas formas para que você possa selecionar uma e manter a consistência em seu projeto.

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

Para a referência completa do pacote, consulte recurso do aplicativo e app.resources. Para um tutorial completo do pacote, consulte Gerenciar aplicativos Databricks usando Pacotes de Automação Declarativa.

Autorização do aplicativo

Por default, o Databricks Apps se autentica usando a autorização do aplicativo. O Databricks cria automaticamente um Service Principal ao criar o aplicativo, e ele atua como a identidade do aplicativo.

Todos os usuários que interagem com o aplicativo compartilham as mesmas permissões definidas para o Service Principal. Este modelo funciona bem quando se 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 informações detalhadas sobre autorização de aplicativo, consulte Autorização de aplicativo.

Conceder permissões ao experimento MLflow

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

Workspace UI

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

Consulte Adicionar um recurso de experimento 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 mais tarde quando você configura as variáveis 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. Reimplante o pacote:

   Bash

   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 seu agente usa outros recursos do Databricks, como Agentes Genie, índices de Pesquisa de AI, ou SQL warehouses, conceda permissões ao Service Principal em cada um deles.

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

Ao conceder acesso a recursos do Unity Catalog, também deve conceder permissões a todos os recursos dependentes a jusante. Por exemplo, se você conceder acesso a um Genie Agent, também deverá conceder acesso às suas tabelas subjacentes, SQL Warehouse e funções do Unity Catalog.

Workspace UI

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

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

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

Declarative Automation Bundles

1. Declare cada recurso que o agente utiliza na lista resources em seu aplicativo em databricks.yml. O exemplo abaixo mostra um agente que utiliza um experimento MLflow, um endpoint de serviço, um Genie Agent, um SQL warehouse, um índice de pesquisa de AI, uma função do Unity Catalog e uma instância do Lakebase. Cada recurso name é referenciado de config.env por meio de value_from para que o agente receba o identificador resolvido em Runtime.

   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 de 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 para None no aplicativo implantado.

2. Implante e comece o pacote:

   Bash

   databricks bundle validate
   databricks bundle deploy
   databricks bundle run my_agent

   bundle deploy faz upload da fonte e configura os recursos. 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 implantado.

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

A tabela a seguir 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:

Tipo de recurso	Permissão de UI do Workspace	recurso e permissão do Declarative Automation Bundles
SQL Warehouse	Can Use	sql_warehouse com CAN_USE
Modelo de ponto de extremidade de serviço	Can Query	serving_endpoint com CAN_QUERY
Função do Unity Catalog	Can Execute	uc_securable com securable_type: FUNCTION e EXECUTE
Genie Agent	Can Run	genie_space com CAN_RUN
Índice de Pesquisa de AI	Can Select	uc_securable com securable_type: TABLE e SELECT
Tabela do Unity Catalog	SELECT	uc_securable com securable_type: TABLE e SELECT
Conexão do Unity Catalog	Use Connection	uc_securable com securable_type: CONNECTION e USE_CONNECTION
Volume do Unity Catalog	Can Read ou Can Read and Write	uc_securable com securable_type: VOLUME e READ_VOLUME ou WRITE_VOLUME
Lakebase (provisionado)	Can Connect and Create	database com CAN_CONNECT_AND_CREATE
Lakebase (autoscale)	Can Connect and Create	postgres com CAN_CONNECT_AND_CREATE

Tipo de recurso	Permissão de UI do Workspace	recurso e permissão do Declarative Automation Bundles
SQL Warehouse	Can Use	sql_warehouse com CAN_USE
Modelo de ponto de extremidade de serviço	Can Query	serving_endpoint com CAN_QUERY
Função do Unity Catalog	Can Execute	uc_securable com securable_type: FUNCTION e EXECUTE
Genie Agent	Can Run	genie_space com CAN_RUN
Índice de Pesquisa de AI	Can Select	uc_securable com securable_type: TABLE e SELECT
Tabela do Unity Catalog	SELECT	uc_securable com securable_type: TABLE e SELECT
Conexão do Unity Catalog	Use Connection	uc_securable com securable_type: CONNECTION e USE_CONNECTION
Volume do Unity Catalog	Can Read ou Can Read and Write	uc_securable com securable_type: VOLUME e READ_VOLUME ou WRITE_VOLUME
Lakebase (provisionado)	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 ao Service Principal apenas as permissões de que o agente precisa e use um Service Principal dedicado por aplicativo. Para a lista completa, consulte Melhores práticas de segurança.

Autorização do usuário

info

Visualização

A autorização do usuário está em Prévia Pública. O administrador do seu workspace deve habilitá-lo antes de 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 faz a solicitação. Isso fornece:

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

Use a autorização do usuário quando seu agente precisar acessar recursos usando a identidade do usuário solicitante em vez do Service Principal do aplicativo.

Como funciona a autorização do usuário

Ao configurar a autorização do usuário para o 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 têm escopo reduzido: o Databricks usa as credenciais do usuário e as restringe apenas aos escopos de API definidos.
3. Encaminhamento de token : O token de escopo reduzido é disponibilizado ao seu aplicativo por meio do cabeçalho HTTP x-forwarded-access-token.
4. OMLflow AgentServer armazena o token : O Agent Server armazena automaticamente este token por solicitação para acesso conveniente no código do agente.

Configure a autorização do usuário adicionando escopos na UI 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 os seguintes recursos da Databricks:

• SQL Warehouse
• Genie Agent
• Arquivos e diretórios
• Endpoint do serviço de modelos
• Índice de Pesquisa de AI
• Conexões do Unity Catalog
• Tabelas do Unity Catalog

Implementar autorização de 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 a semântica do escopo, consulte Segurança baseada em escopo e escalonamento de privilégios.

Workspace UI

1. Na IU do Databricks, vá para 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 recursos em nome do usuário.
3. Salve as alterações e reinicie o aplicativo.

Declarative Automation Bundles

1. Declare 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
           - genie
           - model-serving
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'

2. Reimplantar o pacote e reiniciar o aplicativo:

   Bash

   databricks bundle deploy
   databricks bundle run my_agent

nota

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

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

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

   Se estiver usando um dos padrões fornecidos em databricks/app-templates, importe a utilidade fornecida:

   Python

   from databricks_app.utils import get_user_workspace_client

   Caso contrário, importe das utilidades do Servidor de Agentes:

   Python

   from agent_server.utils import get_user_workspace_client

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

2. Inicialize o cliente do Workspace no momento da query, não durante a Startup do aplicativo:

importante

Chame get_user_workspace_client() dentro dos manipuladores invoke e stream, não em __init__ ou na Startup do aplicativo. Credenciais de usuário estão disponíveis apenas no momento da query quando um usuário faz uma solicitação. A inicialização durante o startup do aplicativo falhará porque nenhum contexto de usuário existe ainda.

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 de que seu agente precisa e registre cada ação executada em nome de um usuário; consulte Melhores práticas para autorização do usuário.

Verificar autorização do usuário

Depois de adicionar escopos e chamar get_user_workspace_client(), confirme se o agente é executado como o chamador e não como o service principal do Databricks do aplicativo. Se o token encaminhado estiver faltando, get_user_workspace_client() retorna ao service principal do Databricks sem levantar uma exceção, para que o agente possa retornar uma resposta de aparência normal enquanto ainda age como o aplicativo. Para verificar, adicione uma ferramenta whoami e a invoque. Se ele retornar o nome de usuário, a autorização do usuário estará funcionando.

current_user.me() É coberto pelo escopo iam.current-user:read default, então você não precisa adicionar nenhum escopo para este teste.

Python

from agents import Agent, function_tool
from agent_server.utils import get_user_workspace_client

@function_tool
def whoami() -> str:
    """Returns the identity of the current user."""
    user_wc = get_user_workspace_client()
    return user_wc.current_user.me().user_name

agent = Agent(
    name="my-agent",
    instructions=(
        "When the user asks who they are, call the whoami tool "
        "and return the raw result."
    ),
    model="databricks-claude-sonnet-4-6",
    tools=[whoami],
)

Reimplante o agente. Consulte Crie um agente de AI e implante-o no Databricks Apps.

Workspace UI

O teste da interface do usuário do Workspace é a verificação de sanidade mais rápida e não requer tokens OAuth.

1. As mudanças de escopo entram em vigor imediatamente, mas os caches internos podem levar até 5 minutos para refresh — espere esse tempo antes de testar (não é necessário reiniciar o aplicativo). Sempre limpe os cookies do seu navegador para o URL do aplicativo (veja o dropdown abaixo para os passos), caso contrário, a sessão reutiliza os tokens emitidos antes da mudança de escopo.
2. Confirme se você tem CAN USE permissão no aplicativo. Consulte Configure permissões para um aplicativo Databricks.
3. Abra a URL do aplicativo em um navegador. Na primeira visita, aceite o prompt de consentimento para os escopos solicitados.
4. No chat, pergunte Who am I? e confirme se o agente retorna seu nome de usuário (por exemplo, you@your-company.com).

Limpar cookies no Chrome

1. Abrir DevTools: pressione F12 , ou Cmd+Option+I no macOS, ou Ctrl+Shift+I no Windows ou Linux.
2. Abra a tab Aplicativo .
3. Em **Armazenamento** > **Cookies**, selecione a URL do seu aplicativo.
4. Clique com o botão direito em cada cookie e escolha **Excluir**.

Python

Use um perfil da CLI ou credenciais de Service Principal do Databricks para invocar o agente. Consulte Query um agente implantado no Databricks para opções de query e Conectar a um aplicativo API do Databricks usando autenticação de token para saber como gerar tokens OAuth.

1. As alterações de escopo entram em vigor imediatamente, mas os caches internos podem levar até 5 minutos para serem refresh, então espere antes de testar (nenhum reinício de aplicativo é necessário).

2. Invoque o agente como você:

   Python

   from databricks.sdk import WorkspaceClient
   from databricks_openai import DatabricksOpenAI
   
   app_name = "<your-app-name>"
   prompt = [{"role": "user", "content": "Call the whoami tool and return only the raw result."}]
   
   w = WorkspaceClient(profile="<your-profile>")
   client = DatabricksOpenAI(workspace_client=w)
   response = client.responses.create(model=f"apps/{app_name}", input=prompt)
   print(response.output_text)

   A saída deve ser seu nome de usuário — por exemplo, you@your-company.com.

Se a ferramenta retornar um UUID em vez de um nome de usuário, o cabeçalho x-forwarded-access-token não está alcançando a ferramenta e o agente recorreu ao Service Principal do Databricks do aplicativo (o UUID é o ID do cliente do Service Principal do aplicativo). Para diagnosticar, confirme cada um dos seguintes:

1. A autorização do usuário está habilitada no workspace.
2. O aplicativo possui escopos configurados.
3. get_user_workspace_client() é chamado dentro do manipulador @invoke ou @stream, não no Startup.
4. O código usa get_user_workspace_client() e não WorkspaceClient().

Alguns pontos a serem observados:

• **Remova a whoami ferramenta antes da produção.** É apenas para diagnóstico e expõe a identidade do usuário a qualquer pessoa que possa invocar o agente.
• Teste com um segundo usuário. Uma verificação de usuário único confirma que o token é encaminhado; um segundo chamador confirma que cada solicitação obtém sua própria identidade em vez de um fallback compartilhado.
• Nunca log o token encaminhado. Consulte Melhores práticas para autorização de usuário.
• Para verificar um escopo específico , substitua current_user.me() por uma chamada que exige esse escopo. Por exemplo, uma instrução SELECT current_user() contra um warehouse exercita o escopo sql de ponta a ponta.

Autenticar em servidores MCP do Databricks

Servidores MCP gerenciados da Databricks expõem índices de Pesquisa de AI e funções do Unity Catalog como ferramentas por meio de URLs no formato https://<workspace>/api/2.0/mcp/ai-search/<catalog>/<schema> e https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema>. O prefixo de URL /api/2.0/mcp/vector-search/ herdado continua a funcionar para compatibilidade com versões anteriores. Para a lista de servidores disponíveis e seus padrões de URL, consulte servidores MCP gerenciados da Databricks.

Para autenticar, conceda o Service Principal do agente (ou ao usuário, se estiver usando autorização de usuário) acesso a cada recurso downstream nesses esquemas.

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

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

É necessário conceder acesso a cada índice de pesquisa de AI em prod.customer_support e prod.billing, e a cada função do 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 do 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. Reimplante o pacote:

   Bash

   databricks bundle deploy
   databricks bundle run my_agent

Servidores MCP personalizados hospedados como seus próprios aplicativos Databricks (nomes de aplicativos prefixados com mcp-) ainda não são suportados como recursos de pacote. Conceda o service principal do agente Can Use no aplicativo do servidor MCP manualmente com databricks apps update-permissions. Consulte a habilidade custom-mcp-server no repository de padrões do agente.

Próximos passos

• Criar um agente de AI e implantá-lo no Databricks Apps.
• Gerenciar aplicativos Databricks usando Bundles de Automação Declarativa
• Configure a autorização em um aplicativo Databricks
• Adicione recursos a um aplicativo Databricks.
• referência de recurso do aplicativo