Connettersi a un agente disponibile tramite il protocollo Agent2Agent (A2A) (anteprima)

Il protocollo Agent2Agent (A2A) è uno standard aperto per la comunicazione e la collaborazione tra gli agenti.

È possibile connettere l'agente personalizzato a un altro agente che supporta il protocollo A2A. Copilot Studio usa il protocollo A2A per orchestrare con questo agente in risposta a una richiesta utente o a un trigger.

Che cos'è il protocollo Agent2Agent (A2A)?

Il protocollo da agente a agente (A2A) definisce un contratto standard per la comunicazione dell'agente. Consente a un agente di orchestrazione o a un agente di:

• Inviare attività agli agenti esterni.
• Fornire metadati avanzati e strutturati.
• Ricevere risposte dell'agente in un formato prevedibile.

Ecco come il protocollo A2A confronta con una connessione HTTP tradizionale per la comunicazione tra agenti:

Usando A2A, Copilot Studio può delegare attività a un altro agente, non solo chiamare le API.

Quando usare le connessioni A2A

Usare una connessione A2A quando si vogliono integrare gli agenti che implementano già il protocollo da agente a agente. Questo approccio funziona bene per gli agenti che sono:

• Basato su framework esterni.
• Ospitato al di fuori di Copilot Studio.
• Dotato dei propri flussi di lavoro o ragionamenti specifici del dominio.

Usare modelli di integrazione alternativi quando appropriato:

È possibile combinare più modelli di integrazione all'interno dello stesso agente di Copilot Studio.

Connettere l'agente a un altro agente tramite il protocollo A2A

1. Passa alla pagina Agenti per l'agente principale e seleziona Aggiungi un agente.

2. Selezionare Connetti a un agente> esternoAgent2Agent.

3. Immetti l'URL dell'endpoint dell'agente A2A. L'URL dell'endpoint deve essere l'endpoint per la comunicazione con l'agente e non l'URL della scheda dell'agente.

   Dopo aver immesso l'URL dell'endpoint, se l'agente ha una scheda agente valida nell'URL standard .well-known, Copilot Studio recupera automaticamente il nome e la descrizione dell'agente dalla scheda e completa il modulo con queste informazioni.

   Nota

   Se un nome e una descrizione non vengono popolati automaticamente per l'agente, è possibile che l'agente non abbia una scheda agente, la scheda si trova in un URL diverso da quello previsto o si è verificato un problema durante la comunicazione con la scheda. Prima di tutto, verifica che l'endpoint dell'agente sia corretto. In questo caso, è possibile immettere manualmente un nome e una descrizione appropriati per l'agente SDK. La descrizione deve descrivere lo scopo dell'agente, in modo che l'agente principale possa comprendere quando deve essere usato il secondo agente. Altre informazioni sulla scrittura di metadati efficaci. È anche possibile provare ad accedere alla scheda del tuo agente nel browser (nella pagina di destinazione dell'agente + /.well-known/agent.json).

4. Selezionare il metodo di autenticazione appropriato, a seconda della configurazione dell'agente SDK nell'elenco a discesa Autenticazione . Le opzioni sono:

   • Nessuno: selezionare questa opzione se l'agente non richiede l'autenticazione o se si usa l'agente di esempio fornito in questa documentazione, che non ha l'autenticazione abilitata.
   • Chiave API: selezionare questa opzione se l'agente richiede una chiave API per l'autenticazione. È necessario specificare il nome dell'intestazione in cui deve essere inclusa la chiave API o il parametro di query.
   • OAuth 2.0: selezionare questa opzione se l'agente usa OAuth 2.0 per l'autenticazione. È necessario specificare l'ID client, il segreto client, l'URL di autorizzazione, l'URL del token e l'URL di aggiornamento.

   Se selezioni un tipo di autenticazione diverso da Nessuno, è necessario completare anche gli altri dettagli di autenticazione.

5. Fare clic su Crea.

6. Selezionare la connessione desiderata dall'elenco delle connessioni disponibili o creare una nuova connessione tra l'agente A2A e l'agente di Copilot Studio.

7. Selezionare Aggiungi e configura.

Esempio di connessione A2A

In questa guida introduttiva si configura un agente abilitato per A2A e lo si connette a un agente di Copilot Studio. Quando completi i passaggi,

• Eseguire un agente abilitato per A2A di esempio in locale o usare un agente A2A esistente già disponibile.
• Esporre l'agente in modo sicuro tramite HTTPS usando Dev Tunnels o un'altra opzione di hosting.
• Connettere l'agente esterno a un agente di Copilot Studio tramite una connessione A2A.
• Convalidare la connessione richiamando l'agente da Copilot Studio con un'attività in linguaggio naturale, ad esempio: "Quale pianta ha bisogno di più luce, una pianta di pomodoro o una pianta di fragola?"

Dopo aver configurato la connessione, viene visualizzato quanto illustrato di seguito:

• Connessione A2A effettuata con successo tramite Copilot Studio.
• Log delle attività dall'agente esterno che conferma di avere ricevuto ed elaborato l'attività delegata.
• Il payload A2A completo, inclusi gli altri metadati che Copilot Studio invia con ogni richiesta.

Prerequisiti

Per seguire lo scenario di esempio, è necessario:

• Una risorsa Azure OpenAI con:
  • URL del punto finale
  • Nome distribuzione
  • Chiave dell'API
• .NET 10 SDK o versione successiva
• Un ambiente Copilot Studio con autorizzazioni per:
  • Modificare gli agenti
  • Configurare le connessioni
• Metodo per esporre pubblicamente l'agente locale:
  • Dev Tunnels (consigliato per lo sviluppo)
  • Oppure un ambiente ospitato, ad esempio Azure App Service o contenitore

Se si dispone già di un agente abilitato per A2A, passare a Creare la connessione A2A in Copilot Studio.

Passaggio 1: Clonare e configurare l'agente A2A di esempio

Clonare il repository dell'agente A2A di esempio:

git clone https://github.com/microsoft/CopilotStudioSamples.git
cd CopilotStudiosamples/A2ASamples/Simple_A2A_Agent

Impostare le impostazioni necessarie Azure OpenAI:

• AZURE_OPENAI_ENDPOINT: URL dell'endpoint OpenAI Azure
• AZURE_OPENAI_DEPLOYMENT_NAME: nome della distribuzione Azure OpenAI
• AZURE_OPENAI_API_KEY: la chiave API di Azure OpenAI

È possibile configurare queste impostazioni come variabili di ambiente o salvandole in appsettings.json o appsettings.Development.json.

Opzione A: Configurare come variabili di ambiente

$env:AZURE_OPENAI_ENDPOINT="https://YOUR-RESOURCE.openai.azure.com"
$env:AZURE_OPENAI_DEPLOYMENT_NAME="YOUR-DEPLOYMENT"
$env:AZURE_OPENAI_API_KEY="YOUR-KEY"

Opzione B: Configurare in appsettings.json

{  
    "AzureOpenAI": {    
        "Endpoint": "https://YOUR-RESOURCE.openai.azure.com",
        "DeploymentName": "YOUR-DEPLOYMENT",
        "ApiKey": "YOUR-KEY"  
    }
}

Passaggio 2: Compilare, eseguire ed esporre l'agente

Ripristinare e costruire le dipendenze:

dotnet restore
dotnet build

Eseguire l'agente:

dotnet run

Nella console viene visualizzato l'URL dell'endpoint A2A locale.

Esporre l'endpoint

Se si usa Visual Studio Code e si prevede di esporre l'endpoint usando Dev Tunnels, esporre una nuova porta del tunnel di sviluppo. Scegliere la porta A2A visualizzata nella console. Fare clic con il pulsante destro del mouse e rendere pubblica la porta; in caso contrario, non è visibile online.

Dev Tunnels offre un URL pubblico, ad esempio : https://xyz123-9000.dev.tunnels.ms/. Prendere nota di questo URL come endpoint di base per poterlo usare durante la configurazione della connessione A2A in Copilot Studio.

Passaggio 3: Creare la connessione A2A in Copilot Studio

Dopo che l'agente A2A è accessibile pubblicamente, creare la connessione A2A all'interno di Copilot Studio.

1. Aprire Copilot Studio e selezionare l'agente primario.
2. Selezionare Agenti.
3. Selezionare Aggiungi agente e quindi scegliere Agente A2A.
4. Immettere i valori di configurazione necessari:
   • Nome: nome descrittivo, ad esempio l'agente botanico.
   • URL endpoint: usare l'URL pubblico di Dev Tunnel seguito dall'endpoint del messaggio A2A, ad esempio: https://xyz123-5073.dev.tunnels.ms/a2a/botanical/v1/message:stream
   • Autenticazione: selezionare Nessuno se si usa l'agente di esempio (nessuna autenticazione applicata).
5. Selezionare Salva per convalidare e stabilire la connessione.

Quando la configurazione è valida, Copilot Studio conferma che l'agente A2A è connesso correttamente.

Passaggio 4: Inviare un'attività da Copilot Studio all'agente A2A

Dopo aver creato la connessione, verificare l'integrazione inviando un'attività.

1. Aprire l'agente principale in Copilot Studio e passare all'area di disegno Test.
2. Inserire un prompt che deve essere delegato all'agente A2A. Ad esempio: "Quale pianta ha bisogno di più luce, una pianta di pomodoro o una pianta di fragola?"
3. L'agente di orchestrazione valuta l'input dell'utente e delega l'attività all'agente A2A.
4. L'agente esterno elabora la richiesta e restituisce una risposta, visualizzata nella chat di test.

Nei log dell'agente esterno viene visualizzato quanto riportato di seguito:

• Ricevuta attività A2A.
• Richiesta in linguaggio naturale.
• Risposta generata restituita a Copilot Studio.

Passaggio 5: Esaminare il payload e i metadati A2A

I messaggi A2A includono metadati strutturati che forniscono contesto aggiuntivo. Questi metadati consentono all'agente di adattare le risposte, gestire il routing o mantenere la continuità tra turni dell'utente.

** Il payload tipico di un messaggio A2A include:

• Un oggetto univoco contextId
• Identificatori di Messaggi
• Informazioni locali
• Cronologia completa della chat, non solo l'espressione utente più recente
• Parti del contenuto del messaggio (testo, chiamate di strumenti o altri metadati)

Estratto del payload di esempio:

{
"method": "message/send",
"params": {
 "message": {
   "contextId": "ee1e68ee-75fc-42bb-83d7-25fd26e559c3",
   "metadata": {
     "copilotstudio.microsoft.com/a2a/chathistory": [
       {
         "From": "agent",
         "Locale": "en-US",
         "Text": "Hello, I'm A2A Agent Demo...",
         "Timestamp": "2025-11-26T23:19:28.764Z"
       },
       {
         "From": "user",
         "Locale": "en-US",
         "Text": "Which plant needs more sunlight...",
         "Timestamp": "2025-11-26T23:20:21.484Z"
       }
     ]
   }
 }
}
}

È possibile usare questi metadati per qualsiasi logica downstream implementata dall'agente A2A.

Passaggi successivi

Dopo aver stabilito la connessione A2A di base, è possibile:

• Aggiungere nuove competenze o conoscenze sul dominio all'agente A2A.
• Usare i metadati del payload A2A per implementare la logica di routing e personalizzazione.
• Aggiungere l'autenticazione per proteggere l'endpoint A2A e aggiornare le impostazioni di Copilot Studio di conseguenza.
• Connettere altri agenti abilitati per A2A usando lo stesso approccio di configurazione.

Punti chiave

• Copilot Studio può orchestrare agenti esterni usando il protocollo A2A.
• A2A consente flussi di lavoro con più agenti con metadati contestuali avanzati.
• L'agente di esempio illustra il round trip completo: Copilot Studio -> agente A2A -> Copilot Studio.
• I messaggi A2A includono metadati dettagliati che supportano il comportamento dell'agente compatibile con il contesto.

Informazioni pertinenti

• Esplora i modelli di orchestrazione multi-agente
• Progettazione di soluzioni dell'agente: modelli multi-agente