Probleme mit der Agent-Registrierung beheben

Wenn Sie Komponenten in der Agent Registry registrieren, erkennen oder verbinden, können Sie häufige Probleme wie Kontingentlimits, Fehler bei der Nutzlast- und Skill-Validierung, Standortabweichungen, Synchronisierungsverzögerungen und Berechtigungsfehler diagnostizieren und beheben.

API-Ratenkontingent überschritten

Der folgende Fehler tritt auf, wenn Sie das Limit für die Anfragerate überschreiten, während Sie mit der Agent Registry API interagieren oder schnell durch die Agent Registry in derGoogle Cloud Console navigieren:

429 Too Many Requests

Implementieren Sie zur Behebung dieses Problems einen exponentiellen Backoff in Ihren API-Clients, um die Anforderungsraten zu verwalten. Die Agent Registry API hat ein Standard-Ratenkontingent von 1.200 Anfragen pro Minute oder 20 Abfragen pro Sekunde, global und pro Region.

Wenn beim Wechseln der Tabs in der Google Cloud Console eine Drosselung auftritt, warten Sie einen Moment und versuchen Sie es dann noch einmal. Wenn Ihr programmatischer Anwendungsfall höhere Limits erfordert, können Sie eine Kontingenterhöhung für den Messwert RequestsPerMinute anfordern.

Fehler bei der Nutzlastgröße während der manuellen Registrierung

Der folgende Fehler tritt auf, wenn Sie einen KI-Agenten oder MCP-Server manuell mit einer Spezifikationsdatei registrieren, die das Größenlimit überschreitet:

Die API lehnt die Anfrage mit einem Fehler ab, der besagt, dass die Nutzlast zu groß ist.

Prüfen Sie, ob die Datei agent-card.json oder toolspec.json kleiner als 10 KB ist, um dieses Problem zu beheben. Die Größe der Inhalte von AgentSpec und McpServerSpec ist auf 10 KB beschränkt. Minimieren Sie Ihre JSON-Dateien, entfernen Sie unnötige Leerzeichen oder kürzen Sie Toolbeschreibungen, um dieses Limit einzuhalten. Weitere Informationen finden Sie unter JSON-Schemas.

Fehlende KI-Agenten oder MCP-Server nach der Erstellung

Der folgende Fehler tritt auf, nachdem Sie einen Agenten oder MCP-Server in einem unterstützten Google Cloud Produkt wie Google Workspace oder Gemini Enterprise erstellt haben:

Die Ressource wird nicht in der Ausgabe angezeigt, wenn Sie die APIs ListAgents oder ListMcpServers aufrufen.

Warten Sie, bis die Hintergrundsynchronisierung abgeschlossen ist, um dieses Problem zu beheben. Ihre Ressourcen werden in Echtzeit aktualisiert, aber andere Integrationen werden durch regelmäßige Offline-Batchjobs gefüllt. Wenn Ihre Ressource nach mehreren Stunden nicht angezeigt wird, prüfen Sie die Service Usage-Einstellungen Ihres Projekts und ob die entsprechende API aktiviert ist.

Vorgänge mit langer Ausführungszeit scheinen hängengeblieben zu sein

Der folgende Fehler tritt auf, wenn Sie Agents bereitstellen oder komplexe Bindungen konfigurieren:

Der Vorgang dauert sehr lange und scheint hängen geblieben zu sein.

Verwenden Sie das MCP-Tool get_operation oder den API-Endpunkt google.longrunning.Operations.GetOperation, um den Status des Vorgangs abzufragen und das Problem zu beheben. Für die Erstellung einiger Agenten und MCP-Backends ist eine umfangreiche Infrastrukturbereitstellung erforderlich. Dies kann zu Vorgängen mit langer Ausführungszeit (Long-Running Operation, LRO) führen, die bis zu 30 Minuten dauern können. Konfigurieren Sie die Zeitüberschreitungseinstellungen des Clients entsprechend und rufen Sie das boolesche Flag done ab, um den Abschluss zu prüfen.

Leere Ergebnisse beim Abrufen verfügbarer Bindungen

Der folgende Fehler tritt auf, wenn Sie verfügbare Bindungen für einen Authentifizierungsanbieter ohne ausreichende Berechtigungen für die Zielressource AuthProvider abrufen:

Die API gibt ein leeres Array oder einen Zugriffsfehler zurück, auch wenn die Bindung vorhanden ist.

Prüfen Sie zur Behebung dieses Problems, ob Ihr Hauptkonto die richtigen IAM-Berechtigungen (Identity and Access Management) für die Zielressource AuthProvider hat. Die API wendet strenge IAM-Prüfungen an und entfernt Binding-Objekte, die auf Authentifizierungsanbieter verweisen, auf die der Aufrufer keinen Zugriff hat. Achten Sie darauf, dass Ihr Hauptkonto den erforderlichen Zugriff auf den Authentifizierungsanbieter und die Rolle roles/agentregistry.viewer für das Projekt hat.

Herunterladen der Skill-Version schlägt mit dem Fehler 302 fehl

Der folgende Fehler tritt auf, wenn Sie versuchen, eine Skill-Überarbeitungs-Nutzlast mit der GetSkillRevision API mit dem Suchparameter ?alt=media herunterzuladen und Ihr HTTP-Client keine Weiterleitungen befolgt:

{
  "error": {
    "code": 302,
    "message": "Unknown Error.",
    "status": "UNKNOWN"
  }
}

Prüfen Sie zur Behebung dieses Problems, ob Ihr HTTP-Client so konfiguriert ist, dass er Weiterleitungen automatisch folgt. Der Endpunkt ?alt=media erfordert eine 302-Weiterleitung, um das Archiv des Skills herunterzuladen. Wenn Sie beispielsweise curl verwenden, fügen Sie dem Befehl das Flag -L oder --location hinzu.

Validierung der Skill-Version schlägt fehl oder zeigt den Status FAILED an

Der folgende Fehler tritt auf, wenn Sie eine neue Skill-Version mit einem ungültigen ZIP-Archiv erstellen:

Die Version wechselt in den Status FAILED und kann nicht von KI-Agenten geladen werden.

Prüfen Sie zur Behebung dieses Problems die Validierungslogs oder den Inhalt der ZIP-Nutzlast:

  • Das ZIP-Archiv muss im Stammverzeichnis eine SKILL.md-Datei enthalten.
  • Prüfen Sie, ob die Datei SKILL.md einen gültigen YAML-Frontmatter-Block enthält, in dem sowohl name als auch description definiert sind.
  • Prüfen Sie, ob die ZIP-Nutzlast die Größenbeschränkungen nicht überschreitet: Die komprimierte Größe muss weniger als 500 KB, die unkomprimierte Gesamtgröße weniger als 10 MB und die Größe der einzelnen Dateien weniger als 1 MB betragen.
  • Prüfen Sie, ob das Archiv symbolische Links, Elemente zur Verzeichnisdurchquerung wie .. oder absolute Pfade enthält.

Eigenständige Skills werden nicht in Ressourcenlisten für Dienste oder Agenten angezeigt

Der folgende Fehler tritt auf, wenn Sie die Agenten- oder Dienstlisten nach eigenständigen Skills abfragen, z. B. durch Ausführen von gcloud agent-registry services list oder gcloud agent-registry agents list:

Der eigenständige Skill wird in der Ausgabe nicht angezeigt.

Fragen Sie stattdessen die Sammlung skills ab, um dieses Problem zu beheben:

  • Im Gegensatz zu manuell registrierten KI-Agenten, MCP-Servern und Endpunkten verwenden eigenständige Skills keine beschreibbaren Service-Ressourcen oder Agent-, McpServer- oder Endpoint-Erkennungsressourcen. Stattdessen stellt die Agent Registry eigenständige Skills direkt als Skill-Ressourcen der obersten Ebene und als versionierte SkillRevision-Ressourcen dar.
  • Wenn Sie eigenständige Skills auflisten, suchen oder prüfen möchten, verwenden Sie den Tab Skills in derGoogle Cloud Console, führen Sie gcloud alpha agent-registry skills list oder gcloud alpha agent-registry skills search aus oder rufen Sie die REST API-Methoden skills auf. Eine Anleitung finden Sie unter Fähigkeiten verwalten und Nach eigenständigen Fähigkeiten suchen.
  • Wenn Sie nach Inline-A2A-Skills suchen, die in der Agentenkarte eines KI-Agenten deklariert sind, prüfen Sie das Feld skills in der Agent-Erkennungsressource mit gcloud agent-registry agents describe oder gcloud agent-registry agents search.

Fehler „Ressourcenentität nicht gefunden“ beim Verwalten von IAP-Richtlinien

Der folgende Fehler tritt auf, wenn Sie gcloud iap web-Befehle verwenden, um IAP-Richtlinien (Identity-Aware Proxy) für ausgehenden Traffic für Agent Registry-Ressourcen zu verwalten:

NOT_FOUND: Requested entity was not found

Prüfen Sie Folgendes, um das Problem zu beheben:

  • Registrierungsstatus: Prüfen Sie, ob die Zielkomponente in der Agent Registry am erwarteten Speicherort registriert ist.
  • Kennzeichnungsformat: Prüfen Sie, ob in Ihrem Befehl oder Ihrer Richtlinienbindung der standardmäßige Ressourcenname und nicht ein URN für die Registry-Kennzeichnung angegeben ist.
  • Ressourcen-Flag: Prüfen Sie, ob das Ressourcen-Flag, das Sie an gcloud iap web übergeben, mit dem zugrunde liegenden untergeordneten Ressourcentyp der Agent Registry übereinstimmt:
    • Verwenden Sie für Endpunkte wie externe APIs oder ausgehende Google API-Punkte das Flag --endpoint.
    • Verwenden Sie für MCP-Server (Model Context Protocol) das Flag --mcp-server.
    • Verwenden Sie für registrierte Agenten das Flag --agent.

Prüfen Sie den von gcloud agent-registry endpoints list, gcloud agent-registry mcp-servers list oder gcloud agent-registry agents list zurückgegebenen Ressourcennamen, um festzustellen, ob der Ressourcenname /endpoints/, /mcpServers/ oder /agents/ enthält. Wenn Sie das falsche Ressourcen-Flag übergeben, z. B. --endpoint für eine MCP-Server-ID, wird ein NOT_FOUND-Fehler verursacht.

Berechtigung beim Anwenden von IAM-Richtlinien für IAP-Web verweigert

Der folgende Fehler tritt auf, wenn Sie IAP-Web-IAM-Richtlinien für Agent Registry-Ressourcen ohne die erforderlichen Administratorrollen anwenden oder ändern:

ERROR: (gcloud.iap.web.set-iam-policy) PERMISSION_DENIED

Prüfen Sie zur Behebung dieses Problems, ob Ihr aktives Nutzer- oder Dienstkonto die erforderlichen Berechtigungen für das Projekt hat, in dem die Registry und das Gateway gehostet werden:

  • Der Aufrufer muss die Rolle „IAP Policy Admin“ (roles/iap.admin) oder „Project IAM Admin“ (roles/resourcemanager.projectIamAdmin) für das zentrale Governance-Projekt haben.
  • Prüfen Sie, ob der Aufrufer die Berechtigungen iap.web.setIamPolicy und resourcemanager.projects.setIamPolicy hat.

Remote-MCP-Server nicht an einem regionalen Standort gefunden

Der folgende Fehler tritt auf, wenn Sie einen automatisch registrierten Remote-MCP-Server von Google oder Google Cloud abfragen oder eine IAP-Richtlinie für ausgehenden Traffic auf ihn anwenden, und zwar in einem regionalen Standort wie us-central1:

Die Anfrage gibt einen NOT_FOUND-Fehler oder eine leere Liste zurück, auch wenn der Dienst regionale Endpunkte (REPs) bereitstellt oder der Traffic über ein regionales Agent Gateway weitergeleitet wird.

Wenn die Agent Registry automatisch einen Google- oderGoogle Cloud -Remote-MCP-Server für eine aktivierte API registriert, wird die McpServer-Ressource nur am Standort global erstellt, nicht in einzelnen Regionen wie us-central1. Wenn der Dienst regionale Endpunkte wie https://SERVICE.REGION.rep.googleapis.com/mcp bereitstellt, werden diese regionalen URLs in der Agent Registry im Feld interfaces dieser einzelnen global-McpServer-Ressource aufgeführt.

Führen Sie einen der folgenden Schritte aus, um das Problem zu lösen:

  • global für automatisch registrierte Server verwenden: Geben Sie den Standort global an, wenn Sie den Server in der Agent Registry mit --location=global abfragen oder IAP-Richtlinien für ausgehenden Traffic mit --region=global darauf anwenden, auch wenn der aufrufende Agent Traffic über ein regionales Gateway weiterleitet.
  • In einer Region für den Datenstandort registrieren: Wenn Sie Registry-Metadaten in einer bestimmten Region speichern müssen, stellen Sie benutzerdefinierte MCP-Server in regionalen Cloud Run- oder Google Kubernetes Engine (GKE)-Laufzeiten bereit oder registrieren Sie den MCP-Server und seine regionale Endpunkt-URL manuell in dieser Region. Wenden Sie dann Ihre IAP-Richtlinie in derselben Region an. Wenn Agent Gateway eine Ziel-URL auflöst, haben regionale Registry-Einträge Vorrang vor global-Einträgen.

Fehler aufgrund von nicht übereinstimmenden Regionen beim Konfigurieren von Model Armor im Agent Gateway

Der folgende Fehler tritt auf, wenn Sie Model Armor-Richtlinienfilter im Agent Gateway in nicht übereinstimmenden Regionen konfigurieren:

Das Erstellen der Autorisierungsrichtlinie schlägt mit einem Fehler aufgrund einer nicht übereinstimmenden Region fehl oder der Traffic, der über das Gateway an einen MCP-Server weitergeleitet wird, besteht die Richtlinienprüfung nicht.

Prüfen Sie zur Behebung dieses Problems die regionale Ausrichtung Ihrer Gateway-Ressourcen und Zielrichtlinienbindungen:

  • Gateway- und Model Armor-Regionen aufeinander abstimmen: Achten Sie darauf, dass sich das Agent Gateway, die Model Armor-Vorlagen sowie die Autorisierungserweiterung und -richtlinie in derselben Region befinden, z. B. us-central1.
  • An global- oder regionale MCP-Server weiterleiten: Sie müssen global-MCP-Server nicht nur für die Verwendung von Model Armor in einer Region neu registrieren. Da Model Armor Anfrage- und Antwortnutzlasten am regionalen Gateway prüft, kann ein regionales Gateway Traffic prüfen und steuern, der an MCP-Server weitergeleitet wird, die am Standort global registriert sind, sowie an regionale Ziele.
  • IAP-Ausgangsbindungen mit dem Registrierungsstandort des Ziels abgleichen: Wenden Sie die IAP-Ausgangsautorisierungsbindung an dem Standort an, an dem die Zielressource McpServer registriert ist. Verwenden Sie global für automatisch registrierte Remote-MCP-Server oder die spezifische Region für regional registrierte MCP-Server.

Manuelle Registrierung oder Bindungserstellung schlägt an einem multiregionalen Standort fehl

Der folgende Fehler tritt auf, wenn Sie versuchen, einen Agent, einen MCP-Server oder einen Endpunkt manuell zu registrieren oder eine Bindung an einem multiregionalen Standort wie us oder eu zu erstellen:

Die API lehnt die Anfrage mit einem Fehler wegen nicht unterstütztem Standort oder ungültigem Argument ab.

Geben Sie stattdessen einen unterstützten regionalen Standort wie us-central1 oder europe-west1 oder den Standort global an, um dieses Problem zu beheben. Die multiregionalen Standorte us und eu unterstützen nur das Erkennen automatisch registrierter Komponenten und das Registrieren oder Erkennen eigenständiger Skills. Eine Liste der unterstützten Standorte finden Sie unter Agent Registry-Standorte.

Fehler beim Zugriff auf Agent Registry mit Workforce Identity Federation

Die folgenden Fehler treten auf, wenn Sie in derGoogle Cloud -Konsole auf die Agent-Registry zugreifen oder die Google Cloud CLI verwenden, während Sie mit Workforce Identity Federation authentifiziert sind:

In derGoogle Cloud -Konsole werden allgemeine Ladefehler angezeigt, z. B.:

  • „Beim Laden ist ein Fehler aufgetreten…“
  • „Der Server konnte Ihre Anfrage nicht verarbeiten.“
  • „Fehler beim Laden“

Außerdem können gcloud-Befehle einen internen Fehler wie error 13: an internal error has occurred zurückgeben.

Authentifizieren Sie sich mit einem Standard-Google-Konto, das über Cloud Identity oder Google Workspace verwaltet wird, um dieses Problem zu beheben. Prüfen Sie, ob das Konto die erforderlichen Berechtigungen hat, z. B. roles/agentregistry.admin oder roles/agentregistry.viewer.

Die Governance-Dienste der Gemini Enterprise Agent Platform bieten nur eingeschränkte Unterstützung für föderierte Identitäten. Das Problem lässt sich nicht beheben, indem Sie einem föderierten Hauptkonto umfassendere IAM-Rollen zuweisen.