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:

Método	Description	Quando utilizar
Autorização da aplicação	O agente autentica-se usando um principal de serviço criado automaticamente com permissões consistentes. Anteriormente chamado de autenticação de Service Principal.	O caso de uso mais comum. Use quando todos os utilizadores deveriam ter o mesmo acesso aos recursos.
Autorização do utilizador	O agente autentica-se usando a identidade do utilizador que faz o pedido. Anteriormente denominado autenticação "Em Nome De" (OBO).	Use quando precisar de permissões específicas do utilizador, registos de auditoria ou controlo de acesso detalhado com o Unity Catalog.

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.

Autorização do aplicativo

Por defeito, as aplicações Databricks autenticam-se usando autorização de aplicação. O Azure Databricks cria automaticamente um principal de serviço quando cria a aplicação, e este 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 serviço principal Can Edit no experimento MLflow.

Clique em Editar na página inicial da sua aplicação.
Navegue até ao passo Configurar .
Na secção de recursos da App , adicione o recurso de experiências MLflow.

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

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 através da interface Databricks Apps. Consulte Adicionar recursos a uma aplicação Databricks para a lista completa de recursos suportados e instruções de configuração.

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

A tabela seguinte lista as permissões mínimas necessárias para que os agentes acedam aos recursos comuns do Databricks:

Tipo de recurso	Permissão
Armazém SQL	`Can Use`
Endpoint de serviço do modelo	`Can Query`
Função do Unity Catalog	`CAN Execute`
Espaço Genie	`Can Run`
Índice de pesquisa vetorial	`Can Select`
Tabela do Catálogo Unity	`SELECT`
Conexão do catálogo Unity	`Use Connection`
Volume do Catálogo Unity	`Can Read` ou `Can Read and Write`
Lakebase	`Can Connect and Create`

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.

O utilizador que adiciona o recurso deve ter permissão Can Manage tanto para o recurso como para a aplicação. Para a lista completa de recursos suportados e todas as permissões disponíveis, veja tipos de recursos suportados.

Para melhores práticas na gestão segura da autorização de aplicações, incluindo gestão de credenciais e princípios de privilégios mínimos, consulte Autorização de aplicações.

Autorização do utilizador

Importante

A autorização do usuário está em Visualização pública. O administrador do seu espaço de trabalho tem de o ativar antes de poder usar 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:

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.
As credenciais do utilizador são reduzidas: o Azure Databricks recolhe as credenciais do utilizador e restringe-as apenas aos escopos da API que definiste.
Encaminhamento de tokens: O token com escopo reduzido é disponibilizado para a sua aplicação através do x-forwarded-access-token cabeçalho HTTP.
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.

Na interface do Databricks, vá às definições de Autorização de Aplicações Databricks.
Clica em +Adicionar âmbito e seleciona os escopos aos quais queres aceder aos recursos em nome do utilizador.
Salve as alterações.

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.

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

Autenticar em servidores MCP Databricks

Para autenticar nos servidores MCP da Databricks, especifique todos os recursos que o seu agente precisa no seu databricks.yaml ficheiro. Conceda ao principal de serviço da aplicação (ou utilizadores, se estiver a usar autorização de utilizador) acesso a todos os recursos subsequentes.

Por exemplo, se o seu agente usar os URLs dos servidores MCP listados abaixo, deve conceder acesso a todos os índices de pesquisa vetorial nos esquemas prod.customer_support e prod.billing, e a todas as funções do Unity Catalog em prod.billing:

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

Configurar autenticação com Databricks Asset Bundles

Pode configurar todas as definições de autenticação de forma programática usando os Databricks Asset Bundles em vez da interface do Databricks Apps. Esta página mostra a configuração baseada na interface de utilizador para ilustrar que recursos e permissões são necessários, mas a mesma configuração pode ser definida nos ficheiros YAML do seu bundle. Consulte Apps in bundles para a referência completa da configuração do bundle.

Próximos passos

Comentários

Esta página foi útil?

Last updated on 2026-02-14