Pular para o conteúdo principal

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

info

Para novos casos de uso, a Databricks recomenda implantar agentes em 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 Criar um agente de AI e implantá-lo em Databricks Apps. Para migrar um agente existente, consulte Migrar um agente de Model Serving para Databricks Apps.

Agentes de AI frequentemente precisam autenticar-se em outros recursos para concluir tarefas. Por exemplo, um agente implantado pode precisar acessar um índice de Pesquisa de AI para fazer query de 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 Custom Agents.

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.

O agente é executado com as permissões 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 - declare dependências no momento do registro

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

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

Utiliza as credenciais do usuário final com escopos restritos

Médio - exige declaração de escopo e inicialização de runtime

Autenticação manual

Forneça credenciais explicitamente usando variáveis de ambiente

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

Alto — requer gerenciamento manual de credenciais

Método

Descrição

Postura de segurança

Complexidade da configuração

Passagem automática de autenticação.

O agente é executado com as permissões 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 - declare dependências no momento do registro

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

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

Utiliza as credenciais do usuário final com escopos restritos

Médio - exige declaração de escopo e inicialização de runtime

Autenticação manual

Forneça credenciais explicitamente usando variáveis 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. 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 em servidores MCP do Databricks

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

Por exemplo, se o seu agente usar os URLs de servidor MCP listados abaixo, você deve especificar todos os índices de AI 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/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 databricks-mcp PyPI databricks_mcp.DatabricksMCPClient().get_databricks_resources(<server_url>) para recuperar os recursos necessários pelo servidor MCP gerenciado.

Se seu agente fizer query em 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

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

Esse comportamento de autenticação é semelhante ao comportamento de "Executar como proprietário" para dashboards Databricks. Recursos downstream, como tabelas do Unity Catalog, são acessados usando as credenciais de um Service Principal 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 através de um Endpoint usando 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 log do agente.

  2. **Criação e concessões de Service Principal**: Um Service Principal é criado para a versão do modelo de agente e tem acesso de leitura automaticamente concedido aos recursos do agente.

nota

A Service Principal 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 Service Principal também será excluída.

  1. Provisionamento e rotação de credenciais : Credenciais de curta duração (um token OAuth M2M) para o Service Principal são injetadas no Endpoint, permitindo que o código do agente acesse os recursos do Databricks. O Databricks também rotaciona as credenciais, garantindo que seu agente tenha acesso contínuo e seguro a recursos dependentes.

Recursos compatíveis para passagem automática de autenticação

A tabela a seguir lista os recursos do Databricks que oferecem suporte à transmissão automática de autenticação e as permissões que o criador do Endpoint deve ter ao implantar o agente.

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 Agent

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

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 Agent

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 automática de autenticação

Para ativar o pass-through de autenticação automático, especifique os recursos dependentes ao registrar o agente. Use o parâmetro resources da API log_model():

nota

Lembre-se de registrar também todos os recursos dependentes downstream. Por exemplo, se você registrar um Genie Agent, também deverá registrar suas tabelas, SQL Warehouses 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

Esse recurso está em Pré-lançamento público.

A autenticação em nome do usuário (OBO) permite que um agente atue como o usuário do Databricks que executa a query. Isso fornece:

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

Requisitos

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

Recursos compatíveis com OBO

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/download 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 em Databricks Apps, que oferece suporte a escopos OAuth adicionais. Consulte Migre um agente do Model Serving para o Databricks Apps.

Recurso da 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 UC, você deve usar consultas SQL usando a API de Execução de Instruções SQL)

Genie Agent

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

Protocolo de Contexto de Modelo (MCP)

databricks_mcp.DatabricksMCPClient

Recurso da 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 UC, você deve usar consultas SQL usando a API de Execução de Instruções SQL)

Genie Agent

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

Protocolo de Contexto de Modelo (MCP)

databricks_mcp.DatabricksMCPClient

Implementar a autenticação OBO

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

  1. Atualize as chamadas do 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 é conhecida apenas em runtime.
  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 Databricks. Ao inicializar ferramentas, trate os 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 é conhecida apenas no tempo de query, é necessário 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 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 escopos de API REST ao registrar o agente

Ao registrar seu agente OBO para implantação, é preciso listar os escopos da API REST do Databricks que o 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 token.

Em Endpoints de Model Serving, você só pode usar escopos que correspondem aos recursos com suporte OBO listados acima.

Para habilitar a autenticação em nome do usuário, passe um AuthPolicy do MLflow 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 Databricks SDK para autenticar automaticamente durante a implantação. O Databricks SDK 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 endpoint de Model Serving em resources para autenticar-se automaticamente no momento da implantação.

Considerações de segurança de OBO

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

Acesso expandido a recursos: agentes podem acessar recursos confidenciais 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 da API adicionais que o agente original não está autorizado a usar.

Notebooks de exemplo do OBO

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

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

O notebook a seguir demonstra como criar um agente que oferece suporte à execução de SQL em um SQL Warehouse usando autorização em nome do usuário. Isso permite que o agente invoque com segurança funções do Unity Catalog usando credenciais do usuário.

nota

Esta é atualmente a maneira recomendada de executar funções UC com OBO, pois 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

Autenticação manual

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

  • O recurso dependente não oferece suporte à passagem automática de autenticação.
  • O agente precisa usar credenciais que não sejam as do implantador do agente
  • O agente acessa recursos ou APIs externas fora da Databricks.
  • O agente implantado acessa o registro de prompts.
importante

A substituição das variáveis de ambiente de segurança desabilita 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 tem autenticação segura baseada em tokens para Service Principals com recursos de refresh automático de tokens:

  1. Crie um Service Principal e gere credenciais OAuth.

  2. Conceda ao service principal permissões a qualquer recurso da Databricks ao qual o agente tenha acesso privilégios para acessar recursos da Databricks. 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 de 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. Use os segredos 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. 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 Personal Access Token (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 um Service Principal ou account pessoal:

    Service Principal (recomendado para segurança):

    1. Crie um Service Principal.
    2. Conceda ao service principal permissões a qualquer recurso da Databricks ao qual o agente tenha acesso privilégios para acessar recursos da Databricks. 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. Crie um PAT para o Service Principal.

    Personal account:

    1. Crie um PAT para uma conta pessoal.
  2. Armazene o PAT com segurança criando um segredo Databricks para o PAT.

  3. Configurar 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}}"
    },
    )