Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

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

エージェント レジストリの問題をトラブルシューティングする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。