Autenticazione per gli agenti di intelligenza artificiale

Gli agenti di intelligenza artificiale spesso devono eseguire l'autenticazione ad altre risorse per completare le attività. Ad esempio, un agente distribuito potrebbe dover accedere a un indice di ricerca vettoriale per eseguire query su dati non strutturati o prompt del Registro di sistema per caricare richieste dinamiche.

Questa pagina illustra i metodi di autenticazione disponibili durante lo sviluppo e la distribuzione di agenti con Mosaic AI Agent Framework.

Metodi di autenticazione

Nella tabella seguente vengono confrontati i metodi di autenticazione disponibili. È possibile combinare e associare uno di questi approcci:

Metodo	Description	Comportamento di sicurezza	Complessità della configurazione
Pass-through di autenticazione automatica	Agent viene eseguito con le autorizzazioni dell'utente che lo ha distribuito Databricks gestisce automaticamente le credenziali di breve durata per le risorse dichiarate	Credenziali di breve durata, rotazione automatica	Bassa: dichiarare le dipendenze in fase di registrazione
Autenticazione per conto dell'utente (OBO)	Agent viene eseguito con le autorizzazioni dell'utente finale che effettua la richiesta	Usa le credenziali dell'utente finale con ambiti limitati	Medium: richiede la dichiarazione di ambito e l'inizializzazione di runtime
Autenticazione manuale	Fornire in modo esplicito le credenziali usando le variabili di ambiente	Le credenziali di lunga durata richiedono la gestione della rotazione	Elevato: richiede la gestione manuale delle credenziali

Eseguire l'autenticazione a sistemi esterni e server MCP

Per indicazioni su come eseguire l'autenticazione a API esterne e server MCP dall'agente, vedere Connettere gli strumenti dell'agente di intelligenza artificiale ai servizi esterni. Queste risorse possono anche essere sottoposte a query per conto dell'agente o dell'utente, come descritto in Metodi di autenticazione.

Scegliere il metodo di autenticazione appropriato per la risorsa

Usare questo diagramma di flusso per scegliere il metodo di autenticazione corretto per ogni risorsa. È possibile combinare i metodi in base alle esigenze e un agente può usare un metodo diverso per ogni risorsa a seconda del relativo caso d'uso.

È necessario il controllo di accesso per utente o il controllo con attributi utente?
- Sì → Usare l'autenticazione a nome dell'utente
- Nessuna → Continuare al passaggio 2
Tutte le risorse supportano l'autenticazione automatica?
- Sì → Usare il pass-through di autenticazione automatica (scelta consigliata)
- Nessuna → usare l'autenticazione manuale

Passaggio automatico dell'autenticazione

Il pass-through di autenticazione automatica è il metodo più semplice per accedere alle risorse gestite da Databricks. Dichiarare le dipendenze delle risorse durante la registrazione dell'agente, e Databricks provvede automaticamente a gestire, ruotare e gestire le credenziali di breve durata quando l'agente viene distribuito.

Questo comportamento di autenticazione è simile al comportamento "Run as owner" per i dashboard di Databricks. Le risorse downstream, come le tabelle del catalogo di Unity, sono accessibili usando le credenziali di un principale di servizio con accesso con privilegi minimi solo alle risorse necessarie per l'agente.

Funzionamento del pass-through di autenticazione automatica

Quando un agente viene gestito dietro un endpoint usando il pass-through di autenticazione automatica, Databricks esegue i passaggi seguenti:

Verifica delle autorizzazioni: Databricks verifica che l'autore dell'endpoint possa accedere a tutte le dipendenze specificate durante la registrazione dell'agente.
Creazione e concessione dell'entità servizio: Viene creata un'entità servizio per la versione del modello dell'agente e viene concesso automaticamente l'accesso in lettura alle risorse dell'agente.

Annotazioni

L'entità principale servizio generata dal sistema non appare nelle liste API o dell'interfaccia utente. Se la versione del modello dell'agente viene rimossa dall'endpoint, anche il servizio principale viene eliminato.
Provisioning e rotazione delle credenziali: credenziali di breve durata (un token OAuth M2M) per il service principal vengono inserite nell'endpoint, consentendo al codice dell'agente di accedere alle risorse di Databricks. Databricks sostituisce regolarmente le credenziali, assicurandosi che l'agente abbia un accesso continuo e sicuro alle risorse dipendenti.

Risorse supportate per il pass-through di autenticazione automatica

Nella tabella seguente sono elencate le risorse di Databricks che supportano il pass-through di autenticazione automatica e le autorizzazioni che l'autore dell'endpoint deve avere durante la distribuzione dell'agente.

Annotazioni

Le risorse del catalogo unity richiedono anche USE SCHEMA nello schema padre e USE CATALOG nel catalogo padre.

Tipo di risorsa	Autorizzazione	Versione minima di MLflow
SQL Warehouse	`Use Endpoint`	2.16.1 o versione successiva
Endpoint di gestione del modello	`Can Query`	2.13.1 o versione successiva
Funzione di Unity Catalog	`EXECUTE`	2.16.1 o versione successiva
Spazio Genie	`Can Run`	2.17.1 o versione successiva
Indice di ricerca vettoriale	`Can Use`	2.13.1 o versione successiva
Tabella del catalogo Unity	`SELECT`	2.18.0 o versione successiva
Connessione al catalogo Unity	`Use Connection`	2.17.1 o versione successiva
Lakebase	`databricks_superuser`	3.3.2 o versione successiva

Implementare il pass-through di autenticazione automatica

Per abilitare il pass-through di autenticazione automatica, specificare le risorse dipendenti quando si fa il log dell'agente. Usare il resources parametro dell'API log_model() :

Annotazioni

Ricordarsi di registrare anche tutte le risorse dipendenti downstream. Ad esempio, se si registra uno spazio Genie, è necessario registrare anche le relative tabelle, SQL Warehouse e le funzioni del catalogo Unity.

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

Autenticazione per conto utente

Importante

Questa funzionalità è in Anteprima Pubblica.

L'autenticazione OBO (On-behalf-of-user) consente a un agente di fungere da utente di Databricks che esegue la query. In questo modo sono disponibili le opzioni seguenti:

Accesso per utente ai dati sensibili
Controlli dati con granularità fine applicati dal catalogo Unity
I token di sicurezza sono limitati ("downscoped") solo alle API dichiarate dall'agente, riducendo il rischio di uso improprio

Requisiti

L'autenticazione "per conto dell'utente" richiede MLflow 2.22.1 e versioni successive.
L'autenticazione on-behalf-of-user è disabilitata per impostazione predefinita e deve essere abilitata da un amministratore dell'area di lavoro. Esaminare le considerazioni sulla sicurezza prima di abilitare questa funzionalità.

Risorse supportate da OBO

Gli agenti con autenticazione OBO possono accedere alle risorse di Databricks seguenti:

Risorsa Databricks	Client compatibili
Indice di ricerca vettoriale	`databricks_langchain.VectorSearchRetrieverTool`, `databricks_openai.VectorSearchRetrieverTool`, `VectorSearchClient`
Endpoint di gestione del modello	`databricks.sdk.WorkspaceClient`
SQL Warehouse	`databricks.sdk.WorkspaceClient`
Connessioni UC	`databricks.sdk.WorkspaceClient`
Tabelle e funzioni UC	`databricks.sdk.WorkspaceClient` Per accedere alle tabelle UC è necessario usare query SQL con l'API di esecuzione delle istruzioni SQL.
Spazio Genie	`databricks.sdk.WorkspaceClient` (scelta consigliata), `databricks_langchain.GenieAgent`o `databricks_ai_bridge.GenieAgent`
Model Context Protocol (MCP)	`databricks_mcp.DatabricksMCPClient`

Implementare l'autenticazione OBO

Per abilitare l'autenticazione per conto dell'utente, completare la seguente procedura:

Aggiornare le chiamate SDK per specificare che le risorse sono accessibili per conto dell'utente finale.
Aggiornare il codice dell'agente per inizializzare l'accesso OBO all'interno della predict funzione, non in __init__, perché l'identità utente è nota solo in fase di esecuzione.
Quando si registra l'agente per la distribuzione, dichiarare gli ambiti dell'API REST di Databricks richiesti dall'agente.

I frammenti di codice seguenti illustrano come configurare l'accesso on-behalf-of-user a diverse risorse di Databricks. Quando si inizializzano gli strumenti, gestire gli errori di autorizzazione in modo elegante avvolgendo l'inizializzazione in un blocco try-except.

Strumento di recupero per la ricerca vettoriale

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

Client di ricerca vettoriale

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

MCP

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
  )

Endpoint di gestione del modello

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

Connessioni UC

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ExternalFunctionRequestHttpMethod
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())

user_client.serving_endpoints.http_request(
  conn="connection_name",
  method=ExternalFunctionRequestHttpMethod.POST,
  path="/api/v1/resource",
  json={"key": "value"},
  headers={"extra_header_key": "extra_header_value"},
)

Genie Spaces (WorkspaceClient)

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 space 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")

Genie Spaces (LangChain)

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
  )

Inizializza l'agente nella funzione di previsione

Poiché l'identità dell'utente è nota solo in fase di query, è necessario accedere alle risorse OBO all'interno predict o predict_stream, non nel metodo dell'agente __init__ . Ciò garantisce che le risorse siano isolate tra le chiamate.

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

Dichiarare gli ambiti dell'API REST durante la registrazione dell'agente

Quando si registra l'agente OBO per la distribuzione, è necessario elencare gli ambiti dell'API REST di Databricks che l'agente chiama per conto dell'utente. Ciò garantisce che l'agente segua il principio dei privilegi minimi: i token sono limitati solo alle API richieste dall'agente, riducendo la probabilità di azioni non autorizzate o uso improprio dei token.

Di seguito è riportato un elenco di ambiti necessari per accedere a diversi tipi comuni di risorse di Databricks:

Tipo di risorsa	Ambito API obbligatorio
Endpoint di gestione dei modelli	`serving.serving-endpoints`
Endpoint di Ricerca vettoriale	`vectorsearch.vector-search-endpoints`
Indici di ricerca vettoriale	`vectorsearch.vector-search-indexes`
Magazzini SQL	`sql.warehouses`, `sql.statement-execution`
Spazi genie	`dashboards.genie`
Connessioni UC	`catalog.connections` e `serving.serving-endpoints`
Applicazioni Databricks	`apps.apps`
Spazi MCP Genie	`mcp.genie`
Funzioni UC MCP	`mcp.functions`
Ricerca vettoriale MCP	`mcp.vectorsearch`
MCP DBSQL	`mcp.sql`, `sql.warehouses`, `sql.statement-execution`
Funzioni esterne MCP	`mcp.external`

Per abilitare l'autenticazione per conto utente, passare un MLflow AuthPolicy a 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=[
    "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
        )
    )

Autenticazione OBO per i client OpenAI

Per gli agenti che usano il client OpenAI, usare Databricks SDK per l'autenticazione automatica durante la distribuzione. Databricks SDK dispone di un wrapper per costruire il client OpenAI con l'autenticazione configurata 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()

Specificare quindi l'endpoint Model Serving come parte di resources per l'autenticazione automatica in fase di distribuzione.

Considerazioni sulla sicurezza OBO

Considerare i seguenti aspetti di sicurezza prima di abilitare l'autenticazione on-behalf-of-user per gli agenti.

Accesso alle risorse espanso: gli agenti possono accedere a risorse sensibili per conto degli utenti. Mentre gli ambiti limitano le API, gli endpoint potrebbero consentire più azioni rispetto alle richieste esplicite dell'agente. Ad esempio, l'ambito API concede a un agente l'autorizzazione serving.serving-endpoints per eseguire un endpoint di servizio per conto dell'utente. Tuttavia, l'endpoint di servizio può accedere ad ambiti API aggiuntivi che l'agente originale non è autorizzato a usare.

Notebook di esempio OBO

Il seguente notebook mostra come creare un agente con ricerca vettoriale utilizzando l'autorizzazione per conto dell'utente.

Per conto dell'autorizzazione utente con ricerca vettoriale

Ottieni il notebook

Il seguente notebook illustra come creare un agente che supporta l'esecuzione di SQL su un SQL Warehouse usando l'autorizzazione per conto dell'utente. In questo modo l'agente può richiamare in modo sicuro le funzioni del catalogo Unity usando le credenziali utente. Nota: questo è attualmente il modo consigliato per eseguire funzioni UC con OBO perché l'esecuzione di Spark serverless con OBO non è ancora supportata.

Per conto dell'autorizzazione utente con esecuzione SQL

Ottieni il notebook

Autenticazione manuale

L'autenticazione manuale consente di specificare in modo esplicito le credenziali durante la distribuzione dell'agente. Questo metodo offre la massima flessibilità, ma richiede una maggiore configurazione e una gestione continua delle credenziali. Usare questo metodo quando:

La risorsa dipendente non supporta il pass-through di autenticazione automatica
L'agente deve usare credenziali diverse da quelle del deployer dell'agente
L'agente accede a risorse o API esterne a Databricks
L'agente distribuito accede al Registro di sistema dei prompt

Importante

L'override delle variabili di ambiente di sicurezza disabilita il pass-through automatico per altre risorse da cui dipende l'agente.

Autenticazione OAuth (scelta consigliata)

OAuth è l'approccio consigliato per l'autenticazione manuale perché dispone di autenticazione sicura basata su token per le entità servizio con funzionalità di aggiornamento automatico dei token:

Creare un'entità servizio e generare le credenziali OAuth.
Concedi al principale del servizio le autorizzazioni per qualsiasi risorsa di Databricks a cui l'agente ha privilegi di accesso per accedere alle risorse di Databricks. Per accedere al registro dei prompt, concedere le autorizzazioni CREATE FUNCTION, EXECUTE e MANAGE sullo schema di Unity Catalog per l'archiviazione dei prompt.
Creare segreti di databricks per le credenziali OAuth.

Configurare le credenziali OAuth nel codice dell'agente:

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)

Usare i segreti per connettersi all'area di lavoro:

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

Quando si esegue la distribuzione con agents.deploy(), includere le credenziali OAuth come variabili di ambiente:

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

Autenticazione PAT

L'autenticazione pat (Personal Access Token) offre una configurazione più semplice per gli ambienti di sviluppo e test, anche se richiede una gestione delle credenziali più manuale:

Ottieni un token di accesso personale utilizzando un'entità servizio principale o un account personale:

Principale del servizio (scelta consigliata per la sicurezza):
1. Creare un'entità servizio.
2. Concedi al principale del servizio le autorizzazioni per qualsiasi risorsa di Databricks a cui l'agente ha privilegi di accesso per accedere alle risorse di Databricks. Per accedere al registro dei prompt, concedere le autorizzazioni CREATE FUNCTION, EXECUTE e MANAGE nello schema del catalogo Unity usato per archiviare i prompt.
3. Creare un token di accesso personale per l'entità servizio.
Account personale:
1. Creare un Token di Accesso Personale (PAT) per un account personale.
Archiviare il token di accesso personale in modo sicuro creando un segreto in Databricks per il PAT.

Configurare l'autenticazione PAT nel codice dell'agente:

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"

Quando si distribuisce l'agente usando agents.deploy(), includere il pat come variabile di ambiente:

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

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-09-22