Endpunkte registrieren

In der Agent Registry stellt ein Endpunkt eine Ziel-URL dar, in der Regel eine REST API, auf die Ihre Agenten zugreifen. Wenn Sie diese Ziele als verwaltete Agentenkomponenten in der Agent Registry registrieren, können Sie zentral steuern, mit welchen externen Endpunkten sich Ihre Agentenflotte verbinden kann.

In diesem Dokument wird erläutert, wie Sie externe Endpunkte explizit in der Registry registrieren.

Hinweis

Richten Sie die Agent Registry ein, bevor Sie beginnen. Sie benötigen Ihre 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 Agent Registry API Editor (roles/agentregistry.editor) IAM-Rolle für das Projekt zu erteilen, um die Berechtigungen zu erhalten, die Sie zum Registrieren von Endpunkten in der Agent Registry benötigen. 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.

Endpunkt registrieren

Da Endpunkte benutzerdefinierte, externe Ziele sind, müssen Sie sie manuell registrieren, um sie der Agent Registry hinzuzufügen:

Console

  1. Rufen Sie in der Google Cloud Console die Seite Agent Registry auf:

    Zur Agent Registry

  2. Wählen Sie in der Projektauswahl das Google Cloud Projekt aus, in dem Sie die Agent Registry eingerichtet haben.

  3. Wählen Sie den Tab Endpunkte aus.

  4. Klicken Sie auf Endpunkt hinzufügen.

  5. Geben Sie im Bereich Endpunktdetails den Anzeigenamen, eine Beschreibung, die geografische Region und die Ziel-URL ein.

    Optional können Sie in diesem Bereich auf Verbindung testen klicken, um die Verbindung zur Ziel-URL zu testen.

  6. Klicken Sie auf Speichern.

gcloud

Erstellen Sie eine Service-Ressource mit dem endpoint-spec-type von no-spec.

Registrieren Sie den Endpunkt und definieren Sie die Details der Schnittstellenverbindung:

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

Ersetzen Sie Folgendes:

  • ENDPOINT_NAME: Der Name, den Sie Ihrem Endpunkt geben möchten, z. B. my-external-api.
  • PROJECT_ID: Die Projekt-ID.
  • REGION: Die Registry-Region.
  • DISPLAY_NAME: Der für Nutzer lesbare Name des Endpunkts.
  • ENDPOINT_URL: Die Ziel-URL, z. B. https://api.example.com/v1/data.
  • PROTOCOL: Die Protokollbindung für die Schnittstelle. Gültige Werte sind http-json, grpc oder jsonrpc.

Nachdem die Service Ressource erstellt wurde, generiert die Agent Registry automatisch eine schreibgeschützte Endpoint Ressource auf der Consumerseite, die von Agenten und Orchestratoren erkannt und verwendet werden kann.

Terraform

Konfigurieren Sie die Ressource google_agent_registry_service mit dem Block endpoint_spec, um einen externen Endpunkt zu registrieren:

resource "google_agent_registry_service" "endpoint" {
  location     = "REGION"
  service_id   = "ENDPOINT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "An external REST API registered using Terraform."

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

  endpoint_spec {
    type = "NO_SPEC"
  }
}

output "endpoint_resource_name" {
  description = "The generated read-only Endpoint resource name."
  value       = google_agent_registry_service.endpoint.registry_resource
}

Ersetzen Sie Folgendes:

  • REGION: Die Registry-Region.
  • ENDPOINT_NAME: Der eindeutige Name, den Sie Ihrem Endpunkt geben möchten, z. B. my-external-api.
  • DISPLAY_NAME: Der für Nutzer lesbare Name des Endpunkts.
  • ENDPOINT_URL: Die Ziel-URL, z. B. https://api.example.com/v1/data.
  • PROTOCOL: Die Protokollbindung für die Schnittstelle. Gültige Werte sind HTTP_JSON, GRPC oder JSONRPC.

Zusammengesetzten Google APIs-Endpunkt registrieren

In einer projektübergreifenden Architektur hostet ein zentrales Governance-Projekt eine freigegebene Infrastruktur wie die Agent Registry und das Agent Gateway. In einzelnen Workload-Projekten werden Agent-Compute-Instanzen gehostet.

Wenn Sie den Agent-Traffic im Egress-Modus über das Agent Gateway leiten, wird der ausgehende Netzwerk-Traffic standardmäßig blockiert. Damit Agenten in Workload-Projekten mit wichtigen Google Cloud APIs kommunizieren können, können Sie mehrere API-Schnittstellen in einem einzigen zusammengesetzten Service Endpunkt im zentralen Governance-Projekt gruppieren.

Durch das Gruppieren von Schnittstellen in einem einzigen Endpunkt wird die Richtlinienverwaltung vereinfacht, da Sie eine einzelne IAP-Richtlinienbindung für die gesamte Suite der wichtigsten Google APIs verwalten können.

So registrieren Sie einen zusammengesetzten Google APIs-Endpunkt:

gcloud

Registrieren Sie den Endpunkt mit mehreren Schnittstellen-URLs im zentralen Governance-Projekt:

gcloud agent-registry services create SERVICE_NAME \
  --project=CENTRAL_PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION" \
  --endpoint-spec-type=no-spec \
  --interfaces=protocolBinding=jsonrpc,url=API_URL \
  --interfaces=protocolBinding=jsonrpc,url=ADDITIONAL_API_URL

Ersetzen Sie Folgendes:

  • SERVICE_NAME: Die Kennung für den Dienst, z. B. core-gapi-services.
  • CENTRAL_PROJECT_ID: Die Projekt-ID des zentralen Governance-Projekts, in dem die Agent Registry und das Agent Gateway gehostet werden.
  • REGION: Die Region , in der sich Ihr Gateway und Ihre Registry befinden.
  • DISPLAY_NAME: Der für Nutzer lesbare Name, z. B. Core Google APIs.
  • DESCRIPTION: Eine kurze Beschreibung, z. B. Essential Google APIs for agent operations.
  • API_URL: Die URL der primären Google API, z. B. https://telemetry.googleapis.com.
  • ADDITIONAL_API_URL: Wiederholen Sie das Flag --interfaces für jede zusätzliche Google API-URL oder -Variante, die von Ihren Agenten benötigt wird, z. B. https://cloudresourcemanager.googleapis.com, https://iamcredentials.googleapis.com, https://agentregistry.googleapis.com oder regionale und mTLS-Varianten wie https://telemetry.mtls.googleapis.com.

Terraform

Wenn Sie den zusammengesetzten Google APIs-Endpunkt mit Terraform registrieren möchten, definieren Sie die Ressource google_agent_registry_service mit mehreren Blöcken interfaces:

resource "google_agent_registry_service" "core_gapi_services" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "SERVICE_NAME"
  display_name = "DISPLAY_NAME"
  description  = "DESCRIPTION"

  endpoint_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "API_URL"
    protocol_binding = "JSONRPC"
  }

  # Add an interfaces block for each additional Google API URL
  interfaces {
    url              = "ADDITIONAL_API_URL"
    protocol_binding = "JSONRPC"
  }
}

Ersetzen Sie Folgendes:

  • CENTRAL_PROJECT_ID: Die Projekt-ID des zentralen Governance-Projekts.
  • REGION: Die Registry-Region.
  • SERVICE_NAME: Die Dienst-ID.
  • DISPLAY_NAME: Der für Nutzer lesbare Name.
  • DESCRIPTION: Die Dienstbeschreibung.
  • API_URL: Die URL der primären Google API, z. B. https://telemetry.googleapis.com.
  • ADDITIONAL_API_URL: Wiederholen Sie den Block interfaces für jede zusätzliche Google API-URL oder -Variante, die von Ihren Agenten benötigt wird, z. B. https://cloudresourcemanager.googleapis.com, https://iamcredentials.googleapis.com, https://agentregistry.googleapis.com oder regionale und mTLS-Varianten wie https://telemetry.mtls.googleapis.com.

Nächste Schritte