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

Autenticação para agentes de AI (Model Serving)

info

Para novos casos de uso, a Databricks recomenda implantar 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. Consulte Crie um agente de AI e o tenha implantado no Databricks Apps. Para migrar um agente existente, consulte Migre um agente do Model Serving para o Databricks Apps.

Agentes de AI geralmente precisam se autenticar em outros recursos para concluir tarefas. Por exemplo, um agente implantado pode precisar acessar um índice da Pesquisa de AI para consultar dados não estruturados ou o Registro de Prompt para carregar prompts dinâmicos.

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

Métodos de autenticação​

A tabela a seguir compara os métodos de autenticação disponíveis. É possível combinar qualquer uma dessas abordagens:

Método

Descrição

Postura de segurança

Complexidade de configuração

Passagem de autenticação automática.

O agente é executado com as permissões de execução do usuário que o implantou

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

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

Baixo - declarar dependências no momento do registro

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

O agente realiza a execução com as permissões do usuário final que faz a solicitação.

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

Médio - requer declaração de escopo e inicialização de tempo de execução

Autenticação manual

Fornecer explicitamente credenciais usando variáveis de ambiente

Credenciais de longa duração precisam de gerenciamento de rotação.

Alta — exige gerenciamento manual de credenciais

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

Use 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 atribuída ao usuário?

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

Autenticar-se em servidores MCP do Databricks​

Para autenticar-se em servidores Databricks MCP, especifique todos os recursos que seu agente precisa no momento do registro.

Por exemplo, se seu agente usa os URLs de servidor MCP listados abaixo, você deve especificar todos os índices de pesquisa de AI 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/ai-search/prod/customer_support
  • https://<your-workspace-hostname>/api/2.0/mcp/ai-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 MCP gerenciados, use o pacote PyPI databricks-mcp databricks_mcp.DatabricksMCPClient().get_databricks_resources(<server_url>) para recuperar os recursos necessários para o servidor MCP gerenciado.

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

Passagem automática de autenticação​

A passagem automática de autenticação é a maneira mais simples de acessar recursos gerenciados pelo Databricks. Declare dependências de recursos ao registrar o agente, e o Databricks provisiona, rotaciona e gerencia automaticamente credenciais de curta duração quando o agente é implantado.

Este comportamento de autenticação é semelhante ao comportamento "Execução como proprietário" para painéis do Databricks. Recursos downstream, como tabelas do Unity Catalog, são acessados usando as credenciais de uma entidade de serviço com acesso de privilégio mínimo apenas aos recursos que o agente precisa.

Como funciona a passagem automática de autenticação​

Quando um agente é disponibilizado atrás de um endpoint utilizando a passagem de autenticação automática, a Databricks executa os seguintes passos:

  1. Verificação de permissão : 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ões de entidade de serviço**: Uma entidade de serviço é criada para a versão do modelo de agente e recebe automaticamente acesso de leitura aos recursos do agente.

nota

A entidade de serviço gerada pelo sistema não aparece nas listagens da API ou da UI. Se a versão do modelo do 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 (um token OAuth M2M) para a entidade de serviço são injetadas no endpoint, permitindo que o código do agente acesse os recursos do Databricks. A Databricks também rotaciona as credenciais, garantindo que seu agente tenha acesso contínuo e seguro aos recursos dependentes.

Recursos suportados para passagem de autenticação automática​

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

nota

Os recursos do Unity Catalog também exigem 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 acima

Modelo de ponto de extremidade de serviço

Can Query

2.13.1 ou acima

Função do Unity Catalog

EXECUTE

2.16.1 ou acima

Genie Space

Can Run

2.17.1 ou acima

Índice de Pesquisa de AI

Can Use

2.13.1 ou acima

Tabela do Unity Catalog

SELECT

2.18.0 ou acima

Conexão do Unity Catalog

Use Connection

2.17.1 ou acima

Lakebase

databricks_superuser

3.3.2 ou acima

Implementar passagem de autenticação automática​

Para habilitar a passagem automática de autenticação, especifique os recursos dependentes ao fazer o log do agente. Use o parâmetro resources da API log_model():

nota

Lembre-se de log também todos os recurso dependentes downstream. Por exemplo, se você registrar um Genie Space, você também deve registrar suas tabelas, SQL warehouse e funções do 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é-lançamento público.

A autenticação em nome de usuário (OBO) permite que um agente atue como o usuário Databricks que faz a execução da consulta. Isso fornece:

  • Acesso por usuário a dados confidenciais
  • Controles de dados refinados aplicados pelo Unity Catalog
  • Os tokens de segurança são restritos (“downscoped”) apenas às APIs que seu agente declara, o que reduz o risco de uso indevido.

Requisitos​

  • A autenticação em nome do usuário requer MLflow 2.22.1 e acima.
  • A autenticação em nome do usuário está desabilitada por default e deve ser habilitada por um administrador do workspace. Revise as considerações de segurança antes de habilitar este recurso.

Recursos OBO com suporte​

Em endpoints de Model Serving, agentes com autenticação OBO só podem acessar os recursos do Databricks listados na tabela a seguir. Recursos não listados aqui, como Volumes do Unity Catalog (upload/downloads de arquivos), não são compatíveis com OBO no Model Serving.

nota

Se seu agente exigir acesso OBO a um conjunto mais amplo de recursos, a Databricks recomenda implantar seu agente no Databricks Apps, que suporta escopos OAuth adicionais. Consulte Migrar um agente do Model Serving para o Databricks Apps.

Recurso do Databricks

Clientes compatíveis

Índice de Pesquisa de AI

databricks_langchain.VectorSearchRetrieverTool, databricks_openai.VectorSearchRetrieverTool, VectorSearchClient

Endpoint do serviço de modelos

databricks.sdk.WorkspaceClient

SQL Warehouse

databricks.sdk.WorkspaceClient

Conexões do UC

databricks.sdk.WorkspaceClient

Tabelas e Funções UC

databricks.sdk.WorkspaceClient (Para acessar tabelas do UC, você deve usar consultas SQL usando a API de Execução de Instruções SQL)

Genie Space

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

Protocolo de Contexto de Modelo (MCP)

databricks_mcp.DatabricksMCPClient

Implementar autenticação OBO​

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

  1. Atualizar chamadas SDK para especificar que 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__, pois a identidade do usuário é conhecida apenas em tempo de execução.
  3. Ao registrar o agente para implantação, declare os escopos da API REST Databricks que o agente requer.

Os snippets a seguir demonstram como configurar o acesso em nome do usuário a diferentes recursos do Databricks. Ao inicializar ferramentas, trate os erros de permissão de forma elegante, encapsulando 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 é conhecida apenas no momento da consulta, você deve acessar os recursos OBO dentro de predict ou predict_stream, e não no método __init__ do agente. Isso garante que os recursos sejam 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)
    ...

Declarar escopos de API REST ao registrar o agente​

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

Em endpoint do Model Serving, você só pode usar escopos que correspondem aos recurso suportados por OBO listados acima.

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=[
    "model-serving",
    "ai-search"
])

# 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 usam o cliente OpenAI, use o SDK do Databricks para autenticar automaticamente durante a implantação. O SDK do Databricks possui um wrapper para construir o cliente OpenAI com a 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 de Model Serving em resources para autenticar-se automaticamente no momento da implantação.

Considerações de segurança OBO​

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

Acesso expandido a recursos : Agentes podem acessar recursos sensíveis em nome dos usuários. Embora os escopos restrinjam as APIs, os endpoints podem permitir mais ações do que seu agente solicita explicitamente. Por exemplo, o escopo da API model-serving 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 de API adicionais que o agente original não está autorizado a usar.

Notebook de exemplo OBO​

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

Autorização em Nome do Usuário com Pesquisa de AI

Abrir notebook em uma nova aba

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

nota

Esta é atualmente a forma recomendada para executar Funções UC com OBO, já que a Execução Serverless do Spark com OBO ainda não é compatível.

Autorização em Nome do Usuário com Execução de SQL

Abrir notebook em uma nova aba

Autenticação manual​

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

  • O recurso dependente não oferece suporte à passagem automática de autenticação
  • O agente precisa usar credenciais diferentes das do implantador do agente.
  • O agent acessa recursos ou APIs externos fora do Databricks
  • O agente implantado acessa o registro de prompt
importante

A substituição das variáveis de ambiente de segurança desativa a passagem automática para outros recursos dos quais seu agente depende.

Autenticação OAuth (recomendado)​

OAuth é a abordagem recomendada para autenticação manual porque possui autenticação segura baseada em tokens para entidades de serviço com recursos de refresh automático de tokens:

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

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

  3. Crie segredos do Databricks para as credenciais do OAuth.

  4. Configure as credenciais do 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. Use os segredos para 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. Ao implantar com agents.deploy(), inclua as credenciais OAuth como variáveis de ambiente:

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

Autenticação PAT​

A autenticação de access token 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 uma 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 a qualquer recurso do Databricks que o agente tenha acesso a privilégios para acessar recursos do Databricks. Para acessar o registro de prompt, conceda as 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. Criar um PAT para uma account pessoal.

  2. Armazene o PAT de forma segura 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 uma variável de ambiente:

    Python
    agents.deploy(
        UC_MODEL_NAME,
        uc_registered_model_info.version,
        environment_vars={
         &quot;DATABRICKS_HOST&quot;: &quot;https://&lt;your-workspace-url&gt;&quot;,
         &quot;DATABRICKS_TOKEN&quot;: f&quot;{secrets/{secret_scope_name}/{secret_key_name}}"
        },
    )
Nesta página