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

Autenticação para agentes AI (modelo de serviço)

info

Para novos casos de uso, Databricks recomenda a implantação de agentes no Databricks Apps para controle total sobre o código do agente, a configuração do servidor e o fluxo de trabalho de implantação. Veja Criar um agente AI e implantá-lo em Databricks Apps.

Os agentes AI frequentemente 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 ou o Registro de prompts para carregar prompts dinâmicos.

Esta página aborda os métodos de autenticação disponíveis ao desenvolver e implantar agentes usando o Agent Framework.

Métodos de autenticação​

A tabela a seguir compara os métodos de autenticação disponíveis. Você pode combinar quaisquer dessas abordagens:

Método

Descrição

Postura de segurança

Complexidade de configuração

Autenticação automática pass-through

Execução do agente com as permissões do usuário que o implantou

Databricks gerencia automaticamente credenciais de curta duração para recursos declarados.

Credenciais de curta duração, rotação automática

Baixa - declarar dependências no momento do registro de logs

Autenticação em nome do usuário (OBO)

A execução do agente ocorre com as permissões do usuário final que fez a solicitação.

Utiliza as credenciais do usuário final com escopos restritos.

Nível Médio - requer declaração de escopo e inicialização em tempo de execução.

Autenticação manual

Forneça credenciais explicitamente usando variável de ambiente

As credenciais de longa duração precisam de gestão de rotação.

Nível elevado - requer gerenciamento manual de credenciais.

Escolha o método de autenticação adequado para o seu recurso.​

Utilize este fluxograma para escolher o método de autenticação correto para cada recurso. Você pode combinar métodos conforme necessário, e um agente pode usar um método diferente para cada recurso, dependendo do seu caso de uso.

  1. É necessário controle de acesso por usuário ou auditoria com atribuição de usuários?

  2. Todos os recursos suportam autenticação automática?

Autentique-se nos servidores Databricks MCP.​

Para autenticar nos servidores Databricks MCP, especifique todos os recursos que seu agente precisa no momento do login.

Por exemplo, se o seu agente usar os URLs do servidor MCP listados abaixo, você deverá especificar todos os índices do Vector Search nos esquemas prod.customer_support e prod.billing . Você também deve especificar 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

Para simplificar o processo de identificação de todos os recursos dependentes para servidores de gerenciamento MCP, use o pacote PyPI databricks-mcp databricks_mcp.DatabricksMCPClient().get_databricks_resources(<server_url>) para recuperar os recursos necessários para o servidor de gerenciamento MCP.

Se o seu agente consultar um servidor MCP personalizado hospedado em um aplicativo Databricks, você poderá configurar a autorização incluindo explicitamente o servidor como um recurso ao registrar seu modelo.

Autenticação automática pass-through​

A autenticação automática passthrough é a maneira mais simples de acessar Databricks-gerenciar recurso. Declare as dependências de recursos ao registrar o agente, e Databricks provisionará, rotacionará e gerenciará automaticamente as credenciais de curta duração quando o agente for implantado.

Esse comportamento de autenticação é semelhante ao comportamento de "execução como proprietário" dos dashboards Databricks . Os recursos downstream, como as tabelas Unity Catalog , são acessados usando as credenciais de uma entidade de serviço com acesso de privilégio mínimo, restringindo-se apenas aos recursos necessários ao agente.

Como funciona a autenticação automática direta​

Quando um agente é atendido por trás de um endpoint usando autenticação automática direta, Databricks executa os seguintes passos:

  1. Verificação de permissões : o Databricks verifica se o criador do endpoint pode acessar todas as dependências especificadas durante o registro do agente.

  2. criação e concessão de entidade de serviço : Uma entidade de serviço é criada para a versão do modelo do agente e recebe automaticamente acesso de leitura ao recurso do agente.

nota

A entidade de serviço gerada pelo sistema não aparece nas listagens da API ou da interface do usuário. Se a versão do modelo de agente for removida do endpoint, a entidade de serviço também será excluída.

  1. Provisionamento e rotação de credenciais : Credenciais de curta duração ( tokens OAuth M2M) para a entidade de serviço são injetadas no endpoint, permitindo que o código do agente acesse o recurso Databricks . Databricks também rotaciona as credenciais, garantindo que seu agente tenha acesso contínuo e seguro aos recursos dependentes.

Recurso compatível para passagem automática de autenticação​

A tabela a seguir lista os recursos Databricks que suportam autenticação automática e as permissões que o criador endpoint deve ter ao implantar o agente.

nota

O recurso Unity Catalog também requer USE SCHEMA no esquema pai e USE CATALOG no catálogo pai.

Tipo de recurso

Permissão

Versão mínima do MLflow

SQL Warehouse

Use Endpoint

2.16.1 ou superior

Modelo de ponto de extremidade de serviço

Can Query

2.13.1 ou superior

Função Unity Catalog

EXECUTE

2.16.1 ou superior

Espaço Genie

Can Run

2.17.1 ou superior

Índice de busca vetorial

Can Use

2.13.1 ou superior

Tabela Unity Catalog

SELECT

2.18.0 ou superior

Conexão Unity Catalog

Use Connection

2.17.1 ou superior

Lakebase

databricks_superuser

3.3.2 ou acima

Implementar autenticação automática pass-through​

Para habilitar a autenticação automática, especifique o recurso dependente ao fazer log no agente. Utilize o parâmetro resources da API log_model() :

nota

Lembre-se também de log todos os recursos dependentes subsequentes. Por exemplo, se você log um Genie Space, também deverá log suas tabelas, o banco de dados SQL e as funções Unity Catalog .

Python
import mlflow
from mlflow.models.resources import (
  DatabricksVectorSearchIndex,
  DatabricksServingEndpoint,
  DatabricksSQLWarehouse,
  DatabricksFunction,
  DatabricksGenieSpace,
  DatabricksTable,
  DatabricksUCConnection,
  DatabricksApp,
  DatabricksLakebase
)

with mlflow.start_run():
  logged_agent_info = mlflow.pyfunc.log_model(
    python_model="agent.py",
    artifact_path="agent",
    input_example=input_example,
    example_no_conversion=True,
    # Specify resources for automatic authentication passthrough
    resources=[
      DatabricksVectorSearchIndex(index_name="prod.agents.databricks_docs_index"),
      DatabricksServingEndpoint(endpoint_name="databricks-meta-llama-3-3-70b-instruct"),
      DatabricksServingEndpoint(endpoint_name="databricks-bge-large-en"),
      DatabricksSQLWarehouse(warehouse_id="your_warehouse_id"),
      DatabricksFunction(function_name="ml.tools.python_exec"),
      DatabricksGenieSpace(genie_space_id="your_genie_space_id"),
      DatabricksTable(table_name="your_table_name"),
      DatabricksUCConnection(connection_name="your_connection_name"),
      DatabricksApp(app_name="app_name"),
      DatabricksLakebase(database_instance_name="lakebase_instance_name"),
    ]
  )

Autenticação em nome do usuário​

info

Visualização

Este recurso está em Pré-visualização Pública.

A autenticação em nome do usuário (OBO) permite que um agente atue como o usuário Databricks que executou a consulta. Isto proporciona:

  • Acesso a dados sensíveis por usuário
  • Controles de dados refinados aplicados pelo Unity Catalog
  • Os tokens de segurança são restritos ("com escopo reduzido") apenas às APIs que seu agente declara, reduzindo o risco de uso indevido.

Requisitos​

  • A autenticação em nome do usuário requer MLflow 2.22.1 ou superior.
  • A autenticação em nome do usuário está desativada por default e deve ser ativada por um administrador workspace . Analise as considerações de segurança antes de ativar este recurso.

Recurso apoiado pela OBO​

Agentes com autenticação OBO podem acessar o seguinte recurso Databricks :

Recurso Databricks

Clientes compatíveis

Índice de Busca Vetorial

databricks_langchain.VectorSearchRetrieverTool, databricks_openai.VectorSearchRetrieverTool, VectorSearchClient

Endpoint do serviço de modelos

databricks.sdk.WorkspaceClient

SQL Warehouse

databricks.sdk.WorkspaceClient

Conexões da UC

databricks.sdk.WorkspaceClient

Tabelas e funções da UC

databricks.sdk.WorkspaceClient (Para acessar as tabelas UC, você deve usar consultas SQL por meio da API de Execução de Instruções SQL)

Espaço Genie

databricks.sdk.WorkspaceClient (recomendado), databricks_langchain.GenieAgent ou databricks_ai_bridge.GenieAgent

Protocolo de Contexto do Modelo (MCP)

databricks_mcp.DatabricksMCPClient

Implementar autenticação OBO​

Para habilitar a autenticação em nome do usuário, siga os passos abaixo:

  1. Atualize as chamadas SDK para especificar que os recursos são acessados em nome do usuário final.
  2. Atualize o código do agente para inicializar o acesso OBO dentro da função predict , não em __init__, porque a identidade do usuário só é conhecida em tempo de execução.
  3. Ao registrar o agente para implantação, declare os escopos da API REST do Databricks que o agente requer.

Os trechos de código a seguir demonstram como configurar o acesso em nome do usuário a diferentes recursos Databricks . Ao inicializar ferramentas, trate erros de permissão de forma elegante, envolvendo a inicialização em um bloco try-except .

Python
from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
from databricks_langchain import VectorSearchRetrieverTool

# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy = ModelServingUserCredentials())

vector_search_tools = []
# Exclude exception handling if the agent should fail
# when users lack access to all required Databricks resources
try:
  tool = VectorSearchRetrieverTool(
    index_name="<index_name>",
    description="...",
    tool_name="...",
    workspace_client=user_client # Specify the user authorized client
    )
    vector_search_tools.append(tool)
except Exception as e:
    _logger.debug("Skipping adding tool as user does not have permissions")

Inicialize o agente na função de previsão.​

Como a identidade do usuário só é conhecida no momento da consulta, você deve acessar o recurso OBO dentro de predict ou predict_stream, não no método __init__ do agente. Isso garante que os recursos fiquem isolados entre as invocações.

Python
from mlflow.pyfunc import ResponsesAgent

class OBOResponsesAgent(ResponsesAgent):
  def initialize_agent():
    user_client = WorkspaceClient(
      credentials_strategy=ModelServingUserCredentials()
    )
    system_authorized_client = WorkspaceClient()
    ### Use the clients above to access resources with either system or user authentication

  def predict(
    self, request
  ) -> ResponsesAgentResponse:
    agent = initialize_agent() # Initialize the Agent in Predict

    agent.predict(request)
    ...

Declare os escopos da API REST ao registrar o agente.​

Ao log seu agente OBO para implantação, você deve listar os escopos API REST Databricks que seu agente chama em nome do usuário. Isso garante que o agente siga o princípio do menor privilégio: tokens são restritos apenas às APIs que o agente requer, reduzindo a possibilidade de ações não autorizadas ou uso indevido de tokens.

A seguir, uma lista dos escopos necessários para acessar vários tipos comuns de recursos Databricks :

Tipo de recurso

Escopo de API necessário

servindo modelo endpoint

serving.serving-endpoints

Endpoints de pesquisa vetorial

vectorsearch.vector-search-endpoints

Índices de busca vetorial

vectorsearch.vector-search-indexes

SQL warehouses

sql.warehouses, sql.statement-execution

Genie spaces

dashboards.genie

Conexões da UC

catalog.connections e serving.serving-endpoints

Databricks Apps

apps.apps

Genie spaces

genie

Funções MCP UC

unity-catalog

Busca vetorial MCP

vector-search

MCP DBSQL

sql

funções externas do MCP

unity-catalog

Para habilitar a autenticação em nome do usuário, passe um MLflow AuthPolicy para log_model():

Python
import mlflow
from mlflow.models.auth_policy import AuthPolicy, SystemAuthPolicy, UserAuthPolicy
from mlflow.models.resources import DatabricksServingEndpoint

# System policy: resources accessed with system credentials
system_policy = SystemAuthPolicy(
    resources=[DatabricksServingEndpoint(endpoint_name="my_endpoint")]
)

# User policy: API scopes for OBO access
user_policy = UserAuthPolicy(api_scopes=[
    "serving.serving-endpoints",
    "vectorsearch.vector-search-endpoints",
    "vectorsearch.vector-search-indexes"
])

# Log the agent with both policies
with mlflow.start_run():
    mlflow.pyfunc.log_model(
        name="agent",
        python_model="agent.py",
        auth_policy=AuthPolicy(
            system_auth_policy=system_policy,
            user_auth_policy=user_policy
        )
    )

Autenticação OBO para clientes OpenAI​

Para agentes que utilizam o cliente OpenAI, use o SDK do Databricks para autenticar automaticamente durante a implantação. O SDK Databricks possui um wrapper para construir o cliente OpenAI com autenticação configurada automaticamente, get_open_ai_client():

Python
% pip install databricks-sdk[openai]
Python
from databricks.sdk import WorkspaceClient
def openai_client(self):
  w = WorkspaceClient()
  return w.serving_endpoints.get_open_ai_client()

Em seguida, especifique o endpoint servindo modelo em resources para autenticar automaticamente no momento da implantação.

Considerações de segurança da OBO​

Considere as seguintes questões de segurança antes de habilitar a autenticação em nome do usuário com agentes.

Acesso expandido a recursos : os agentes podem acessar recursos confidenciais em nome dos usuários. Embora os escopos restrinjam APIs, o endpoint pode permitir mais ações do que seu agente solicita explicitamente. Por exemplo, o escopo API serving.serving-endpoints concede a um agente permissão para executar um endpoint de serviço em nome do usuário. No entanto, o endpoint de serviço pode acessar escopos API adicionais que o agente original não está autorizado a usar.

Exemplo de caderno OBO​

O seguinte Notebook mostra como criar um agente com o Vector Search usando autorização em nome do usuário.

Em nome da autorização do usuário com a Vector Search

Open notebook in new tab

O seguinte Notebook mostra como criar um agente que suporta a execução SQL em um data warehouse SQL usando autorização em nome do usuário. Isso permite que o agente invoque funções do Unity Catalog com segurança, usando as credenciais do usuário.

nota

Atualmente, esta é a maneira recomendada de executar funções UC com o OBO, visto que a execução Spark sem servidor com o OBO ainda não é suportada.

Autorização em nome do usuário com execução de SQL

Open notebook in new tab

Autenticação manual​

A autenticação manual permite que as credenciais sejam especificadas explicitamente durante a implantação do agente. Este método oferece maior flexibilidade, mas requer mais configuração e gerenciamento contínuo de credenciais. Utilize este método quando:

  • O recurso dependente não suporta a autenticação automática.
  • O agente precisa usar credenciais diferentes das do implantador do agente.
  • O agente acessa recursos externos ou APIs fora do Databricks
  • O agente implantado acessa o registro de prompts.
importante

Sobrescrever a variável de segurança de ambiente desativa a passagem automática para outros recursos dos quais seu agente depende.

Autenticação OAuth (recomendada)​

OAuth é a abordagem recomendada para autenticação manual, pois oferece autenticação segura baseada em tokens para entidades de serviço, com recursos refresh automática de tokens:

  1. Crie uma entidade de serviço e gere credenciais OAuth.

  2. Conceda à entidade de serviço permissões para qualquer recurso Databricks ao qual o agente tenha Databricks de acesso. Para acessar o registro de prompts, conceda permissões CREATE FUNCTION, EXECUTE e MANAGE no esquema do Unity Catalog para armazenar prompts.

  3. Crie segredos do Databricks para as credenciais OAuth.

  4. Configure as credenciais OAuth no código do agente:

    Python
    import os

    # Configure OAuth authentication for Prompt Registry access
    # Replace with actual secret scope and key names
    secret_scope_name = "your-secret-scope"
    client_id_key = "oauth-client-id"
    client_secret_key = "oauth-client-secret"

    os.environ["DATABRICKS_HOST"] = "https://<your-workspace-url>"
    os.environ["DATABRICKS_CLIENT_ID"] = dbutils.secrets.get(scope=secret_scope_name, key=client_id_key)
    os.environ["DATABRICKS_CLIENT_SECRET"] = dbutils.secrets.get(scope=secret_scope_name, key=client_secret_key)

  5. Utilize as senhas para se conectar ao workspace:

    Python
    w = WorkspaceClient(
      host=os.environ["DATABRICKS_HOST"],
      client_id=os.environ["DATABRICKS_CLIENT_ID"],
      client_secret = os.environ["DATABRICKS_CLIENT_SECRET"]
    )

  6. Quando implantado com agents.deploy(), inclua as credenciais OAuth como variável de ambiente:

    Python
    agents.deploy(
        UC_MODEL_NAME,
        uc_registered_model_info.version,
        environment_vars={
            "DATABRICKS_HOST": "https://<your-workspace-url>",
            "DATABRICKS_CLIENT_ID": f"{secrets/{secret_scope_name}/{client_id_key}}",
            "DATABRICKS_CLIENT_SECRET": f"{secrets/{secret_scope_name}/{client_secret_key}}"
        },
    )

autenticação PAT​

A autenticação por token de acesso pessoal (PAT) oferece uma configuração mais simples para ambientes de desenvolvimento e teste, embora exija um gerenciamento de credenciais mais manual:

  1. Obtenha um PAT usando uma entidade de serviço ou account pessoal:

    entidade de serviço (recomendado para segurança):

    1. Criar uma entidade de serviço.
    2. Conceda à entidade de serviço permissões para qualquer recurso Databricks ao qual o agente tenha Databricks de acesso. Para acessar o registro de prompts, conceda permissões CREATE FUNCTION, EXECUTE e MANAGE no esquema do Unity Catalog usado para armazenar prompts.
    3. Crie um PAT para a entidade de serviço.

    account pessoal:

    1. Crie um PAT para uma accountpessoal.

  2. Armazene o PAT com segurança criando um segredo do Databricks para o PAT.

  3. Configure a autenticação PAT no código do agente:

    Python
    import os

    # Configure PAT authentication for Prompt Registry access
    # Replace with your actual secret scope and key names
    secret_scope_name = "your-secret-scope"
    secret_key_name = "your-pat-key"

    os.environ["DATABRICKS_HOST"] = "https://<your-workspace-url>"
    os.environ["DATABRICKS_TOKEN"] = dbutils.secrets.get(scope=secret_scope_name, key=secret_key_name)

    # Validate configuration
    assert os.environ["DATABRICKS_HOST"], "DATABRICKS_HOST must be set"
    assert os.environ["DATABRICKS_TOKEN"], "DATABRICKS_TOKEN must be set"

  4. Ao implantar o agente usando agents.deploy(), inclua o PAT como variável de ambiente:

    Python
    agents.deploy(
        UC_MODEL_NAME,
        uc_registered_model_info.version,
        environment_vars={
            "DATABRICKS_HOST": "https://<your-workspace-url>",
            "DATABRICKS_TOKEN": f"{secrets/{secret_scope_name}/{secret_key_name}}"
        },
    )