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

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

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

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

デプロイ中に 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

考えられる原因:

これは、カスタム サービス アカウントとエージェントが異なるプロジェクトにあり、AI Platform Reasoning Engine サービス エージェントにカスタム サービス アカウントに対する iam.serviceAccounts.getAccessToken 権限がない場合に発生する可能性があります。

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

推奨される解決策:

エージェント プロジェクトの AI Platform Reasoning Engine サービス エージェントに、カスタム サービス アカウントに対するサービス アカウント トークン作成者（roles/iam.serviceAccountTokenCreator）ロールを付与するよう管理者に依頼します。

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

リソース不足またはレート制限エラー（エラー 429）

問題:

デプロイが失敗し、ステータスが Error 429 または RESOURCE_EXHAUSTED になります。

考えられる原因:

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

推奨される解決策:

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

リージョンが一時的に容量を超えている

問題:

デプロイが 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 を変更せずに再試行しても、このエラーは解決しません。これは、チェックで単一のデプロイのピーク割り当てが静的上限に対して評価されるためです。

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: エージェントで使用されるサービス アカウントに、参照されたシークレットに対する 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）を、シークレットを取得するサービス アカウントに付与します。
    • デフォルトのサービス アカウント: AI Platform Reasoning Engine サービス エージェント（service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com）にロールを付与します。
    • カスタム サービス アカウント: エージェントで構成されたカスタム サービス アカウントにロールを付与します。

サポート リソース

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