Einen verfügbaren Agent über das Agent2Agent (A2A)-Protokoll verbinden (Vorschauversion)

Das Agent2Agent (A2A)-Protokoll ist ein offener Standard für die Kommunikation und Zusammenarbeit zwischen Agents.

Sie können Ihren benutzerdefinierten Agent mit einem anderen Agent verbinden, der das A2A-Protokoll unterstützt. Copilot Studio verwendet das A2A-Protokoll, um diesen Agent als Reaktion auf eine Benutzeranforderung oder einen Trigger zu koordinieren.

Was ist das Agent2Agent (A2A)-Protokoll?

Das Agent-zu-Agent-Protokoll (A2A) definiert einen Standardvertrag für die Agentkommunikation. Er ermöglicht einem Orchestrator oder Agent Folgendes:

• Aufgaben an externe Agents senden.
• Stellen Sie umfangreiche, strukturierte Metadaten bereit.
• Empfangen von Agentantworten in einem vorhersehbaren Format.

So schneidet das A2A-Protokoll im Vergleich zu einer herkömmlichen HTTP-Verbindung für die Kommunikation zwischen Agenten ab:

Mithilfe von A2A kann Copilot Studio Aufgaben an einen anderen Agent delegieren, nicht nur APIs aufrufen.

Wann A2A-Verbindungen verwendet werden sollen

Verwenden Sie eine A2A-Verbindung, wenn Sie Agents integrieren möchten, die bereits das Agent-zu-Agent-Protokoll implementieren. Dieser Ansatz eignet sich gut für Agents, die:

• Basiert auf externen Frameworks.
• Außerhalb von Copilot Studio gehostet.
• Ausgestattet mit domänenspezifischem logischen Denken oder Workflows.

Verwenden Sie bei Bedarf alternative Integrationsmuster:

Sie können mehrere Integrationsmodelle innerhalb desselben Copilot Studio-Agents kombinieren.

Verbinden Ihres Agents mit einem anderen Agent über das A2A-Protokoll

1. Wechseln Sie zur Seite Agents für Ihren Haupt-Agent, und wählen Sie Agent hinzufügen aus.

2. Wählen Sie "Mit einem externen Agent Agent2Agent> verbinden" aus.

3. Geben Sie die Endpunkt-URL Ihres A2A-Agents ein. Die Endpunkt-URL sollte der Endpunkt für die Kommunikation mit dem Agent und nicht die URL für die Agent-Karte sein.

   Sobald Sie Ihre Endpunkt-URL eingegeben haben, und Ihr Agent über eine gültige Agentenkarte auf der Standard-.well-known-URL verfügt, ruft Copilot Studio automatisch den Namen und die Beschreibung Ihres Agenten von der Karte ab und füllt sie in das Formular ein.

   Anmerkung

   Wenn Name und Beschreibung nicht automatisch für Ihren Agent ausgefüllt werden, ist es möglich, dass Ihr Agent keine Agent-Karte hat, dass sich die Karte unter einer anderen URL befindet als die erwartete URL oder dass es ein Problem bei der Kommunikation mit der Karte gibt. Überprüfen Sie zunächst, ob der Endpunkt Ihres Agents korrekt ist. Wenn dies der Fall ist, können Sie manuell einen geeigneten Namen und eine geeignete Beschreibung für Ihren SDK-Agent eingeben. Die Beschreibung sollte den Zweck Ihres Agents beschreiben, damit Ihr Haupt-Agent verstehen kann, wann der zweite Agent verwendet werden sollte. Erfahren Sie mehr über das Schreiben effektiver Metadaten. Sie können auch versuchen, zur Karte Ihres Agents in Ihrem Browser zu navigieren (befindet sich am Endpunkt Ihres Agents + /.well-known/agent.json).

4. Wählen Sie in der Dropdownliste " Authentifizierung " die entsprechende Authentifizierungsmethode aus, je nachdem, wie Ihr SDK-Agent konfiguriert ist. Folgende Optionen sind verfügbar:

   • Keine: Wählen Sie diese Option aus, wenn Ihr Agent keine Authentifizierung erfordert oder wenn Sie den in dieser Dokumentation bereitgestellten Beispiel-Agent verwenden, der keine Authentifizierung aktiviert hat.
   • API-Schlüssel: Wählen Sie diese Option aus, wenn Ihr Agent einen API-Schlüssel für die Authentifizierung benötigt. Sie müssen den Namen des Headers angeben, in den der API-Schlüssel oder der Abfrageparameter eingeschlossen werden soll.
   • OAuth 2.0: Wählen Sie diese Option aus, wenn Ihr Agent OAuth 2.0 für die Authentifizierung verwendet. Sie müssen die Client-ID, den geheimen Clientschlüssel, die Autorisierungs-URL, die Token-URL und die Aktualisierungs-URL angeben.

   Wenn Sie einen anderen Authentifizierungstyp als Keinen auswählen, müssen Sie auch die anderen Authentifizierungsdetails angeben.

5. Wählen Sie "Erstellen" aus.

6. Wählen Sie die gewünschte Verbindung aus der Liste der verfügbaren Verbindungen aus, oder erstellen Sie eine neue Verbindung zwischen Ihrem A2A-Agent und Ihrem Copilot Studio-Agent.

7. Wählen Sie "Hinzufügen" und "Konfigurieren" aus.

A2A-Verbindungsbeispiel

In dieser Schnellstartanleitung konfigurieren Sie einen A2A-fähigen Agent und verbinden ihn mit einem Copilot Studio-Agent. Wenn Sie die Schritte abgeschlossen haben

• Führen Sie einen A2A-fähigen Beispiel-Agent lokal aus, oder verwenden Sie einen vorhandenen A2A-Agent, den Sie bereits haben.
• Machen Sie den Agent sicher über HTTPS verfügbar, indem Sie Dev Tunnels oder eine andere Hostingoption verwenden.
• Verbinden Sie den externen Agent über eine A2A-Verbindung mit einem Copilot Studio-Agent.
• Überprüfen Sie die Verbindung, indem Sie den Agent von Copilot Studio mit einer natürlichen Sprachaufgabe aufrufen, z. B.: "Welche Pflanze benötigt mehr Licht - ein Tomatenstrauch oder eine Erdbeerpflanze?"

Nach dem Konfigurieren der Verbindung wird Folgendes angezeigt:

• Eine erfolgreiche A2A-Verbindung, die von Copilot Studio hergestellt wurde.
• Aktivitätsprotokolle des externen Agents, der bestätigt, dass er die delegierte Aufgabe empfangen und verarbeitet hat.
• Die vollständige A2A-Nutzlast, einschließlich der anderen Metadaten, die Copilot Studio mit jeder Anforderung sendet.

Voraussetzungen

Um dem Beispielszenario zu folgen, benötigen Sie Folgendes:

• Eine Azure OpenAI-Ressource mit:
  • Endpunkt-URL
  • Bereitstellungsname
  • API-Schlüssel
• .NET 10 SDK oder höher
• Eine Copilot Studio-Umgebung mit Berechtigungen für:
  • Agenten bearbeiten
  • Konfigurieren von Verbindungen
• Eine Methode, um den lokalen Agent öffentlich verfügbar zu machen:
  • Dev Tunnels (empfohlen für die Entwicklung)
  • Oder eine gehostete Umgebung wie Azure App Service oder Container

Wenn Sie bereits über einen A2A-aktivierten Agent verfügen, wechseln Sie zu Create the A2A connection in Copilot Studio.

Schritt 1: Klonen und Konfigurieren des A2A-Beispiel-Agents

Klonen Sie das Beispiel-A2A-Agent-Repository:

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

Legen Sie die erforderlichen Azure OpenAI-Einstellungen fest:

• AZURE_OPENAI_ENDPOINT: Ihre Azure OpenAI-Endpunkt-URL
• AZURE_OPENAI_DEPLOYMENT_NAME: Name Ihrer Azure OpenAI-Bereitstellung
• AZURE_OPENAI_API_KEY: Ihr Azure OpenAI-API-Schlüssel

Sie können diese Einstellungen entweder als Umgebungsvariablen konfigurieren oder in appsettings.json oder appsettings.Development.jsonspeichern.

Option A: Als Umgebungsvariablen konfigurieren

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

Option B: Konfigurieren in appsettings.json

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

Schritt 2: Erstellen, Ausführen und Verfügbarmachen des Agents

Wiederherstellen und Erstellen von Abhängigkeiten:

dotnet restore
dotnet build

Führen Sie den Agent aus:

dotnet run

Die Konsole zeigt die lokale A2A-Endpunkt-URL an.

Verfügbarmachen des Endpunkts

Wenn Sie Visual Studio Code verwenden und beabsichtigen, den Endpunkt mithilfe von Dev Tunnels verfügbar zu machen, machen Sie einen neuen Dev-Tunnel-Port verfügbar. Wählen Sie den in der Konsole angezeigten A2A-Port aus. Klicken Sie mit der rechten Maustaste, und machen Sie den Port öffentlich; andernfalls ist sie nicht online sichtbar.

Dev Tunnels gibt Ihnen eine öffentliche URL, z. B.: https://xyz123-9000.dev.tunnels.ms/. Notieren Sie sich diese URL als Basisendpunkt, damit Sie sie beim Konfigurieren der A2A-Verbindung in Copilot Studio verwenden können.

Schritt 3: Erstellen der A2A-Verbindung in Copilot Studio

Nachdem der A2A-Agent öffentlich zugänglich ist, erstellen Sie die A2A-Verbindung in Copilot Studio.

1. Öffnen Sie Copilot Studio, und wählen Sie Ihren primären Agent aus.
2. Wählen Sie Agentsaus.
3. Wählen Sie "Agent hinzufügen" und dann "A2A-Agent" aus.
4. Geben Sie die erforderlichen Konfigurationswerte ein:
   • Name: Ein beschreibender Name, z. B. Botanischer Agent.
   • Endpunkt-URL: Verwenden Sie die öffentliche Dev Tunnel-URL gefolgt vom A2A-Nachrichtenendpunkt, z. B.: https://xyz123-5073.dev.tunnels.ms/a2a/botanical/v1/message:stream
   • Authentifizierung: Wählen Sie "Keine" aus, wenn Sie den Beispiel-Agent verwenden (keine Authentifizierung erzwungen).
5. Wählen Sie "Speichern" aus, um die Verbindung zu überprüfen und einzurichten.

Wenn die Konfiguration gültig ist, bestätigt Copilot Studio, dass der A2A-Agent erfolgreich verbunden ist.

Schritt 4: Senden einer Aufgabe von Copilot Studio an den A2A-Agent

Überprüfen Sie nach dem Erstellen der Verbindung die Integration, indem Sie eine Aufgabe senden.

1. Öffnen Sie Ihren Hauptagenten in Copilot Studio, und wechseln Sie zum Zeichenbereich Test.
2. Geben Sie eine Eingabeaufforderung ein, die an den A2A-Agent delegiert werden soll. Beispiel: "Welche Pflanze braucht mehr Licht – eine Tomatenpflanze oder eine Erdbeerpflanze?"
3. Der Agent Orchestrator wertet die Benutzereingabe aus und delegiert die Aufgabe an den A2A-Agent.
4. Der externe Agent verarbeitet die Anforderung und gibt eine Antwort zurück, die im Testchat angezeigt wird.

In den Protokollen des externen Agents wird Folgendes angezeigt:

• Eine empfangene A2A-Aufgabe.
• Die Eingabeaufforderung für natürliche Sprache.
• Die generierte Antwort wurde an Copilot Studio zurückgegeben.

Schritt 5: Überprüfen der A2A-Nutzlast und -Metadaten

A2A-Nachrichten enthalten strukturierte Metadaten, die zusätzlichen Kontext bieten. Diese Metadaten können dem Agent helfen, Antworten anzupassen, Routing zu verwalten oder die Kontinuität über benutzerübergreifende Wendungen hinweg aufrechtzuerhalten.

Eine typische A2A-Nachrichtennutzlast umfasst:

• Ein einzigartiger contextId
• Nachrichten-IDs
• Gebietsparameter-Informationen
• Vollständiger Chatverlauf, nicht nur die letzte Äußerung des Benutzers
• Nachrichteninhaltsteile (Text, Toolaufrufe oder andere Metadaten)

Beispiel für Datenpaketauszug:

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

Sie können diese Metadaten für jede nachgeschaltete Logik verwenden, die Ihr A2A-Agent implementiert.

Nächste Schritte

Nachdem Sie die grundlegende A2A-Verbindung hergestellt haben, können Sie:

• Fügen Sie Ihrem A2A-Agent neue Fähigkeiten oder Domänenkenntnisse hinzu.
• Verwenden Sie Metadaten aus der A2A-Nutzlast, um Routing- und Personalisierungslogik zu implementieren.
• Fügen Sie die Authentifizierung hinzu, um Ihren A2A-Endpunkt zu schützen, und aktualisieren Sie Copilot Studio-Einstellungen entsprechend.
• Verbinden Sie andere A2A-fähige Agents mithilfe des gleichen Konfigurationsansatzes.

Wichtige Erkenntnisse

• Copilot Studio können externe Agents mithilfe des A2A-Protokolls orchestrieren.
• A2A ermöglicht Multi-Agent-Workflows mit umfangreichen Metadaten im Kontext.
• Der Beispiel-Agent veranschaulicht den vollständigen Roundtrip: Copilot Studio -> A2A-Agent -> Copilot Studio.
• A2A-Nachrichten enthalten detaillierte Metadaten, die das Kontextbezogene Agent-Verhalten unterstützen.

Verwandte Informationen

• Entdecken Sie Muster der Multi-Agenten-Orchestrierung
• Gestaltung von Agentenlösungen: Multi-Agent-Muster