Autenticação para agentes de AI (Model Serving)
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 |
|---|---|---|---|
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 | |
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 | |
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.
-
É necessário controle de acesso por usuário ou auditoria atribuída ao usuário?
- Sim → Use autenticação em nome do usuário
- Não → Continue para a Etapa 2
-
Todos os recursos suportam autenticação automática?
- Sim → Use passagem de autenticação automática (recomendado)
- Não → Use autenticação manual
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_supporthttps://<your-workspace-hostname>/api/2.0/mcp/ai-search/prod/billinghttps://<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:
-
**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.
-
**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.
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.
- 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.
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 |
| 2.16.1 ou acima |
Modelo de ponto de extremidade de serviço |
| 2.13.1 ou acima |
Função do Unity Catalog |
| 2.16.1 ou acima |
Genie Agent |
| 2.17.1 ou acima |
Índice de Pesquisa de AI |
| 2.13.1 ou acima |
Tabela do Unity Catalog |
| 2.18.0 ou acima |
Conexão do Unity Catalog |
| 2.17.1 ou acima |
Lakebase |
| 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():
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.
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
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.
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 |
|
Endpoint do serviço de modelos |
|
SQL Warehouse |
|
Conexões do UC |
|
Tabelas e Funções UC |
|
Genie Agent |
|
Protocolo de Contexto de Modelo (MCP) |
|
Implementar a autenticação OBO
Para habilitar a autenticação em nome do usuário, conclua os passos a seguir:
- Atualize as chamadas do SDK para especificar que os recursos são acessados em nome do usuário final.
- 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. - 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.
- AI Search Retriever Tool
- AI Search Client
- MCP
- Model Serving Endpoint
- UC Connections
- Genie Agents (WorkspaceClient)
- Genie Agents (LangChain)
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")
from databricks.vector_search.client import VectorSearchClient
from databricks.vector_search.utils import CredentialStrategy
# Configure a VectorSearch Client to use on behalf of end
# user authentication
user_authenticated_vsc = VectorSearchClient(credential_strategy=CredentialStrategy.MODEL_SERVING_USER_CREDENTIALS)
# Exclude exception handling if the agent should fail when
# users lack access to all required Databricks resources
try:
vs_index = user_authenticated_vsc.get_index(endpoint_name="endpoint_name", index_name="index_name")
...
except Exception as e:
_logger.debug("Skipping Vector Index because user does not have permissions")
from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
from databricks_mcp import DatabricksMCPClient
# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())
mcp_client = DatabricksMCPClient(
server_url="<mcp_server_url>",
workspace_client=user_client, # Specify the user client here
)
from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())
# Exclude exception handling if the agent should fail
# when users lack access to all required Databricks resources
try:
user_client.serving_endpoints.query("endpoint_name", input="")
except Exception as e:
_logger.debug("Skipping Model Serving Endpoint due to no permissions")
import requests
from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())
response = requests.post(
f"{user_client.config.host}/api/2.0/unity-catalog/connections/connection_name/proxy/api/v1/resource",
headers={
**user_client.config.authenticate(),
"Content-Type": "application/json",
},
json={"key": "value"},
)
from databricks_langchain.genie import GenieAgent
from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())
genie_agent = GenieAgent(
genie_space_id="space-id",
genie_agent_name="Genie",
description="This Genie Agent has access to sales data in Europe",
client=user_client
)
# Use the Genie SDK methods available through WorkspaceClient
try:
response = agent.invoke("Your query here")
except Exception as e:
_logger.debug("Skipping Genie due to no permissions")
from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
from databricks_langchain.genie import GenieAgent
# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())
genie_agent = GenieAgent(
genie_space_id="<genie_space_id>",
genie_agent_name="Genie",
description="Genie_description",
client=user_client, # Specify the user client here
)
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.
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():
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():
% pip install databricks-sdk[openai]
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.
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.
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:
-
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,EXECUTEeMANAGEno esquema do Unity Catalog para armazenar prompts. -
Crie segredos do Databricks para as credenciais de OAuth.
-
Configure as credenciais OAuth no código do agente:
Pythonimport 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) -
Use os segredos para se conectar ao Workspace:
Pythonw = WorkspaceClient(
host=os.environ["DATABRICKS_HOST"],
client_id=os.environ["DATABRICKS_CLIENT_ID"],
client_secret = os.environ["DATABRICKS_CLIENT_SECRET"]
) -
Ao implantar com
agents.deploy(), inclua as credenciais OAuth como variáveis de ambiente:Pythonagents.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 Personal Access Token (PAT) oferece uma configuração mais simples para ambientes de desenvolvimento e teste, embora exija um gerenciamento de credenciais mais manual:
-
Obtenha um PAT usando um Service Principal ou account pessoal:
Service Principal (recomendado para segurança):
- Crie um Service Principal.
- 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,EXECUTEeMANAGEno esquema do Unity Catalog usado para armazenar prompts. - Crie um PAT para o Service Principal.
Personal account:
-
Armazene o PAT com segurança criando um segredo Databricks para o PAT.
-
Configurar a autenticação PAT no código do agente:
Pythonimport 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" -
Ao implantar o agente usando
agents.deploy(), inclua o PAT como uma variável de ambiente:Pythonagents.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}}"
},
)