Opret forbindelse til en agent, der er tilgængelig via Agent2Agent (A2A)-protokollen (forhåndsversion)

Agent2Agent (A2A)-protokollen er en åben standard for kommunikation og samarbejde mellem agenter.

Du kan oprette forbindelse mellem din brugerdefinerede agent og en anden agent, der understøtter A2A-protokollen. Copilot Studio bruger A2A-protokollen til at orkestrere med denne agent som svar på en brugeranmodning eller en udløser.

Hvad er A2A-protokollen (Agent2Agent)?

A2A-protokollen (Agent-to-Agent) definerer en standardkontrakt for agentkommunikation. Det gør det muligt for en orchestrator eller agent at:

• Send opgaver til eksterne agenter.
• Angiv omfattende, strukturerede metadata.
• Modtag agentsvar i et forudsigeligt format.

Sådan sammenlignes A2A-protokollen med en traditionel HTTP-forbindelse til kommunikation mellem agenter:

Ved hjælp af A2A kan Copilot Studio delegere opgaver til en anden agent og ikke blot kalde API'er.

Hvornår skal du bruge A2A-forbindelser?

Brug en A2A-forbindelse, når du vil integrere agenter, der allerede implementerer Agent-to-Agent-protokollen. Denne fremgangsmåde fungerer godt for agenter, der er:

• Bygget på eksterne strukturer.
• Hostet uden for Copilot Studio.
• Udstyret med deres egne domænespecifikke ræsonnerer eller arbejdsprocesser.

Brug alternative integrationsmønstre, når det er relevant:

Du kan kombinere flere integrationsmodeller inden for samme Copilot Studio-agent.

Opret forbindelse mellem din agent og en anden agent via A2A-protokollen

1. Gå til siden Agenter for din hovedagent, og vælg Tilføj en agent.

2. Vælg Opret forbindelse til en ekstern agent>Agent2Agent.

3. Angiv URL-adressen til A2A-agentens slutpunkt. Slutpunktets URL-adresse skal være slutpunktet for kommunikation med agenten og ikke URL-adressen for agentkortet.

   Når du har angivet URL-adressen til slutpunktet, og din agent har et gyldigt agentkort på standard-.well-known URL-adresse, henter Copilot Studio automatisk navnet og beskrivelsen på agenten fra kortet og udfylder dem i formularen for dig.

   Bemærk

   Hvis et navn og en beskrivelse ikke udfyldes automatisk for din agent, er det muligt, at agenten ikke har et agentkort, at kortet er placeret på en anden URL-adresse end den forventede, eller at der er problemer med at kommunikere med kortet. Først skal du kontrollere, at din agents slutpunkt er korrekt. Hvis det er, kan du manuelt angive et passende navn og en passende beskrivelse til din SDK-agent. Beskrivelsen skal beskrive formålet med din agent, så din hovedagent kan forstå, hvornår den anden agent skal bruges. Få mere at vide om at skrive effektive metadata. Du kan også prøve at navigere til agentens kort i din browser (placeret på agentens slutpunkt + /.well-known/agent.json).

4. Vælg den relevante godkendelsesmetode, afhængigt af hvordan SDK-agenten er konfigureret, på rullelisten Godkendelse . Indstillingerne er:

   • Ingen: Vælg denne indstilling, hvis din agent ikke kræver godkendelse, eller hvis du bruger den eksempelagent, der er angivet i denne dokumentation, som ikke har aktiveret godkendelse.
   • API-nøgle: Vælg denne indstilling, hvis din agent kræver en API-nøgle til godkendelse. Du skal angive navnet på headeren, hvor API-nøglen skal medtages, eller forespørgselsparameteren.
   • OAuth 2.0: Vælg denne indstilling, hvis din agent bruger OAuth 2.0 til godkendelse. Du skal angive klient-id,klienthemmelighed, URL-adresse til godkendelse, URL-adresse til token og URL-adresse til opdatering.

   Hvis du vælger en anden godkendelsestype end Ingen, skal du også udfylde de andre godkendelsesoplysninger.

5. Vælg Opret.

6. Vælg den ønskede forbindelse på listen over tilgængelige forbindelser, eller opret en ny forbindelse mellem din A2A-agent og din Copilot Studio-agent.

7. Vælg Tilføj og konfigurer.

Eksempel på A2A-forbindelse

I denne hurtige introduktion konfigurerer du en A2A-aktiveret agent og forbinder den med en Copilot Studio-agent. Når du har fuldført trinnene,

• Kør et eksempel på en A2A-aktiveret agent lokalt, eller brug en eksisterende A2A-agent, du allerede har.
• Vis agenten sikkert via HTTPS ved hjælp af Dev-tunneler eller en anden hostingindstilling.
• Forbind den eksterne agent med en Copilot Studio-agent via en A2A-forbindelse.
• Valider forbindelsen ved at aktivere agenten fra Copilot Studio med en opgave på et naturligt sprog, f.eks.: "Hvilken plante har brug for mere lys tomatplante eller en jordbærplante?"

Når du har konfigureret forbindelsen, kan du se:

• En vellykket A2A-forbindelse, der er oprettet fra Copilot Studio.
• Aktivitetslogge fra den eksterne agent, der bekræfter, at den har modtaget og behandlet den delegerede opgave.
• Den komplette A2A-nyttedata, herunder de andre metadata Copilot Studio sender med hver anmodning.

Forudsætninger

Hvis du vil følge eksempelscenariet, skal du bruge:

• En Azure OpenAI-ressource med:
  • URL-slutpunkt
  • Installationsnavn
  • API-nøgle
• .NET 10 SDK eller nyere
• Et Copilot Studio-miljø med tilladelser til:
  • Rediger agenter
  • Konfigurer forbindelser
• En metode til at vise den lokale agent offentligt:
  • Udvikling af tunneler (anbefales til udvikling)
  • Eller et hostet miljø, f.eks. Azure App Service eller objektbeholder

Hvis du allerede har en A2A-aktiveret agent, skal du gå til Opret A2A-forbindelsen i Copilot Studio.

Trin 1: Klon og konfigurer A2A-eksempelagenten

Klon A2A-agentens eksempellager:

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

Angiv de nødvendige Azure OpenAI-indstillinger:

• AZURE_OPENAI_ENDPOINT: URL-adressen til dit Azure OpenAI-slutpunkt
• AZURE_OPENAI_DEPLOYMENT_NAME: Navnet på din Azure OpenAI-installation
• AZURE_OPENAI_API_KEY: Din Azure OpenAI API-nøgle

Du kan konfigurere disse indstillinger enten som miljøvariabler eller ved at gemme dem i appsettings.json eller appsettings.Development.json.

Mulighed A: Konfigurer som miljøvariabler

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

Mulighed B: Konfigurer i appsettings.json

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

Trin 2: Opret, kør og vis agenten

Gendan og byg afhængigheder:

dotnet restore
dotnet build

Kør agenten:

dotnet run

Konsollen viser URL-adressen til det lokale A2A-slutpunkt.

Vis slutpunktet

Hvis du bruger Visual Studio Code og planlægger at vise slutpunktet ved hjælp af Dev-tunneler, kan du fremvise en ny tunnelport til udvikling. Vælg den A2A-port, der vises i konsollen. Højreklik, og gør porten offentlig. Ellers er den ikke synlig online.

Dev Tunnels giver dig en offentlig URL-adresse, f.eks.: https://xyz123-9000.dev.tunnels.ms/. Vær opmærksom på denne URL-adresse som basisslutpunkt, så du kan bruge den, når du konfigurerer A2A-forbindelsen i Copilot Studio.

Trin 3: Opret A2A-forbindelsen i Copilot Studio

Når A2A-agenten er offentligt tilgængelig, skal du oprette A2A-forbindelsen i Copilot Studio.

1. Åbn Copilot Studio og vælg din primære agent.
2. Vælg Agenter.
3. Vælg Tilføj agent, og vælg derefter A2A-agent.
4. Angiv de påkrævede konfigurationsværdier:
   • Navn: Et beskrivende navn, f.eks . Botanisk agent.
   • URL-adresse til slutpunkt: Brug url-adressen til den offentlige udviklingstunnel efterfulgt af A2A-meddelelsesslutpunktet, f.eks.: https://xyz123-5073.dev.tunnels.ms/a2a/botanical/v1/message:stream
   • Godkendelse: Vælg Ingen , hvis du bruger eksempelagenten (ingen godkendelse gennemtvinges).
5. Vælg Gem for at validere og oprette forbindelsen.

Når konfigurationen er gyldig, bekræfter Copilot Studio, at A2A-agenten er tilsluttet.

Trin 4: Send en opgave fra Copilot Studio til A2A-agenten

Når du har oprettet forbindelsen, skal du kontrollere integrationen ved at sende en opgave.

1. Åbn din hovedagent i Copilot Studio og gå til lærredet Test.
2. Angiv en prompt, der skal delegeres til A2A-agenten. For eksempel: "Hvilken plante har brug for mere lys – en tomatplante eller en jordbærplante?"
3. Agentens orchestrator evaluerer brugerinputtet og uddelegerer opgaven til A2A-agenten.
4. Den eksterne agent behandler anmodningen og returnerer et svar, som vises i testchatten.

I den eksterne agents logfiler kan du se:

• En modtaget A2A-opgave.
• Prompten for naturligt sprog.
• Det genererede svar, der blev returneret til Copilot Studio.

Trin 5: Undersøg A2A-nyttedata og metadata

A2A-meddelelser indeholder strukturerede metadata, der giver ekstra kontekst. Disse metadata kan hjælpe agenten med at tilpasse svar, administrere routing eller opretholde kontinuitet på tværs af brugersving.

En typisk A2A-besked-payload omfatter:

• Et unikt contextId
• Meddelelses-id'er
• Locale-oplysninger
• Fuld chathistorik, ikke kun den seneste brugerytring
• Dele af meddelelsesindhold (tekst, værktøjskald eller andre metadata)

Eksempel på nyttedatauddrag:

{
"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"
       }
     ]
   }
 }
}
}

Du kan bruge disse metadata til enhver downstream-logik, som A2A-agenten implementerer.

Næste trin

Når du har oprettet den grundlæggende A2A-forbindelse, kan du:

• Føj nye færdigheder eller domænekendskab til din A2A-agent.
• Brug metadata fra A2A-nyttedata til at implementere routing- og tilpasningslogik.
• Tilføj godkendelse for at sikre dit A2A-slutpunkt, og opdater Copilot Studio-indstillingerne i overensstemmelse hermed.
• Opret forbindelse mellem andre A2A-aktiverede agenter ved hjælp af den samme konfigurationstilgang.

Vigtige takeaways

• Copilot Studio kan orkestrere eksterne agenter ved hjælp af A2A-protokollen.
• A2A muliggør arbejdsprocesser med flere agenter med omfattende kontekstafhængige metadata.
• Eksempelagenten viser hele rundturen: Copilot Studio -> A2A-agent -> Copilot Studio.
• A2A-meddelelser indeholder detaljerede metadata, der understøtter kontekstafhængig agentfunktionalitet.

Relaterede oplysninger

• Udforsk mønstre for orkestrering af flere agenter
• Løsninger til arkitektagenter: Mønstre med flere agenter