Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

A2A Protocol-Tools

Das Agent-to-Agent-Protokoll (A2A) ist ein offener Messaging-Standard, der es autonomen KI-Agenten ermöglicht, Aufgaben in verschiedenen Systemen zu kommunizieren und zu koordinieren.

In CX Agent Studio können Sie mit A2A-Protokolltools Aufgaben von Ihrer Agent-Anwendung an externe Remote-Agenten delegieren oder externe Anwendungen und Orchestratoren können Ihre CX Agent Studio-Agenten über standardisierte Nachrichten aufrufen.

So funktioniert A2A

Das A2A-Protokoll in CX Agent Studio basiert auf einem Delegierungsmodell.

Delegierungsmodell

Im Delegierungsmodell fungiert der initiierende CX Agent Studio-Agent als primärer Orchestrator und behält die gesamte Sitzungssteuerung bei:

Sitzungsinhaberschaft:Der primäre Agent verwaltet die Unterhaltungssitzung des Nutzers. Wenn eine spezielle untergeordnete Aufgabe erforderlich ist, ruft der primäre Agent den Remote-Agenten als Tool auf.
Kontrollfluss:Der Remote-Agent verarbeitet die Anfrage und gibt strukturierte Antwortdaten zurück. Die Steuerung wird sofort an den primären Agent zurückgegeben, der die Ergebnisse für den Endnutzer zusammenfasst oder einbindet.
Kontextübertragung:Der primäre Agent überträgt nur die Parameter und den Unterhaltungskontext, die für die delegierte Aufgabe erforderlich sind.

A2A-Delegierungssequenzdiagramm

Textbasierte Kommunikation

Die gesamte Kommunikation zwischen Agenten im A2A-Protokoll ist textbasiert:

Wenn ein Endnutzer über einen Sprachkanal (z. B. Telefonie oder WebRTC) mit einem primären Agenten interagiert, wird die Sprache zuerst in Text umgewandelt.
Der primäre Agent sendet das Text-Transkript und die Parameter in der Nutzlast einer HTTP-Anfrage an den Remote-Unteragenten.
Rohaudiodaten und Einbettungen werden nicht über die A2A-Netzwerkschnittstelle übertragen.

Unterstützung von Modalitäten

Die Unterstützung von Modalitäten (Text oder Sprache) für das A2A-Protokoll hängt von der Richtung der Kommunikation ab:

Remote-Agent zu CX Agent Studio:Unterstützt nur die Textmodalität.
CX Agent Studio an Remote-Agent: Modusunabhängig für CX Agent Studio. Das bedeutet, dass in der CX Agent Studio-Sitzung jeder unterstützte Modus wie Sprache oder Text verwendet werden kann, der Remote-Agent jedoch nur Text empfängt.

Abrechnung

Wenn sich sowohl die primäre als auch die Remote-Sitzung in CX Agent Studio und im selben Projekt befinden, wird Ihnen nur eine Sitzung in Rechnung gestellt.

Andernfalls werden für primäre und Remote-Sitzungen in mehreren Projekten oder Drittanbietersystemen zwei Sitzungen in Rechnung gestellt.

Authentifizierung und Zugriffssteuerung

Die Authentifizierungsanforderungen hängen von der Kommunikationsrichtung und dem Zieldienst ab.

Richtung	Ziel	Authentifizierungsmechanismus	Erforderliche IAM-Rolle	Beschreibung
Eingehend (extern zu CX Agent Studio)	CX Agent Studio-Agent-Anwendung	OAuth 2.0-Zugriffstoken	`roles/ces.client`	Erforderlich, damit externe Anrufer den eingehenden Endpunkt von CX Agent Studio aufrufen können.
Ausgehend (CX Agent Studio zu CX Agent Studio)	CX Agent Studio-Agent in einem anderen Projekt	Dienst-Agent	`roles/ces.client`	Wird dem Dienst-Agent des aufrufenden Projekts im Zielprojekt gewährt.
Ausgehend (CX Agent Studio zu Cloud Run)	Cloud Run-Dienst	Dienst-Agent-ID-Token	`roles/run.invoker`	Dem Dienst-Agenten des aufrufenden Projekts für den Cloud Run-Dienst gewährt.
Ausgehend (CX Agent Studio zu Vertex AI)	Vertex AI Agent Engine	OAuth für Dienst-Agenten	`roles/aiplatform.user`	Wird dem Dienst-Agent des aufrufenden Projekts im Zielprojekt gewährt.
Ausgehend (CX Agent Studio an Drittanbieter)	Externer Endpunkt (z. B. ServiceNow oder Salesforce)	API-Schlüssel oder OAuth	Mit Secret Manager verwaltet	Gespeicherte Anmeldedaten, die während der Toolausführung eingefügt werden.

Identität des Dienst-Agents

Für ausgehende Anfragen von CX Agent Studio wird der CX Agent Studio-Dienst-Agent verwendet:

service-PROJECT_NUMBER@gcp-sa-ces.iam.gserviceaccount.com

Ersetzen Sie PROJECT_NUMBER durch die Google Cloud Projektnummer.

Eingehende Authentifizierung

Wenn eine externe Anwendung, ein benutzerdefinierter Agent oder ein Orchestrator CX Agent Studio aufruft, muss ein gültiges von Google ausgestelltes OAuth 2.0-Zugriffstoken im Authorization-Header übergeben werden:

Testen:Generieren Sie ein temporäres Zugriffstoken für Ihr aktives Konto:
```
gcloud auth print-access-token
```
Programmatische Clients:Verwenden Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC):
```
gcloud auth application-default print-access-token
```
Produktion:Verwenden Sie ein dediziertes Google-Dienstkonto mit der Rolle roles/ces.client (Customer Engagement Suite Client).

Vorbereitung

Bevor Sie A2A Protocol-Tools konfigurieren:

Aktivieren Sie die Gemini Enterprise for Customer Experience API (ces.googleapis.com) in Ihrem Projekt:
```
gcloud services enable ces.googleapis.com --project=PROJECT_ID
```
Achten Sie darauf, dass dem aufrufenden Hauptkonto oder Dienstkonto die Rolle Customer Engagement Suite Client (roles/ces.client) zugewiesen wurde.

A2A Protocol-Tool konfigurieren

So verbinden Sie Ihren primären Agent mit einem externen Remote-Agent:

Öffnen Sie die CX Agent Studio Console.
Wählen Sie Ihr Projekt aus und öffnen Sie Ihre Agent-Anwendung.
Klicken Sie im Agent Builder auf das Symbol Tools.
Klicken Sie auf das + (Hinzufügen), um ein neues Tool zu erstellen.
Wählen Sie die Toolcard A2A Protocol aus.
Konfigurieren Sie die Agent-Karte entweder mit dem UI-Formular oder dem JSON-Editor.
Geben Sie im Feld URL die Basisendpunkt-URL des Remote-Agents ein (z. B. https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID oder die URL Ihres Cloud Run-Dienstes). Hängen Sie /message:send nicht an die URL an. CX Agent Studio hängt /message:send automatisch zur Laufzeit an.
Wählen Sie den entsprechenden Authentifizierungstyp für den Endpunkt aus.
Klicken Sie auf Erstellen.

Beispiel für eine Agentenkarte

Im folgenden Beispiel-JSON wird eine Agentenkarte für einen Remote-Wetter-Agenten definiert:

{
  "name": "weather_agent",
  "description": "Agent capable of querying weather conditions and local time for given locations.",
  "version": "0.1.0",
  "supportedInterfaces": [
    {
      "url": "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ],
  "skills": [
    {
      "id": "get_weather",
      "name": "get_weather",
      "description": "Retrieves weather conditions for a specified location.",
      "tags": [
        "weather",
        "forecast"
      ],
      "examples": [],
      "inputModes": [],
      "outputModes": []
    },
    {
      "id": "get_current_time",
      "name": "get_current_time",
      "description": "Retrieves current local time for a specified city or timezone.",
      "tags": [
        "time",
        "clock"
      ],
      "examples": [],
      "inputModes": [],
      "outputModes": []
    }
  ]
}

Routinganweisungen hinzufügen

Weisen Sie Ihren primären Agenten an, wann er an das A2A-Tool delegieren soll. Beispiel:

If the user asks for weather information or local time, use {@TOOL: weather_agent}.
Pass the city or location specified by the user.
If the tool returns an error, inform the user that weather details are temporarily unavailable.

Eingehende Nachrichten

Externe Systeme können Nachrichten direkt an eine CX Agent Studio-Agent-Anwendung senden, indem sie den eingehenden A2A-Messaging-Endpunkt verwenden.

URL des eingehenden Endpunkts

Senden Sie HTTP-POST-Anfragen an den folgenden Endpunkt:

https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID/message:send

Ersetzen Sie Folgendes:

PROJECT_ID: Ihre Google Cloud Projekt-ID
LOCATION: Die Region, in der Ihre Agent-Anwendung gehostet wird, z. B. us-central1.
APP_ID: Die eindeutige Kennung Ihrer CX Agent Studio-Agentenanwendung.

Schema der Anfragenutzlast

Die JSON-Nutzlaststruktur zum Senden einer eingehenden Nachricht:

{
  "message": {
    "messageId": "msg-MY_UNIQUE_MESSAGE_UUID",
    "role": "ROLE_USER",
    "content": [
      {
        "text": "Hello! I would like help checking my account balance."
      }
    ],
    "metadata": {
      "gecx_a2a_agent_context": "MY_SERIALIZED_AGENT_CONTEXT_STRING"
    }
  }
}

Hinweis:In CX Agent Studio wird im Nachrichten-Payload das Feld content verwendet, um Nachrichtentextteile zu enthalten.

Beispielanfrage mit curl

Sie können eingehende Nachrichten mit curl testen:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "messageId": "msg-'"$(uuidgen)"'",
      "role": "ROLE_USER",
      "content": [
        {
          "text": "Hello!"
        }
      ]
    }
  }' \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID/message:send"

Kontext- und Statusverwaltung

Das A2A-Protokoll verwendet die AgentContext-Nachricht, um Variablen und Sitzungsstatus zwischen Agenten zu verwalten. Der Kontext wird in den Metadaten von SendMessageRequest mit dem Schlüssel gecx_a2a_agent_context übergeben.

Variablenzuordnung

Wenn Sie eine Aufgabe delegieren, können Sie Variablen zwischen dem primären und dem Remote-Agenten zuordnen:

Ausgehende Zuordnung:RemoteAgentTool.input_variable_mapping Berechnet die AgentContext.variables, die an den Remote-Agenten gesendet wird.
Eingehende Zuordnung:RemoteAgentTool.output_variable_mapping Aktualisiert die Variablen des primären Agenten, wenn der Remote-Agent antwortet.

Bei eingehenden Anfragen (externer Client an CX Agent Studio) deserialisiert die Anwendung die gecx_a2a_agent_context-Metadaten und schreibt die AgentContext.variables direkt in die aktuelle Sitzung. Die aktualisierten Variablen werden beim Antworten an den Client in AgentContext.variables zurückgeschrieben.

Sitzung schließen

Der primäre Agent überwacht AgentContext.session_metadata.closed, um festzustellen, wann eine Remotesitzung endet:

Bei ausgehenden Anfragen wird closed immer auf false gesetzt. Wenn in der Antwort des Remote-Agents closed auf true gesetzt ist, wird die A2A-Verbindung beendet.
Bei eingehenden Antworten an den Kunden wird closed in der CX Agent Studio App auf true gesetzt, wenn die Sitzung beendet wurde.

Zustandsorientierter Modus

Remote-Sitzungen mit CXAS-Apps sind immer zustandsbehaftet. Primäre und Remote-CXAS-Sitzungen haben dieselbe Sitzungs-ID und in Remote-Sitzungen wird der Unterhaltungsverlauf zwischen dem primären und dem Remote-Agenten beibehalten.

Bei Remote-Sitzungen mit Drittanbietersystemen sind die Remote-Sitzungen standardmäßig zustandslos und der Remote-Agent empfängt jede Nachricht vom primären Agenten als neue Sitzung (d. h. mit einer neuen Kontext-ID).

Sie können das Feld RemoteAgentTool.stateful_agent aktivieren, um die erste vom Remote-Agent zurückgegebene Kontext-ID automatisch zu speichern und wiederzuverwenden.

Diese zwischengespeicherte Kontext-ID wird für den Rest der Sitzung verwendet, sofern der Remote-Agent nicht mit AgentContext.session_metadata.closed == true antwortet. Wenn die Sitzung geschlossen wird, wird der Cache zurückgesetzt und beim nächsten Tool-Aufruf wird eine neue Kontext-ID im Cache gespeichert.

Remote-Sub-Agent bereitstellen

Sie können benutzerdefinierte Remote-Agents auf Google Cloud Diensten bereitstellen, die als untergeordnete Agents für CX Agent Studio fungieren.

In Cloud Run bereitstellen

So hosten Sie einen mit dem Agent Development Kit (ADK) erstellten Agenten in Cloud Run:

Erstellen Sie im Verzeichnis Ihres Projekts für KI-Agenten eine Dockerfile-Datei:

FROM python:3.11-slim

WORKDIR /app

COPY pyproject.toml requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
RUN pip install --no-cache-dir "google-adk[a2a]==1.32.0" "a2a-sdk[all]==0.3.26"

COPY . .

ENV PORT=8080
ENV PYTHONUNBUFFERED=1

EXPOSE 8080

CMD ["python", "-m", "app.a2a_rest_server"]

Container in Cloud Run bereitstellen:

gcloud run deploy my-adk-agent \
  --project=PROJECT_ID \
  --region=us-central1 \
  --source=. \
  --memory=4Gi \
  --no-cpu-throttling

Weisen Sie dem CX Agent Studio-Dienst-Agent Ihres aufrufenden Projekts die Rolle roles/run.invoker für den Cloud Run-Dienst zu.
Folgen Sie der Anleitung unter A2A-Protokolltool konfigurieren, um die Cloud Run-Dienst-URL an CX Agent Studio anzuhängen.

In der Vertex AI Agent Engine bereitstellen

So stellen Sie einen ADK-Agenten in der Vertex AI Agent Engine bereit:

Definieren Sie die Abhängigkeiten in requirements.txt:
```
a2a-sdk==0.3.26
google-adk[a2a]>=1.15.0,<2.0.0
```

Stellen Sie die Engine mit dem Vertex AI SDK bereit:

import os
import sys
from google.protobuf import json_format
import vertexai
from vertexai.agent_engines import _agent_engines

sys.path.append("./")
from app.agent_runtime_app import agent_runtime

client = vertexai.Client(project="PROJECT_ID", location="us-central1")

ops = agent_runtime.register_operations()
class_methods_proto = _agent_engines._generate_class_methods_spec_or_raise(
    agent_engine=agent_runtime,
    operations=ops
)
class_methods_list = [
    json_format.MessageToDict(cm, preserving_proto_field_name=True)
    for cm in class_methods_proto
]

agent_config = {
    "entrypoint_module": "app.agent_runtime_app",
    "entrypoint_object": "agent_runtime",
    "source_packages": ["app", "requirements.txt"],
    "requirements_file": "requirements.txt",
    "class_methods": class_methods_list,
    "agent_framework": "google-adk",
    "env_vars": {
        "GOOGLE_CLOUD_LOCATION": "us-central1",
    },
    "min_instances": 1,
    "max_instances": 10,
    "resource_limits": {"cpu": "4", "memory": "8Gi"},
}

engine = client.agent_engines.create(config=agent_config)
print(f"Deployed Engine Resource Name: {engine.api_resource.name}")

Weisen Sie dem CX Agent Studio-Dienst-Agent Ihres aufrufenden Projekts die Rolle roles/aiplatform.user für das Zielprojekt zu.
Folgen Sie der Anleitung unter A2A-Protokolltool konfigurieren, um den Agent Engine-Endpunkt an CX Agent Studio anzuhängen.

Verbindung zu Drittanbieterendpunkten herstellen

In CX Agent Studio können Aufgaben an externe Drittanbieter-Endpunkte wie ServiceNow oder Salesforce delegiert werden.

Beim Konfigurieren des Tools in der Console:

Folgen Sie der Anleitung unter A2A-Protokolltool konfigurieren.
Wählen Sie die Authentifizierungsmethode aus, die für den Drittanbieter-Endpunkt erforderlich ist, z. B. API-Schlüssel oder OAuth.
Anmeldedaten sicher mit Secret Manager speichern

A2A-Protokolltools im Vergleich zu „Agent als Tool“

CX Agent Studio bietet mehrere Methoden zum Koordinieren von Multi-Agenten-Workflows.

Funktion	Agent als Tool	A2A Protocol-Tool
Bereich	Innerhalb einer Anwendung (Agents in derselben CX Agent Studio-App).	Anwendungen untereinander (externe Agents, Remotedienste oder Drittanbieterplattformen).
Kommunikation	Direkte In-Memory-/interne Ausführung.	Netzwerk-HTTP-Anfragen mit dem A2A-Messaging-Standard.
Anwendungsfälle	Interne untergeordnete KI‑Agenten werden wiederverwendet, ohne die Sitzung zu übergeben.	Benutzerdefinierte ADK-Agents in Cloud Run, Vertex AI oder externen APIs aufrufen.
Protokoll	Plattforminterne Tool-Ausführung.	Standardisierte A2A-JSON-Nutzlast über REST.

LLM-Toolausführung

A2A-Protokollaufrufe erfolgen über standardmäßige LLM-Toolaufrufe:

Wenn einem Agenten ein A2A-Tool zugewiesen wird, werden die Toolbeschreibung und die Skill-Definitionen dem Modell als Funktionsdeklarationen bereitgestellt.
Wenn das Modell beschließt, eine untergeordnete Aufgabe zu delegieren, wird ein Funktionsaufrufereignis generiert.
Die CX Agent Studio-Laufzeit fängt den Funktionsaufruf ab, übersetzt die Parameter in eine A2A-HTTP-Anfrage und sendet sie an den konfigurierten Remote-Endpunkt.
Die vom Remote-Agent zurückgegebene Antwort wird an das Modell zurückgegeben, damit die Unterhaltungsantwort weiter generiert werden kann.

Weitere Informationen dazu, wie Agenten als aufrufbare Tools gekapselt werden, finden Sie auf GitHub unter ADK AgentTool implementation.

A2A Protocol-Tools Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

So funktioniert A2A

Delegierungsmodell

Textbasierte Kommunikation

Unterstützung von Modalitäten

Abrechnung

Authentifizierung und Zugriffssteuerung

Identität des Dienst-Agents

Eingehende Authentifizierung

Vorbereitung

A2A Protocol-Tool konfigurieren

Beispiel für eine Agentenkarte

Routinganweisungen hinzufügen

Eingehende Nachrichten

URL des eingehenden Endpunkts

Schema der Anfragenutzlast

Beispielanfrage mit curl

Kontext- und Statusverwaltung

Variablenzuordnung

Sitzung schließen

Zustandsorientierter Modus

Remote-Sub-Agent bereitstellen

In Cloud Run bereitstellen

In der Vertex AI Agent Engine bereitstellen

Verbindung zu Drittanbieterendpunkten herstellen

A2A-Protokolltools im Vergleich zu „Agent als Tool“

LLM-Toolausführung

A2A Protocol-Tools