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

Manuelle Registrierung verwenden

Für Agenten, die außerhalb von Google Cloudgehostet werden, auf nicht unterstützten Laufzeiten ausgeführt werden oder in verschiedenen Google Cloud Projekten bereitgestellt werden, ist eine manuelle Registrierung in Agent Registry erforderlich. In diesem Dokument wird beschrieben, wie Sie Agenten manuell in Agent Registry registrieren.

Warnung: Diese Funktion wird in den us und eu Multi-Region Standorten nicht unterstützt. Sie müssen eine unterstützte Region oder den Standort global verwenden. Weitere Informationen finden Sie unter Agent Registry-Standorte.

Hinweis

Richten Sie Agent Registry ein, bevor Sie beginnen. Sie benötigen die Projekt-ID um diese Aufgaben auszuführen.

Wenn Sie die Google Cloud CLI-Befehle in diesem Dokument verwenden möchten, müssen Sie Ihre gcloud CLI-Umgebung eingerichtet haben.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum manuellen Registrieren von Agenten in Agent Registry benötigen:

Zum Registrieren von Agenten in Agent Registry: Agent Registry API Editor (roles/agentregistry.editor)
Für die projektübergreifende Registrierung, um auf Agentenmetadaten in einem Remote-Projekt zuzugreifen: Agent Registry API Viewer (roles/agentregistry.viewer)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Sie benötigen keine zusätzlichen Berechtigungen, wenn der Endpunkt oder die Agentenkarte des Agenten über öffentliche Standard-URLs zugänglich ist oder über vorkonfigurierte Anmeldedaten authentifiziert wird.

A2A-konformen Agenten registrieren

Wenn Ihr Remote-Agent die Agent2Agent-Spezifikation (A2A) implementiert, leiten Sie Agent Registry zur agent-card.json-Nutzlast des Agenten weiter. Die Registry synchronisiert die Agentenkarte automatisch und indexiert die verfügbaren A2A-Fähigkeiten des Agenten zur Erkennung.

So registrieren Sie den Agenten:

Console

Rufen Sie in der Google Cloud Console Agent Registry auf:

Zu Agent Registry
Wählen Sie in der Projektauswahl das Google Cloud Projekt aus, in dem Sie Agent Registry eingerichtet haben.
Wählen Sie den Tab Agenten aus.
Klicken Sie auf Agent hinzufügen.
Geben Sie im Bereich Agentendetails die folgenden Details ein:
- Typ: Wählen Sie A2A aus.
- Region: Wählen Sie den geografischen Standort aus, an dem Sie den Agenten registrieren möchten.
Wählen Sie eine der folgenden Optionen aus:
- Wenn Sie den Agenten mit seinem Ressourcen-URI registrieren möchten, wählen Sie den Von URI Tab aus und geben Sie eine gültige URL in das URI Feld ein. Klicken Sie dann auf Importieren , um die Agentenkarte von der URL abzurufen.
- Wenn Sie den Inhalt der Agentenkarte kopieren und einfügen möchten, wählen Sie den Tab JSON einfügen aus und fügen Sie den vollständigen Inhalt Ihrer agent-card.json-Datei ein.
Klicken Sie auf Speichern.

gcloud

Wenn Sie einen A2A-Agenten registrieren möchten, speichern Sie die Agentenkarte des Agenten als lokale JSON-Datei, z. B. agent-card.json, und gehen Sie so vor:

gcloud agent-registry services create AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content=@agent-card.json

Die maximale Dateigröße für die Spezifikationsdatei beträgt 10 KB.

Ersetzen Sie Folgendes:

AGENT_NAME: Der Name, den Sie Ihrem Agenten geben möchten, z. B. my-support-agent.
PROJECT_ID: Die Projekt-ID.
REGION: Die Region , in der Sie den Agenten registrieren möchten. Wenn Sie keine bestimmte Region verwenden möchten, verwenden Sie den Wert global.
DISPLAY_NAME: Der für Menschen lesbare Name, den Sie Ihrem Agenten geben möchten, z. B. Support Agent.

Terraform

Konfigurieren Sie die Ressource google_agent_registry_service, um einen A2A-konformen Agenten zu registrieren. Geben Sie den Block agent_spec mit dem Typ A2A_AGENT_CARD und dem content an, der Ihre JSON-Nutzlast der Agentenkarte darstellt:

resource "google_agent_registry_service" "a2a_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"

  agent_spec {
    type    = "A2A_AGENT_CARD"
    content = jsonencode({
      schemaVersion = "v1"
      displayName   = "DISPLAY_NAME"
      description   = "A custom support agent registered using Terraform."
      skills = [
        {
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
        }
      ]
    })
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.a2a_agent.registry_resource
}

Ersetzen Sie Folgendes:

REGION: Die Region, in der Sie den Agenten registrieren.
AGENT_NAME: Der eindeutige Name, den Sie Ihrem Agenten geben möchten, z. B. my-support-agent.
DISPLAY_NAME: Der für Menschen lesbare Name, den Sie Ihrem Agenten geben möchten, z. B. Support Agent.

Standard-REST-Agenten registrieren

Standard-REST-Agenten können nach Name und Beschreibung gesucht werden, haben aber keine durchsuchbaren A2A-Fähigkeiten , es sei denn, sie verwenden das A2A Protokoll.

Wenn Sie einen Remote-Agenten registrieren möchten, der die A2A-Spezifikation nicht implementiert, z. B. einen Standard-REST- oder SaaS-API-Endpunkt, erstellt die Agent Registry API eine Service-Ressource ohne Spezifikation des Agentenprotokolls.

So registrieren Sie den Agenten:

Console

Rufen Sie in der Google Cloud Console Agent Registry auf:

Zu Agent Registry
Wählen Sie in der Projektauswahl das Google Cloud Projekt aus, in dem Sie Agent Registry eingerichtet haben.
Wählen Sie den Tab Agenten aus.
Klicken Sie auf Agent hinzufügen.
Geben Sie im Bereich Agentendetails die folgenden Details ein:
- Typ: Wählen Sie Nicht-A2A aus.
- Name: Geben Sie einen für Menschen lesbaren Anzeigenamen für Ihren Agenten ein, z. B. Travel Agent.
- Beschreibung: Geben Sie eine Beschreibung der Fähigkeiten des Agenten ein, z. B. A test agent that plans travel itineraries.
- Region: Wählen Sie den geografischen Standort aus, an dem Sie den Agenten registrieren möchten.
- Endpunkt: Geben Sie den Endpunkt ein, an dem der Agent gehostet wird.
Klicken Sie auf Speichern.

gcloud

Optional können Sie die definierte HTTP/JSON-Endpunktschnittstelle mit dem Flag --interfaces angeben, damit die Registry eine Verbindung zum Agenten herstellt.

So registrieren Sie einen Standard-REST-Agenten:

gcloud agent-registry services create AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=no-spec \
  --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

Ersetzen Sie Folgendes:

AGENT_NAME: Der Name, den Sie Ihrem Agenten geben möchten, z. B. my-remote-rest-agent.
PROJECT_ID: Die Projekt-ID.
REGION: Die Registry-Region.
DISPLAY_NAME: Der für Menschen lesbare Name, den Sie Ihrem Agenten geben möchten, z. B. Remote REST Agent.
ENDPOINT_URL: Die API-Endpunkt-URL des Agenten, z. B. https://api.remote-service.com/v1/agents/1234.
PROTOCOL: Die Protokollbindung für den Endpunkt. Gültige Werte sind http-json, grpc oder jsonrpc.

Terraform

Konfigurieren Sie die Ressource google_agent_registry_service mit agent_spec auf den Typ NO_SPEC gesetzt und definieren Sie die Verbindungen der Endpunktschnittstelle, um einen Standard-REST-Agenten zu registrieren:

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "A standard REST agent registered using Terraform."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.rest_agent.registry_resource
}

Ersetzen Sie Folgendes:

REGION: Die Region, in der Sie den Agenten registrieren.
AGENT_NAME: Der eindeutige Name, den Sie Ihrem Agenten geben möchten, z. B. my-remote-rest-agent.
DISPLAY_NAME: Der für Menschen lesbare Name, den Sie Ihrem Agenten geben möchten, z. B. Remote REST Agent.
ENDPOINT_URL: Die API-Endpunkt-URL des Agenten, z. B. https://api.remote-service.com/v1/agents/1234.
PROTOCOL: Die Protokollbindung für den Endpunkt. Gültige Werte sind HTTP_JSON, GRPC oder JSONRPC.

Agenten aus einem anderen Projekt registrieren

Wenn Ihre Organisation Agenten in mehreren Google Cloud Projekten bereitstellt und ein zentrales Agenten-Gateway verwendet, um den ausgehenden Traffic zu verwalten, können Sie Agenten aus Spoke- oder Workload Projekten im zentralen Agent Registry-Katalog registrieren.

Da bei der automatischen Registrierung nur Ressourcen erkannt werden, die im selben Projekt erstellt wurden, müssen Sie jeden Remote-Agenten manuell in der Registry des zentralen Governance-Projekts registrieren.

Überlegungen zur projektübergreifenden Registrierung

Bevor Sie Agenten in verschiedenen Projekten registrieren, sollten Sie Folgendes beachten:

Kompatible Standorte: Die Agent Registry-Instanz, das Agenten-Gateway und die Agentenendpunkte müssen sich in derselben geografischen Region oder am Standort global befinden.
Einschränkung der automatischen Erkennung: Die automatische projektübergreifende Erkennung wird nicht unterstützt. Sie müssen jeden Remote-Agenten manuell registrieren.
Lebenszyklusverwaltung: Manuelle Einträge in Agent Registry werden nicht automatisch aktualisiert oder gelöscht, wenn Änderungen im Remote-Projekt auftreten. Sie müssen den Lebenszyklus dieser Einträge in der zentralen Registry verwalten, wenn Remote-Agenten geändert oder entfernt werden.
Nur Ausgabemodus: Die projektübergreifende Governance mit Agenten-Gateway wird nur für Agent-to-Anywhere -Gateways (Ausgabe) unterstützt. Für Client-to-Agent-Eingabe-Gateways müssen sich der Agent und das Gateway im selben Projekt befinden.

Remote-Agenten registrieren

So registrieren Sie einen Agenten manuell aus einem anderen Projekt:

Console

Rufen Sie in der Google Cloud Console Agent Registry auf:

Zu Agent Registry
Wählen Sie in der Projektauswahl das zentrale Governance Google Cloud Projekt aus, in dem Sie den Agenten registrieren möchten.
Wählen Sie den Tab Agenten aus.
Klicken Sie auf Agent hinzufügen.
Geben Sie im Bereich Agentendetails die folgenden Details ein:
- Typ: Wählen Sie A2A aus, wenn der Remote-Agent das A2A Protokoll implementiert, oder Nicht-A2A für einen Standard-REST-Endpunkt.
- Region: Wählen Sie die Region aus, die Ihrem zentralen Gateway und der Bereitstellung des Remote- Agenten entspricht.
Geben Sie den Agentenendpunkt an:
- Wählen Sie für A2A-Agenten Von URI aus und geben Sie die URL der Agentenkarte des Remote-Agenten ein oder wählen Sie JSON einfügen aus und fügen Sie den Inhalt von agent-card.json ein.
- Geben Sie für Nicht-A2A-Agenten die Endpunkt -URL des Remote-Agenten ein.
Klicken Sie auf Speichern.

gcloud

A2A-Agent: Führen Sie den folgenden Befehl im zentralen Governance Projekt aus, um einen A2A-Agenten aus einem anderen Projekt mit der gcloud CLI zu registrieren:

gcloud agent-registry services create AGENT_NAME \
  --project=CENTRAL_PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content=@agent-card.json

REST-Agent: Führen Sie den folgenden Befehl im zentralen Governance-Projekt aus, um einen Standard-REST-Agenten aus einem anderen Projekt zu registrieren:

gcloud agent-registry services create AGENT_NAME \
  --project=CENTRAL_PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=no-spec \
  --interfaces=url=REMOTE_ENDPOINT_URL,protocolBinding=PROTOCOL

Ersetzen Sie Folgendes:

AGENT_NAME: Der Name für Ihren Agenten in der zentralen Registry, z. B. remote-support-agent.
CENTRAL_PROJECT_ID: Die Projekt-ID des zentralen Governance-Projekts.
REGION: Die Region, in der Sie den Agenten registrieren.
DISPLAY_NAME: Der für Menschen lesbare Name für den Agenten, z. B. Remote Support Agent.
REMOTE_ENDPOINT_URL: Die Endpunkt-URL des Agenten, der im Remote-Projekt ausgeführt wird, z. B. https://<var>AGENT_SERVICE_NAME</var>-<var>HASH</var>.<var>REGION</var>.run.app.
PROTOCOL: Die Protokollbindung für den Endpunkt. Gültige Werte sind http-json, grpc oder jsonrpc.

Terraform

Konfigurieren Sie die Ressource google_agent_registry_service und geben Sie das zentrale Projekt an, um einen Remote-Agenten in einem zentralen Governance-Projekt mit Terraform zu registrieren:

resource "google_agent_registry_service" "remote_agent" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Remote agent registered from project REMOTE_PROJECT_ID."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "REMOTE_ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.remote_agent.registry_resource
}

Ersetzen Sie Folgendes:

CENTRAL_PROJECT_ID: Die Projekt-ID des zentralen Governance-Projekts.
REGION: Die Region, in der Sie den Agenten registrieren.
AGENT_NAME: Der eindeutige Name für Ihren Agenten in der Registry, z. B. remote-support-agent.
DISPLAY_NAME: Der für Menschen lesbare Name für den Agenten, z. B. Remote Support Agent.
REMOTE_PROJECT_ID: Die Projekt-ID, in der der Agent gehostet wird.
REMOTE_ENDPOINT_URL: Die Endpunkt-URL des Agenten, der im Remote-Projekt ausgeführt wird.
PROTOCOL: Die Protokollbindung für den Endpunkt. Gültige Werte sind HTTP_JSON, GRPC oder JSONRPC.

Registrierung bestätigen

Prüfen Sie nach der Registrierung Ihres Agenten, ob Agent Registry den Service erfolgreich verarbeitet und die entsprechende Agent-Ressource erstellt hat:

Console

Rufen Sie in der Google Cloud Console Agent Registry auf:

Zu Agent Registry
Wählen Sie in der Projektauswahl das Google Cloud Projekt aus, in dem Sie Agent Registry eingerichtet haben.
Wählen Sie den Tab Agenten aus.

Auf der Seite wird eine Liste aller registrierten Agenten und ihrer Details angezeigt.

gcloud

gcloud agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION

Wenn Sie mehrere Agenten haben oder die Registrierung eines einzelnen Agenten bestätigen möchten, können Sie die Liste nach den Metadaten des Agenten filtern:

gcloud agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION \
  --filter="FILTER_EXPRESSION"

Ersetzen Sie Folgendes:

PROJECT_ID: Die Projekt-ID.
REGION: Die Region , in der Sie den Agenten registrieren möchten. Wenn Sie keine bestimmte Region verwenden möchten, verwenden Sie den Wert global.
FILTER_EXPRESSION: Der Filterausdruck für die Agenten, die Sie filtern möchten. Wenn Sie beispielsweise nach Anzeigenamen filtern möchten, können Sie verwenden displayName='DISPLAY_NAME'. Wenn Sie nach der global eindeutigen ID (URN) filtern möchten, können Sie agentId='urn:agent:AGENT_URN' verwenden.

Terraform

Verweisen Sie mit der Datenquelle google_agent_registry_agent in anderen Terraform-Konfigurationen auf Ihren registrierten Agenten:

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  filter = "displayName=\"DISPLAY_NAME\""
}

output "agent_urn" {
  value = data.google_agent_registry_agent.my_agent.urn
}

Ersetzen Sie Folgendes:

REGION: Die Registry-Region.
DISPLAY_NAME: Der für Menschen lesbare Anzeigename des Agenten.

Nächste Schritte

Informationen zum Verwalten registrierter Agenten .
Informationen zu automatischer Registrierung, der empfohlenen Methode zum Registrieren von Agenten, die in verwalteten Laufzeiten bereitgestellt werden

Manuelle Registrierung verwenden Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Hinweis

Erforderliche Rollen

A2A-konformen Agenten registrieren

Console

gcloud

Terraform

Standard-REST-Agenten registrieren

Console

gcloud

Terraform

Agenten aus einem anderen Projekt registrieren

Überlegungen zur projektübergreifenden Registrierung

Remote-Agenten registrieren

Console

gcloud

Terraform

Registrierung bestätigen

Console

gcloud

Terraform

Nächste Schritte

Manuelle Registrierung verwenden