Pular para o conteúdo principal
Última atualização em

Autenticação para agentes de AI

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

Esta página aborda 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 oferece 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 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. Use quando todos os usuários devem ter o mesmo acesso aos recursos.

Autorização do usuário

O agente autentica-se usando a identidade do usuário que faz a solicitação. Anteriormente chamada de autenticação Em Nome De (OBO).

Use quando precisar de permissões específicas do usuário, trilhas de auditoria ou controle de acesso granular com o Unity Catalog.

É possível combinar ambos os métodos em um único agente. Por exemplo, use a autorização do aplicativo para acessar um índice de pesquisa de AI compartilhado enquanto usa a autorização do usuário para consultar 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:

  • IU do Workspace: edite o aplicativo e gerencie recursos e escopos a partir do passo Configurar . Recomendado ao iterar em um único aplicativo no workspace.
  • Pacotes de Automação Declarativa : Declare recurso, escopos e variável de ambiente em um arquivo databricks.yml e databricks bundle deploy implantado. Recomendado quando você deseja versionamento baseado em Git, CI/CD, ou distribuir o mesmo agente entre workspaces. Todos os padrões de agente vêm 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 ambas as formas para que se possa selecionar uma e manter a consistência em seu projeto.

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

Para a referência completa do pacote, consulte recurso do aplicativo e app.recurso. 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 autentica usando a autorização do aplicativo. O Databricks cria automaticamente uma entidade de serviço ao criar o aplicativo, e ela atua 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. 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​

O seu agente precisa de acesso a um experimento do MLflow para log rastreamentos e resultados de avaliação. Conceda à entidade de serviço Can Edit permissão no experimento.

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

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

Conceder permissões a outros recursos do Databricks​

Se seu agente usa outros recursos do Databricks, como Espaços Genie, índices de Pesquisa de AI ou SQL warehouses, 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 aos recursos do Unity Catalog, o usuário também deve conceder permissões a todos os recursos dependentes downstream. Por exemplo, se conceder acesso a um Genie Space, também deverá conceder acesso às suas tabelas subjacentes, SQL warehouse e funções do Unity Catalog.

Adicione recursos ao aplicativo através da 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. Acesse o passo 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 obter a lista completa de recursos compatíveis e capturas de tela.

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 da IU do Workspace

Recurso e Permissão de Pacotes de Automação Declarativa

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 Space

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 (provisionamento)

Can Connect and Create

database com CAN_CONNECT_AND_CREATE

Lakebase (autoscaling)

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 de que o agente precisa e use uma entidade de serviço dedicada por aplicativo. Para ver a lista completa, consulte Práticas recomendadas de segurança.

Autorização do usuário​

info

Visualização

A autorização do usuário está em Pré-visualização pública. O administrador do seu workspace deve habilitá-lo antes que você possa usar a autorização do usuário.

A autorização do usuário permite que um agente atue 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 de 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 da entidade de serviço do aplicativo.

Como funciona a autorização do usuário​

Quando você configura 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. Credenciais do usuário com escopo reduzido: a Databricks usa as credenciais do usuário e as restringe apenas aos escopos de API que você definiu.
  3. **Encaminhamento de token**: O token com escopo reduzido é disponibilizado para seu aplicativo por meio do x-forwarded-access-token cabeçalho HTTP.
  4. ** MLflow AgentServer armazena os tokens**: O Agent Server armazena automaticamente estes tokens por solicitação para acesso conveniente no código do agente.

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

  • SQL Warehouse
  • Genie Space
  • 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, é preciso adicionar escopos de autorização ao seu aplicativo. Escopos restringem o que o aplicativo pode fazer em nome do usuário. Para a lista de escopos disponíveis e semânticas de escopo, consulte Segurança baseada em escopo e escalonamento de privilégios.

  1. Na interface de usuário 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.

Para configurar a autorização do usuário no 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 código do seu agente, importe a utilidade de autenticação:

    Se for usar um dos padrões fornecidos de 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, lidando com 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 o 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 estão disponíveis somente no momento da consulta, quando um usuário faz uma solicitação. A inicialização durante a 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 escopos, consulte Segurança baseada em escopos e escalonamento de privilégios. Solicite apenas os escopos mínimos que seu agente precisa e log cada ação realizada em nome de um usuário; consulte Práticas recomendadas para autorização do usuário.

Verificar autorização do usuário​

Depois de adicionar escopos e chamar get_user_workspace_client(), confirme que o agente executa como o chamador e não como a entidade de serviço do Databricks do aplicativo. Se o token encaminhado estiver ausente, get_user_workspace_client() retorna para a entidade de serviço do Databricks sem gerar um erro, para que o agente possa retornar uma resposta com aparência normal enquanto ainda age como o aplicativo. Para verificar, adicione uma ferramenta whoami e invoque-a como você mesmo. Se ele retornar seu 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],
)

Reimplemente o agente. Consulte Criar um agente de AI e implantá-lo no Databricks Apps.

O teste de UI do workspace é a verificação de sanidade mais rápida e não requer tokens OAuth.

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

Limpar cookies no Chrome

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

Chrome DevTools mostrando a tab Aplicação, cookies para uma URL de aplicativo e o menu Excluir com o botão direito do mouse.

Se a ferramenta retornar um UUID em vez de um nome de usuário, o cabeçalho x-forwarded-access-token não está chegando à ferramenta e o agente voltou para a entidade de serviço Databricks do aplicativo (o UUID é o ID do cliente da entidade de serviço do aplicativo). Para diagnosticar, confirme cada um dos seguintes:

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

Algumas coisas a observar:

  • Remova a whoami ferramenta antes da produção. É apenas 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 os tokens encaminhados. Consulte Práticas recomendadas para autorização do usuário.
  • Para verificar um escopo específico , substitua current_user.me() por uma chamada que exija esse escopo. Por exemplo, uma instrução SELECT current_user() contra um warehouse exerce o escopo sql de ponta a ponta.

Autenticar-se em servidores MCP do Databricks​

Os servidores MCP gerenciados do Databricks expõem os índices de Pesquisa de AI e as 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 da URL herdada /api/2.0/mcp/vector-search/ continua funcionando para compatibilidade com versões anteriores. Para a lista de servidores disponíveis e seus padrões de URL, consulte servidores MCP gerenciados do Databricks.

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

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

Você deve conceder acesso a todos os índices do AI Search em prod.customer_support e prod.billing, e a todas as funções do Unity Catalog em prod.billing.

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

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 à 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órios de padrões de agente.

Próximos os passos​

Nesta página