このページでは、エージェント レジストリに関する問題を解決する方法について説明します。
API レートに基づく割り当てを超過しました
この問題は、Agent Registry API を操作する場合や、 Google Cloud コンソールで Agent Registry をすばやく移動する場合に発生することがあります。
429 Too Many Requests
この問題を解決するには、API クライアントに指数バックオフを実装して、リクエスト レートを管理します。Agent Registry API のデフォルトのレートに基づく割り当ては、グローバルとリージョンごとに 1 分あたり 1,200 リクエスト（秒間クエリ数 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 ロールがあることを確認します。