Agenten über den registrierten A2A-Endpunkt aufrufen

Agent2Agent-Agenten (A2A) in der Agent Registry stellen Protokollschnittstellen bereit, die eine Endpunkt-URL und eine Protokollbindung (z. B. HTTP_JSON) enthalten. Sie können die URL eines Agenten in der Registry finden, um seine A2A-Methoden über benutzerdefinierte Orchestratoren oder Clients aufzurufen.

Auf einen Blick

Spezifikation	Details
Discovery API	agentregistry.googleapis.com (v1)
Aufruf-Proxy-Host	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 dem aufrufenden Hauptkonto die entsprechenden IAM-Berechtigungen:
   • Zum Lesen der Registry: Agent Registry Viewer (roles/agentregistry.viewer).
   • Zum Aufrufen des KI-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: Installieren Sie die Agent Development Kit (ADK)-Bibliothek, wenn Sie Remote-Agenten als programmatische Sub-Agenten einbinden möchten: pip install "google-adk[a2a]>=1.29.0".

Schritt 1: Agenten und seinen A2A-Endpunkt ermitteln

Wenn Sie einen A2A-Agenten aufrufen möchten, müssen Sie zuerst die veröffentlichten url in der Agent Registry finden. Listen Sie die KI-Agenten in Ihrem Registry-Speicherort auf (z. B. us oder eu, übergeben als Pfadparameter auf dem globalen agentregistry.googleapis.com-Host):

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 -Befehlszeile 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 KI-Agentenressource das Array protocols. Suchen Sie den Eintrag, bei dem type gleich A2A_AGENT und interfaces[].protocolBinding gleich HTTP_JSON ist. Extrahieren Sie die entsprechenden 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 den zurückgegebenen url-String unverändert. Bei Gemini Enterprise-Agenten wird der Traffic über diese URL durch den Discovery Engine-A2A-Proxy geleitet. Außerdem wird Ihre Google Cloud Projektnummer anstelle der Projekt-ID eingebettet. Nicht alle registrierten Agenten stellen eine A2A-Schnittstelle bereit. Wenn protocols leer ist oder A2A_AGENT weggelassen wird, kann der Agent nicht über A2A aufgerufen werden.

Das vollständige Schema der Agentenressource 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. Wenn Sie die Karte abrufen möchten, senden Sie eine HTTP-GET-Anfrage an den Pfad /v1/card, der an die A2A-Endpunkt-URL des Agents angehängt ist:

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

Beispiel für eine Antwortnutzlast:

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

Hinweis: Achten Sie darauf, /v1/card anzufordern. Alternative Pfadvarianten (z. B. /v1:getCard, /v1/getCard oder /.well-known/agent-card.json) geben bei der HTTP+JSON-Protokollbindung einen HTTP-404 Not Found-Fehler zurück.

Schritt 3: Nachricht senden

Wenn Sie eine Nutzeranfrage an den Agenten senden möchten, stellen Sie eine POST-Anfrage an /v1/message:send. Der Anfragetext muss dem A2A-Nachrichtenschema entsprechen. Dazu muss role auf ROLE_USER festgelegt sein, ein content-Array mit Textteilen enthalten sein und eine eindeutig generierte messageId vorhanden sein:

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 KI-Agenten im Objekt message 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 schrittweise 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 von gestreamten Chunk-Objekten über HTTP zurück. Hängen Sie die content[].text-Fragmente nacheinander an, sobald sie eintreffen. Gestreamte Chunks enthalten auch metadata.sessionInfo und metadata.assistToken.

Die Spezifikation der Streaming-Nutzlast 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 über 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 verpackt Remote-A2A-Agenten als Sub-Agenten:

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

A2A-Endpunkte haben die folgenden Verhaltensweisen:

• 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 "user" als Rolle übergeben, wird ein HTTP-400 Bad Request-Fehler zurückgegeben. Sie müssen den Enum-String "ROLE_USER" übergeben. Ebenso muss der Nachrichtentext im content-Array und nicht im parts-Array enthalten sein. messageId ist unbedingt erforderlich.
• Fehler beim Aufruf eines 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 („… wird noch nicht unterstützt“) und der Aufruf von message:send 400 INVALID_ARGUMENT („Nicht unterstützter Agent“) zurück.
• Projektnummer in URL: Die Registry gibt eine A2A-URL zurück, die die Projektnummer anstelle der 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	Verwendung eines falschen Pfad-Alias (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'"*	Verwendung der alten oder generativen KI-Client-Textformatierung.	Platzieren Sie Textstrings in content, nicht in parts.
HTTP 400 – Ungültiger Enum-Wert für role	Übergabe von "user" oder "user_role" in Kleinbuchstaben.	Setzen Sie message.role genau auf "ROLE_USER".
HTTP 501 *"is not supported yet"*	Aufruf von getCard für einen Agenten, der keine A2A-Schnittstelle veröffentlicht.	Prüfen Sie das Array protocols der Registry-Ressource, um die Unterstützung von A2A_AGENT vor dem Aufruf zu bestätigen.
HTTP 400 *"Unsupported agent"*	Aufruf von message:send für einen Nicht-A2A-Agenten.	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 Kontingentprojekt-Header.	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 Standardanmeldedaten für Anwendungen verwenden.

Weitere Informationen

• Agent Registry – Übersicht
• In der Agent Registry nach Agenten und Tools suchen
• Endpunkte auflösen und Orchestratoren erstellen (ADK)
• A2A-Nachricht:REST API-Referenz „send“