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

Manuelle Registrierung für Agenten verwenden

Mit der Agent Registry können Sie A2A-konforme und Standard-REST-Agents manuell registrieren, die außerhalb von Google Cloudgehostet werden, auf nicht unterstützten Laufzeiten ausgeführt werden oder in verschiedenen Google Cloud -Projekten bereitgestellt werden. Wenn Sie eine Service-Ressource für diese KI-Agenten erstellen, werden ihre Endpunkte und Funktionen in Ihrer gesamten KI-Umgebung sichtbar.

Agent Registry verwendet ein zentrales Governance-Projekt von Google Cloud. In diesem Dokument bezieht sich der Begriff Remote auf Agenten, die außerhalb des Governance-Projekts gehostet werden, z. B. in separaten Google Cloud -Projekten, lokalen Umgebungen oder externen Clouds, oder die auf nicht unterstützten Laufzeiten ausgeführt werden. Da bei der automatischen Registrierung nur unterstützte Ressourcen erkannt werden, die im Governance-Projekt bereitgestellt wurden, in dem die Agent Registry aktiviert ist, müssen Sie Remote-Agents manuell in der Registry des Governance-Projekts registrieren.

Arten von KI-Agenten und Einschränkungen

Sie können zwei Arten von Agenten manuell registrieren:

A2A-konforme KI-Agenten: KI-Agenten, die die Agent2Agent-Spezifikation (A2A) mit dem Typ A2A_AGENT_CARD implementieren. Die Registry scannt den agent-card.json-Endpunkt der Agentenkarte, um die A2A-Skills zu indexieren.
Standard-REST-Agenten: Remote-Agenten, die die A2A-Spezifikation nicht implementieren und den Typ NO_SPEC verwenden, z. B. Agenten, die einen REST API-Endpunkt bereitstellen.

Die manuelle Registrierung 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

Agent Registry einrichten
Rufen Sie die Projekt-ID für das Governance-Projekt ab, in dem die Agent Registry aktiviert ist.
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 folgenden IAM-Rollen für das Governance-Projekt zuzuweisen, in dem Agent Registry aktiviert ist, 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 Agent-Metadaten in einem anderen Google Cloud -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 standardmäßige öffentliche URLs zugänglich ist oder über vorkonfigurierte Anmeldedaten authentifiziert wird.

A2A-konformen KI-Agenten registrieren

Wenn Ihr Remote-Agent die A2A-Spezifikation implementiert, verweisen Sie die Agent Registry auf die agent-card.json-Nutzlast des KI-Agenten. Die Registry synchronisiert automatisch die Agentenkarte und indexiert die verfügbaren A2A-Skills des Agenten, damit sie gefunden werden können.

So registrieren Sie den Agenten:

Console

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

Zur Agent Registry
Wählen Sie in der Projektauswahl das Google Cloud -Projekt aus, in dem Sie die Agent Registry eingerichtet haben.
Wählen Sie den Tab KI-Agenten aus.
Klicken Sie auf KI-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 KI-Agenten über die URL seiner KI-Agentenkarte registrieren möchten, wählen Sie den Tab Aus URI aus und geben Sie eine gültige URL in das Feld URI 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 gesamten Inhalt der Datei agent-card.json ein.
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 einen A2A-Agenten registrieren möchten, speichern Sie die Agentenkarte des Agenten als lokale JSON-Datei, z. B. agent-card.json, und führen Sie dann den Befehl gcloud agent-registry services create aus:

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: die ID, die Sie Ihrem Agenten zuweisen möchten, z. B. my-support-agent. Die ID muss 4 bis 63 Zeichen lang sein und darf nur Kleinbuchstaben, Ziffern und Bindestriche enthalten.
PROJECT_ID: 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 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).

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 der content an, die 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({
      name               = "AGENT_NAME"
      description        = "A custom support agent registered using Terraform."
      version            = "1.0.0"
      capabilities       = {}
      defaultInputModes  = ["text/plain"]
      defaultOutputModes = ["text/plain"]
      supportedInterfaces = [
        {
          url             = "https://api.example.com/v1/agents/support"
          protocolBinding = "JSONRPC"
          protocolVersion = "1.0"
        }
      ]
      skills = [
        {
          id          = "customer_lookup"
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
          tags        = ["support", "customer"]
        }
      ]
    })
  }
}

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: die eindeutige ID, die Sie Ihrem Agenten zuweisen möchten, z. B. my-support-agent. Die ID muss 4 bis 63 Zeichen lang sein und darf nur Kleinbuchstaben, Ziffern und Bindestriche enthalten.
DISPLAY_NAME: der menschenlesbare Name, den Sie Ihrem Agenten geben möchten, z. B. Support Agent.

Standard-REST-Agenten registrieren

Standard-REST-Agenten sind anhand ihres Namens und ihrer Beschreibung auffindbar, haben aber keine durchsuchbaren A2A-Fähigkeiten, es sei denn, sie übernehmen das A2A-Protokoll.

Wenn Sie einen Remote-Agenten registrieren möchten, der die A2A-Spezifikation nicht implementiert, erstellen Sie eine Nicht-A2A-Service-Ressource. Die Agent Registry generiert eine schreibgeschützte Agent-Ressource für den Nicht-A2A-Agenten in der Sammlung agents, einschließlich seiner Endpunkt-URL, damit Orchestratoren, andere Agenten und das Agent Gateway den Agenten finden und eine Verbindung zu ihm herstellen können.

Wenn Sie den Agent-Typ in der Google Cloud Console auf Nicht-A2A festlegen oder das Flag --agent-spec-type=no-spec in gcloud CLI-Befehlen verwenden, wird ein KI-Agent registriert. Registrieren Sie diesen Agenten nicht separat als Endpoint-Ressource. Registrieren Sie eine Endpoint-Ressource nur, wenn Sie ausgehende Verbindungen von KI-Agenten zu einer REST API oder einem Webdienst steuern möchten, die nicht zu einem KI-Agenten gehören, z. B. eine Datenbank-API, eine SaaS-API eines Drittanbieters oder Google APIs. Eine Anleitung zum Registrieren von API-Zielen, die keine Agenten sind, finden Sie unter Endpunkte registrieren.

So registrieren Sie den Agenten:

Console

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

Zur Agent Registry
Wählen Sie in der Projektauswahl das Google Cloud -Projekt aus, in dem Sie die Agent Registry eingerichtet haben.
Wählen Sie den Tab KI-Agenten aus.
Klicken Sie auf KI-Agent hinzufügen.
Geben Sie im Bereich 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 Agenten registrieren möchten.
- Endpunkt: Geben Sie den Endpunkt ein, an dem der Agent gehostet wird.
Klicken Sie auf Speichern.

gcloud

Führen Sie den Befehl gcloud agent-registry services create mit --agent-spec-type=no-spec und dem Flag --interfaces aus, um einen Standard-REST-Agenten zu registrieren und die Endpunkt-URL anzugeben, unter der der Agent gehostet wird:

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: die ID, die Sie Ihrem Agenten zuweisen möchten, z. B. my-remote-rest-agent. Die ID 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, den Sie Ihrem Agenten geben möchten, z. B. Remote REST Agent.
ENDPOINT_URL: die API-Endpunkt-URL des KI-Agenten, z. B. https://api.example.com/v1/agents/1234.
PROTOCOL: die Protokollbindung für den Endpunkt. Gültige Werte sind http-json, grpc oder jsonrpc.

Terraform

Wenn Sie einen Standard-REST-Agenten registrieren möchten, konfigurieren Sie die Ressource google_agent_registry_service mit dem Typ NO_SPEC für agent_spec und definieren Sie die Endpunkt-Schnittstellenverbindungen:

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: die eindeutige ID, die Sie Ihrem Agenten zuweisen möchten, z. B. my-remote-rest-agent. Die ID muss 4 bis 63 Zeichen lang sein und darf nur Kleinbuchstaben, Ziffern und Bindestriche enthalten.
DISPLAY_NAME: der menschenlesbare Name, den Sie Ihrem Agenten geben möchten, z. B. Remote REST Agent.
ENDPOINT_URL: die API-Endpunkt-URL des KI-Agenten, z. B. https://api.example.com/v1/agents/1234.
PROTOCOL: die Protokollbindung für den Endpunkt. Gültige Werte sind HTTP_JSON, GRPC oder JSONRPC.

KI-Agenten aus einem anderen Projekt registrieren

Wenn Ihre Organisation Agenten in mehreren Google Cloud -Projekten bereitstellt und ein zentrales Agent Gateway im Agent-to-Anywhere-Modus für ausgehenden Traffic verwendet, um den Traffic zu steuern, müssen Sie jeden Remote-Agenten aus diesen anderen Google Cloud -Projekten manuell in der Registry des zentralen Governance-Projekts registrieren. Weitere Informationen zu dieser Architektur finden Sie unter Beispielbereitstellungsmuster.

Ü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 anderenGoogle Cloud -Projekt auftreten, in dem der Agent ausgeführt wird. Sie müssen den Lebenszyklus dieser Einträge in der zentralen Registry verwalten, wenn Remote-Agenten geändert oder entfernt werden.
Nur Modus für ausgehenden Traffic: Die projektübergreifende Governance mit Agent Gateway wird nur für Gateways für ausgehenden Traffic vom Typ „Agent-to-Anywhere“ unterstützt. Für Client-zu-Agent-Ingress-Gateways müssen sich der Agent und das Gateway im selben Projekt befinden.

Remote-Agent registrieren

So registrieren Sie einen Agenten aus einem anderen Projekt manuell:

Console

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

Zur Agent Registry
Wählen Sie in der Projektauswahl das zentrale Governance-Projekt aus, in dem Sie den Agenten registrieren möchten.
Wählen Sie den Tab KI-Agenten aus.
Klicken Sie auf KI-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 Remote-Agent-Bereitstellung entspricht.
Geben Sie den Agenten-Endpunkt an:
- Wählen Sie für A2A-Agenten Aus 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: Wenn Sie einen A2A-Agenten aus einem anderen Projekt registrieren möchten, führen Sie den Befehl gcloud agent-registry services create 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-Agenten aus einem anderen Projekt registrieren möchten, führen Sie den Befehl gcloud agent-registry services create 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: die ID für Ihren Agenten in der zentralen Registry, z. B. remote-support-agent. Die ID 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.
REGION: die Region, in der Sie den Agenten registrieren und in der sich das zentrale Gateway und der Remote-Agent befinden, z. B. us-central1.
DISPLAY_NAME: der menschenlesbare Name für den Agenten, z. B. Remote Support Agent.
REMOTE_ENDPOINT_URL: die Endpunkt-URL des Remote-Agents, der im anderen Google Cloud -Projekt ausgeführt wird, z. B. https://remote-support-agent-abc123.us-central1.run.app oder https://api.example.com/v1/agents/support.
PROTOCOL: die Protokollbindung für den Endpunkt. Gültige Werte sind http-json, grpc oder jsonrpc.

Terraform

Wenn Sie einen Remote-Agenten 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 AGENT_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 und in der sich das zentrale Gateway und der Remote-Agent befinden, z. B. us-central1.
AGENT_NAME: die eindeutige ID für Ihren Agenten in der Registry, z. B. remote-support-agent. Die ID muss 4 bis 63 Zeichen lang sein und darf nur Kleinbuchstaben, Ziffern und Bindestriche enthalten.
DISPLAY_NAME: der menschenlesbare Name für den Agenten, z. B. Remote Support Agent.
AGENT_PROJECT_ID: die Projekt-ID des separaten Google Cloud -Projekts, in dem der Remote-Agent gehostet wird.
REMOTE_ENDPOINT_URL: die Endpunkt-URL des Remote-Agents, der im anderen Google Cloud -Projekt ausgeführt wird, z. B. https://remote-support-agent-abc123.us-central1.run.app oder https://api.example.com/v1/agents/support.
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 KI-Agenten, ob die Agent Registry die Ressource Service erfolgreich verarbeitet und die entsprechende schreibgeschützte Ressource Agent erstellt hat:

Console

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

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

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

gcloud

Listen Sie die registrierten Agenten in Ihrer Registry mit dem Befehl gcloud agent-registry agents list auf:

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: 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 dem Anzeigenamen filtern möchten, können Sie displayName='DISPLAY_NAME' verwenden. Wenn Sie nach der global eindeutigen Agent-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 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 KI-Agenten.

Nächste Schritte

Registrierte Agents verwalten
Informationen zur automatischen Registrierung, der empfohlenen Methode zum Registrieren von Agents, die in verwalteten Laufzeiten bereitgestellt werden.

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

Arten von KI-Agenten und Einschränkungen

Hinweis

Erforderliche Rollen

A2A-konformen KI-Agenten registrieren

Console

gcloud

Terraform

Standard-REST-Agenten registrieren

Console

gcloud

Terraform

KI-Agenten aus einem anderen Projekt registrieren

Überlegungen zur projektübergreifenden Registrierung

Remote-Agent registrieren

Console

gcloud

Terraform

Registrierung bestätigen

Console

gcloud

Terraform

Nächste Schritte

Manuelle Registrierung für Agenten verwenden