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.

Configurare l'autenticazione con l'interfaccia utente dell'area di lavoro o con i pacchetti di automazione dichiarativa

È possibile configurare tutte le impostazioni di autenticazione in due modi:

  • Interfaccia utente dell'area di lavoro: modificare l'app e gestire risorse e ambiti dal passaggio Configura . Consigliato quando si itera su una singola app nell'area di lavoro.
  • Bundle di automazione dichiarativa: dichiarare risorse, ambiti e variabili di ambiente in un databricks.yml file e distribuirne con databricks bundle deploy. Consigliato quando si desidera il versionamento basato su Git, CI/CD, o distribuire lo stesso agente tra diversi spazi di lavoro. Tutti i modelli di agente vengono forniti con un oggetto databricks.yml.

Entrambi i percorsi producono la stessa configurazione di runtime. La parte restante di questa pagina mostra ogni istruzione in entrambi i moduli in modo da poter selezionare una e rimanere coerente all'interno del progetto.

Per aggiungere una risorsa all'app tramite uno dei due percorsi, è necessario disporre Can Manage dell'autorizzazione sia per la risorsa che per l'app.

Per informazioni di riferimento sul bundle completo, vedere risorsa dell'app e app.resources. Per una guida dettagliata end-to-end, vedere Gestire le app Databricks usando Bundles di Automazione Dichiarativi.

Autorizzazione dell'app

Per impostazione predefinita, Le app Databricks eseguono l'autenticazione usando l'autorizzazione dell'app. Databricks crea automaticamente un'entità servizio quando si crea 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 l'autorizzazione all'entità servizio Can Edit per l'esperimento.

Interfaccia utente dell'area di lavoro

  1. Fare clic su Modifica nella home page dell'app.
  2. Passare al passaggio Configura .
  3. Nella sezione Risorse dell'app, aggiungere la risorsa esperimento MLflow con l'autorizzazione Can Edit.

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

Pacchetti di automazione dichiarativa

  1. Dichiarare l'esperimento nell'elenco dell'app resources in databricks.yml. L'oggetto name che assegni alla risorsa viene richiamato successivamente quando configuri le variabili di ambiente.

    resources:
  apps:
    my_agent:
      name: 'my-agent'
      source_code_path: ./
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'

  2. Ridistribuire il bundle:

    databricks bundle deploy
databricks bundle run my_agent

Per tutti i campi, vedere app.resources.experiment .

Concedere autorizzazioni ad altre risorse di Databricks

Se il tuo agente utilizza altre risorse di Databricks, come gli spazi Genie, gli indici di Ricerca Vettoriale o i magazzini di SQL, concedi le autorizzazioni dell'entità servizio su ciascuna di esse.

Per accedere al registro dei prompt, concedere le autorizzazioni CREATE FUNCTION, EXECUTE e MANAGE sullo schema di Unity Catalog per l'archiviazione dei prompt.

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.

Interfaccia utente dell'area di lavoro

Aggiungere risorse all'app tramite la sezione Risorse dell'app quando si crea o si modifica l'app nell'area di lavoro Databricks.

  1. Fare clic su Modifica nella home page dell'app.
  2. Passare al passaggio Configura .
  3. In Risorse dell'app fare clic su + Aggiungi risorsa per ogni risorsa usata dall'agente e impostare l'autorizzazione.

Per l'elenco completo delle risorse e degli screenshot supportati, vedere Aggiungere risorse a un'app Databricks .

Pacchetti di automazione dichiarativa

  1. Dichiara ogni risorsa usata dall'agente nell'elenco sotto l'app resources in databricks.yml. L'esempio seguente illustra un agente che usa un esperimento MLflow, un endpoint di gestione, uno spazio Genie, un magazzino SQL, un indice di ricerca vettoriale, una funzione del catalogo Unity e un'istanza di Lakebase. A ogni risorsa name viene fatto riferimento da config.env in value_from modo che l'agente riceva l'identificatore risolto in fase di esecuzione.

    bundle:
  name: my_agent

resources:
  apps:
    my_agent:
      name: 'my-agent'
      description: 'Custom agent deployed on Databricks Apps'
      source_code_path: ./
      config:
        command: ['uv', 'run', 'start-app']
        env:
          - name: MLFLOW_EXPERIMENT_ID
            value_from: 'experiment'
          - name: LAKEBASE_INSTANCE_NAME
            value_from: 'database'

      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'

        - name: 'llm'
          serving_endpoint:
            name: 'databricks-claude-sonnet-4-5'
            permission: 'CAN_QUERY'

        - name: 'sales-genie'
          genie_space:
            space_id: '<genie-space-id>'
            permission: 'CAN_RUN'

        - name: 'warehouse'
          sql_warehouse:
            id: '<warehouse-id>'
            permission: 'CAN_USE'

        - name: 'docs-index'
          uc_securable:
            securable_full_name: 'main.docs.chunks_index'
            securable_type: 'TABLE'
            permission: 'SELECT'

        - name: 'lookup-function'
          uc_securable:
            securable_full_name: 'main.tools.order_lookup'
            securable_type: 'FUNCTION'
            permission: 'EXECUTE'

        - name: 'database'
          database:
            instance_name: '<lakebase-instance-name>'
            database_name: 'databricks_postgres'
            permission: 'CAN_CONNECT_AND_CREATE'

targets:
  dev:
    mode: development
    default: true

    Importante

    Ogni value_from valore in config.env deve corrispondere a un name campo nell'elenco resources . Le mancate corrispondenze fanno sì che la variabile di ambiente si risolva in None nell'app distribuita.

  2. Distribuire e avviare il bundle:

    databricks bundle validate
databricks bundle deploy
databricks bundle run my_agent

    bundle deploy carica il sorgente e configura le risorse. bundle run avvia o riavvia l'app con l'origine più recente. L'argomento di bundle run è la chiave YAML in resources.apps (qui my_agent), non il campo dell'app name implementata.

Per lo schema completo di ogni sottotipo di risorsa, vedere app.resources.

La tabella seguente elenca le autorizzazioni minime usate negli esempi precedenti e il valore dei bundle di automazione dichiarativa equivalente per ogni tipo di risorsa:

Tipo di risorsa Autorizzazione dell'interfaccia utente dell'area di lavoro Risorse e permessi dei Bundle di automazione dichiarativi
SQL Warehouse Can Use sql_warehouse con CAN_USE
Endpoint di gestione del modello Can Query serving_endpoint con CAN_QUERY
Funzione di Unity Catalog Can Execute uc_securable con securable_type: FUNCTION e EXECUTE
Spazio Genie Can Run genie_space con CAN_RUN
Indice di ricerca vettoriale Can Select uc_securable con securable_type: TABLE e SELECT
Tabella del catalogo Unity SELECT uc_securable con securable_type: TABLE e SELECT
Connessione al catalogo Unity Use Connection uc_securable con securable_type: CONNECTION e USE_CONNECTION
Volume del catalogo Unity Can Read o Can Read and Write uc_securable con securable_type: VOLUME e READ_VOLUME o WRITE_VOLUME
Lakebase (approvvigionato) Can Connect and Create database con CAN_CONNECT_AND_CREATE
Lakebase (scalabilità automatica) Can Connect and Create postgres con CAN_CONNECT_AND_CREATE

Seguire il principio dei privilegi minimi. Concedere al principal del servizio solo le autorizzazioni necessarie all'agente e utilizzare un principal del servizio dedicato per ogni applicazione. Per l'elenco completo, vedere Procedure consigliate per la sicurezza.

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:

  1. 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.
  2. Le credenziali utente sono ridotte di ambito: Databricks prende le credenziali dell'utente e le limita solo agli ambiti API da te definiti.
  3. Inoltro di token: il token con ambito inferiore viene reso disponibile per l'app tramite l'intestazione x-forwarded-access-token HTTP.
  4. 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. Per l'elenco degli ambiti disponibili e della semantica dell'ambito, vedere Escalation dei privilegi e della sicurezza basata sull'ambito.

Interfaccia utente dell'area di lavoro

  1. Nell'interfaccia utente di Databricks passare alle impostazioni di autorizzazione dell'app.
  2. In Autorizzazione utente fare clic su + Aggiungi ambito e selezionare gli ambiti necessari all'app per accedere alle risorse per conto dell'utente.
  3. Salvare le modifiche e riavviare l'app.

Pacchetti di automazione dichiarativa

  1. Dichiara ambiti sotto user_api_scopes nella risorsa dell'app in databricks.yml:

    resources:
  apps:
    my_agent:
      name: 'my-agent'
      source_code_path: ./
      user_api_scopes:
        - sql
        - dashboards.genie
        - serving.serving-endpoints
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'

  2. Ridistribuire il bundle e riavviare l'app:

    databricks bundle deploy
databricks bundle run my_agent

    Note

    Dopo aver abilitato l'autorizzazione utente in un'area di lavoro per la prima volta, è necessario riavviare le app esistenti prima di poter usare gli ambiti. Vedere Aggiungere ambiti a un'app.

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.

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

  2. 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. Richiedere solo gli ambiti minimi necessari all'agente e registrare ogni azione eseguita per conto di un utente; vedere Procedure consigliate per l'autorizzazione utente.

Eseguire l'autenticazione nei server MCP di Databricks

I server MCP gestiti di Databricks espongono gli indici di Ricerca vettoriale e le funzioni di Unity Catalog come strumenti tramite URL del modulo https://<workspace>/api/2.0/mcp/vector-search/<catalog>/<schema> e https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema>. Per l'elenco dei server disponibili e dei relativi modelli di URL, vedere Usare i server MCP gestiti di Databricks.

Per eseguire l'autenticazione, concedere all'entità servizio dell'agente (o all'utente, se si utilizza l'autorizzazione dell'utente) l'accesso a tutte le risorse downstream presenti in quegli schemi.

Ad esempio, se l'agente usa gli URL del server MCP seguenti:

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

È necessario concedere l'accesso a ogni indice di ricerca vettoriale in prod.customer_support e prod.billinge a ogni funzione del catalogo Unity in prod.billing.

Interfaccia utente dell'area di lavoro

Aggiungere ogni indice e funzione come risorsa in Risorse dell'app. Seguire la stessa procedura descritta in Concedere le autorizzazioni ad altre risorse di Databricks.

Pacchetti di automazione dichiarativa

  1. Aggiungere una uc_securable voce per indice e per funzione nell'elenco dell'app resources :

    resources:
  apps:
    my_agent:
      resources:
        - name: 'support-index'
          uc_securable:
            securable_full_name: 'prod.customer_support.tickets_index'
            securable_type: 'TABLE'
            permission: 'SELECT'

        - name: 'billing-index'
          uc_securable:
            securable_full_name: 'prod.billing.invoices_index'
            securable_type: 'TABLE'
            permission: 'SELECT'

        - name: 'refund-function'
          uc_securable:
            securable_full_name: 'prod.billing.process_refund'
            securable_type: 'FUNCTION'
            permission: 'EXECUTE'

  2. Ridistribuire il bundle:

    databricks bundle deploy
databricks bundle run my_agent

I server MCP personalizzati ospitati come app Databricks (i nomi delle app preceduti da mcp-) non sono ancora supportati come risorse bundle. Concedere manualmente il principale del servizio dell'agente nell'app MCP server con databricks apps update-permissions. Vedere la competenza custom-mcp-server nel repository dei modelli di agente.

Passaggi successivi

  • Last updated on