このドキュメントでは、Agent Runtime の環境を設定する際に発生する可能性のあるエラーの解決方法について説明します。パッケージのインポートに関する問題のトラブルシューティング手順についても説明します。
Agent Platform SDK のインポート時のエラー
Agent Platform SDK for Python をインポートできない場合は、次のいずれかの問題が原因である可能性があります。
旧バージョンの Agent Platform SDK for Python
問題:
次のようなエラー メッセージが表示されます。
ImportError: cannot import name 'reasoning_engines' from 'vertexai.preview'
または
ImportError: cannot import name 'agent_angines' from 'vertexai'
考えられる原因:
これは、google-cloud-aiplatform パッケージのバージョンが 1.82.0（agent_engines の場合）または 1.47.0（reasoning_engines の場合）より古い場合に発生することがあります。google-cloud-aiplatform パッケージのバージョンを確認するには、ターミナルで次のコマンドを実行します。
pip show google-cloud-aiplatform推奨される解決策:
ターミナルで次のコマンドを実行して、google-cloud-aiplatform パッケージを更新します。
pip install google-cloud-aiplatform --upgrade次のコマンドを実行して、更新されたバージョンが 1.82.0 以降であることを確認します。
pip show google-cloud-aiplatformノートブック インスタンス（Jupyter、Colab、Workbench など）を使用している場合、更新されたパッケージを使用するには、ランタイムを再起動する必要があります。
401 認証エラー
問題:
次のようなエラー メッセージが表示されます。
Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"
または
Agent Engine Error: An error occurred during invocation. Exception: API request failed with status 401:
Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.
考えられる原因:
デフォルトでは、エージェント ランタイムでエージェント ID を使用すると、トークンの盗難を防ぐために、証明書バインド アクセス トークンが認証に使用されます。次の 2 つのシナリオのいずれかで、実行時に 401 エラーが発生する可能性があります。
- ユーザーまたはエージェントが、発行されたコンテキスト外でアクセス トークンを使用しようとしている（エージェント間でトークンを渡すなど）。
- エージェントが、telemetry.mtls.googleapis.com ではなく telemetry.googleapis.com などの mTLS 互換でない API エンドポイントを呼び出している。
推奨される解決策:
シナリオ 1 の場合、エージェント間でトークンを共有する正当な理由がある場合は、デフォルトのコンテキストアウェア アクセス（CAA）ポリシーを無効にできます。この操作を行うと、エージェントが認証情報の窃取に対して脆弱になるため、強く非推奨とされます。
Agent Runtime インスタンスの作成時に次の環境変数を設定して、デフォルトの CAA ポリシーをオプトアウトします。
config={
"env_vars": {
"GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
}
}
シナリオ 2 の場合も同様に、GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES 変数を False に設定して、エージェントが一時的な回避策として非 mTLS API エンドポイントを使用できるようにします。この場合、根本的な問題は ADK の既知の問題である可能性があります。