Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Usa gli agenti connessi per permettere al tuo agente primario di delegare attività specifiche ad agenti specializzati. Questo articolo ti mostra come collegare un agente costruito con l'Managed Disks, così il tuo agente principale può trasferirgli i compiti.
Note
Il framework utilizzato per costruire questo agente utilizza una fatturazione basata sull'uso. Utilizzare, costruire, testare e valutare agenti potrebbe consumare Copilot Credits. Scopri di più in Panoramica della fatturazione basata sull'uso.
Un agente costruito con l'Managed Disks espone un endpoint di messaggistica che parla il protocollo Activity. Lo colleghi inserendo direttamente quell'endpoint. A differenza di un agente A2A, un agente SDK non pubblica una scheda agente, quindi Copilot Studio non può individuarne il nome e la descrizione per te. Fornisci tu stesso questi dettagli.
Aggiungi ogni agente connesso dalla stessa finestra di dialogo Aggiungi un agente connesso . Per una panoramica degli agenti connessi e di come funziona il routing, vedi Panoramica degli agenti connessi. Per collegare un altro agente Copilot Studio, vedi Aggiungi un agente Copilot Studio come agente connesso. Per collegare un agente Microsoft Foundry, vedi Aggiungi un agente Foundry come agente connesso. Per collegare un agente remoto tramite il protocollo Agent2Agent (A2A), vedi Aggiungi un agente A2A come agente connesso.
Prerequisites
- Un agente creato con Microsoft Copilot harness per fungere da agente principale. Vedi Creare un agente (anteprima).
- Un agente costruito con l'Managed Disks, distribuito e raggiungibile da Copilot Studio.
- L'URL dell'endpoint di messaggistica dell'agente, tipicamente
https://<your-agent-host>/api/messages. L'URL deve essere un URL assolutohttpohttpsURL. - I dettagli di autenticazione richiesti dall'agente SDK, se ce ne sono. Copilot Studio supporta l'assenza di autenticazione, chiavi API e OAuth 2.0.
Aggiungi un agente Managed Disks
Il wizard ti guida attraverso tre passaggi: connettiti a un agente Managed Disks, connettiti all'agente Managed Disks, poi rivedi e aggiungi.
Accedere a Copilot Studio.
Scegli e apri l'agente che vuoi usare come agente primario.
Nella barra di navigazione agente, seleziona la scheda Build .
Nel pannello dei componenti, seleziona Agenti connessi per aprire la finestra di dialogo Aggiungi un agente connesso.
Nel dialogo, seleziona Aggiungi e poi seleziona Aggiungi agente Managed Disks.
Nel passaggio Connect to a Managed Disks agent, inserisci i dettagli dell'agente:
-
URL endpoint di messaggistica: ad esempio l'endpoint del protocollo Activity del tuo agente
https://agent.example.com/api/messagesSDK. - Nome: il nome mostrato all'autore agente, fino a 30 caratteri.
- Descrizione: una descrizione chiara di quando questo agente SDK dovrebbe essere utilizzato, tra 30 e 1.000 caratteri. L'orchestratore usa questa descrizione per decidere quando instradare una richiesta all'agente, quindi rendila specifica ed evita sovrapposizioni con gli altri strumenti e agenti. Scopri di più sulla scrittura di metadati efficaci.
-
URL endpoint di messaggistica: ad esempio l'endpoint del protocollo Activity del tuo agente
In Autenticazione, seleziona come Copilot Studio si autentica con l'agente SDK, e poi completa i dettagli per il metodo scelto:
- Nessuno: l'agente SDK non richiede autenticazione.
- Chiave API: l'agente SDK richiede una chiave API. Vedi Configura l'autenticazione della chiave API.
- OAuth 2.0: l'agente SDK utilizza OAuth 2.0. Vedi Configurare l'autenticazione OAuth 2.0.
Non puoi continuare finché i dettagli dell'autenticazione non sono completi.
Selezionare Avanti.
Nel passaggio Connect to the Managed Disks agent, Copilot Studio crea il connettore per l'agente. Poi scegli la connessione che questo agente utilizza per raggiungere l'agente SDK:
- Seleziona una connessione esistente dall'elenco delle connessioni disponibili.
- Se non c'è nessuna connessione disponibile, crea una nuova connessione. Se l'agente SDK utilizza l'autenticazione della chiave API, inserisci il valore della chiave API quando crei la connessione.
Se il connettore non può essere creato, seleziona Retry.
Selezionare Avanti.
Nel passaggio Revisione e aggiungi, rivedi nome, descrizione e URL dell'endpoint messaggistica, poi seleziona Aggiungi all'agente.
Conferma che l'agente connesso appare sotto Agenti connessi nel pannello componenti.
Se torni indietro e cambi l'URL dell'endpoint di messaggistica nel passaggio Connect to a Managed Disks agent, Copilot Studio elimina il connettore che era stato costruito dall'URL precedente. Devi scegliere di nuovo una connessione.
Note
Sei responsabile di rivedere e testare attentamente gli agenti connessi nel contesto dei tuoi casi d'uso specifici, e di prendere tutte le decisioni e personalizzazioni appropriate. Quando ti connetti ad agenti esterni a Copilot Studio, sei responsabile dell'utilizzo di tali agenti. Le considerazioni includono garantire:
- I flussi di dati, la gestione dei dati e la condivisione dei dati tra agenti sono appropriati per il tuo caso d'uso e rispettano i requisiti e le leggi pertinenti.
- Gli agenti soddisfano adeguati standard di qualità, affidabilità, sicurezza e fidatezza.
- Sono previsti permessi, limiti e approvazioni appropriati, se opportuno per il tuo caso d'uso.
- Sono presenti adeguate funzionalità di osservabilità, identità e tracciabilità, nonché funzioni di supervisione umana.
Configurare l'autenticazione della chiave API
Quando selezioni la chiave API, scegli dove Copilot Studio invia la chiave selezionando un tipo di parametro:
-
Header: la chiave viene inviata come intestazione di richiesta. In Nome intestazione, inserisci il nome dell'intestazione che l'agente SDK si aspetta, come
x-api-key. - Query string: la chiave viene inviata come parametro query string. Nell'etichetta Parametro, inserisci il nome del parametro della stringa di query che l'agente SDK si aspetta.
Inserisci il valore chiave API stesso quando crei la connessione, non in questo passaggio. In questo modo la chiave viene memorizzata con la connessione e non è visibile nella configurazione dell'agente.
Configurare l'autenticazione OAuth 2.0
Quando selezioni OAuth 2.0, scegli un tipo di configurazione:
Dinamico: Copilot Studio registra un client presso il provider di identità dell'agente SDK per te. Inserisci l'URL di Autorizzazione e l'URL del Token.
Manuale: utilizza una registrazione dell’applicazione già creata con il provider di identità dell’agente SDK. Immettere i valori seguenti:
- ID client: l'ID client della registrazione della tua app.
- Segreto cliente: il segreto cliente della registrazione della tua app.
- URL di autorizzazione: l'endpoint di autorizzazione del fornitore di identità.
- URL del token: l'endpoint del token del fornitore di identità.
- URL del token di aggiornamento: l'endpoint utilizzato per aggiornare i token di accesso.
- Ambiti (opzionali): gli ambiti da richiedere, separati da spazi.
Usa Dynamic quando il provider di identità dell'agente SDK supporta la registrazione dinamica del client. Usa Manual quando devi controllare la registrazione dell'app, ad esempio quando il tuo fornitore di identità richiede URI di reindirizzamento preregistrati o il consenso.
Come l'orchestratore instrada verso l'agente SDK
Dopo aver aggiunto l'agente SDK, il runtime di orchestrazione determina automaticamente quando delegare a esso. La decisione di instradamento si basa su:
- Il nome e la descrizione dell'agente connesso
- Il messaggio dell'utente e il contesto della conversazione
- Le istruzioni dell'agente primario
Tip
Scrivi una descrizione chiara e specifica per l'agente SDK così che l'orchestratore possa determinare con precisione quando instradare le richieste verso di esso. Evita descrizioni sovrapposte tra agenti connessi.
Delega di test
Dopo aver aggiunto l'agente SDK:
Nella barra di spostamento dell'agente seleziona la scheda Anteprima.
Invia un messaggio che corrisponda al dominio dell'agente SDK.
Verifica che la risposta provenga dall'agente SDK e sia appropriata.
Invia un messaggio al di fuori del dominio dell'agente SDK per confermare che il tuo agente principale lo gestisce.
Se dovrai cambiare nome o descrizione in seguito, modifica l'agente connesso dal pannello componenti. Vedi "Gestire gli agenti connessi in un agente".
Risolvere i problemi di connessione
| Problem | Controlli da eseguire |
|---|---|
| L'URL dell'endpoint della messaggistica viene rifiutata | L'URL deve essere un URL assoluto http o https che punti all'endpoint del protocollo Activity dell'agente, come https://agent.example.com/api/messages. |
| Avanti rimane non disponibile nel passaggio di connessione | Il nome, la descrizione e l'URL dell'endpoint della messaggistica sono tutti necessari, e la descrizione deve avere almeno 30 caratteri. Dettagli di autenticazione incompleti impediscono anche questo passaggio. |
| La creazione del connettore fallisce | Seleziona Riprova. Se continua a fallire, controlla che l'URL dell'endpoint messaggistica sia corretto e che il tuo ambiente permetta connettori personalizzati. |
| La connessione che hai creato non funziona più dopo aver modificato il wizard | Cambiando l'URL dell'endpoint della messaggistica il connettore costruito dall'URL precedente viene eliminato. Scegli di nuovo una connessione. |