Manuelle Registrierung verwenden

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

Hinweis

Richten Sie die 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 Agent Registry API Editor (roles/agentregistry.editor) IAM-Rolle für das Projekt zu erteilen, um die Berechtigungen zu erhalten, die Sie zum manuellen Registrieren von Agenten 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.

A2A-konformen Agenten registrieren

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

So registrieren Sie den Agenten:

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 Agenten aus.

  4. Klicken Sie auf Agent hinzufügen.

  5. 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.

  6. 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.

  7. 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 gefunden werden, haben aber keine durchsuchbaren Skills, 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

  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 Agenten aus.

  4. Klicken Sie auf Agent hinzufügen.

  5. 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.
    • Description (Beschreibung): Geben Sie eine Beschreibung der Funktionen 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.

  6. 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.

Registrierung bestätigen

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

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 Agenten aus.

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

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 in anderen Terraform-Konfigurationen mit der Datenquelle google_agent_registry_agent 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