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 ブール値フラグをポーリングして完了を確認します。

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

この問題は、認証プロバイダの利用可能なバインディングを取得するときに発生する可能性があります。バインディングが存在することを確認しても、API が empty array またはアクセスエラーを返します。

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

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

?alt=media クエリパラメータを指定して GetSkillRevision API を使用してスキルリビジョンペイロードをダウンロードしようとすると、この問題が発生する可能性があります。リクエストが失敗し、次のようなエラーが返されます。

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

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

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

この問題は、新しいスキルリビジョンを作成した後に発生する可能性があります。リビジョンが FAILED 状態に移行し、エージェントが読み込むことができなくなります。

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

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

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

gcloud iap web コマンドを使用して Agent Registry リソースのアウトバウンドポリシーを管理する場合、この問題が発生することがあります。

NOT_FOUND: Requested entity was not found

この問題を解決するには、gcloud iap web に渡すリソースフラグが、基盤となる Agent Registry の子リソースタイプと一致していることを確認します。

外部 API や Google API の下り（外向き）ポイントなどのエンドポイントには、--endpoint フラグを使用します。
Model Context Protocol サーバーの場合は、--mcp-server フラグを使用します。
登録済みエージェントの場合は、--agent フラグを使用します。

gcloud agent-registry [endpoints|mcp-servers|agents] list から返されたリソース URI を確認して、リソースパスに /endpoints/、/mcpServers/、/agents/ のいずれかが含まれているかどうかを確認します。間違ったリソースフラグを渡すと（MCP サーバー ID に --endpoint を渡すなど）、NOT_FOUND エラーが発生します。

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

Agent Registry リソースに Identity-Aware Proxy ウェブ IAM ポリシーを適用または変更すると、この問題が発生する可能性があります。

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

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

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

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