Pular para o conteúdo principal

Autenticação para agentes AI

AI Os agentes geralmente precisam se autenticar em outro recurso para concluir a tarefa. Por exemplo, um agente implantado pode precisar acessar um índice do Vector Search para consultar dados não estruturados ou o Prompt Registry para carregar prompts dinâmicos.

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

Métodos de autenticação​

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

Método

Descrição

Postura de segurança

Complexidade da configuração

Passagem automática de autenticação

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

Databricks Gerenciar automaticamente credenciais de curta duração para recurso declarado

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

Baixo - declare dependências no momento do registro

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

Execução do agente 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 do tempo de execução

Autenticação manual

Fornecer explicitamente credenciais usando variável de ambiente

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

Alto - requer gerenciamento manual de credenciais

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

Use este fluxograma para escolher o método de autenticação correto para cada recurso. O senhor 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 são compatíveis com a autenticação automática?

Passagem automática de autenticação​

A passagem automática de autenticação é o método mais simples de acessar Databricks-gerenciar recurso. Declare as dependências de recurso ao registrar o agente e Databricks provisione, gire e gerencie 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" para Databricks dashboards. 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 apenas aos recursos de que o agente precisa.

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

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

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

  2. criação e concessões da 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 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 ( tokens M2M OAuth) para a entidade de serviço são injetadas no site endpoint, permitindo que o código do agente acesse o recurso Databricks. Databricks também alterna as credenciais, garantindo que seu agente tenha acesso contínuo e seguro ao recurso dependente.

Recurso suportado para passagem automática de autenticação​

A tabela a seguir lista o recurso Databricks que suporta a passagem automática de autenticação e as permissões que o criador do endpoint deve ter ao implantar o agente.

nota

Unity Catalog O recurso também exige 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

Unity Catalog Função

EXECUTE

2.16.1 ou acima

Espaço Genie

Can Run

2.17.1 ou acima

Índice de pesquisa vetorial

Can Use

2.13.1 ou acima

Unity Catalog Tabela

SELECT

2.18.0 ou acima

Unity Catalog Conexão

Use Connection

2.17.1 ou acima

Implemente a passagem automática de autenticação​

Para ativar a passagem automática de autenticação, especifique o recurso dependente quando o senhor acessarlog o agente. Use o parâmetro resources da log_model() API:

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

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"),
    ]
  )

Autenticação em nome do usuário​

info

Visualização

Esse recurso está em Public Preview.

A autenticação no local do usuário (OBO) permite que um agente atue como o usuário Databricks que executou a 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 declaradas pelo seu agente, reduzindo o risco de uso indevido

Requisitos​

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

Recurso suportado pela OBO​

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

Databricks recurso

Clientes compatíveis

Índice de pesquisa vetorial

databricks_langchain.VectorSearchRetrieverTool, databricks_openai.VectorSearchRetrieverTool, VectorSearchClient

Endpoint do serviço de modelos

databricks.sdk.WorkspaceClient

SQL Warehouse

databricks.sdk.WorkspaceClient

Conexões UC

databricks.sdk.WorkspaceClient

Tabelas e funções de UC

Não é suportado diretamente. Use o Genie com OBO para acessar dados estruturados.

Espaço Genie

databricks_langchain.GenieAgent, databricks_openai.GenieAgent

Protocolo de contexto modelo (MCP)

databricks_mcp.DatabricksMCPClient

Implemente a autenticação OBO​

Para ativar a autenticação no local do usuário, conclua os seguintes passos:

  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 da Databricks que o agente requer.

Os snippets a seguir demonstram como configurar o acesso em nome do usuário a diferentes recursos do site Databricks. Ao inicializar as ferramentas, gerencie os erros de permissão normalmente agrupando 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, o senhor deve acessar o recurso 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)
    ...

Declare os escopos da API REST ao registrar o agente​

Ao log seu agente OBO para implementação, o senhor deve listar os escopos Databricks REST API que o agente chama em nome do usuário. Isso garante que o agente siga o princípio do menor privilégio: tokens é restrito apenas ao APIs que o agente precisa, reduzindo a chance de ações não autorizadas ou uso indevido de tokens.

abaixo é uma lista de escopos necessários para acessar vários tipos comuns de Databricks recurso:

Tipo de recurso

Escopo necessário da API

servindo modelo endpoint

serving.serving-endpoints

Endpoints de pesquisa vetorial

vectorsearch.vector-search-endpoints

Índices de pesquisa vetorial

vectorsearch.vector-search-indexes

SQL warehouses

sql.warehouses, sql.statement-execution

Genie spaces

dashboards.genie

Conexões UC

catalog.connections e serving.serving-endpoints

Databricks Apps

apps.apps

MCP Genie spaces

mcp.genie

Funções MCP UC

mcp.functions

Pesquisa vetorial MCP

mcp.vectorsearch

Funções externas do MCP

mcp.external

Para habilitar a autenticação no meio 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 usam o cliente OpenAI, use o SDK da Databricks para autenticar automaticamente durante a implementação. O SDK da Databricks tem 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 modelo de serviço endpoint como parte de resources para autenticar automaticamente no momento da implementação.

Considerações de segurança do OBO​

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

Acesso ampliado a recursos : Os agentes podem acessar recursos confidenciais em nome dos usuários. Enquanto os escopos restringem APIs, o endpoint pode permitir mais ações do que o agente solicita explicitamente. Por exemplo, o escopo serving.serving-endpoints API concede a um agente permissão para executar um serviço endpoint 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 da OBO​

O Notebook a seguir mostra como criar um agente com o Vector Search usando a autorização por parte do usuário.

Em nome da autorização do usuário com pesquisa vetorial

Open notebook in new tab

Autenticação manual​

A autenticação manual permite especificar explicitamente as credenciais durante a implantação do agente. Esse método tem a maior flexibilidade, mas exige mais configuração e gerenciamento contínuo de credenciais. Use esse método quando:

  • O recurso dependente não é compatível com a passagem automática de autenticação
  • O agente precisa usar credenciais diferentes das do implantador do agente
  • O agente acessa o recurso externo ou APIs fora do Databricks
  • O agente implantado acessa o registro de prompt
important

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

Autenticação OAuth (recomendada)​

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

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

  2. Conceda à entidade de serviço permissões para qualquer Databricks recurso que o agente tenha acesso a privilégios para acessar Databricks recurso. 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 de databricks para as credenciais 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 se conectar ao site 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 mais manual das credenciais:

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

    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 Databricks recurso que o agente tenha acesso a privilégios para acessar Databricks recurso. Para acessar o registro de prompts, conceda as permissões CREATE FUNCTION, EXECUTE e MANAGE no esquema do Unity Catalog usado para armazenar prompts.
    3. Criar um PAT para a entidade de serviço.

    Pessoal account:

    1. Criar um PAT para um site pessoal account.

  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. Quando o agente for implantado 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={
            "DATABRICKS_HOST": "https://<your-workspace-url>",
            "DATABRICKS_TOKEN": f"{secrets/{secret_scope_name}/{secret_key_name}}"
        },
    )
Última atualização em