Collega Databricks Genie a Microsoft Agent 365

Usa questa guida per collegare uno spazio di lavoro Databricks a Microsoft Agent 365. Dopo la connessione, Agent 365 sincronizza gli agenti Genie dello spazio di lavoro nel registro degli agenti Microsoft 365 e raccoglie la loro attività di conversazione per osservabilità.

Note

Databricks ha rinominato gli spazi Genie in agenti Genie. Alcune API e documentazione Databricks utilizzano ancora il termine spazio Genie.

Funzionamento della connessione

L'Agente 365 accede allo spazio di lavoro come service principal Databricks utilizzando l'autenticazione OAuth machine-to-machine (M2M). La connessione utilizza questi valori:

Campo di connessione Valore di Databricks Dove trovarla
URL dello spazio di lavoro L'URL dello spazio di lavoro con solo lo schema e l'host Ottieni l'URL dello spazio di lavoro
Client ID L'ID dell'applicazione dell'entità servizio Creare un'entità servizio
Segreto del cliente Un segreto OAuth per l'entità servizio Genera un segreto OAuth

Con queste credenziali, Agent 365:

  • Elenca gli agenti Genie a cui il principal del servizio può accedere e ne legge i dati.
  • Legge le conversazioni e i messaggi Genie di ogni agente sincronizzato quando viene selezionato Raccogliere dati di osservabilità dell'agente , e mostra l'attività nella scheda Attività dell'agente.

L'Agent 365 non fa domande agli agenti Genie, non esegue query SQL né cambia agenti Genie. L'unica eccezione è quando un amministratore rimuove un agente sincronizzato in Agent 365 e l'entità servizio ha l'autorizzazione Can Manage per l'agente Genie. In tal caso, l'Agente 365 sposta l'agente Genie nel cestino di Databricks.

Prima di iniziare

  • Conferma che l'amministratore AI di Agent 365 possa creare connessioni nel interfaccia di amministrazione di Microsoft 365.
  • Identifica l'area di lavoro Databricks che contiene gli agenti Genie che vuoi sincronizzare. Ogni connessione include un workspace.
  • Chiedi a un amministratore di workspace Databricks di completare i passaggi Databricks in questo articolo. Gli amministratori dello spazio di lavoro possono creare service principal, generare segreti OAuth e condividere agenti Genie.
  • Conferma che Genie funzioni nello spazio di lavoro.

Ottieni l'URL dello spazio di lavoro

  1. Accedi all'area di lavoro Databricks.

  2. Copiare l'URL dalla barra degli indirizzi del browser.

  3. Tieni solo lo schema e l'host. Rimuovere qualsiasi percorso o stringa di query, come /genie o ?o=1234567890123456.

    Screenshot di un workspace Databricks aperto in un browser, con l'URL dello workspace nella barra degli indirizzi.

Il formato dell'URL dello spazio di lavoro dipende dal cloud che ospita lo spazio di lavoro:

Cloud Esempio di URL dello spazio di lavoro
AWS https://dbc-a1b2c3d4-e5f6.cloud.databricks.com
Azure https://adb-1234567890123456.7.azuredatabricks.net
Google Cloud https://1234567890123456.7.gcp.databricks.com

Gli amministratori degli account possono anche trovare l'URL dello spazio di lavoro nella console account Databricks sotto Workspaces.

Creare un principale servizio

Crea un'entità servizio dedicata per Agente 365 così da poter controllarne e revocarne l'accesso indipendentemente dalle altre integrazioni.

  1. Nell'area di lavoro Databricks, seleziona il tuo username nella barra in alto, poi seleziona Impostazioni.

  2. Selezionare Identità e accesso. Accanto a Entità servizio, seleziona Gestisci.

  3. Selezionare Aggiungi service principal.

    Screenshot della pagina delle entità servizio nelle impostazioni dell'area di lavoro di Databricks, con il pulsante Aggiungi entità servizio.

  4. Crea un nuovo service principal con un nome descrittivo, come agent365-connector. In Azure Databricks, seleziona Aggiungi nuovo e poi Gestito da Databricks.

  5. Attiva i diritti di accesso a Databricks SQL e di accesso all'area di lavoro. Agent 365 non ha bisogno dell'accesso Consumer. Attiva l'accesso Admin solo se scegli di rendere il service principal amministratore dello spazio di lavoro.

    Puoi impostare le autorizzazioni quando aggiungi il service principal, o successivamente nella scheda Configurazioni del service principal.

  6. Apri il service principal e copia il suo ID applicazione. Usa questo valore come ID client per la connessione.

    Screenshot della pagina dei dettagli del service principal in Databricks, che mostra l'ID dell'applicazione nella scheda Configurazioni.

Per altre informazioni, vedere Gestisci i principi del servizio.

Genera un segreto OAuth

  1. Nella pagina dei dettagli dell'entità servizio, seleziona la scheda Segreti e quindi seleziona Genera segreto.

    Screenshot della scheda Segreti di un'entità servizio Databricks, con il pulsante Genera segreto.

  2. Nel campo Lifetime (giorni), inserisci quanto tempo il segreto è valido. Il massimo è di 730 giorni.

  3. In Scope, seleziona Other APIs, seleziona Add scope e poi seleziona all-apis.

    Screenshot della finestra di dialogo Genera segreto OAuth in Databricks, con una durata in giorni e l'opzione all-apis nell'elenco Aggiungi ambito.

  4. Seleziona Genera.

  5. Copia il segreto e l'ID client, poi seleziona Fine.

Importante

Databricks mostra il segreto solo una volta. Conservalo in un luogo sicuro e non condividerlo via email, chat o richieste di supporto. Se perdi il segreto, generane uno nuovo. L'ID client è lo stesso dell'ID applicazione dell'entità servizio.

Il dialogo segna all-apis come non raccomandato. I diritti dell'entità servizio e i permessi dell'agente Genie limitano ancora ciò che l'Agente 365 può leggere. Annota la data di scadenza del segreto così da poterlo rinnovare prima che scada.

Dare al service principal accesso agli agenti Genie

Agent 365 sincronizza e monitora solo gli agenti Genie a cui l'entità servizio può accedere. Selezionare una delle seguenti opzioni.

Condividi gli agenti Genie con il service principal

Questa opzione è consigliata perché concede accesso solo agli agenti Genie che scegli.

  1. Nel workspace Databricks, seleziona Genie Agents nella barra laterale e poi apri un Genie agent.
  2. Seleziona Condividi.
  3. Inserisci il nome dell'entità servizio, seleziona Aggiungi e poi imposta il livello di autorizzazione. Per raccogliere attività, seleziona Può gestire tutto.
  4. Ripeti questi passaggi per ogni agente Genie che vuoi sincronizzare.

Il livello di autorizzazione determina cosa può fare l'Agente 365:

Autorizzazione Cosa può fare Agent 365
Può visualizzare Sincronizza il nome, la descrizione e il cloud e la regione dello spazio di lavoro dell'agente.
Modifica consentita Leggi anche le istruzioni e le fonti dati dell'agente, che appaiono come le sue istruzioni e le fonti di conoscenza.
Può gestire Leggi anche i dettagli di condivisione dell'agente, raccogli le attività di conversazione di tutti gli utenti dell'agente e sposta l'agente nel cestino quando un amministratore lo rimuove in Agent 365.

L'attività richiede Gestione. Databricks restituisce le conversazioni di tutti gli utenti di un agente Genie solo alle entità che hanno l'autorizzazione Can Manage. Con un permesso inferiore, l'agente si sincronizza, ma non appare alcuna attività.

Tip

Gli agenti Genie ereditano i permessi dalla loro cartella workspace. Per condividere diversi agenti Genie contemporaneamente, tienili in una cartella e condividila con il service principal.

Dopo aver condiviso un agente Genie, può volerci un minuto o due prima che l'entità servizio possa elencarlo.

Rendi il service principal un amministratore dello spazio di lavoro

Per coprire ogni agente Genie nello spazio di lavoro, inclusi quelli creati successivamente, attiva l'accesso Admin per il service principal invece di condividere gli agenti Genie individualmente.

Caution

Gli amministratori dello spazio di lavoro hanno il pieno controllo amministrativo dello spazio di lavoro, inclusa l'autorizzazione Può gestire per ogni agente Genie. Usa questa opzione solo se la politica di sicurezza della tua organizzazione lo consente.

  1. Nella pagina dei dettagli dell'entità servizio, seleziona la scheda Configurazioni.
  2. Seleziona Accesso amministratore, poi seleziona Aggiorna. Databricks aggiunge il service principal al gruppo workspace admins.
  3. Per confermare, vai su Impostazioni>Identità e accesso. Accanto a Gruppi, seleziona Gestisci. Apri il gruppo amministratori e controlla che il service principal sia indicato nella scheda Membri

Le modifiche ai permessi possono richiedere alcuni minuti per essere applicate.

Creare la connessione

  1. Apri l'interfaccia di amministrazione di Microsoft 365.

  2. Seleziona Agenti>:tutti gli agenti.

  3. Nelle piattaforme connesse, seleziona Gestisci.

  4. Selezionare + Connetti una piattaforma.

  5. Inserisci un nome e una descrizione per la connessione.

  6. Nella piattaforma esterna, seleziona Databricks Genie. Il metodo di autenticazione è OAuth (Service principal).

  7. Inserisci l'URL dello spazio di lavoro, l'ID del client e Client secret.

  8. Assicurarsi che Raccogli i dati di osservabilità dell'agente sia selezionato.

  9. Selezionare Verifica autenticazione.

  10. Quando viene visualizzato "Connessione verificata correttamente", seleziona Salva.

    Screenshot delle impostazioni di connessione Databricks Genie nel interfaccia di amministrazione di Microsoft 365, con l'URL dello spazio di lavoro, l'ID client e il client secret inseriti, un messaggio Connessione verificata con successo e l'opzione Raccolta dati di osservabilità dell'agente selezionata.

La verifica conferma che l'Agente 365 può accedere allo spazio di lavoro e elencare gli agenti Genie. Riesce anche se il service principal non può ancora accedere ad alcun agente Genie.

Sincronizza gli agenti

Quando salvi la connessione, il pannello dettagli si apre e inizia la prima sincronizzazione. Quando la sincronizzazione termina, il pannello mostra **Sync

Screenshot di una connessione Genie Databricks nell'interfaccia di amministrazione di Microsoft 365, che mostra Sync completata e l'elenco degli agenti Genie sincronizzati.

Agent 365 sincronizza ogni agente Genie a cui l'entità servizio può accedere. Gli agenti sincronizzati compaiono nel registro degli agenti Microsoft 365. Per trovarli, vai su Agenti>Tutti gli agenti e filtra Piattaforma per Databricks Genie. Appaiono anche in un cluster Databricks Genie sulla mappa Agent.

Per sincronizzarli dopo aver creato o condiviso altri agenti Genie, apri la connessione e seleziona Sincronizza agenti.

Verifica l'attività

  1. In Databricks, apri un agente Genie sincronizzato e ponigli qualche domanda. Salta questo passaggio se l'agente ha già conversazioni recenti.

  2. Nell'interfaccia di amministrazione di Microsoft 365, apri l'agente dall'elenco Agenti sincronizzati della connessione o da Agents>All agents.

  3. Seleziona la scheda Attività . Quando l'attività viene raccolta, Sessioni ne mostra una o più.

    Screenshot della scheda Attività di un agente Databricks Genie sincronizzato nel interfaccia di amministrazione di Microsoft 365, che mostra sessioni, eccezioni, tempo di esecuzione dell'agente e un grafico delle sessioni nel tempo.

L'attività può richiedere un po' di tempo per manifestarsi dopo una conversazione. Databricks non fornisce le identità utente Microsoft Entra, quindi gli utenti attivi mostrano N/A. Per definizioni di metriche, vedi Osservabilità di agente di terze parti (Frontier).

Ruota o revoca l'accesso

Per ruotare il segreto del cliente:

  1. In Databricks, generare un nuovo segreto OAuth per il service principal. Un service principal può avere fino a cinque credenziali, quindi puoi creare la nuova credenziale prima di eliminare quella vecchia.
  2. Nel interfaccia di amministrazione di Microsoft 365, apri la connessione e seleziona Modifica. Inserisci il nuovo client secret, seleziona Verifica autenticazione e poi salva la connessione.
  3. In Databricks, elimina il vecchio segreto dalla scheda Segreti dell'entità servizio.

Per revocare l'accesso:

  • Per bloccare l'accesso a uno specifico agente Genie, rimuovi il service principal dalle impostazioni di condivisione dell'agente Genie.
  • Per bloccare ogni accesso, elimina i segreti OAuth del service principal o rimuovi il service principal dallo spazio di lavoro.

Troubleshoot

Sintomo Causa possibile Resolution
Autenticazione non riuscita L'ID client o il segreto è errato o include spazi extra, il segreto è scaduto o cancellato, oppure l'URL dello spazio di lavoro appartiene a un altro spazio di lavoro Copia di nuovo i valori, genera un nuovo segreto se necessario e inserisci l'URL dello spazio di lavoro solo con lo schema e l'host.
La verifica ha successo, ma nessun agente o solo alcuni agenti si sincronizzano L'entità servizio non può accedere agli agenti Genie, o gli agenti sono stati condivisi pochi istanti fa Condividi gli agenti Genie con l'entità servizio o rendila un amministratore dello spazio di lavoro. Aspetta un minuto o due, poi seleziona Sincronizza agenti.
Gli agenti non mostrano istruzioni o fonti di conoscenza L'entità servizio ha solo l'autorizzazione Can View Concedi Can Edit o Can Manage sull'agente Genie, quindi sincronizza di nuovo.
Gli agenti si sincronizzano, ma Attività non mostra alcuna sessione Raccogliere i dati di osservabilità dell'agente è deselezionato, l'entità servizio non ha Can Manage, nessuno ha usato l'agente o l'elaborazione è ancora in corso Seleziona Raccogli dati di osservabilità dell'agente sulla connessione, concedi Can Manage, interagisci con l'agente e controlla di nuovo in seguito.
Gli agenti Genie non sono disponibili in Databricks Le funzionalità di IA basate sui partner sono disattivate per l'account o lo spazio di lavoro Chiedi a un account admin Databricks di attivare le funzionalità di IA basate sui partner.
Il client secret è andato perduto Databricks mostra un segreto solo una volta Genera un nuovo segreto e aggiorna la connessione.

Verifica le credenziali al di fuori di Agent 365

Se la verifica continua a fallire, un amministratore di Databricks può testare direttamente le credenziali. Imposta le variabili di ambiente DATABRICKS_CLIENT_ID e DATABRICKS_CLIENT_SECRET, quindi richiedi un token di accesso dal workspace. Sostituisci <workspace-host> con l'host dell'URL dello spazio di lavoro.

curl --request POST "https://<workspace-host>/oidc/v1/token" \
  --user "$DATABRICKS_CLIENT_ID:$DATABRICKS_CLIENT_SECRET" \
  --data "grant_type=client_credentials&scope=all-apis"

Una risposta di successo è un oggetto JSON che contiene un valore access_token e un token_type di Bearer. Per verificare a quali agenti Genie il service principal può accedere, imposta la variabile di ambiente DATABRICKS_TOKEN sul valore access_token e poi elenca gli agenti Genie:

curl --request GET "https://<workspace-host>/api/2.0/genie/spaces" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN"

Non salvare né condividere il token di accesso.

Per problemi di connessione che non sono specifici di Databricks Genie, vedi Risoluzione dei problemi delle piattaforme connesse.

  • Ultimo aggiornamento: