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, un endpoint di servizio per chiamare un modello di base o funzioni del catalogo Unity per eseguire la logica personalizzata.

Questa pagina illustra i metodi di autenticazione per gli agenti distribuiti nelle app Databricks. Per gli agenti distribuiti sugli endpoint di gestione dei modelli, vedere Autenticazione per gli agenti di intelligenza artificiale (Model Serving).

Databricks Apps fornisce due metodi di autenticazione per gli agenti. Ogni metodo serve casi d'uso diversi:

Metodo	Description	Quando utilizzare
Autorizzazione dell'app	Agent esegue l'autenticazione usando un'entità servizio creata automaticamente con autorizzazioni coerenti. In precedenza denominata autenticazione del Service Principal.	Caso d'uso più comune. Usare quando tutti gli utenti devono avere lo stesso accesso alle risorse.
Autorizzazione utente	Agent esegue l'autenticazione usando l'identità dell'utente che effettua la richiesta. In precedenza chiamata Autenticazione On-Behalf-Of (OBO).	Usare quando sono necessarie autorizzazioni specifiche dell'utente, audit trail o controllo di accesso con granularità fine con Unity Catalog.

È possibile combinare entrambi i metodi in un singolo agente. Ad esempio, usare l'autorizzazione dell'app per accedere a un indice di ricerca vettoriale condiviso usando l'autorizzazione utente per eseguire query su tabelle specifiche dell'utente.

Autorizzazione dell'app

Per impostazione predefinita, Le app Databricks eseguono l'autenticazione usando l'autorizzazione dell'app. Azure Databricks crea automaticamente un principal di servizio quando crei l'app e funge da identità dell'app.

Tutti gli utenti che interagiscono con l'app condividono le stesse autorizzazioni definite per l'entità servizio. Questo modello funziona bene quando si desidera che tutti gli utenti visualizzino gli stessi dati o quando l'app esegue operazioni condivise non associate a controlli di accesso specifici dell'utente.

Per informazioni dettagliate sull'autorizzazione dell'app, vedere Autorizzazione dell'app.

Concedere le autorizzazioni all'esperimento MLflow

L'agente deve accedere a un esperimento MLflow per registrare tracce e risultati di valutazione.

Concedere al principal del servizio Can Edit l'autorizzazione sull'esperimento MLflow:

Fare clic su Modifica nella home page dell'app.
Passare al passaggio Configura .
Nella sezione Risorse dell'app aggiungere la risorsa esperimento MLflow.

Vedere Aggiungere una risorsa esperimento MLflow a un'app Databricks.

Concedere autorizzazioni ad altre risorse di Databricks

Se l'agente usa altre risorse di Databricks, ad esempio spazi Genie, indici di Ricerca Vettoriale o SQL warehouses, concedere le autorizzazioni dell'entità servizio tramite l'interfaccia utente delle app Databricks. Per l'elenco completo delle risorse supportate e delle istruzioni di configurazione, vedere Aggiungere risorse a un'app 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.

La tabella seguente elenca le autorizzazioni minime necessarie per gli agenti per accedere alle risorse di Databricks comuni:

Tipo di risorsa	Autorizzazione
SQL Warehouse	`Can Use`
Endpoint di gestione del modello	`Can Query`
Funzione di Unity Catalog	`CAN Execute`
Spazio Genie	`Can Run`
Indice di ricerca vettoriale	`Can Select`
Tabella del catalogo Unity	`SELECT`
Connessione al catalogo Unity	`Use Connection`
Volume del catalogo Unity	`Can Read` o `Can Read and Write`
Lakebase	`Can Connect and Create`

Quando si concede l'accesso alle risorse del catalogo Unity, è necessario concedere anche le autorizzazioni a tutte le risorse dipendenti downstream. Ad esempio, se si concede l'accesso a uno spazio Genie, è necessario concedere anche l'accesso alle tabelle sottostanti, ai warehouse SQL e alle funzioni del catalogo Unity.

L'utente che aggiunge la risorsa deve disporre dell'autorizzazione Can Manage sia per la risorsa che per l'app. Per l'elenco completo delle risorse supportate e di tutte le autorizzazioni disponibili, vedere Tipi di risorse supportati.

Per le procedure consigliate per la gestione sicura dell'autorizzazione delle app, tra cui la gestione delle credenziali e i principi dei privilegi minimi, vedere Autorizzazione delle app.

Autorizzazione utente

Importante

L'autorizzazione utente è in anteprima pubblica. L'amministratore dell'area di lavoro deve abilitarlo prima di poter usare l'autorizzazione utente.

L'autorizzazione utente consente a un agente di agire con l'identità dell'utente che effettua la richiesta. In questo modo sono disponibili le opzioni seguenti:

Accesso per utente ai dati sensibili
Controlli dati con granularità fine applicati dal catalogo Unity
Tracce di audit specifiche per utente
Imposizione automatica dei filtri a livello di riga e delle maschere di colonna

Usare l'autorizzazione utente quando l'agente deve accedere alle risorse utilizzando l'identità dell’utente che ha effettuato la richiesta anziché il principale del servizio dell'applicazione.

Funzionamento dell'autorizzazione utente

Quando si configura l'autorizzazione utente per l'agente:

Aggiungere ambiti API all'app: definire le API di Databricks a cui l'app può accedere per conto degli utenti. Vedere Aggiungere ambiti a un'app.
Le credenziali utente sono ridotte: Azure Databricks riceve le credenziali dell'utente e le limita solo agli ambiti API definiti.
Inoltro di token: il token con ambito inferiore viene reso disponibile per l'app tramite l'intestazione x-forwarded-access-token HTTP.
MLflow AgentServer archivia il token: il server agent archivia automaticamente questo token per ogni richiesta di accesso pratico nel codice dell'agente.

Configurare l'autorizzazione utente aggiungendo ambiti nell'interfaccia utente di Databricks Apps durante la creazione o la modifica dell'app o a livello di codice tramite l'API. Per istruzioni dettagliate, vedere Aggiungere ambiti a un'app .

Gli agenti con autorizzazione utente possono accedere alle risorse di Databricks seguenti:

SQL Warehouse
Spazio Genie
File e directory
Endpoint di gestione del modello
Indice di ricerca vettoriale
Connessioni al catalogo Unity
Tabelle del catalogo Unity

Implementare l'autorizzazione utente

Per implementare l'autorizzazione utente, è necessario aggiungere ambiti di autorizzazione all'app. Gli ambiti limitano le operazioni che l'app può eseguire per conto dell'utente.

Nell'interfaccia utente di Databricks passare alle impostazioni di autorizzazione di Databricks Apps.
Fare clic su +Aggiungi ambito e selezionare gli ambiti a cui si desidera accedere alle risorse per conto dell'utente.
Salvare le modifiche.

Per configurare l'autorizzazione utente nel codice dell'agente, recuperare l'intestazione per questa richiesta da AgentServer e costruire un client dell'area di lavoro con tali credenziali.

Nel codice dell'agente importare l'utilità di autenticazione:

Se si usa uno dei modelli forniti da databricks/app-templates, importare l'utilità fornita:
```
from databricks_app.utils import get_user_workspace_client
```
In caso contrario, importare dalle utilità di Agent Server:
```
from agent_server.utils import get_user_workspace_client
```
La funzione get_user_workspace_client() utilizza il x-forwarded-access-token Agent Server per acquisire l'intestazione e costruisce un cliente workspace con tali credenziali utente, gestendo l'autenticazione tra l'utente, l'app e il server agente.
Inizializzare il client dell'area di lavoro quando si esegue una query, non durante l'avvio dell'app.

Importante

Chiamare get_user_workspace_client() all'interno dei gestori invoke e stream, non in __init__ o all'avvio dell'app. Le credenziali utente sono disponibili solo in fase di query quando un utente effettua una richiesta. L'inizializzazione durante l'avvio dell'app avrà esito negativo perché non esiste ancora alcun contesto utente.
```
# In your agent code (inside invoke or stream handler)
user_client = get_user_workspace_client()


# Use user_client to access Databricks resources with user permissions
response = user_client.serving_endpoints.query(name="my-endpoint", inputs=inputs)
```

Per una guida completa sull'aggiunta degli ambiti e sulla comprensione della sicurezza basata sugli ambiti, vedere Sicurezza basata sugli ambiti ed escalation dei privilegi.

Eseguire l'autenticazione nei server MCP di Databricks

Per eseguire l'autenticazione nei server MCP di Databricks, specificare tutte le risorse necessarie per l'agente nel databricks.yaml file. Garantire all'entità servizio dell'app (o agli utenti, se si utilizza l'autorizzazione utente) l'accesso a tutte le risorse a valle.

Ad esempio, se l'agente usa gli URL del server MCP elencati di seguito, è necessario concedere l'accesso a tutti gli indici di ricerca vettoriali negli prod.customer_support schemi e prod.billing e tutte le funzioni del catalogo Unity in prod.billing:

https://<your-workspace-hostname>/api/2.0/mcp/vector-search/prod/customer_support
https://<your-workspace-hostname>/api/2.0/mcp/vector-search/prod/billing
https://<your-workspace-hostname>/api/2.0/mcp/functions/prod/billing

Configurare l'autenticazione con i bundle di asset di Databricks

È possibile configurare tutte le impostazioni di autenticazione a livello di codice usando i bundle di asset di Databricks anziché l'interfaccia utente di Databricks Apps. Questa pagina mostra la configurazione basata sull'interfaccia utente per illustrare le risorse e le autorizzazioni necessarie, ma è possibile definire la stessa configurazione nei file YAML del bundle. Per informazioni di riferimento sulla configurazione completa del bundle, vedere App nei bundle .

Passaggi successivi

Valutazione

Questa pagina ti è stata utile?

Last updated on 2026-02-14