エージェント レジストリの問題をトラブルシューティングする

Agent Registry でコンポーネントを登録、検出、接続する際に、割り当て制限、ペイロードとスキルの検証エラー、ロケーションの不一致、同期の遅延、権限エラーなどの一般的な問題を診断して解決できます。

API レートに基づく割り当てを超過しました

Agent Registry API を操作するとき、またはGoogle Cloud コンソールで Agent Registry をすばやく移動するときに、リクエスト率の上限を超えると、次のエラーが発生します。

429 Too Many Requests

この問題を解決するには、API クライアントに指数バックオフを実装してリクエスト率を管理します。Agent Registry API には、グローバルおよびリージョンごとに、1 分あたり 1,200 リクエスト（1 秒あたり 20 秒間クエリ数）のデフォルトのレートに基づく割り当てがあります。

Google Cloud コンソールでタブを切り替えるときにスロットリングが発生した場合は、しばらく待ってからもう一度お試しください。プログラムによるユースケースでより高い上限が必要な場合は、RequestsPerMinute 指標の割り当ての増加をリクエストします。

手動登録時のペイロード サイズエラー

サイズ上限を超える仕様ファイルを使用してエージェントまたは MCP サーバーを手動で登録すると、次のエラーが発生します。

API は、ペイロードが大きすぎるというエラーでリクエストを拒否します。

この問題を解決するには、agent-card.json ファイルまたは toolspec.json ファイルが 10 KB 未満であることを確認します。AgentSpec と McpServerSpec のコンテンツ サイズは 10 KB に制限されています。この上限を遵守するには、JSON ファイルを縮小するか、不要な空白を削除するか、ツールの説明を簡潔にします。詳細については、JSON スキーマをご覧ください。

作成後にエージェントまたは MCP サーバーが見つからない

Google Workspace や Gemini Enterprise などのサポートされている Google Cloud プロダクトでエージェントまたは MCP サーバーを作成すると、次のエラーが発生します。

ListAgents API または ListMcpServers API を呼び出しても、リソースが出力に表示されない。

この問題を解決するには、バックグラウンド同期が完了するまで待ちます。リソースはリアルタイムで更新されますが、定期的なオフライン バッチジョブによって他の統合が入力されます。数時間経ってもリソースが表示されない場合は、プロジェクトの Service Usage の設定を確認し、関連する API が有効になっていることを確認します。

長時間実行オペレーションが停止しているように見える

エージェントをデプロイするか、複雑なバインディングを構成すると、次のエラーが発生します。

オペレーションにかなりの時間がかかり、停止しているように見える。

この問題を解決するには、get_operation MCP ツールまたは google.longrunning.Operations.GetOperation API エンドポイントを使用して、オペレーションのステータスをポーリングします。エージェントと MCP バックエンドの作成によっては、大規模なインフラストラクチャのプロビジョニングが必要になるため、長時間実行オペレーション（LRO）に最大 30 分かかることがあります。その結果としてクライアントのタイムアウト設定を構成し、done ブール値フラグをポーリングして完了を確認します。

利用可能なバインディングの取得時に結果が空になる

ターゲット AuthProvider リソースに対する十分な権限がない状態で、認証プロバイダの使用可能なバインディングを取得すると、次のエラーが発生します。

バインディングが存在する場合でも、API は空の配列またはアクセスエラーを返します。

この問題を解決するには、プリンシパルにターゲット AuthProvider リソースに対する正しい Identity and Access Management（IAM）権限があることを確認します。API は厳格な IAM チェックを適用し、呼び出し元がアクセスできない認証プロバイダを参照する Binding オブジェクトを削除します。プリンシパルに、認証プロバイダに対する必要なアクセス権と、プロジェクトに対する roles/agentregistry.viewer ロールがあることを確認します。

スキル リビジョンのダウンロードが 302 エラーで失敗する

?alt=media クエリ パラメータを指定して GetSkillRevision API を使用してスキル リビジョン ペイロードをダウンロードしようとしたときに、HTTP クライアントがリダイレクトに従わない場合、次のエラーが発生します。

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

この問題を解決するには、HTTP クライアントがリダイレクトを自動的にフォローするように構成されていることを確認します。?alt=media エンドポイントでは、スキルのアーカイブを正常にダウンロードするために 302 リダイレクトが必要です。たとえば、curl を使用している場合は、コマンドに -L フラグまたは --location フラグを追加します。

スキルのリビジョン検証が失敗するか、FAILED 状態が表示される

無効な ZIP アーカイブを使用して新しいスキル リビジョンを作成すると、次のエラーが発生します。

リビジョンは FAILED 状態に移行し、エージェントによって読み込むことができません。

この問題を解決するには、検証ログを確認するか、ZIP ペイロードの内容を検査します。

  • ZIP アーカイブのルートに SKILL.md ファイルが含まれていることを確認します。
  • SKILL.md ファイルに、name と description の両方が定義された有効な YAML フロントマター ブロックがあることを確認します。
  • ZIP ペイロードがサイズ制限を超えていないことを確認します。圧縮サイズは 500 KB 未満、非圧縮時の合計サイズは 10 MB 未満、個々のファイルサイズは 1 MB 未満にする必要があります。
  • アーカイブにシンボリック リンク、ディレクトリ トラバーサル要素（.. など）、絶対パスが含まれていないことを確認します。

スタンドアロン スキルがサービスまたはエージェントのリソースリストに表示されない

gcloud agent-registry services list や gcloud agent-registry agents list を実行するなどして、スタンドアロンのスキルのエージェント リストまたはサービスリストをクエリすると、次のエラーが発生します。

スタンドアロン スキルは出力に表示されません。

この問題を解決するには、代わりに skills コレクションをクエリします。

  • 手動で登録されたエージェント、MCP サーバー、エンドポイントとは異なり、スタンドアロン スキルは書き込み可能な Service リソースや、Agent、McpServer、Endpoint の検出リソースを使用しません。代わりに、Agent Registry はスタンドアロン スキルを最上位の Skill リソースとバージョニングされた SkillRevision リソースとして直接表します。
  • スタンドアロン スキルを一覧表示、検索、検査するには、Google Cloud コンソールの [スキル] タブを使用するか、gcloud alpha agent-registry skills list または gcloud alpha agent-registry skills search を実行するか、skills REST API メソッドを呼び出します。手順については、スキルを管理するとスタンドアロン スキルを検索するをご覧ください。
  • エージェントのエージェント カードで宣言されているインライン A2A スキルを探している場合は、gcloud agent-registry agents describe または gcloud agent-registry agents search を使用して、Agent 検出リソースの skills フィールドを調べます。

IAP ポリシーの管理時にリソース エンティティが見つからないエラー

gcloud iap web コマンドを使用して Agent Registry リソースの Identity-Aware Proxy（IAP）下り（外向き）ポリシーを管理すると、次のエラーが発生します。

NOT_FOUND: Requested entity was not found

この問題を解決するには、次の点を確認してください。

  • 登録ステータス: ターゲット コンポーネントが Agent Registry の想定される場所に登録されていることを確認します。
  • 識別子の形式: コマンドまたはポリシー バインディングで、レジストリ識別子 URN ではなく、標準のリソース名が指定されていることを確認します。
  • リソースフラグ: gcloud iap web に渡すリソースフラグが、基盤となる Agent Registry の子リソースタイプと一致していることを確認します。
    • 外部 API や Google API の下り（外向き）ポイントなどのエンドポイントには、--endpoint フラグを使用します。
    • Model Context Protocol サーバーの場合は、--mcp-server フラグを使用します。
    • 登録済みエージェントの場合は、--agent フラグを使用します。

gcloud agent-registry endpoints list、gcloud agent-registry mcp-servers list、gcloud agent-registry agents list から返されたリソース名をチェックして、リソース名に /endpoints/、/mcpServers/、/agents/ が含まれているかどうかを確認します。間違ったリソースフラグを渡すと（たとえば、MCP サーバー ID に --endpoint を渡すと）、NOT_FOUND エラーが発生します。

IAP ウェブ IAM ポリシーの適用時に権限が拒否される

必要な管理ロールがない状態で Agent Registry リソースに IAP ウェブ IAM ポリシーを適用または変更すると、次のエラーが発生します。

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

この問題を解決するには、アクティブなユーザーまたはサービス アカウントに、レジストリとゲートウェイをホストするプロジェクトに対する必要な権限があることを確認します。

  • 呼び出し元に、中央のガバナンス プロジェクトに対する IAP ポリシー管理者（roles/iap.admin）またはプロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）のロールが付与されていることを確認します。
  • 呼び出し元に iap.web.setIamPolicy 権限と resourcemanager.projects.setIamPolicy 権限があることを確認します。

リージョン ロケーションにリモート MCP サーバーが見つかりません

自動的に登録された Google または Google Cloud リモート MCP サーバーをクエリするか、us-central1 などのリージョン ロケーションで IAP 下り（外向き）ポリシーを適用すると、次のエラーが発生します。

サービスがリージョン エンドポイント（REP）を提供している場合や、トラフィックがリージョン Agent Gateway を経由してルーティングされている場合でも、リクエストは NOT_FOUND エラーまたは空のリストを返します。

Agent Registry が、有効な API の Google またはGoogle Cloud リモート MCP サーバーを自動的に登録すると、McpServer リソースは global ロケーションにのみ作成され、us-central1 などの個々のリージョンには作成されません。サービスが https://SERVICE.REGION.rep.googleapis.com/mcp などのリージョン エンドポイントを提供している場合、Agent Registry は、それらのリージョン URL を、その単一の global McpServer リソースの interfaces フィールドに一覧表示します。

この問題を解決するには、以下のいずれかを行います。

  • 自動登録されたサーバーに global を使用する: 呼び出し元のエージェントがリージョン ゲートウェイを介してトラフィックをルーティングする場合でも、--location=global を使用して Agent Registry でサーバーをクエリする場合や、--region=global を使用して IAP 下り（外向き）ポリシーを適用する場合は、global のロケーションを指定します。
  • データ所在地のリージョンに登録する: レジストリ メタデータを特定のリージョンに保持する必要がある場合は、カスタム MCP サーバーをリージョンの Cloud Run または Google Kubernetes Engine（GKE） ランタイムにデプロイするか、MCP サーバーとそのリージョン エンドポイント URL をそのリージョンに手動で登録し、同じリージョンに IAP ポリシーを適用します。Agent Gateway がターゲット URL を解決するときに、リージョン レジストリ エントリが global エントリよりも優先されます。

Agent Gateway で Model Armor を構成する際のリージョン不一致エラー

一致しないリージョン間で Agent Gateway に Model Armor ポリシー フィルタを構成すると、次のエラーが発生します。

認可ポリシーの作成がリージョン不一致エラーで失敗するか、ゲートウェイを介して MCP サーバーにルーティングされたトラフィックがポリシー評価に失敗します。

この問題を解決するには、ゲートウェイ リソースとターゲット ポリシー バインディングのリージョンの一致を確認します。

  • ゲートウェイと Model Armor のリージョンを一致させる: Agent Gateway、Model Armor テンプレート、認可拡張機能、ポリシーがすべて同じリージョン（us-central1 など）に存在することを確認します。
  • global またはリージョン MCP サーバーにルーティングする: Model Armor を使用するためだけに、リージョンに global MCP サーバーを再登録する必要はありません。Model Armor はリージョン ゲートウェイでリクエストとレスポンスのペイロードを検査するため、リージョン ゲートウェイは、リージョン宛先だけでなく、global ロケーションに登録されている MCP サーバーにルーティングされるトラフィックも検査して管理できます。
  • IAP 下り（外向き）バインディングをターゲットの登録ロケーションに一致させる: ターゲット McpServer リソースが登録されているロケーションに IAP 下り（外向き）認可バインディングを適用します。自動的に登録されたリモート MCP サーバーには global を使用し、リージョンに登録された MCP サーバーには特定のリージョンを使用します。

マルチリージョン ロケーションで手動登録またはバインディングの作成が失敗する

us や eu などのマルチリージョン ロケーションで、エージェント、MCP サーバー、エンドポイントを手動で登録しようとしたり、バインディングを作成しようとしたりすると、次のエラーが発生します。

API は、サポートされていないロケーションまたは無効な引数エラーでリクエストを拒否します。

この問題を解決するには、サポート対象の地域（us-central1 や europe-west1 など）または global ロケーションを指定します。us と eu のマルチリージョン ロケーションでは、自動的に登録されたコンポーネントの検出と、スタンドアロンのスキルの登録または検出のみがサポートされています。サポートされているロケーションの一覧については、Agent Registry のロケーションをご覧ください。

Workforce Identity 連携を使用して Agent Registry にアクセスする際の失敗

Workforce Identity 連携で認証されたときに、Google Cloud コンソールで Agent Registry にアクセスするか、Google Cloud CLI を使用すると、次のエラーが発生します。

Google Cloud コンソールに、次のような一般的な読み込みエラーが表示されます。

  • 「読み込み中にエラーが発生しました...」
  • 「サーバーはリクエストを実行できませんでした」
  • 「読み込めませんでした」

また、gcloud コマンドから error 13: an internal error has occurred などの内部エラーが返されることがあります。

この問題を解決するには、Cloud Identity または Google Workspace で管理されている標準の Google アカウントで認証します。アカウントに roles/agentregistry.admin や roles/agentregistry.viewer などの必要な権限があることを確認します。

Gemini Enterprise Agent Platform のガバナンス サービスでは、フェデレーション ID のサポートが制限されています。連携プリンシパルに広範な IAM ロールを付与しても、問題は解決しません。