Manuelle Registrierung verwenden

Sie benötigen eine manuelle Registrierung in der Agent Registry für Agenten, die außerhalb vonGoogle Cloudgehostet werden, auf nicht unterstützten Runtimes ausgeführt werden oder in verschiedenen Google Cloud -Projekten bereitgestellt werden. In diesem Dokument wird beschrieben, wie Sie Agenten manuell in der Agent Registry registrieren.

Hinweis

Richten Sie zuerst die Agent Registry ein. Für diese Aufgaben benötigen Sie die Projekt-ID.

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

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 Agents in der Agent Registry benötigen:

  • So registrieren Sie Agents in der Agent Registry: Agent Registry API Editor (roles/agentregistry.editor)
  • Für die projektübergreifende Registrierung, um auf Agent-Metadaten 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 des Agents oder die Agent-Karte über öffentliche Standard-URLs zugänglich ist oder die Authentifizierung über vorkonfigurierte Anmeldedaten erfolgt.

A2A-konformen Agenten registrieren

Wenn Ihr Remote-KI-Agent die Agent2Agent-Spezifikation (A2A) implementiert, leiten Sie die Agent Registry direkt an die agent-card.json-Nutzlast des KI-Agenten weiter. Die Registrierung synchronisiert automatisch die Agentenkarte und indexiert die verfügbaren A2A-Skills des Agenten für die Erkennung.

So registrieren Sie den Agent:

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 die Agent Registry eingerichtet haben.

  3. Wählen Sie den Tab KI-Agents aus.

  4. Klicken Sie auf KI-Agent hinzufügen.

  5. Geben Sie im Bereich Agent details (Agentendetails) die folgenden Details ein:

    • Typ: Wählen Sie A2A aus.
    • Region: Wählen Sie den geografischen Standort aus, an dem Sie den Agent registrieren möchten.

  6. Wählen Sie eine der folgenden Optionen aus:

    • Wenn Sie den Agenten über die URL der Agentenkarte registrieren möchten, wählen Sie den Tab Über URI aus und geben Sie eine gültige URL in das Feld URI ein. Klicken Sie dann auf Importieren, um die Agent-Karte über die 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 gesamten Inhalt Ihrer agent-card.json-Datei ein.

  7. Klicken Sie auf Speichern.

gcloud

Die von Ihnen verwendeten Spezifikations-Flags bestimmen, zu welcher Ressourcensammlung Ihr Dienst gehört. Eine vollständige Zuordnung von Flags zu Ressourcensammlungen finden Sie unter API-Ressourcen.

Um einen A2A-Agenten zu registrieren, 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 menschenlesbare Name, den Sie Ihrem Agenten geben möchten, z. B. Support Agent.

Terraform

Der von Ihnen konfigurierte Spezifikationsblock, z. B. agent_spec, bestimmt, zu welcher Ressourcensammlung Ihr Dienst gehört. Eine vollständige Zuordnung von Spezifikationen zu Ressourcensammlungen finden Sie unter API-Ressourcen.

Wenn Sie einen A2A-konformen Agenten registrieren möchten, konfigurieren Sie die google_agent_registry_service-Ressource. Geben Sie den agent_spec-Block mit dem Typ A2A_AGENT_CARD und dem content an, der die JSON-Nutzlast Ihrer 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 menschenlesbare Name, den Sie Ihrem Agenten geben möchten, z. B. Support Agent.

Standard-REST-Agent registrieren

Standard-REST-Agents sind anhand von Name und Beschreibung auffindbar, haben aber keine durchsuchbaren A2A-Skills, sofern sie das A2A-Protokoll nicht verwenden.

Wenn Sie einen Remote-Agent registrieren möchten, der die A2A-Spezifikation nicht implementiert, erstellen Sie eine Service-Ressource, die mit --agent-spec-type=no-spec konfiguriert ist. Die Agent Registry generiert dann eine entsprechende Agent-Ressource in der agents-Sammlung.

Mit --agent-spec-type=no-spec wird ein Agent registriert, nicht ein Ziel-API-Ziel. Wenn Sie ein externes API-Ziel registrieren möchten, mit dem sich Agents verbinden, müssen Sie einen Endpunkt registrieren. Eine Anleitung finden Sie unter Endpunkte registrieren.

So registrieren Sie den Agent:

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 die Agent Registry eingerichtet haben.

  3. Wählen Sie den Tab KI-Agents aus.

  4. Klicken Sie auf KI-Agent hinzufügen.

  5. Geben Sie im Bereich Agent details (Agentendetails) die folgenden Details ein:

    • Typ: Wählen Sie Nicht-A2A aus.
    • Name: Geben Sie einen menschenlesbaren Anzeigenamen für Ihren Agenten ein, z. B. Travel Agent.
    • Beschreibung: Geben Sie eine Beschreibung der Funktionen des KI-Agenten ein, z. B. A test agent that plans travel itineraries..
    • Region: Wählen Sie den geografischen Standort aus, an dem Sie den Agent registrieren möchten.
    • Endpunkt: Geben Sie den Endpunkt ein, auf dem der Agent gehostet wird.

  6. Klicken Sie auf Speichern.

gcloud

Die von Ihnen verwendeten Spezifikations-Flags bestimmen, zu welcher Ressourcensammlung Ihr Dienst gehört. Eine vollständige Zuordnung von Flags zu Ressourcensammlungen finden Sie unter API-Ressourcen.

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

So registrieren Sie einen Standard-REST-Agent:

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 menschenlesbare Name, den Sie Ihrem Agenten geben möchten, z. B. Remote REST Agent.
  • ENDPOINT_URL: Die API-Endpunkt-URL des Agents, z. B. https://api.remote-service.com/v1/agents/1234.
  • PROTOCOL: Die Protokollbindung für den Endpunkt. Gültige Werte sind http-json, grpc und jsonrpc.

Terraform

Der von Ihnen konfigurierte Spezifikationsblock, z. B. agent_spec, bestimmt, zu welcher Ressourcensammlung Ihr Dienst gehört. Eine vollständige Zuordnung von Spezifikationen zu Ressourcensammlungen finden Sie unter API-Ressourcen.

Wenn Sie einen Standard-REST-Agenten registrieren möchten, konfigurieren Sie die google_agent_registry_service-Ressource mit agent_spec auf den Typ NO_SPEC und definieren Sie die Endpunktschnittstellenverbindungen:

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 menschenlesbare Name, den Sie Ihrem Agenten geben möchten, z. B. Remote REST Agent.
  • ENDPOINT_URL: Die API-Endpunkt-URL des Agents, z. B. https://api.remote-service.com/v1/agents/1234.
  • PROTOCOL: Die Protokollbindung für den Endpunkt. Gültige Werte sind HTTP_JSON, GRPC und JSONRPC.

KI‑Agent aus einem anderen Projekt registrieren

Wenn Ihre Organisation Agenten in mehreren Google Cloud-Projekten bereitstellt und ein zentrales Agent Gateway verwendet, um ausgehenden Traffic zu steuern, können Sie Agenten aus Spoke- oder Arbeitslastprojekten 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-Agent manuell in der Registry des zentralen Governance-Projekts registrieren.

Überlegungen zur projektübergreifenden Registrierung

Bevor Sie Agents projektübergreifend registrieren, sollten Sie Folgendes beachten:

  • Kompatible Standorte: Die Agent Registry-Instanz, das Agent Gateway und die Agent-Endpunkte 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-Agent manuell registrieren.
  • Lebenszyklusverwaltung: Manuelle Einträge in der Agent Registry werden nicht automatisch aktualisiert oder gelöscht, wenn Änderungen im Remote-Projekt vorgenommen werden. Sie müssen den Lebenszyklus dieser Einträge in der zentralen Registrierung verwalten, wenn Remote-Agents geändert oder entfernt werden.
  • Nur Egress-Modus: Die projektübergreifende Verwaltung mit Agent Gateway wird nur für Agent-to-Anywhere-Gateways (Egress) unterstützt. Für Client-to-Agent-Ingress-Gateways müssen sich der Agent und das Gateway im selben Projekt befinden.

Remote-Agent registrieren

So registrieren Sie einen Agenten manuell aus einem anderen Projekt:

Console

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

    Zur Agent Registry

  2. Wählen Sie in der Projektauswahl das Projekt Google Cloudfür die zentrale Verwaltung aus, in dem Sie den Agent registrieren möchten.

  3. Wählen Sie den Tab KI-Agents aus.

  4. Klicken Sie auf KI-Agent hinzufügen.

  5. Geben Sie im Bereich Agent details (Agentendetails) die folgenden Details ein:

    • Typ: Wählen Sie A2A aus, wenn der Remote-Agent das A2A-Protokoll implementiert, oder Non-A2A für einen Standard-REST-Endpunkt.
    • Region: Wählen Sie die Region aus, die Ihrem zentralen Gateway und der Bereitstellung des Remote-Agents entspricht.

  6. Geben Sie den Agent-Endpunkt an:

    • Wählen Sie für A2A-Agents From URI (Über URI) aus und geben Sie die Agent Card-URL des Remote-Agents ein. Alternativ können Sie Paste JSON (JSON einfügen) auswählen und den agent-card.json-Inhalt einfügen.
    • Geben Sie für Nicht-A2A-Agenten die Endpoint-URL des Remote-Agenten ein.

  7. Klicken Sie auf Speichern.

gcloud

Die von Ihnen verwendeten Spezifikations-Flags bestimmen, zu welcher Ressourcensammlung Ihr Dienst gehört. Eine vollständige Zuordnung von Flags zu Ressourcensammlungen finden Sie unter API-Ressourcen.

  • A2A-Agent: Wenn Sie einen A2A-Agenten aus einem anderen Projekt über die gcloud CLI registrieren möchten, führen Sie den folgenden Befehl im zentralen Governance-Projekt aus:
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: Wenn Sie einen Standard-REST-Agent aus einem anderen Projekt registrieren möchten, führen Sie den folgenden Befehl im zentralen Governance-Projekt aus:
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 Ihres Agents in der zentralen Registrierung, 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 menschenlesbare Name des Agents, z. B. Remote Support Agent.
  • REMOTE_ENDPOINT_URL: Die Endpunkt-URL des Agents, 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 und jsonrpc.

Terraform

Der von Ihnen konfigurierte Spezifikationsblock, z. B. agent_spec, bestimmt, zu welcher Ressourcensammlung Ihr Dienst gehört. Eine vollständige Zuordnung von Spezifikationen zu Ressourcensammlungen finden Sie unter API-Ressourcen.

Wenn Sie einen Remote-Agent in einem zentralen Governance-Projekt mit Terraform registrieren möchten, konfigurieren Sie die Ressource google_agent_registry_service und geben Sie das zentrale Projekt an:

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 Registrierung, z. B. remote-support-agent.
  • DISPLAY_NAME: Der menschenlesbare Name des Agents, 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 und JSONRPC.

Registrierung bestätigen

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

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 die Agent Registry eingerichtet haben.

  3. Wählen Sie den Tab KI-Agents aus.

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

gcloud 

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

Wenn Sie mehrere Agents haben oder die Registrierung eines einzelnen Agents bestätigen möchten, können Sie die Liste nach den Metadaten des Agents 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 Agents, die Sie filtern möchten. Wenn Sie beispielsweise nach dem Anzeigenamen filtern möchten, können Sie displayName='DISPLAY_NAME' verwenden. Wenn Sie nach der global eindeutigen Kennung (URN) filtern möchten, können Sie agentId='urn:agent:AGENT_URN' verwenden.

Terraform

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

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 menschenlesbare Anzeigename des Agenten.

Nächste Schritte