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

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

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

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

429 Too Many Requests

この問題を解決するには、API クライアントに指数バックオフを実装してリクエスト率を管理します。Agent Registry API には、Agent Registry リソースに適用される、1 分あたり 1 ロケーションあたりのリクエストのデフォルトのレートに基づく割り当てがあります。

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 ペイロードがサイズ制限を超えていないことを確認します。圧縮サイズは 1 MB 未満、非圧縮時の合計サイズは 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 agent-registry skills list または gcloud 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 は、その単一の global McpServer リソースの interfaces フィールドに、それらのリージョン URL を一覧表示します。

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

  • 自動登録されたサーバーに 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 サーバーには特定のリージョンを使用します。

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 ロールを付与しても、問題は解決しません。

セキュリティ上の検出結果により、スキル リビジョンのダウンロードがブロックされました

スキルのスキャン ポリシーが ENABLED_BLOCKING に設定されていて、リビジョンにセキュリティ検出結果がある場合に、スキル リビジョン ペイロードをダウンロードしようとすると、次のエラーが発生します。

FAILED_PRECONDITION: cannot download skill revision with scan findings when scanning policy is ENABLED_BLOCKING

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

  1. gcloud agent-registry findings list コマンドを実行して、リビジョンで検出されたセキュリティ検出結果を検査します。このコマンドには roles/agentregistry.admin ロールが必要です。
  2. ローカル ソースファイルで検出結果を修正します。たとえば、不正なネットワーク下り（外向き）コードの削除、公開された認証情報の削除、プロンプト インジェクション パターンの排除などを行います。
  3. 新しいスキル リビジョンをアップロードして登録します。
  4. または、承認済みのテスト環境またはステージング環境で作業している場合は、--scanning-policy=enabled-nonblocking を使用してスキルのスキャン ポリシーを ENABLED_NONBLOCKING に更新します。詳細については、セキュリティ問題のスキルをスキャンするをご覧ください。

デフォルトのリビジョンの設定またはブロック ポリシーの有効化が失敗する

リビジョンに検出結果または保留中のスキャン結果があるときに、スキルのデフォルトのリビジョン ポインタ（--default-revision）を更新するか、スキルのスキャン ポリシーを ENABLED_BLOCKING に変更すると、次のエラーが発生します。

API から FAILED_PRECONDITION エラーが返され、次のいずれかのメッセージが表示されます。

  • cannot set default revision to a revision with scan findings when scanning policy is ENABLED_BLOCKING
  • cannot set default revision to a revision with pending scan results when scanning policy is ENABLED_BLOCKING
  • cannot set scanning policy to ENABLED_BLOCKING when default revision has scan findings
  • cannot set scanning policy to ENABLED_BLOCKING when default revision has pending scan results

この問題を解決するには、次の操作を行います。

  • スキャンがまだ保留中（RUNNING）の場合は、バックグラウンド スキャンが完了するまで待ち、scanResult.scanState が SUCCEEDED に解決され、findings がないことを確認してから、リビジョンをデフォルトとして設定するか、ENABLED_BLOCKING を有効にします。
  • ターゲットまたは現在のデフォルト リビジョンにセキュリティに関する検出結果がある場合は、セキュリティの問題が解決された新しいリビジョンを公開し、scanResult.scanState が SUCCEEDED に解決され、findings がリストされていないことを確認して、そのクリーンなリビジョンをスキルの defaultRevision として設定します。

非圧縮サイズの上限を超えているため、スキル リビジョンが拒否されました

非圧縮スキャンサイズの上限を超えるスキル リビジョンをアップロードすると、次のエラーが発生します。

長時間実行オペレーションが INVALID_ARGUMENT エラーで失敗するか、リビジョンの scanResult.scanState が UNSUPPORTED_FORMAT に移行します。

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

  • ZIP パッケージ内の非圧縮ファイルを検査します。大規模なデータセット、モデル バイナリ、不要なアセットを削除して、各ファイルを 1 MB 未満、抽出されたパッケージの合計を 10 MB 未満にしてください。
  • 開発ワークフローで、プロジェクトの迅速なプロトタイピングのために大きなファイルをアップロードする必要がある場合は、組織のポリシーで許可されている場合は、--scanning-policy=disabled を使用してスキルのスキャン ポリシーを DISABLED に更新します。

組織のポリシーにより、スキル スキャンを無効にできません

スキャン ポリシーを DISABLED に設定してスキルを作成または更新した場合、または scanningConfig.policy が以前に DISABLED に設定されていた既存のスキルのフィールドを更新した場合、次のエラーが発生します。

リクエストは、カスタム組織のポリシーの制約違反エラーで失敗します。

この問題を解決するには、次の操作を行います。

  • 組織が、resource.scanningConfig.policy == "DISABLED" を拒否する agentregistry.googleapis.com/Skill に custom.skillsScanningEnforcement などのカスタム組織ポリシー制約を適用している。
  • 組織ポリシーが適用される前に scanningConfig.policy が DISABLED に設定されていた既存のスキルを更新する場合は、UpdateSkill リクエストに scanningConfig.policy の更新を含め、ENABLED_BLOCKING または許可された値に設定します。
  • テスト環境またはサンドボックス環境でスキャンを無効にするには、組織のポリシー管理者に、exempt-scanning-enforcement: true などの条件付き除外タグをプロジェクトに追加するよう依頼します。

詳細については、組織ポリシー サービスを使用してスキャンを適用するをご覧ください。

スキャンを有効にした後にスキル リビジョンがスキャンされない

以前にアップロードされたリビジョンがある既存のスキルでスキャンを有効にすると、次のエラーが発生します。

既存のリビジョンのスキャン ステータス（scanResult.scanState）は DISABLED のままになり、リビジョンはスキャンされず、セキュリティ検出結果は生成されません。

スキルのスキャンを有効にすると、スキャンが有効になった後に作成されたスキル リビジョンにのみ適用されます。Agent Registry は、スキャンが有効になる前に作成されたリビジョンを遡ってスキャンしません。

この問題を解決するには、スキルの新しいスキル リビジョンをアップロードして登録します。新しいリビジョンをアップロードすると、Agent Registry はスキルの更新されたスキャン構成に従ってペイロードをスキャンします。詳細については、スキル リビジョンを作成するとスキルをスキャンしてセキュリティの問題を検出するをご覧ください。

スキルがすでに存在するため、CMEK を構成できない

スキルがすでに存在するロケーションに SkillEncryptionSpec を設定または更新しようとすると、次のエラーが発生します。

FAILED_PRECONDITION: crypto_key_name can only be set or updated when no Skills exist in this location

プロジェクトとロケーションで顧客管理の暗号鍵（CMEK）を構成または更新できるのは、そのロケーションにスキルが存在しない場合のみです。

この問題を解決するには、対象のロケーションで最初のスキルを登録する前に SkillEncryptionSpec を構成するか、Cloud Key Management Service 鍵を設定または更新する前に、そのロケーションにある既存のスキルを削除します。詳細については、スキルの CMEK を構成するをご覧ください。

スキルの Cloud KMS 鍵のロケーションが無効です

必要な Cloud KMS のロケーションにない Cloud KMS 鍵、またはサポートされていないスキル ロケーションの Cloud KMS 鍵を使用して SkillEncryptionSpec を構成すると、次のエラーが発生します。

リクエストは失敗し、次のいずれかを示す INVALID_ARGUMENT エラーが返されます。

  • crypto_key_name "..." is in location "...", but Skills in location "..." can only be encrypted with a Cloud KMS key in location "..."
  • customer-managed encryption keys aren't supported for Skills in location "..."

この問題を解決するには、サポートされているスキルのロケーション（us または eu）で CMEK を構成していること、および Cloud KMS 鍵が必要な Cloud KMS マルチリージョン ロケーションに存在することを確認します。

スキルの場所 必要な Cloud KMS 鍵のロケーション
us us
eu europe

Cloud KMS は、欧州連合のマルチリージョンのロケーション識別子として europe を使用します。global などの他のロケーションでは CMEK はサポートされていません。詳細については、スキルの CMEK を構成するをご覧ください。

CMEK 組織のポリシーによりスキルの作成がブロックされる

CMEK 組織ポリシーの制約が適用されるプロジェクトでスキルまたはスキル リビジョンを作成すると、次のエラーが発生します。

リクエストは失敗し、次のいずれかを示す FAILED_PRECONDITION エラーが返されます。

  • constraint "constraints/gcp.restrictNonCmekServices" violated for value "agentregistry.googleapis.com". See https://cloud.google.com/kms/docs/cmek-org-policy#require-cmek for more information.
  • constraint "constraints/gcp.restrictCmekCryptoKeyProjects" violated for value "projects/KMS_PROJECT_ID". See https://cloud.google.com/kms/docs/cmek-org-policy#restrict-cmek-projects for more information.

この問題を解決するには、次の操作を行います。

  • constraints/gcp.restrictNonCmekServices に違反している場合、組織では Agent Registry に CMEK 保護が必要です。CMEK がサポートされているロケーション（us または eu）にスキルを作成し、そのロケーションにスキルを作成する前に、そのロケーションの SkillEncryptionSpec を構成します。
  • constraints/gcp.restrictCmekCryptoKeyProjects に違反している場合、ロケーションの SkillEncryptionSpec で構成された Cloud KMS 鍵は、組織の constraints/gcp.restrictCmekCryptoKeyProjects ポリシーで許可されていないプロジェクトに属しています。そのロケーションにスキルが存在しない場合は、許可されたプロジェクトの Cloud KMS 鍵を参照するように SkillEncryptionSpec を更新するか、組織のポリシー管理者に連絡して鍵プロジェクトを許可します。

詳細については、組織ポリシー サービスを使用して CMEK を適用するをご覧ください。