Aggiungi un agente Agent2Agent (A2A) come agente connesso (GitHub Copilot)

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 remoto disponibile tramite il protocollo Agent2Agent (A2A), così il tuo agente principale può trasferirgli i compiti.

Annotazioni

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.

Il protocollo A2A è uno standard aperto per la comunicazione e la collaborazione tra agenti. Poiché è uno standard aperto, puoi collegare agenti ospitati fuori da Copilot Studio e basati su altri framework, purché implementino A2A. Copilot Studio scopre l'agente remoto dalla sua scheda dell'agente, quindi utilizza il protocollo A2A per delegare compiti a esso durante l'esecuzione.

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.

Prerequisites

  • Un agente creato con il harness GitHub Copilot per essere l'agente principale. Vedi Creare un agente (anteprima).
  • Un agente remoto che implementa il protocollo Agent-to-Agent ed è raggiungibile da Copilot Studio tramite internet pubblico.
  • L'URL della scheda agente dell'agente remoto, tipicamente https://<your-agent-host>/.well-known/agent-card.json.
  • I dettagli di autenticazione che l'agente remoto richiede, se presenti. Copilot Studio supporta l'assenza di autenticazione, chiavi API e OAuth 2.0.
  • Per OAuth 2.0, permesso di aggiungere un URI di reindirizzamento alla registrazione dell'app che il provider di identità dell'agente remoto usa. Copilot Studio genera l'URL di reindirizzamento durante il wizard, e devi registrarlo prima di creare la connessione.

Annotazioni

Poiché le connessioni A2A usano l'infrastruttura del connettore personalizzata, è anche possibile usarle per connettersi agli agenti A2A in esecuzione in locale o all'interno di una rete virtuale.

Aggiungi un agente Agent2Agent (A2A)

Il wizard ti guida attraverso tre o quattro passaggi, a seconda del metodo di autenticazione che scegli:

  • Se scegli Nessuno o API key: connettiti a un agente A2A, connettiti all'agente A2A, poi Rivedi e aggiungi.
  • Se scegli OAuth 2.0: Connettiti a un agente A2A, aggiungi URL di reindirizzamento, collegati all'agente A2A, poi rivedi e aggiungi.

  1. Accedere a Copilot Studio.

  2. Scegli e apri l'agente che vuoi usare come agente primario.

  3. Nella barra di navigazione agente, seleziona la scheda Build .

  4. Nel pannello dei componenti, seleziona Agenti connessi per aprire la finestra di dialogo Aggiungi un agente connesso.

  5. Nella finestra di dialogo, seleziona Aggiungi e poi seleziona Aggiungi agente A2A.

  6. Nel passaggio Collegati a un agente A2A , inserisci i dettagli dell'agente remoto:

    • URL della scheda agente: l'URL della scheda agente dell'agente remoto, ad esempio https://agent.example.com/.well-known/agent-card.json. Copilot Studio legge la scheda per scoprire l'endpoint e le capacità dell'agente.
    • Nome: il nome mostrato all'agente autore. Se la scheda dell'agente include un nome, Copilot Studio riempie questo campo per te.
    • Descrizione: una descrizione chiara di quando dovrebbe essere utilizzato questo agente A2A, tra 30 e 1.000 caratteri. Se la scheda dell'agente include una descrizione, Copilot Studio riempie questo campo per te. 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.

    Annotazioni

    Se nome e descrizione non vengono compilati automaticamente, l'agente remoto potrebbe non avere una scheda agente, la scheda potrebbe trovarsi a un URL diverso da quello inserito oppure Copilot Studio potrebbe non riuscire a raggiungerla. Controlla prima l'URL e prova ad aprire la scheda agente nel browser. Se la carta non è disponibile, inserisci manualmente nome e descrizione.

  7. In Autenticazione, seleziona come Copilot Studio si autentica con l'agente remoto e poi completa i dettagli per il metodo scelto:

    Non puoi continuare finché i dettagli dell'autenticazione non sono completi.

  8. Selezionare Avanti.

  9. Se hai selezionato OAuth 2.0, compare il passaggio Aggiungi URL di reindirizzamento . Copilot Studio crea il connettore per l'agente A2A e la piattaforma genera un URL di reindirizzamento per esso. Registra quell'URL presso il tuo provider di identità prima di creare la connessione:

    1. Aspetta che il campo URL di Redirect si riempia. Il connettore deve esistere prima che l'URL venga generato.
    2. Seleziona il pulsante di copia accanto al campo per copiare l'URL.
    3. Nella registrazione dell'app OAuth, aggiungi l'URL come URI di redirect e salva la registrazione dell'app.
    4. Selezionare Avanti.

    Importante

    Se non registri prima l'URL di reindirizzamento, il primo tentativo di autorizzare la connessione fallisce. L'URL di reindirizzamento viene generato per connettore, quindi è specifico per questo agente A2A e non può essere riutilizzato da un altro connettore. Se ti serve di nuovo l'URL in seguito, seleziona l'agente A2A sotto Connected agents nel pannello componenti per riaprirlo.

  10. Nel passaggio Collegati all'agente A2A , scegli la connessione che questo agente utilizza per raggiungere l'agente remoto:

    • Seleziona una connessione esistente dall'elenco delle connessioni disponibili.
    • Se non c'è nessuna connessione disponibile, crea una nuova connessione. Se l'agente remoto utilizza l'autenticazione della chiave API, inserisci il valore della chiave API quando crei la connessione.

  11. Selezionare Avanti.

  12. Nella fase Review and add, rivedi nome, descrizione e URL della scheda agente, poi seleziona Aggiungi all'agente.

  13. Conferma che l'agente connesso appare sotto Agenti connessi nel pannello componenti.

Se torni indietro e modifichi le impostazioni di autenticazione nel passaggio Collega a un agente A2A, Copilot Studio scarta il connettore che era stato costruito dalle impostazioni precedenti. Devi registrare un nuovo URL di redirect e scegliere di nuovo una connessione.

Annotazioni

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. Nel nome dell'intestazione inserisci il nome dell'intestazione che l'agente remoto 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 remoto 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 per te presso il provider di identità dell'agente remoto. Inserisci l'URL di Autorizzazione e l'URL del Token.

  • Manuale: usa una registrazione dell'app che hai già creato presso il fornitore di identità dell'agente remoto. Immettere i valori seguenti:

    • ID client: l'ID client della registrazione della tua app.
    • Segreto client: il segreto client della registrazione dell'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.
    • Scope (opzionali): gli scope da richiedere, separati da spazi.

Usa Dynamic quando il fornitore di identità dell'agente remoto supporta la registrazione dinamica del cliente. 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.

Entrambi i tipi di configurazione richiedono di registrare un URL di reindirizzamento presso il tuo fornitore di identità. Dopo aver selezionato Next, Copilot Studio crea il connettore e mostra l'URL di reindirizzamento generato nel passaggio Aggiungi URL di reindirizzamento.

Recupera l'URL di reindirizzamento in seguito

Se chiudi il wizard o perdi l'URL di reindirizzamento, puoi visualizzarlo di nuovo in qualsiasi momento:

  1. Nella scheda Build, seleziona l'agente A2A sotto Agenti connessi nel pannello componenti.

  2. Nella finestra di dialogo Modifica agente A2A , copia il valore nel campo URL Redirect .

Il campo URL di Reindirizzamento appare solo per gli agenti A2A che utilizzano OAuth 2.0.

Come l'orchestratore instrada verso l'agente A2A

Dopo aver aggiunto l'agente A2A, 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 A2A 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 A2A:

  1. Nella barra di spostamento dell'agente seleziona la scheda Anteprima.

  2. Invia un messaggio che corrisponda al dominio dell'agente A2A.

  3. Verifica che la risposta provenga dall'agente A2A e sia appropriata.

  4. Invia un messaggio al di fuori del dominio dell'agente A2A 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

Problema Controlli da eseguire
L'autorizzazione della connessione fallisce con un errore di reindirizzamento URI L'URL di reindirizzamento generato da Copilot Studio non è registrato presso il tuo fornitore di identità. Copia l'URL dalla finestra di dialogo Modifica agente A2A , aggiungilo alla registrazione dell'app e poi autorizza nuovamente la connessione.
Il campo URL di Redirect rimane vuoto nella procedura guidata Il connettore è ancora in fase di creazione. Se il passaggio mostra un errore invece, seleziona Retry.
Il nome e la descrizione non si riempiono dalla scheda dell'agente Controlla che l'URL della scheda agente sia corretto e che Copilot Studio possa raggiungere la scheda. Inserisci manualmente nome e descrizione se la carta non è disponibile.
La connessione che hai creato non funziona più dopo aver modificato il wizard Cambiando le impostazioni di autenticazione, il connettore creato con le impostazioni precedenti viene scartato. Registra il nuovo URL di reindirizzamento e scegli di nuovo una connessione.
  • Ultimo aggiornamento: