エージェントのデプロイのトラブルシューティング

このドキュメントでは、Agent Runtime にエージェントをデプロイするときに発生する可能性のあるエラーを解決する方法について説明します。シリアル化エラー、権限エラー、VPC-SC 境界違反など、さまざまな一般的な問題について説明します。

注: エージェントのエラーログを検索してフィルタするには、ログ エクスプローラを使用し、RESOURCE TYPE に「Vertex AI 推論エンジン」を選択して、対応する RESOURCE CONTAINER 値(プロジェクト番号など)と REASONING ENGINE ID 値を選択します。

コンテナのビルドエラーと起動エラー

Agent Runtime がエージェントのコンテナをビルドまたは起動しているときにデプロイが失敗した場合は、次のいずれかの問題が原因である可能性があります。

コンテナ イメージのビルドに失敗しました

問題:

デプロイが失敗し、400、INVALID_ARGUMENT ステータス(REASONING_ENGINE_BUILD_FAILED)と次のようなメッセージが表示されます。

The Reasoning Engine could not be deployed because its container image failed to build.

考えられる原因:

エージェント オブジェクト、ソースファイル、Dockerfile からエージェントをデプロイすると、Agent Runtime はエージェントのコンテナ イメージをビルドします。次のいずれかのステップが失敗すると、ビルドは失敗します。

  • パッケージ要件のインストール: requirements のパッケージまたはソースファイルの要件ファイルが存在しない、存在しないバージョンを固定している、別のパッケージと競合している、またはエージェントの Python バージョンをサポートしていない。
  • ローカル ホイールのインストール: requirements にリストされているホイール ファイルは extra_packages にも含まれていないため、インストールできません。
  • インストール スクリプトの実行: installation_scripts ディレクトリ内のスクリプトがエラーで終了します。
  • Dockerfile のビルド: Dockerfile(image_spec)からデプロイすると、Dockerfile の命令が失敗します。

推奨される解決策:

  • エラー メタデータの logs_url フィールドにリンクされているビルドログを確認して、失敗したステップを見つけます。ビルドログ エントリには、ログ ID reasoning_engine_build が含まれます。ログをクエリするには、クエリの作成をご覧ください。
  • エラーをローカルで再現するには、デプロイされたエージェントの Python バージョンを使用する新しい仮想環境に同じ要件をインストールし、pip が報告するエラーを修正します。

    python -m venv agent-env
    agent-env/bin/pip install -r requirements.txt
  • ローカルでテストしたバージョンをビルドでインストールするには、パッケージ バージョンを固定します。パッケージの要件を定義するをご覧ください。

  • ローカル ホイールをインストールする場合は、requirements と extra_packages の両方に含めます。追加のパッケージを定義するをご覧ください。

  • インストール スクリプトを使用する場合は、クリーンな環境で root 権限で実行したときに、各スクリプトが正常に終了することを確認してください。ビルド オプションを定義するをご覧ください。

  • Dockerfile からデプロイする場合は、同じソースファイルからローカルでコンテナ イメージをビルドし(docker build などを使用)、失敗した命令を修正します。

適用されないソリューション:

  • 要件、インストール スクリプト、Dockerfile を変更せずにデプロイを再試行すると、ビルドで同じ手順が実行されるため、同じように失敗します。

コンテナ イメージのビルドがタイムアウトしました

問題:

デプロイが 504、DEADLINE_EXCEEDED ステータス(REASONING_ENGINE_BUILD_TIMEOUT)で失敗し、エージェントのコンテナ イメージのビルドが時間内に完了しなかったというメッセージが表示されます。

考えられる原因:

ソースファイルからデプロイすると、Agent Runtime はコードとその依存関係をインストールするコンテナ イメージをビルドします。許可された時間が経過してもビルドが実行されている場合、デプロイは失敗します。ビルドに時間がかかるのは、通常、インストールする依存関係が原因です。次に例を示します。

  • requirements 内のパッケージの長いリスト(エージェントが使用しないパッケージを含む)。
  • ビルド環境用のビルド済みホイールがないパッケージ。ビルド中にソースからコンパイルされます。
  • 固定されていないバージョンや、固定が緩いバージョン。依存関係の解決が遅くなります。

推奨される解決策:

  • エラー メタデータの logs_url フィールドにリンクされているビルドログを確認して、ビルドが停止したときに実行されていたステップを確認します。
  • 不要な依存関係を削除し、必要なすべてのパッケージのバージョンを固定します。
  • ビルド中にコンパイルされないように、ビルド済みの wheel を公開するパッケージとバージョンを優先します。
  • デプロイを再試行します。コードとは関係のない理由で、ビルドが通常よりも長く実行されることがあります。

コンテナを起動できませんでした

問題:

デプロイが 400、INVALID_ARGUMENT ステータス(REASONING_ENGINE_CONTAINER_FAILED_TO_START)で失敗し、エージェントのコンテナが起動タイムアウト内にサービスを開始しなかったというメッセージが表示されます。

考えられる原因:

Agent Runtime はコンテナでエージェントを起動し、リクエストの受信を待機します。起動タイムアウト前にコンテナが終了するか、応答しない場合、デプロイは失敗します。一般的な原因は次のとおりです。

  • 依存関係がない: エージェントが requirements または extra_packages にリストされていないパッケージをインポートしているため、エージェントの読み込みが失敗し、ModuleNotFoundError などのエラーが発生します。
  • パッケージ バージョンの不一致: デプロイされた環境にインストールされているパッケージが開発環境のパッケージと異なるため、エージェントの読み込みが AttributeError: Can't get attribute などのエラーで失敗します。シリアル化エラーをご覧ください。
  • 初期化中のエラー: エージェントの set_up() メソッド、またはエージェントの読み込み時に実行される他のコードが例外を発生させるか、到達できないリソースを待機します。
  • 初期化が遅い: エージェントの読み込みに、起動タイムアウトよりも時間がかかります。
  • カスタム コンテナがリッスンしていない: カスタム コンテナは、ポート 8080 の 0.0.0.0 で HTTP リクエストをリッスンする必要があります。ランタイム コントラクトをご覧ください。
  • Agent Gateway が起動をブロックする: Agent Gateway を介してトラフィックをルーティングする場合、Identity-Aware Proxy(IAP)が初期化呼び出しをブロックした場合、エージェント ID に必要なロールがない場合、またはカスタム コンテナがゲートウェイのルート証明書を信頼していない場合、起動は失敗します。Agent Runtime の起動中のエラーとカスタム コンテナ(BYOC)でデプロイされたエージェントが Agent Gateway に接続できないをご覧ください。

推奨される解決策:

  • エラー メタデータの logs_url フィールドにリンクされているエージェントのログを確認して、コンテナを停止したエラーを見つけます。エージェントのログを表示するをご覧ください。
  • 不足しているパッケージを requirements または extra_packages に追加し、開発で使用するバージョンを固定します。
  • ローカルでエラーを再現するには、同じ Python バージョンのクリーンな環境に requirements にリストされているパッケージのみをインストールし、エージェントをインポートしてインスタンス化します。
  • 外部サービスへの接続など、処理が遅い、または失敗しやすい作業をエージェントの初期化から除外します。
  • カスタム コンテナの場合は、サーバーが 0.0.0.0 と PORT 環境変数のポート(デフォルトは 8080)をリッスンしていることを確認します。

適用されないソリューション:

  • エージェントまたはその依存関係を変更せずにデプロイを再試行すると、通常は同じように失敗します。これは、原因がエージェント コードまたはその環境にあるためです。

コンテナが時間内に起動しなかった

問題:

デプロイが 504、DEADLINE_EXCEEDED ステータス(REASONING_ENGINE_CONTAINER_START_TIMEOUT)で失敗し、エージェントのコンテナが時間内にサービスを開始しなかったというメッセージが表示されます。

考えられる原因:

イメージがビルドされると、Agent Runtime はエージェントのコンテナを起動し、リクエストを処理する準備が整うまで待機します。許可された時間が経過してもコンテナが起動している場合、デプロイは失敗します。一般的な原因は次のとおりです。

  • インポート時の処理が遅い。たとえば、エージェントのモジュールがインポートされるときに、大規模なモデルやファイルが読み込まれる。
  • エージェントの set_up() メソッドでの処理が遅い、またはブロックされている(到達不能なサービスを待機するネットワーク呼び出しなど)。

推奨される解決策:

  • エラー メタデータの logs_url フィールドにリンクされているコンテナログを確認して、起動が停止した場所を確認します。
  • コストの高い初期化をモジュールのインポート時間から外し、set_up() のステップ数を最小限に抑えます。最初のリクエストを処理するために必要のない作業を延期します。
  • 起動中にエージェントが呼び出すサービスにエージェントからアクセスできることを確認し、それらの呼び出しにタイムアウトを設定して、起動がいつまでもブロックされないようにします。
  • コンテナログにエージェントが正常に起動したことが示されている場合は、デプロイを再試行します。コードとは関係のない理由で、起動に通常よりも時間がかかることがあります。

事前構築テンプレートのエラー

デプロイ中に LangchainAgent テンプレートで問題が発生した場合は、このセクションで説明する問題のいずれかが原因である可能性があります。

サーバーエラー

問題:

次のようなエラー メッセージが表示されます。

InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.

残念ながら、これは実行時のコンテナに関する問題に対するキャッチオール エラーであり、発生する可能性のある多くのエラーのいずれかが原因である可能性があります。

考えられる原因:

  • LangchainAgent の状態が不正。これは、エージェントをデプロイする前に LangchainAgent で .set_up() が呼び出された場合に発生する可能性があります。
  • パッケージ バージョンに一貫性がない。これは、開発環境にインストールされているパッケージが、Agent Runtime のリモート環境にインストールされているパッケージと異なる場合に発生する可能性があります。

推奨される解決策:

  • LangchainAgent の状態が不正。エージェントをデプロイする前に、LangchainAgent の新しいインスタンスをインスタンス化するか、コードから agent.set_up() を削除します。
  • パッケージの仕様が一致しない。シリアル化エラーのトラブルシューティングに関するセクションをご覧ください。

シリアル化エラー

一般に、エージェントをデプロイするときは、「ローカル」環境と「リモート」環境が同期していることを確認することが重要です。これを行うには、エージェントをデプロイするときに requirements= を指定します。

シリアル化に関する問題が発生した場合(「pickle」または「pickling」に関連するエラーは「serialization」エラーと同義です)、このセクションで説明する問題のいずれかが原因である可能性があります。

Pydantic のバージョン

問題:

次のようなエラー メッセージが表示されます。

PicklingError: Can't pickle <cyfunction str_validator at 0x7ca030133d30>: it's
not the same object as pydantic.validators.str_validator

考えられる原因:

これは、pydantic パッケージがバージョン 2.6.4 より古い場合に発生することがあります。使用しているバージョンを確認するには、ターミナルで次のコマンドを実行します。

pip show pydantic

推奨される解決策:

ターミナルで次のコマンドを実行して、パッケージを更新します。

pip install pydantic --upgrade

ターミナルで次のコマンドを実行して、バージョン 2.6.4 以降を使用していることを確認します。

pip show pydantic

ノートブック インスタンス(Jupyter、Colab、Workbench など)を使用している場合、更新されたパッケージを使用するには、ランタイムを再起動する必要があります。

Cloudpickle のバージョン

問題:

次のようなエラー メッセージが表示されます。

AttributeError: Can't get attribute '_class_setstate' on <module 'cloudpickle.cloudpickle'
from '/usr/local/lib/python3.10/site-packages/cloudpickle/cloudpickle.py'>

考えられる原因:

これは、開発環境とデプロイ環境で cloudpickle パッケージのバージョンが異なる場合に発生することがあります。開発で使用しているバージョンを確認するには、ターミナルで次のコマンドを実行します。

pip show cloudpickle

推奨される解決策:

エージェントをデプロイする際に requirements= を指定して、両方の環境(ローカル開発環境とリモートでデプロイされたエージェントなど)に同じバージョンの cloudpickle をデプロイします。

サーバーエラー

問題:

次のようなエラー メッセージが表示されます。

InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.

考えられる原因:

これは、エージェントをデプロイするときに、sys_version= が開発環境と異なる場合に発生する可能性があります。

推奨される解決策:

エージェントをデプロイしたら、入力引数から sys_version= を削除することを検討してください。問題が解決しない場合は、バグレポートを提出してください。

Cloud Storage バケットのエラー

エージェントの収集とアップロードにデプロイ時に使用される Cloud Storage ステージング バケットで問題が発生した場合は、次のいずれかの問題が原因である可能性があります。

権限に関するエラー

推奨される解決策:

既存のバケットを使用する場合は、Agent Platform の使用を認証されたプリンシパル(ご自身またはサービス アカウント)に、バケットへの Storage Admin アクセス権があることを確認し、サービス アカウントに権限を付与します。

または、エージェントをデプロイするときに新しいバケットを指定すると、SDK が必要な権限を持つバケットを作成します。

問題が解決しない場合は、バグレポートを提出してください。

Cloud Storage バケットのサブディレクトリが作成されない

問題:

次のようなエラー メッセージが表示されます。

NotFound: 404 Can not copy from \"gs://[LOCATION]-*/agent_engine/agent_engine.pkl\" to \"gs://*/code.pkl\", check if the source object and target bucket exist.

(404 は、存在しないフォルダにコピーしようとすると発生します)

考えられる原因:

これは、バージョン 1.49.0 より前の google-cloud-aiplatform のバージョンで文字列補間に問題があるためと考えられます。この問題は、以降のバージョンで修正されています。使用している google-cloud-aiplatform のバージョンを確認するには、ターミナルで次のコマンドを実行します。

pip show google-cloud-aiplatform

推奨される解決策:

ターミナルで次のコマンドを実行して、パッケージを更新します。

pip install google-cloud-aiplatform --upgrade

ターミナルで次のコマンドを実行して、google-cloud-aiplatform のバージョン 1.49.0 以降を使用していることを確認します。

pip show google-cloud-aiplatform

ノートブック インスタンス(Jupyter、Colab、Workbench など)を使用している場合、更新されたパッケージを使用する前にランタイムを再起動する必要があります。

VPC-SC 違反エラー

VPC-SC で問題が発生している場合は、次のいずれかの問題が原因である可能性があります。

権限に関するエラー

問題:

次のようなエラー メッセージが表示されます。

Reasoning Engine instance REASONING_ENGINE_ID failed to start and cannot serve traffic.

または

Request is prohibited by organization's policy.

考えられる原因:

これは、VPC-SC 境界に必要な上り(内向き)ルールがないことが原因である可能性があります。

推奨される解決策:

VPC-SC 環境で Agent Platform を使用する場合は、境界に上り(内向き)ルールを作成して、推論エンジン サービス エージェント(service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com)から storage.googleapis.com サービスと artifactregistry.googleapis.com サービスへの上り(内向き)トラフィックを許可する必要があります。

カスタム サービス アカウントのエラー

サービス アカウントで問題が発生している場合は、次のいずれかの問題が原因である可能性があります。

サービス アカウントとして機能する

問題:

次のようなエラー メッセージが表示されます。

You do not have permission to act as service_account.

考えられる原因:

デプロイに使用されるカスタム サービス アカウントに対する iam.serviceAccounts.actAs 権限がない可能性があります。複数のカスタム サービス アカウントが存在するマルチエージェント システムでは、1 人のエージェント作成者またはデプロイ担当者が一部のサービス アカウントとして機能できます。間違ったサービス アカウントを使用している場合、このエラーは想定される動作です。

また、カスタム サービス アカウントがエージェントをデプロイするプロジェクトとは異なるプロジェクトにあり、iam.disableCrossProjectServiceAccountUsage 組織のポリシーがサービス アカウント プロジェクトで適用されている場合にも、このエラーが発生することがあります。

このシナリオに必要な構成の完全なリストについては、クロス プロジェクトのカスタム サービス アカウントをご覧ください。

推奨される解決策:

目的のサービス アカウントを使用していることを確認します。このサービス アカウントにサービス アカウント ユーザー(roles/iam.serviceAccountUser)のロールがあるかどうかを確認します。付与されていない場合は、このサービス アカウントに対するロールを付与するよう管理者に依頼してください。

プロジェクト間のシナリオの場合は、サービス アカウント プロジェクトに iam.disableCrossProjectServiceAccountUsage 組織のポリシーが適用されているかどうかを確認します。その場合は、管理者にポリシーを無効にするよう依頼してください。

メタデータ サーバーが利用不可

問題:

次のようなエラー メッセージが表示されます。

ServiceUnavailable: 503 Getting metadata from plugin failed with error

または

Compute Engine Metadata server unavailable due to : Could not fetch URI /computeMetadata/v1/instance/service-accounts/default/token

考えられる原因:

これは、カスタム サービス アカウントとエージェントが異なるプロジェクトにあり、Agent Platform サービス エージェント(service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com)にカスタム サービス アカウントに対する iam.serviceAccounts.getAccessToken 権限がない場合に発生する可能性があります。

このシナリオに必要な構成の完全なリストについては、クロス プロジェクトのカスタム サービス アカウントをご覧ください。

推奨される解決策:

エージェント プロジェクトの Agent Platform サービス エージェント(service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com)に、カスタム サービス アカウントに対するサービス アカウント トークン作成者(roles/iam.serviceAccountTokenCreator)ロールを付与するよう管理者に依頼します。

Agent Platform サービス エージェントは、エージェントのデプロイに使用するプロジェクトと同じプロジェクトに配置する必要があります。ロール付与の IAM バインディングは、カスタム サービス アカウントが存在するプロジェクトに存在する必要があります。

環境のプロビジョニングに失敗しました

問題:

エージェントの作成が 500、INTERNAL ステータス(REASONING_ENGINE_PROVISIONING_FAILED)で失敗し、エージェントの Google マネージド環境をプロビジョニングできなかったというメッセージが表示されます。

考えられる原因:

Agent Runtime は、プロジェクトとリージョンに最初のエージェントをデプロイする前に、サービス エージェントやホスティング環境など、エージェント用の Google マネージド リソースを設定します。この設定が失敗すると、そのプロジェクトとリージョンで保留中のすべてのエージェント作成が失敗し、このエラーが発生します。

推奨される解決策:

サポートに連絡し、失敗したオペレーションの名前を projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID の形式で伝えます。

適用されないソリューション:

  • Google が失敗した設定を最初に修正する必要があるため、エージェントの作成を再試行してもこのエラーは解決しません。
  • エージェントのコード、要件、resource_limits を変更しても、Agent Runtime がエージェントをデプロイする前にエラーが発生するため、問題は解決しません。
  • これらのリソースは Google が管理しているため、プロジェクトの割り当ての増加をリクエストしても効果はありません。

リソース不足エラー

デプロイが 429、RESOURCE_EXHAUSTED ステータスで失敗した場合は、次のいずれかの問題が原因である可能性があります。

API のレート制限または割り当てを超過している

問題:

デプロイが Error 429 または RESOURCE_EXHAUSTED ステータスで失敗する。

考えられる原因:

プロジェクトが API レート制限または同時リクエストの割り当てを超過している。

推奨される解決策:

  • デプロイ スクリプトに指数バックオフと再試行戦略を実装する。
  • Google Cloud の [割り当て] ページで、現在の使用量と「Agent Platform API」の上限を比較します。
  • 同時デプロイの頻度を減らす。

リージョンが一時的に容量上限に達している

問題:

デプロイが失敗し、429、RESOURCE_EXHAUSTED ステータスと、リージョンがメモリまたは CPU の合計許容量の上限に一時的に達していることを示すメッセージが表示されます。

考えられる原因:

リージョン内のエージェント デプロイは、Agent Runtime がユーザーに代わって管理し、そのリージョン内のすべての顧客が共有するサービス容量のプールを利用します。プールが枯渇すると、容量が解放されるまで、そのリージョンでの新しいデプロイは失敗します。

この上限は、プロジェクトの割り当ての 1 つではありません。Google Cloud の [割り当て] ページには表示されず、割り当ての増加をリクエストして引き上げることはできません。

推奨される解決策:

  • サポートされている別のリージョンにデプロイします。これは、デプロイのブロックを解除する最も簡単な方法です。
  • 後で再試行してください。リージョンの容量不足は一時的な問題であり、通常は自動的に解決されます。
  • エージェントに割り当てるメモリまたは CPU の量を減らします。小規模なデプロイであれば、残りの容量に収まる可能性があります。
  • リージョンでのデプロイが引き続き失敗する場合は、サポートにお問い合わせください。上限を引き上げることはできませんが、ご報告いただいた内容は、必要な場所に容量を割り当てるために役立てさせていただきます。

適用されないソリューション:

  • 既存のエージェントを削除しても、この上限の容量は解放されません。容量はプロジェクトだけで消費されるわけではないためです。
  • 上限はプロジェクトの割り当てではないため、割り当ての増加をリクエストしても効果はありません。

最大インスタンス数がリージョン上限を超えている

問題:

デプロイが失敗し、429、RESOURCE_EXHAUSTED ステータスと、spec.deployment_spec.max_instances がリージョンの resource_limits でリクエストされた CPU またはメモリでサポートされているインスタンスの最大数を超えているというメッセージが表示されます。

考えられる原因:

エージェントをデプロイすると、Agent Runtime は spec.deployment_spec.max_instances に spec.deployment_spec.resource_limits のインスタンスごとの cpu と memory を乗算し、この単一エージェントのピーク割り当てが、基盤となるサービング プロジェクトのリージョン制限内に収まることを確認します。max_instances を指定しない場合、Agent Runtime はデフォルト値(200 など)を適用します。上限が低いリージョンでは、構成されたインスタンスごとの cpu または memory を乗算すると、サポートされている最大インスタンス数を超える可能性があります。

推奨される解決策:

  • spec.deployment_spec.max_instances を、エラー メッセージに表示される最大値(またはそれ以下)に設定します。
  • spec.deployment_spec.resource_limits のインスタンスごとの cpu 値または memory 値を減らします。
  • 上限が高い別のサポート対象の地域にエージェントをデプロイします。

適用されないソリューション:

  • この上限は、プロジェクトではなく Google が管理するサービス プロジェクトに適用されるため、プロジェクトの Google Cloud [割り当て] ページで割り当ての引き上げをリクエストしても効果はありません。
  • このチェックでは、単一のデプロイのピーク割り当てが静的上限に対して評価されるため、プロジェクト内の他のエージェントを削除したり、max_instances または resource_limits を変更せずに再試行しても、このエラーは解決しません。

Agent Gateway のルックアップがスロットリングされた

問題:

Agent Gateway を使用するエージェントのデプロイまたは更新が、429、RESOURCE_EXHAUSTED ステータス(REASONING_ENGINE_AGENT_GATEWAY_LOOKUP_THROTTLED)と次のようなメッセージで失敗する。

The Reasoning Engine could not be created or updated because the request to look up Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` was throttled. Wait about a minute, then try again.

考えられる原因:

デプロイまたは更新が開始される前に、Agent Runtime はエージェントの spec.deployment_spec.agent_gateway_config で各 Agent Gateway を検索してリクエストを検証します。このエラーは、ルックアップが一時的にレート制限されていることを意味します。リクエストはデプロイまたは更新が開始される前に拒否されるため、エージェントは作成または変更されません。

推奨される解決策:

  • 1 分ほど待ってから、デプロイまたは更新を再試行します。
  • 自動ワークフローでは、指数バックオフを使用してリクエストを再試行します。
  • 引き続きエラーが発生する場合は、サポートにお問い合わせください。

適用されないソリューション:

  • エージェントのコード、requirements、resource_limits を変更しても、このエラーは解決しません。また、コンテナまたは Agent Gateway のトラフィック ログを確認してもエラーは表示されません。これは、Agent Runtime がエージェントのコンテナをビルドまたは起動する前にリクエストが拒否されるためです。

Secret Manager のアクセスエラー

問題:

デプロイが失敗し、400、INVALID_ARGUMENT ステータス(REASONING_ENGINE_SECRET_ACCESS_DENIED)と次のようなメッセージが表示されます。

The Reasoning Engine could not access `projects/PROJECT_NUMBER/secrets/SECRET_ID/versions/VERSION_ID` referenced by `spec.deployment_spec.secret_env` (reason: FAILURE_REASON).

考えられる原因:

  • NOT_FOUND: secret_env で指定されたシークレット ID またはバージョン ID が、デプロイされたエージェントと同じプロジェクトの Secret Manager に存在しないか、入力ミスが含まれています。
  • DESTROYED または DISABLED: Secret Manager で参照されているシークレット バージョンが破棄または無効の状態になっています。
  • PERMISSION_DENIED: サービス アカウントベースのデプロイ(カスタム service_account またはデフォルトの AI Platform Reasoning Engine サービス エージェント)で、構成されたサービス アカウントに、デプロイ検証中に参照されたシークレットに対する Secret Manager シークレット アクセサー ロール(roles/secretmanager.secretAccessor)がありません。

推奨される解決策:

  • NOT_FOUND、DESTROYED、DISABLED の場合:
    1. エージェントをデプロイするプロジェクトの Secret Manager ページで、secret_env で参照されている各 SECRET_ID と VERSION_ID が存在し、有効状態であることを確認します。
    2. 参照されているバージョンが無効化または破棄されている場合は、有効なバージョンを有効にするか、有効なバージョンを参照するように secret_env を更新します。
  • PERMISSION_DENIED の場合: シークレットへのアクセスを管理するの手順に沿って、エージェントに構成されている専用のカスタム サービス アカウントに、特定のシークレットに対する Secret Manager のシークレット アクセサーのロール(roles/secretmanager.secretAccessor)を付与します(または、分離されたエージェント ID に切り替えます)。

AGENT_IDENTITY で secret_env を使用するとコンテナの起動に失敗する

問題:

identity_type = AGENT_IDENTITY と secret_env で構成されたエージェントが、コンテナの起動中に失敗するか、タイムアウトします(デプロイの検証中に REASONING_ENGINE_SECRET_ACCESS_DENIED を返すのではなく)。

考えられる原因:

AGENT_IDENTITY デプロイの場合、Agent Runtime はデプロイ時のシークレット アクセス検証をスキップし、コンテナの起動時に参照されたシークレットを取得します。初期作成時に secret_env を渡した場合(プロビジョニングされたエージェント ID が存在し、アクセス権が付与される前)、プロビジョニングされたエージェント ID に参照されたシークレットの roles/secretmanager.secretAccessor がない場合、または参照されたシークレット バージョンが見つからない(NOT_FOUND)、無効(DISABLED)、または破棄(DESTROYED)されている場合、コンテナの起動時にシークレットの取得が繰り返し失敗します。

推奨される解決策:

  1. まず、secret_env を指定せずに AGENT_IDENTITY を使用してエージェントを作成します。
  2. シークレットへのアクセスを管理するの手順に沿って、エージェントのプロビジョニングされたエージェント ID に特定のシークレットに対する roles/secretmanager.secretAccessor を付与します(IAM メンバーを指定するときに spec.effective_identity の前に principal:// を追加します。例: --member="principal://EFFECTIVE_IDENTITY")。
  3. 参照されている各シークレット バージョンが存在し、有効になっていることを確認し、エージェントを更新して secret_env をアタッチします。エージェントの aiplatform.reasoningEngines.update 権限を制限して、承認されたプリンシパルのみがその ID として実行されるコードを変更できるようにします。

Agent Gateway のバインディング エラー

Agent Gateway を介してトラフィックをルーティングし、エージェントが起動する前にエージェントのデプロイまたは更新が失敗した場合は、次のいずれかの問題が原因である可能性があります。

Agent Gateway のバインディングがタイムアウトしました

問題:

エージェントのデプロイまたは更新が失敗し、504、DEADLINE_EXCEEDED ステータス(REASONING_ENGINE_AGENT_GATEWAY_PROVISION_TIMEOUT)と次のようなメッセージが表示されます。

The Reasoning Engine timed out waiting for an in-progress operation on shared Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` to finish. Wait for the other operation to complete, then try again.

考えられる原因:

同じプロジェクトとリージョン内の Agent Runtime エージェントは、構成された各 Agent Gateway へのバインディングを 1 つ共有します。共有バインディングの設定または破棄には、アクティブなバインディングにエージェントをアタッチするよりも数分長くかかることがあります。同じプロジェクトとリージョン内の別のバインドまたはバインド解除オペレーションが許可された時間内に完了しない場合、デプロイまたは更新がタイムアウトします。一般的な原因は次のとおりです。

  • 同時初期バインディング: 最初の共有設定が完了する前に、同じプロジェクトとリージョン内の Agent Gateway に複数のエージェントをバインドします。
  • バインド解除の進行中: プロジェクトとリージョンで最後にゲートウェイにバインドされたエージェントをバインド解除または削除し、共有の破棄が完了する前に、同じゲートウェイまたは別のゲートウェイに別のエージェントをバインドします。
  • バインディングの失敗後に再試行する: ゲートウェイをバインドするデプロイまたは更新が失敗し、Agent Runtime が失敗した設定のクリーンアップを完了する前に再試行します。

推奨される解決策:

  • エラーに記載されているゲートウェイで他のオペレーションが完了するまで数分待ってから、デプロイまたは更新を再試行します。
  • アクティブな Agent Gateway バインディングがないプロジェクトとリージョンで複数のエージェントをバインドするには、まず 1 つのエージェントをバインドし、そのオペレーションが成功するまで待ちます。次に、残りのエージェントを同時にデプロイまたは更新します。
  • 自動化されたワークフローでは、他のエージェントをバインドする直前に、プロジェクトとリージョンで最後にゲートウェイにバインドされたエージェントのバインド解除や削除を行わないでください。最後のゲートウェイ バインド エージェントを削除すると、共有バインディングが破棄されるため、次のデプロイで完全な設定が繰り返されます。

適用されないソリューション:

  • コンテナログや Agent Gateway のトラフィック ログを確認しても、このエラーは表示されません。これは、Agent Runtime がエージェントのコンテナを起動する前にタイムアウトが発生するためです。
  • エージェントのコード、requirements、resource_limits を変更しても、共有バインディングのセットアップ時間は短縮されません。

ゲートウェイ バインディングが成功してもコンテナの起動に失敗する場合は、Agent Runtime の起動中のエラーをご覧ください。

Agent Gateway のバインドが中止されました

問題:

エージェントのデプロイまたは更新が失敗し、409、ABORTED ステータス(REASONING_ENGINE_AGENT_GATEWAY_CONCURRENT_PROVISION_ABORTED)と次のようなメッセージが表示されます。

The Reasoning Engine could not be bound to Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` because a concurrent shared gateway provisioning operation failed and rolled back. Try again.

考えられる原因:

同じプロジェクトとリージョン内の Agent Runtime エージェントは、構成された各 Agent Gateway へのバインディングを 1 つ共有します。共有バインディングが設定される前に複数のエージェントを同じゲートウェイにバインドすると、1 つのデプロイまたは更新でバインディングが設定され、他のエージェントは待機します。バインディングの準備が整う前にそのデプロイまたは更新が失敗すると、Agent Runtime はバインディングをロールバックし、そのバインディングを待機していたすべてのデプロイまたは更新がこのエラーで失敗します。バインディングを設定したデプロイまたは更新は、独自のエラーを報告します。これは Agent Gateway に関連していない可能性があります。

推奨される解決策:

適用されないソリューション:

  • コンテナログまたは Agent Gateway トラフィック ログを確認しても、このエラーのエラーは表示されません。これは、Agent Runtime がエージェントのコンテナを起動する前にエラーが発生するためです。
  • エージェントのコード、requirements、resource_limits を変更しても、このエラーはエージェントではなく別のデプロイまたは更新によって発生したため、解決しません。

Agent Gateway のバインディングが一時的に利用できない

問題:

エージェントのデプロイまたは更新が失敗し、503、UNAVAILABLE ステータス(REASONING_ENGINE_AGENT_GATEWAY_PROVISION_UNAVAILABLE)と次のようなメッセージが表示されます。

The Reasoning Engine could not be bound to Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` because network provisioning encountered a transient upstream service error. Try again.

考えられる原因:

プロジェクトとリージョンの最初のエージェントが Agent Gateway にバインドされると、Agent Runtime は、エージェントをゲートウェイに接続する共有の Google マネージド ネットワーキング リソースを設定します。この設定が依存する Google Cloudサービスが、数回の自動再試行後に一時的なエラーを返し続ける場合、Agent Runtime は設定をロールバックし、デプロイまたは更新がこのエラーで失敗します。同じ設定を待機していた他のデプロイまたは更新は、409、ABORTED ステータスで失敗します。Agent Gateway のバインドが中止されたをご覧ください。

推奨される解決策:

  • Agent Runtime が失敗した設定のロールバックを完了するまで 10 分以上待ってから、デプロイまたは更新を再試行します。ロールバックが完了する前に開始された再試行は、504、DEADLINE_EXCEEDED ステータスで失敗する可能性があります。Agent Gateway のバインディングがタイムアウトしたをご覧ください。
  • 数回再試行してもエラーが解決しない場合は、サポートにお問い合わせください。その際、失敗したオペレーションの名前を projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID の形式で指定してください。

適用されないソリューション:

  • エージェントのコード、requirements、resource_limits を変更しても、エラーは Agent Runtime がエージェントをデプロイする前に発生するため、問題は解決しません。
  • これらのネットワーキング リソースは Google が管理しているため、プロジェクトの割り当ての増加をリクエストしても効果はありません。

サポート リソース

それでも問題が解決しない場合は、サポートガイドを参照してサポートを受けてください。