Usare l'agente supervisore per creare un sistema multi-agente coordinato

Questa pagina descrive come usare l'agente supervisore per creare un sistema di supervisione multi-agente che orchestra gli agenti e gli strumenti di intelligenza artificiale per lavorare insieme su attività complesse. È possibile migliorare il coordinamento in base al feedback del linguaggio naturale degli esperti in materia.

Che cos'è l'agente supervisore?

Utilizzare l'agente supervisore per creare un sistema supervisore che coordina Genie Spaces, endpoint agente, funzioni di Unity Catalog, server MCP e agenti personalizzati che collaborano al completamento di attività complesse in diversi settori specializzati. L'agente supervisore usa modelli avanzati di orchestrazione di intelligenza artificiale per gestire le interazioni degli agenti, la delega delle attività e la sintesi dei risultati per offrire soluzioni complete.

L'agente supervisore crea automaticamente il sistema e consente di migliorarlo nel tempo con il feedback umano. È ideale per supportare i casi d'uso seguenti:

• Fornire analisi e informazioni dettagliate sul mercato eseguendo ricerche in report di ricerca e dati sull'utilizzo.
• Rispondi alle domande sui processi interni e automatizza la gestione del backlog dei ticket.
• Velocizza il servizio clienti rispondendo a domande su politiche, FAQ, account e altri quesiti.

L'agente supervisore consente di migliorare la qualità del coordinamento del supervisore e di regolare il comportamento dell'agente in base al feedback del linguaggio naturale degli esperti in materia. Fornire esempi e linee guida per ottimizzare le prestazioni del sistema.

Supervisor Agent crea un endpoint completo che è possibile usare downstream per le applicazioni. Ad esempio, è possibile interagire con l'endpoint inviando richieste in Playground o compilare un'applicazione di chat usando Databricks Apps. Il supervisore dispone di controlli di accesso predefiniti, in modo che gli utenti finali accevano solo ai subagenti e ai dati a cui hanno accesso.

L'agente supervisore usa l'archiviazione predefinita per archiviare trasformazioni dei dati temporanee, checkpoint del modello e metadati interni che alimentano ogni agente. In caso di eliminazione dell'agente, tutti i dati associati all'agente vengono rimossi dalla risorsa di archiviazione predefinita.

Requirements

• Un'area di lavoro che include quanto segue:
  • Calcolo serverless disponibile (abilitato per impostazione predefinita nelle aree di lavoro con Catalogo Unity in un'area supportata).
  • Catalogo Unity abilitato. Vedere Abilitare un'area di lavoro per il Catalogo Unity.
  • Accesso al Servizio di modelli AI di Mosaic.
  • Accesso a un criterio di utilizzo serverless con un budget diverso da zero.
  • Monitoraggio della produzione per MLflow (Beta) abilitato. Questo è necessario per il funzionamento del tracciamento. Se non è necessario il tracciamento, non è necessario attivare questa anteprima. Consultare Gestisci anteprime Azure Databricks.
• Un'area di lavoro in una delle aree supportate.
• L'endpoint del databricks-gte-large-en modello di incorporamento deve avere guardrail di intelligenza artificiale e limiti di frequenza disabilitati. Consultare Configurare Unity AI Gateway negli endpoint di servizio dei modelli.
• È necessario disporre di agenti o strumenti pronti per l'uso. È necessario specificare almeno uno dei seguenti elementi:
  • Un endpoint esistente dell'agente Knowledge Assistant(/generative-ai/agent-bricks/knowledge-assistant.md).
  • Un Genie Space esistente. Per configurare uno spazio Genie, vedere Configurare e gestire uno spazio Genie.
  • Strumenti di intelligenza artificiale creati come funzioni del Catalogo Unity. Vedere Creare strumenti dell'agente di intelligenza artificiale usando le funzioni del catalogo di Unity.
  • Server MCP esterni con connessioni del catalogo di Unity configurate. È possibile installare un server MCP da Databricks Marketplace o Usare server MCP esterni. La connessione deve usare l'autenticazione con token di accesso, l'autenticazione OAuth da macchina a macchina, oppure l'autenticazione OAuth da utente a macchina. Vedere Metodi di autenticazione per i servizi esterni.
  • Server MCP personalizzati o agenti personalizzati ospitati in Databricks Apps.
• Gli utenti finali dell'agente supervisore devono avere accesso esplicito per interagire con ogni subagente:
  • Per un endpoint agente, gli utenti finali richiedono l'autorizzazione CAN QUERY .
  • Per uno spazio Genie, gli utenti finali richiedono l'accesso sia allo spazio Genie sia ai dati relativi agli oggetti sottostanti del Unity Catalog. Vedi Condividere uno spazio Genie.
  • Per le funzioni del catalogo Unity, gli utenti finali richiedono l'autorizzazione EXECUTE per la funzione.
  • Per i server MCP esterni, gli utenti finali richiedono l'autorizzazione USE CONNECTION per la connessione al catalogo Unity.
  • Per i server MCP personalizzati o gli agenti personalizzati ospitati in Databricks Apps, gli utenti finali richiedono l'autorizzazione sull'applicazione CAN_USE Databricks.
• (Facoltativo) Monitoraggio della produzione per MLflow (Beta) abilitato. Questo è necessario per il funzionamento del tracciamento. Consultare Gestisci anteprime Azure Databricks.

Creare un sistema di supervisione multi-agente

Vai all'icona nel riquadro di navigazione a sinistra della tua area di lavoro. Fare clic su Crea agente e selezionare Supervisor Agent(Agente supervisore).

Passaggio 1: Creare subagenti e concedere autorizzazioni

Poiché l'agente supervisore crea un sistema supervisore che coordina i subagenti per lavorare insieme per completare attività complesse, è prima necessario fornire subagenti per coordinarlo. Questi subagenti possono essere Genie Spaces, endpoint dell'agente Knowledge Assistant, funzioni del Catalogo Unity, server MCP o agenti personalizzati. È anche necessario concedere agli utenti finali l'accesso esplicito a ogni subagent per consentire al supervisore di restituire risposte utili da tale subagente.

Spazio Genie

1. Per creare uno spazio Genie, seguire i passaggi descritti in Configurare e gestire uno spazio Genie.
2. Concedere agli utenti finali l'accesso sia a Genie Space che ai relativi oggetti Catalogo Unity sottostanti. Seguire i passaggi descritti in Condividere uno spazio Genie.

Endpoint agente

1. Per creare un agente di Knowledge Assistant, seguire la procedura descritta in Usare Knowledge Assistant per creare un chatbot di alta qualità sui documenti.
2. Concedere agli utenti finali l'autorizzazione CAN QUERY per l'endpoint dell'agente di Knowledge Assistant.

Funzione del catalogo Unity

1. Per creare funzioni del catalogo Unity come strumenti dell'agente di intelligenza artificiale, seguire la procedura descritta in Creare gli strumenti dell'agente di intelligenza artificiale usando le funzioni del catalogo unity.
2. Concedere agli utenti finali l'autorizzazione EXECUTE per la funzione Catalogo Unity.

MCP esterno

1. Per installare un server MCP da Databricks Marketplace, vedere Ottenere l'accesso ai server MCP esterni. Per configurare server MCP esterni, seguire la procedura descritta in Usare server MCP esterni. La connessione deve usare l'autenticazione con token di accesso, l'autenticazione OAuth da macchina a macchina, oppure l'autenticazione OAuth da utente a macchina. Vedere Metodi di autenticazione per i servizi esterni.
2. Concedere agli utenti finali l'autorizzazione USE CONNECTION per la connessione al catalogo Unity.

MCP personalizzato

1. Per creare un server MCP personalizzato ospitato in un'app Databricks, seguire la procedura descritta in Ospitare server MCP personalizzati usando le app Databricks.
2. Concedere agli utenti finali l'autorizzazione CAN_USE per l'app Databricks. Vedere Autenticazione per gli agenti di intelligenza artificiale.

Agente personalizzato

1. Per creare un agente personalizzato ospitato in un'app Databricks, seguire i passaggi descritti in Creare un agente di intelligenza artificiale e distribuirlo in Databricks Apps.
2. Concedere agli utenti finali l'autorizzazione CAN_USE per l'app Databricks. Vedere Autenticazione per gli agenti di intelligenza artificiale.

Passaggio 2: Configurare il supervisore

Configura il supervisore e aggiungi gli agenti che coordinerà.

1. Nel campo Nome immettere un nome per l'agente supervisore.

2. Nel campo Descrizione descrivere le operazioni che il sistema di supervisione può eseguire.

3. In Configura agenti selezionare fino a 20 agenti e/o strumenti.

   Spazio Genie

   Per fornire uno spazio Genie:

   1. Nel campo Tipo, selezionare Genie Space.

   2. Selezionare il Genie Space dal menu a discesa Genie Space.

   3. Il nome dell'agente e i campi di contenuto vengono popolati automaticamente quando possibile. È possibile modificare il nome e la descrizione, se necessario.

      Il supervisore usa le informazioni nella descrizione per coordinare gli agenti. Fornire il maggior numero di dettagli possibile per migliorare la delega delle attività.

   Per ulteriori informazioni su Genie Spaces, vedere Cos'è uno Spazio Genie. Per configurare uno spazio Genie, vedere Configurare e gestire uno spazio genie

   Endpoint agente

   Per fornire un endpoint agente:

   1. Nel campo Tipo selezionare Endpoint agente.
   2. Selezionare l'endpoint dal menu a tendina Endpoint agente. Sono supportati solo gli endpoint agente creati tramite Knowledge Assistant .
   3. Il campo Nome agente viene popolato automaticamente. Se lo si desidera, è possibile modificarlo.
   4. In Descrivere il contenuto descrivere le operazioni che l'agente può eseguire per aiutare il supervisore a comprendere quando delegare le attività a questo agente.

   Funzione del catalogo Unity

   Per fornire una funzione del catalogo Unity:

   1. Nel campo Tipo selezionare Funzione catalogo Unity.
   2. Selezionare la funzione dal menu a discesa Funzione Catalogo Unity.
   3. Nel campo Nome agente specificare un nome per questo strumento.
   4. In Descrivere il contenuto descrivere le operazioni che questa funzione esegue e quando deve essere usata. Ciò consente al supervisore di comprendere quando usare questo strumento.

   Per altre informazioni sulla creazione di funzioni del catalogo Unity come strumenti agente, vedere Creare strumenti dell'agente di intelligenza artificiale usando le funzioni del catalogo Unity.

   MCP esterno

   Per fornire un server MCP esterno:

   1. Nel campo Tipo selezionare Server MCP esterno.
   2. Selezionare dal menu a discesa la connessione Connessione catalogo Unity.
   3. Nel campo Nome agente specificare un nome per il server MCP.
   4. In Descrivere il contenuto descrivere cosa fornisce il server MCP e quando deve essere usato. Ciò consente al supervisore di comprendere quando delegare a questo server.

   Per altre informazioni sui server MCP esterni, vedere Usare server MCP esterni.

   MCP personalizzato

   Per fornire un server MCP personalizzato ospitato in un'app Databricks:

   1. Nel campo Tipo selezionare Databricks App.
   2. Selezionare il server MCP personalizzato dal menu a discesa App Databricks .
   3. Nel campo Nome agente modificare il nome popolato automaticamente, se necessario.
   4. In Descrivere il contenuto modificare la descrizione popolata automaticamente, se necessario. Il supervisore usa le informazioni nella descrizione per coordinare gli agenti. Fornire il maggior numero di dettagli possibile per migliorare la delega delle attività.

   Per altre informazioni sulle app di Databricks, vedere App di Databricks.

   Agente personalizzato

   Per fornire un agente personalizzato ospitato in un'app Databricks:

   1. Nel campo Tipo selezionare Databricks App.
   2. Selezionare l'agente personalizzato dal menu a discesa App Databricks .
   3. Nel campo Nome agente modificare il nome popolato automaticamente, se necessario.
   4. In Descrivere il contenuto modificare la descrizione popolata automaticamente, se necessario. Il supervisore usa le informazioni nella descrizione per coordinare gli agenti. Fornire il maggior numero di dettagli possibile per migliorare la delega delle attività.

   Per altre informazioni sulle app di Databricks, vedere App di Databricks.

4. (Facoltativo) Per aggiungere altri agenti, fare clic su + Aggiungi. È possibile fornire fino a 20 agenti.

5. (Facoltativo) Nel campo Istruzioni specificare le linee guida per la risposta del supervisore.

6. Fare clic su Crea agente.

Si verrà reindirizzati alla scheda Configura . La creazione del sistema multi-agente e dell'agente supervisore può richiedere alcuni minuti.

Passaggio 3: Testare l'agente supervisore

Dopo che il tuo supervisore ha terminato la costruzione, testarlo per verificare in che modo il supervisore coordina più agenti per gestire attività complesse. In Testare l'agente, nel riquadro laterale destro, chattare con l'agente per valutare le risposte.

1. (Facoltativo) È anche possibile testare l'agente in AI Playground. Clicca su Apri in Playground. Questo apre AI Playground con l'endpoint di supervisione connesso. Se hai abilitate le funzionalità assistive di intelligenza artificiale, puoi attivare AI Judge e Generazione sintetica di compiti per aiutarti a valutare il tuo supervisore.
2. Nel Testa il tuo agente o in AI Playground, inserire un compito complesso per il supervisore.
3. Valutarne la risposta. Assicurarsi che il supervisore delega correttamente le attività agli agenti corretti.
4. In base alle risposte dell'agente, modificare i campi Descrizione e Istruzioni nel pannello a sinistra per migliorarne la configurazione.
5. Fare clic su Aggiorna agente.

Se si è soddisfatti delle prestazioni del supervisore, continuare a usare il supervisore così com'è.

Passaggio 4: Migliorare il supervisore

L'agente supervisore può modificare il comportamento del supervisore in base al feedback del linguaggio naturale. Raccogliere commenti e suggerimenti dagli esperti tramite la pagina di configurazione per migliorare la qualità del coordinamento del supervisore. La raccolta di dati etichettati per il supervisore può migliorare le prestazioni. L'agente supervisore riaddestrerà e ottimizzerà il supervisore utilizzando i nuovi dati.

Nella scheda Esempi aggiungere domande e scenari di attività per il supervisore.

1. Aggiungere domande all'etichetta:

   1. Fare clic su + Aggiungi per aggiungere una domanda.
   2. Nella finestra modale Aggiungi una domanda, inserisci la tua domanda.
   3. Fare clic su Aggiungi. La domanda dovrebbe essere visualizzata nell'interfaccia utente.
   4. Ripetere fino a quando non sono state aggiunte tutte le domande da valutare.
   5. Per eliminare una domanda, fare clic sul menu kebab e quindi su Elimina.

2. Dopo aver aggiunto le domande, è possibile condividere l'agente con altri utenti per esaminare per creare un set di dati con etichetta di alta qualità. Condividere un collegamento alla pagina di configurazione dell'agente supervisore per raccogliere feedback dagli esperti.

3. Assicurarsi che gli esperti abbiano accesso all'agente supervisore e ai subagenti appropriati:

   1. Nell'angolo in alto a destra, fare clic sull'icona del menu Kebab . Concedere agli esperti CAN_MANAGE autorizzazioni in modo da poter accedere all'agente e fornire feedback.
   2. Assicurarsi che lo SME abbia accesso ai subagenti appropriati:
      • Per ogni Spazio Genie, concedere all'SME tutte le autorizzazioni appropriate per interagire con lo spazio. Vedi Condividere uno spazio Genie.
      • Per ogni endpoint dell'agente, concedere allo SME l'autorizzazione CAN QUERY .
      • Per ogni funzione del catalogo Unity, concedere all'SME l'autorizzazione EXECUTE per la funzione.
      • Per ogni server MCP esterno, concedere all'SME l'autorizzazione USE CONNECTION per la connessione al catalogo Unity.
      • Per ogni server MCP personalizzato o agente personalizzato ospitato in Databricks Apps, concedere all'sme l'autorizzazione CAN_USE per l'app Databricks.

   Se lo SME non ha accesso ad alcun subagente, il supervisore terminerà la conversazione. Se l'utente finale ha accesso ad alcuni ma non a tutti i subagenti, il supervisore reindirizzerà la conversazione da subagenti a cui l'utente non può accedere.

4. Per etichettare i dati, fare clic su una domanda e aggiungere linee guida nel pannello visualizzato. Le linee guida si applicano subito dopo il salvataggio.

5. Testare di nuovo l'agente nella pagina di configurazione o in AI Playground per visualizzarne le prestazioni migliorate. Se necessario, aggiungere altre domande e linee guida per continuare a migliorare il comportamento.

Passaggio 5: Gestire le autorizzazioni

Per impostazione predefinita, solo gli autori dell'agente e gli amministratori dell'area di lavoro dispongono delle autorizzazioni per l'agente. Per consentire ad altri utenti di modificare o eseguire query nell'agente, è necessario concedere in modo esplicito l'autorizzazione.

Per gestire le autorizzazioni per l'agente:

1. Apri l'agente nella pagina Agenti.
2. Nella parte superiore fare clic
3. Fare clic su Gestisci autorizzazioni.
4. Nella finestra Impostazioni autorizzazione selezionare l'utente, il gruppo o l'entità servizio.
5. Selezionare l'autorizzazione per concedere:
   • Può gestire: consente di gestire l'agente, incluse le autorizzazioni di impostazione, la modifica della configurazione dell'agente e il miglioramento della qualità.
   • Può eseguire query: consente di eseguire query sull'endpoint dell'agente in AI Playground e tramite l'API. Gli utenti con questa autorizzazione non possono visualizzare o modificare l'agente nella pagina Agenti.
6. Fare clic su Aggiungi.
7. Fare clic su Salva.

Passaggio 6: Eseguire una query sull'endpoint dell'agente

Nella pagina dell'agente fare clic su Endpoint per aprire l'endpoint dell'agente e visualizzare i dettagli.

Esistono diversi modi per eseguire query sull'endpoint supervisore creato. Usare gli esempi di codice forniti in AI Playground come punto di partenza.

1. Seleziona Apri nel playground.
2. Da Playground fare clic su Recupera codice.
3. Scegliere come usare l'endpoint:
   • Selezionare Curl API per un esempio di codice per eseguire una query sull'endpoint usando curl.
   • Selezionare Python API per un esempio di codice per interagire con l'endpoint usando Python.

Gestire gli agenti supervisori con Databricks SDK

È possibile usare Databricks SDK per Python per creare e gestire a livello di codice gli agenti supervisore e i relativi strumenti. Per l'elenco completo delle operazioni disponibili, vedere le informazioni di riferimento su Supervisor Agents SDK.

Creare un agente supervisore

Nell'esempio seguente viene creato un nuovo agente supervisore con un nome visualizzato, una descrizione e istruzioni.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.supervisoragents import SupervisorAgent

w = WorkspaceClient()

supervisor_agent = SupervisorAgent(
    display_name="<display-name>",
    description="<description>",
    instructions="<instructions>",
)
created = w.supervisor_agents.create_supervisor_agent(supervisor_agent=supervisor_agent)
print(created)

Sostituire <display-name>, <description>e <instructions> con i valori per l'agente supervisore.

Gestire gli strumenti (subagenti)

È possibile aggiungere, aggiornare e rimuovere strumenti (subagenti) in un agente supervisore esistente usando l'SDK. Gli strumenti rappresentano subagenti, come ad esempio assistenti di conoscenza, Genie Spaces, funzioni del catalogo Unity e altri endpoint di agenti.

Aggiungere uno strumento (subagent)

Nell'esempio seguente viene aggiunto un assistente alla conoscenza come strumento in un agente supervisore esistente.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.supervisoragents import Tool, KnowledgeAssistant

w = WorkspaceClient()

tool = Tool(
    tool_type="knowledge_assistant",
    description="<tool-description>",
    knowledge_assistant=KnowledgeAssistant(
        knowledge_assistant_id="<knowledge-assistant-id>",
    ),
)

created_tool = w.supervisor_agents.create_tool(
    parent="supervisor-agents/<supervisor-agent-id>",
    tool=tool,
    tool_id="<tool-id>",
)
print(created_tool)

Sostituire <supervisor-agent-id> con l'ID dell'agente supervisore, <knowledge-assistant-id> con l'ID dell'assistente alla knowledge base da aggiungere come strumento e <tool-id> con un identificatore univoco per lo strumento.

Aggiornare uno strumento (subagent)

Nell'esempio seguente viene aggiornata la descrizione di uno strumento esistente.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.supervisoragents import Tool
from databricks.sdk.common.types.fieldmask import FieldMask

w = WorkspaceClient()

updated_tool = w.supervisor_agents.update_tool(
    name="supervisor-agents/<supervisor-agent-id>/tools/<tool-id>",
    tool=Tool(
        tool_type="knowledge_assistant",
        description="<new-description>",
    ),
    update_mask=FieldMask(["description"]),
)
print(updated_tool)

Campi consentiti in update_mask: description.

Rimuovere uno strumento (sottoagente)

Nell'esempio seguente viene eliminato uno strumento dall'agente supervisore.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

w.supervisor_agents.delete_tool(
    name="supervisor-agents/<supervisor-agent-id>/tools/<tool-id>",
)

Limitations

• È supportato solo l'inglese.
• Sono supportati solo gli endpoint agente creati tramite Knowledge Assistant .
• I controlli di intelligenza artificiale e i limiti di frequenza devono essere disabilitati nell'endpoint del databricks-gte-large-en modello. Consultare Configurare Unity AI Gateway negli endpoint di servizio dei modelli.
• Non è possibile utilizzare più di 20 agenti in un unico sistema di supervisione.
• Le aree di lavoro con sicurezza avanzata e conformità abilitate non sono supportate.
• Per consentire il funzionamento della traccia, è necessario abilitare il monitoraggio di produzione per MLflow (Beta). Se non è necessario il tracciamento, non è necessario attivare questa anteprima. Consultare Gestisci anteprime Azure Databricks.

Passaggi successivi

Attività con esecuzione prolungata dell'agente supervisore