Agenten über den registrierten A2A-Endpunkt aufrufen

Agent2Agent-Agenten (A2A) in der Agent Registry werben für Protokollschnittstellen, die eine Endpunkt-URL und eine Protokollbindung (z. B. HTTP_JSON) enthalten. Sie können die URL eines Agenten in der Registry ermitteln, um seine A2A-Methoden von benutzerdefinierten Orchestratoren oder Clients aufzurufen.

Auf einen Blick

Spezifikation	Details
Discovery API	agentregistry.googleapis.com (v1)
Host des Aufruf-Proxys	LOCATION-discoveryengine.googleapis.com
Protokollbindung	HTTP_JSON
URL-Projekt-ID	Google Cloud Projektnummer (nicht Projekt-ID)
Unterstützte A2A-Methoden	GET /v1/card, POST /v1/message:send, POST /v1/message:stream
Erforderliches Nachrichtenschema	message.role = "ROLE_USER", content[].text, eindeutige messageId
Erforderliche IAM-Berechtigungen	roles/agentregistry.viewer (Erkennung) und discoveryengine.assistants.assist (Aufruf)

Hinweis

1. Aktivieren Sie die Agent Registry API (agentregistry.googleapis.com) und die Discovery Engine API (discoveryengine.googleapis.com) in Ihrem Google Cloud Projekt.
2. Wenn der Agent nicht direkt in Ihrer Gemini Enterprise-App erstellt wurde, importieren Sie ihn aus der Agent Registry und gewähren Sie Endnutzern Zugriff darauf. Eine Anleitung finden Sie unter A2A-Agenten aus der Agent Registry importieren.
3. Gewähren Sie Ihrem Aufrufer-Hauptkonto die entsprechenden IAM-Berechtigungen:
   • Zum Lesen der Registry: Agent Registry Viewer (roles/agentregistry.viewer).
   • Zum Aufrufen des Agenten: Discovery Engine-Bearbeiter (roles/discoveryengine.editor) oder eine benutzerdefinierte Rolle mit discoveryengine.assistants.assist.
4. Wenn Sie sich mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) authentifizieren, konfigurieren Sie Ihren Client so, dass er den Header für das Kontingentprojekt sendet: -H "X-Goog-User-Project: PROJECT_ID".
5. Optional können Sie die Agent Development Kit-Bibliothek (ADK) installieren, wenn Sie Remote-Agenten als programmatische Sub-Agenten einbinden möchten: pip install "google-adk[a2a]>=1.29.0".

Schritt 1: Agenten und zugehörigen A2A-Endpunkt ermitteln

Um einen A2A-Agenten aufzurufen, ermitteln Sie zuerst seine beworbene url in der Agent Registry. Listen Sie die Agenten in Ihrem Registry-Standort auf (z. B. us oder eu, als Pfad-Parameter auf dem globalen Host agentregistry.googleapis.com übergeben):

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/agents?pageSize=100"

Sie können auch mit der Google Cloud CLI nach einem Agenten anhand des Präfixes des Anzeigenamens suchen:

gcloud agent-registry agents search \
  --project=PROJECT_ID \
  --location=LOCATION \
  --search-string="displayName:My_Agent_*"

Hinweis: Wenn die Befehlsgruppe agent-registry nicht erkannt wird, führen Sie gcloud components update aus, um Ihre CLI-Distribution zu aktualisieren.

Prüfen Sie in der zurückgegebenen Agent-Ressource das Array protocols. Suchen Sie den Eintrag, bei dem type gleich A2A_AGENT und interfaces[].protocolBinding gleich HTTP_JSON ist. Extrahieren Sie die entsprechende url:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/agents/AGENT_RESOURCE_ID",
  "displayName": "My Agent",
  "protocols": [
    {
      "type": "A2A_AGENT",
      "protocolVersion": "0.3.0",
      "interfaces": [
        {
          "url": "https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/assistants/default_assistant/agents/AGENT_ID/a2a",
          "protocolBinding": "HTTP_JSON"
        }
      ]
    }
  ]
}

Wichtig: Verwenden Sie die zurückgegebene url String genau so, wie sie ist. Bei Gemini Enterprise-Agenten leitet diese URL den Traffic über den Discovery Engine A2A-Proxy und bettet die Google Cloud Nummer Ihres Projekts anstelle der Projekt-ID ein. Nicht alle registrierten Agenten stellen eine A2A-Schnittstelle zur Verfügung. Wenn protocols leer ist oder A2A_AGENT fehlt, kann der Agent nicht über A2A aufgerufen werden.

Das vollständige Schema der Agent-Ressource finden Sie in der projects.locations.agents REST API-Referenz.

Schritt 2: Agentenkarte abrufen

Die Agentenkarte enthält Metadaten, die die Identität, Beschreibung und Ein-/Ausgabefunktionen des Agenten beschreiben. Senden Sie eine HTTP-GET-Anfrage an den Pfad /v1/card, der an die A2A-Endpunkt-URL des Agenten angehängt ist, um die Karte abzurufen:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"A2A_ENDPOINT_URL/v1/card"

Beispiel für die Antwortnutzlast:

{
  "name": "My Agent",
  "description": "What the agent does.",
  "url": "A2A_ENDPOINT_URL",
  "capabilities": {},
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "preferredTransport": "HTTP+JSON"
}

Hinweis: Fragen Sie /v1/card an. Alternative Pfadvarianten wie /v1:getCard, /v1/getCard oder /.well-known/agent-card.json geben bei der HTTP+JSON-Protokollbindung einen HTTP-Fehler 404 Not Found zurück.

Schritt 3: Nachricht senden

Senden Sie eine POST-Anfrage an /v1/message:send, um eine Nutzeranfrage an den Agenten zu senden. Der Anfragetext muss dem A2A-Nachrichtenschema entsprechen. Dazu muss role auf ROLE_USER gesetzt sein, ein content-Array mit Textteilen und eine eindeutig generierte messageId enthalten:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"A2A_ENDPOINT_URL/v1/message:send" \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "content": [
        {
          "text": "What can you help me with?"
        }
      ],
      "messageId": "UNIQUE_UUID_STRING"
    }
  }'

In der Antwortnutzlast wird die Antwort des Agenten im message-Objekt zurückgegeben:

{
  "message": {
    "contextId": "projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/sessions/SESSION_ID",
    "role": "ROLE_AGENT",
    "content": [
      {
        "text": "I am an AI assistant..."
      }
    ]
  }
}

Verketten Sie die Textstrings in content[].text, um die vollständige Antwort anzuzeigen. Wenn Sie die Unterhaltung in derselben Sitzung fortsetzen möchten, speichern Sie den zurückgegebenen contextId-String und geben Sie ihn in Ihrer nächsten Anfrage als message.contextId an.

Das vollständige Schema der Nachrichtennutzlast finden Sie in der A2A message:send REST API-Referenz.

Antworten inkrementell streamen

Senden Sie für die Streamingausgabe eine POST-Anfrage mit einem identischen Inhalt der Nachricht an /v1/message:stream:

curl -N -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"A2A_ENDPOINT_URL/v1/message:stream" \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "content": [
        {
          "text": "Say hello."
        }
      ],
      "messageId": "UNIQUE_UUID_STRING"
    }
  }'

Der Endpunkt gibt ein JSON-Array mit gestreamten Chunk-Objekten über HTTP zurück. Hängen Sie die content[].text-Fragmente sequenziell an, sobald sie eintreffen. Gestreamte Chunks enthalten auch metadata.sessionInfo und metadata.assistToken.

Die Spezifikation der Streamingnutzlast finden Sie in der A2A message:stream REST API-Referenz.

A2A-Endpunkt mit Python aufrufen

Dieses Python-Skript löst einen A2A-Endpunkt in der Agent Registry auf und sendet eine Nachricht mit Roh-HTTP-Anfragen:

# Install dependencies: pip install google-auth requests
import uuid
import google.auth
from google.auth.transport.requests import AuthorizedSession

# TODO(developer): Replace placeholder values with your project ID and location.
project_id = "PROJECT_ID"
location = "LOCATION"          # Registry location (for example: "us" or "eu")
target_display_name = "My Agent"
query_text = "What can you help me with?"

# Initialize credentials and authorized session
creds, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
session = AuthorizedSession(creds)

# Step 1: Resolve the A2A endpoint URL from the Agent Registry
registry_url = (
    f"https://agentregistry.googleapis.com/v1/"
    f"projects/{project_id}/locations/{location}/agents"
)
response = session.get(registry_url)
response.raise_for_status()
agents = response.json().get("agents", [])

def get_a2a_url(agent_resource):
    for proto in agent_resource.get("protocols") or []:
        if proto.get("type") == "A2A_AGENT":
            for iface in proto.get("interfaces", []):
                if iface.get("protocolBinding") == "HTTP_JSON":
                    return iface.get("url")
    return None

target_agent = next(
    (a for a in agents if a.get("displayName") == target_display_name),
    None
)
if not target_agent:
    raise SystemExit(f"Agent '{target_display_name}' not found in registry.")

endpoint_url = get_a2a_url(target_agent)
if not endpoint_url:
    raise SystemExit("Target agent does not publish an HTTP_JSON A2A endpoint.")

# Step 2: Fetch and verify the agent card
card_resp = session.get(f"{endpoint_url}/v1/card")
card_resp.raise_for_status()
card = card_resp.json()
print("Resolved Agent:", card.get("name"))

# Step 3: Send an A2A message
body = {
    "message": {
        "role": "ROLE_USER",
        "content": [{"text": query_text}],
        "messageId": str(uuid.uuid4()),
    }
}
send_resp = session.post(f"{endpoint_url}/v1/message:send", json=body)
send_resp.raise_for_status()

reply_message = send_resp.json().get("message", {})
full_reply_text = "".join(
    part.get("text", "") for part in reply_message.get("content", [])
)
print("Agent Reply:", full_reply_text)

Orchestrierung mit dem ADK vereinfachen

Das Agent Development Kit (ADK) löst Registry-Endpunkte automatisch auf und bindet Remote-A2A-Agenten als Sub-Agenten ein:

from google.adk.integrations.agent_registry import AgentRegistry

# Initialize registry client
registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION")

# Resolve remote A2A agent directly by resource name
remote_agent = registry.get_remote_a2a_agent(
    agent_name="agents/AGENT_RESOURCE_ID"
)

Hinweis: Für diese Integration ist google-adk[a2a]>=1.29.0 erforderlich. Weitere Informationen finden Sie unter Endpunkte auflösen und Orchestratoren erstellen.

Zusätzliche Hinweise

Für A2A-Endpunkte gilt Folgendes:

• Strikte Pfadbenennung: Für HTTP+JSON-Bindungen werden nur GET {url}/v1/card, POST {url}/v1/message:send, und POST {url}/v1/message:stream unterstützt.
• Strikte Schemavalidierung: Wenn Sie nur "user" als Rolle übergeben, wird ein HTTP-Fehler 400 Bad Request zurückgegeben. Sie müssen den Enum-String "ROLE_USER" übergeben. Ebenso muss sich der Nachrichtentext im content-Array und nicht in parts befinden und messageId ist unbedingt erforderlich.
• Fehler beim Aufrufen von Nicht-A2A-Agenten: Wenn ein Agent keinen A2A_AGENT-Protokolleintrag in der Registry hat (z. B. bestimmte vordefinierte oder verwaltete Agenten), gibt der Aufruf von getCard für seine Proxy-URL 501 UNIMPLEMENTED zurück ("... wird noch nicht unterstützt") und der Aufruf von message:send gibt 400 INVALID_ARGUMENT zurück ("Agent wird nicht unterstützt").
• Projektnummer in der URL: Die Registry gibt eine A2A-URL zurück, die die Projektnummer und nicht die Projekt-ID enthält. Ändern Sie diesen numerischen String nicht, wenn Sie HTTP-Anfragen stellen.

Fehlerbehebung

In der folgenden Tabelle finden Sie Informationen zur Fehlerbehebung bei häufigen A2A-Endpunktfehlern:

Symptom	Wahrscheinliche Ursache	Lösung
HTTP 404 bei getCard Anfrage	Falscher Pfadalias (z. B. /v1:getCard oder /.well-known/agent-card.json).	Senden Sie die GET-Anfrage ausschließlich an GET {url}/v1/card.
HTTP 400 *"Unknown name 'parts'"*	Alte oder generative KI-Client-Body-Formatierung.	Platzieren Sie Textstrings in content und nicht in parts.
HTTP 400 Ungültiger Enum-Wert für role	Übergabe von Kleinbuchstaben "user" oder "user_role".	Setzen Sie message.role genau auf "ROLE_USER".
HTTP 501 *"is not supported yet"*	getCard für einen Agenten aufgerufen, der keine A2A-Schnittstelle veröffentlicht.	Prüfen Sie vor dem Aufruf das Array protocols der Registry-Ressource, um die A2A_AGENT-Unterstützung zu bestätigen.
HTTP 400 *"Unsupported agent"*	message:send für einen Nicht-A2A-Agenten aufgerufen.	Wählen Sie einen Agenten aus, dessen Registry-Definition eine aktive A2A_AGENT-Protokollbindung enthält.
HTTP 401 oder HTTP 403 Permission Denied	Fehlende OAuth-Bereiche, fehlende IAM-Rollen oder fehlender Header für das Kontingentprojekt.	Prüfen Sie die IAM-Rollen des Aufrufers (agentregistry.viewer und assistants.assist), prüfen Sie den Bereich cloud-platform und übergeben Sie -H "X-Goog-User-Project: PROJECT_ID", wenn Sie ADC verwenden.

Weitere Informationen

• Agent Registry – Übersicht
• In der Agent Registry nach Agenten und Tools suchen
• Endpunkte auflösen und Orchestratoren erstellen (ADK)
• REST API-Referenz für A2A-Nachrichten senden