Endpunkte registrieren

Mit der Agent Registry können Sie Ziel-URLs wie externe REST APIs manuell als verwaltete Endpunkte registrieren. So können Sie zentral steuern, mit welchen Zielen Ihre KI-Agenten eine Verbindung herstellen können.

Die Endpunktregistrierung wird an den multiregionalen Standorten us und eu nicht unterstützt. Sie müssen eine unterstützte Region oder den Standort global verwenden. Weitere Informationen finden Sie unter Agent Registry-Standorte.

Hinweis

  1. Agent Registry einrichten

  2. Rufen Sie die Projekt-ID für das Governance-Projekt ab, in dem die Agent Registry aktiviert ist.

  3. Wenn Sie die Google Cloud CLI-Befehle in diesem Dokument verwenden möchten, richten Sie Ihre gcloud CLI-Umgebung ein.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Agent Registry API Editor (roles/agentregistry.editor) für das Governance-Projekt zuzuweisen, in dem Agent Registry aktiviert ist, um die Berechtigungen zu erhalten, die Sie zum Registrieren von Endpunkten in 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 mit der manuellen Registrierung zur Agent Registry hinzufügen:

Console

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

    Zur Agent Registry

  2. Wählen Sie in der Projektauswahl das Google Cloud -Projekt aus, in dem Sie 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

Die von Ihnen verwendeten Spezifikations-Flags bestimmen, zu welcher Ressourcensammlung Ihre Komponente gehört. Eine vollständige Zuordnung von Flags zu Ressourcensammlungen finden Sie unter [Dienstressourcen und Erkennungsressourcen](/agent-registry/data-model#service-resources).

Wenn Sie Ihren Endpunkt zur Agent Registry hinzufügen möchten, erstellen Sie eine Service-Ressource mit dem Befehl gcloud agent-registry services create und dem Flag --endpoint-spec-type, das auf no-spec gesetzt ist:

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 dem Endpunkt geben möchten, z. B. my-external-api. Der Name muss 4 bis 63 Zeichen lang sein und darf nur Kleinbuchstaben, Ziffern und Bindestriche enthalten.
  • PROJECT_ID: Projekt-ID.
  • REGION: die Registry-Region.
  • DISPLAY_NAME: der menschenlesbare Name des Endpunkts, z. B. My External API.
  • 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, die von Agenten und Orchestratoren gefunden und verwendet werden kann.

Terraform

Der von Ihnen konfigurierte Spezifikationsblock bestimmt, zu welcher Ressourcensammlung Ihre Komponente gehört. Eine vollständige Zuordnung von Spezifikationen zu Ressourcensammlungen finden Sie unter [Dienstressourcen und Erkennungsressourcen](/agent-registry/data-model#service-resources).

Wenn Sie einen externen Endpunkt registrieren möchten, konfigurieren Sie die Ressource google_agent_registry_service mit dem Block endpoint_spec:

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. Der Name muss 4 bis 63 Zeichen lang sein und darf nur Kleinbuchstaben, Ziffern und Bindestriche enthalten.
  • DISPLAY_NAME: der menschenlesbare Name des Endpunkts, z. B. My External API.
  • 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 die gemeinsam genutzte Infrastruktur wie die Agent Registry und das Agent Gateway, während separate Google Cloud -Projekte die Agent-Compute-Instanzen hosten.

Wenn Sie KI-Agenten-Traffic im Modus für ausgehenden Traffic über Agent Gateway weiterleiten, wird ausgehender Netzwerkverkehr standardmäßig blockiert. Damit Agenten in separaten Google Cloud -Projekten mit wichtigenGoogle Cloud -APIs kommunizieren können, können Sie mehrere API-Schnittstellen in einer einzigen zusammengesetzten Service-Ressource im zentralen Governance-Projekt gruppieren.

Durch die Gruppierung von Schnittstellen in einem einzigen Endpunkt wird die Richtlinienverwaltung vereinfacht, da Sie eine einzige Identity-Aware Proxy-Richtlinienbindung (IAP) 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 mit dem Befehl gcloud agent-registry services create:

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. Der Name muss 4 bis 63 Zeichen lang sein und darf nur Kleinbuchstaben, Ziffern und Bindestriche enthalten.
  • CENTRAL_PROJECT_ID: die Projekt-ID des zentralen Governance-Projekts, in dem Agent Registry und Agent Gateway gehostet werden.
  • REGION: die Region, in der sich Ihr Gateway und Ihre Registry befinden.
  • DISPLAY_NAME: der menschenlesbare 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 Agents 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 interfaces-Blöcken:

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, z. B. core-gapi-services. Der Name muss zwischen 4 und 63 Zeichen lang sein und darf nur Kleinbuchstaben, Ziffern und Bindestriche enthalten.
  • DISPLAY_NAME: der menschenlesbare Name, z. B. Core Google APIs.
  • DESCRIPTION: die Beschreibung des Endpunkts.
  • 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 Agents 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