環境をセットアップする

Vertex AI Agent Engine を使用する前に、環境が設定されていることを確認する必要があります。 Google Cloud プロジェクトに課金が有効になっていること、必要な権限があること、Cloud Storage バケットを設定していること、Vertex AI SDK for Python をインストールしていることを確認してください。以下のトピックを使用して、Vertex AI Agent Engine を使い始めるための準備を整えてください。

Vertex AI Agent Engine 環境の設定とデプロイを効率的に行うための Terraform のリファレンス例については、agent-starter-packをご覧ください。

を設定する Google Cloud

Vertex AI Agent Engine 用の Google Cloud を設定するには、 プロジェクトを作成します Google Cloud 。

Google Cloud プロジェクト

すべてのプロジェクトは、プロジェクト番号またはプロジェクト ID によって識別できます。PROJECT_NUMBER はプロジェクトの作成時に自動的に作成されますが、PROJECT_ID はプロジェクトの作成者が作成します。プロジェクトを設定するには:

アカウントにログインします。 Google Cloud を初めて使用する場合は、 アカウントを作成して、実際のシナリオで Google プロダクトのパフォーマンスを評価してください。 Google Cloud新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

注: API を有効にするには、serviceusage.services.enable 権限が必要です。この権限がない場合は、Service Usage 管理者（roles/serviceusage.serviceUsageAdmin）ロールの付与を管理者に依頼してください。

必要なロールを取得する

Vertex AI Agent Engine の使用に必要な権限を取得するには、プロジェクトに対する Vertex AI ユーザー （roles/aiplatform.user）IAM ロールの付与を管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

エージェントの ID と権限を設定する

ID と権限を設定する際には、次のオプションがあります。

• エージェント ID（推奨） （プレビュー）: Identity Access Management（IAM）エージェント ID を使用して、 Vertex AI Agent Engine ランタイムでエージェントを使用する際に、 セキュリティ機能とアクセス管理機能を提供します。エージェント ID は、個々のエージェントに関連付けられています。

• サービス アカウント: サービス アカウントは 、Vertex AI Agent Engine にデプロイするエージェント間で共有されます 。サービス アカウントには次の 2 つのオプションがあります。

  • デフォルトのサービス エージェント: デフォルトでは、エージェントは AI Platform Reasoning Engine サービス エージェントを使用します。この Google マネージド サービス アカウントには、デプロイされたエージェントに必要なデフォルトの権限を含む Vertex AI Reasoning Engine サービス エージェント ロール（roles/aiplatform.reasoningEngineServiceAgent）があります。
  • カスタム サービス アカウント: エージェントが使用する独自のサービス アカウントを指定できます。これにより、エージェントに付与される権限をより細かく制御できます。

エージェント ID

プレビュー - Private Service Connect インターフェース

この機能は サービス固有規約の「一般サービス規約」セクションの「一般提供前サービス規約」の対象となります 。pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、 リリースステージの説明をご覧ください。

エージェントをデプロイする前に IAM ポリシーを設定するには、エージェント コードをデプロイせずにエージェント ID を作成します。これを行うには、identity_type フィールドのみを使用して Agent Engine インスタンスを作成します。

remote_app = client.agent_engines.create(
      config={
          "identity_type": types.IdentityType.AGENT_IDENTITY,
      },
)

エージェント ID を使用して Agent Engine インスタンスを作成すると、次の操作を行うことができます。

1. 次の推奨ロールを使用してエージェント ID をプロビジョニングします。

   • roles/serviceusage.serviceUsageConsumer: プロジェクトの割り当てと Vertex AI SDK を使用する権限をエージェントに付与します。

2. ユースケースに必要な追加のロールをエージェント ID に付与します。

3. agent_engine.update(...) を使用してエージェント コードを追加します。

デフォルトのサービス エージェント

デフォルトでは、 AI Platform Reasoning Engine サービス エージェントが使用されます。デフォルト権限の全一覧は IAM のドキュメントでご確認ください。

エージェントにデフォルトのセットを超える権限が必要な場合は、このサービス エージェントに追加のロールを付与できます。

1. [IAM] ページに移動し、[Google 提供のロール付与を含める] チェックボックスをオンにします。

   [IAM] に移動

2. [e-mail] に一致するプリンシパルを見つけます。

3. 編集ボタンをクリックして必要なロールをプリンシパルに追加した後、保存ボタンをクリックします。

デフォルトのサービス エージェントを手動で生成する

Reasoning Engine サービス エージェントは、Vertex AI Agent Engine のデプロイ中に自動的にプロビジョニングされますが、事前に手動で生成することが必要になる場合があります。これは、デプロイ プロセスに必要な権限を付与してデプロイの失敗を避けるために、サービス エージェントに特定のロールを割り当てる必要がある場合に特に重要です。

Reasoning Engine サービス エージェントを手動で生成する手順は次のとおりです。

1. Google Cloud CLI を使用して Reasoning Engine サービス エージェントを生成します。

   gcloud beta services identity create --service=aiplatform.googleapis.com --project=PROJECT-ID-OR-PROJECT-NUMBER

   注: Google Cloud CLI コマンドのレスポンスには、Vertex AI サービス エージェントしか表示されない場合がありますが、実際には Reasoning Engine サービス エージェントも作成されています。

2. [IAM] ページに移動し、[アクセスを許可] をクリックします。

   [IAM] に移動

3. [プリンシパルの追加] セクションの [新しいプリンシパル] フィールドに「[e-mail]」と入力します。

4. [ロールを割り当てる] セクションで、必要なロールを見つけて選択します。

5. [保存] をクリックします。

カスタム サービス アカウント

独自のサービス アカウントを使用するには、エージェントを実行するために必要な権限を付与する必要があります。カスタム サービス アカウントには、Vertex AI ユーザーロール（roles/aiplatform.user）が必要になる可能性があります。

1. サービス アカウントがない場合は、サービス アカウントを作成します。サービス アカウントを作成するをご覧ください。

2. サービス アカウントに Vertex AI ユーザー（roles/aiplatform.user）ロールを付与します。

3. エージェント コードに必要な他のロールをサービス アカウントに付与します。

4. このサービス アカウントを使用してエージェントをデプロイするには、このカスタム サービス アカウントに対するサービス アカウント ユーザーのロール（roles/iam.serviceAccountUser）を自分自身に付与します。

5. エージェントをデプロイするときに、カスタム サービス アカウントのメールアドレスを指定します。詳細については、カスタム サービス アカウントを構成するをご覧ください。

プロジェクト間のカスタム サービス アカウント

カスタム サービス アカウントが別のプロジェクトのものである場合は、サービス アカウントが存在するプロジェクトとエージェントをデプロイするプロジェクトの両方で追加の構成が必要です。

1. プロジェクト間サービス アカウントの使用を無効にする組織のポリシー: サービス アカウントが存在するプロジェクトで、iam.disableCrossProjectServiceAccountUsage 組織のポリシーが適用されていないことを確認します。詳細については、 プロジェクト間サービス アカウントの使用の適用を無効にする をご覧ください。

2. Vertex AI サービス エージェントに権限を付与する: サービス アカウントがあるプロジェクトで、エージェントをデプロイするプロジェクトの Vertex AI サービス エージェント ([e-mail]) に サービス アカウント トークン作成者 (roles/iam.serviceAccountTokenCreator) ロールを付与します。

3. カスタム サービス アカウントに権限を付与する: エージェントのデプロイを予定しているプロジェクトで、カスタム サービス アカウントに必要なロールを付与します。通常、これには Vertex AI ユーザーロール（roles/aiplatform.user）と、エージェント コードに必要なその他のロールが含まれます。

（省略可）Cloud Storage バケットを作成する

Cloud Storage バケットが必要かどうかは、Vertex AI SDK for Python でデプロイ前にエージェント コードをステージングする場所が必要かどうかによって異なります。

• ソースファイルからデプロイする: エージェントはファイルとして存在します。Vertex AI SDK for Python は、これらのファイルをバンドルしてデプロイ サービスに直接アップロードできるため、Cloud Storage ステージング バケットは必要ありません。

• エージェント オブジェクトからデプロイする: エージェントはメモリに存在します。Vertex AI SDK for Python は、このオブジェクトをパッケージ化して Cloud Storage バケットにアップロードします。このバケットは、デプロイ サービスのステージング領域として機能します。

ソースファイルからデプロイする

ソースファイルからエージェントをデプロイする場合、Cloud Storage バケットは必要ありません。

オブジェクトからデプロイする

エージェント オブジェクトからデプロイする場合、Vertex AI Agent Engine は、デプロイプロセスの一環として、デプロイされたエージェントのアーティファクトを Cloud Storage バケットにステージングします。Vertex AI の使用を認証されたプリンシパル（ご自身またはサービス アカウント）に、このバケットへの Storage Admin アクセス権があることを確認してください。このアクセス権は、Vertex AI SDK for Python がコードをこのバケットに書き込むために必要になります。

すでにバケットを設定している場合は、この手順をスキップできます。それ以外の場合は、バケットの作成に関する標準の手順に沿って操作します。

**注:** エージェントを Vertex AI Agent Engine にデプロイするプロジェクトと同じプロジェクトに Cloud Storage バケットを作成することを強くおすすめします。別のプロジェクトのバケットを使用する場合は、Vertex AI サービス エージェント（[e-mail]）に Cloud Storage バケットの読み取り権限を手動で付与する必要があります。

管理者に、プロジェクトに対するストレージ管理者（roles/storage.admin）IAM ロールを付与するよう依頼します。

Google Cloud コンソール

1. コンソールで Cloud Storage の Google Cloud [バケット] ページに移動します。

   [バケット] に移動

2. [Create] をクリックします。
3. [バケットの作成] ページでユーザーのバケット情報を入力します。次のステップに進むには、[続行] をクリックします。
   1. [始める] セクションで、次の操作を行います。
      • バケット名の要件を満たす、グローバルに一意の名前を入力します。
      • バケットラベルを追加するには、[ラベル] セクション（）を開き、[ラベルを追加] をクリックして、key と value を指定します。
   2. [データの保存場所の選択] セクションで、次の操作を行います。
      1. ロケーション タイプを選択してください。
      2. [Location type] プルダウン メニューから、バケットのデータが永続的に保存されるロケーションを選択します。
         • ロケーション タイプとして [デュアルリージョン] を選択した場合は、関連するチェックボックスを使用して [ターボ レプリケーション] を有効にすることもできます。
      3. クロスバケット レプリケーションを設定するには、 [Storage Transfer Service 経由でクロスバケット レプリケーションを追加する] を選択し、 次の手順を実施します:

         クロスバケット レプリケーションを設定する

         1. [バケット] メニューで、バケットを選択します。

         2. [レプリケーション設定] セクションで、[構成] をクリックして、レプリケーション ジョブの設定を構成します。

            [**クロスバケット レプリケーションを構成する**] ペインが表示されます。

            • オブジェクト名の接頭辞で複製するオブジェクトをフィルタするには、オブジェクトを追加または除外する接頭辞を入力し、 [Add a prefix] をクリックします。
            • 複製されたオブジェクトのストレージ クラスを設定するには、 [Storage class] メニューからストレージ クラスを選択します。 この手順をスキップすると、複製されたオブジェクトはデフォルトで宛先バケットのストレージ クラスを使用します。
            • [完了] をクリックします。
   3. [データの保存場所を選択する] セクションで、次の操作を行います。
      1. バケットのデフォルトのストレージ クラスを選択するか、バケットデータのストレージ クラスを自動的に管理するAutoclassを選択します。
      2. 階層名前空間を有効にするには、 [データ量が多いワークロード向けにストレージを最適化] セクションで、 [このバケットで階層的な名前空間を有効にする] を選択します。
         注: 既存の バケットで階層名前空間を有効にすることはできません。
   4. In the [オブジェクトへのアクセスを制御する方法を選択する] セクションで、バケットに 公開アクセスの防止 を適用するかどうかを選択し、バケットのオブジェクトに使用する アクセス制御方法 を選択します。
      **注:** 組織の組織ポリシーでこの設定が適用されている場合、[**公開アクセスの防止**] 設定を変更することはできません。
   5. [オブジェクト データを保護する方法を選択する] セクションで、次の操作を行います。
      • [**データ保護**] で、バケットに設定するオプションを選択します。
        • 削除（復元可能）を有効にするには、 [削除（復元可能）ポリシー（データ復旧用）] チェックボックスをオンにして、 削除後にオブジェクトを保持する日数を指定します。
        • オブジェクトのバージョニングを設定するには、 [オブジェクトのバージョニング（バージョン管理用）] チェックボックスをオンにして、 オブジェクトあたりの最大バージョン数と、非現行バージョンが期限切れになるまでの日数を指定します。
        • オブジェクトとバケットの保持ポリシーを有効にするには、[保持（コンプライアンス用）] チェックボックスをオンにして、次の操作を行います。
          • [オブジェクト保持ロック]を有効にするには、 [オブジェクト保持を有効にする]チェックボックスをオンにします。
          • [Bucket Lock] を有効にするには、[バケット保持ポリシーを設定する] チェックボックスをオンにして、保持期間の単位と保持期間を選択します。
      • オブジェクト データの暗号化方法を選択するには、 [データ暗号化] セクション（）を開き、 [データの暗号化] 方法を選択します。
4. [作成] をクリックします。

コマンドライン

Cloud Storage バケットを作成し、次のように構成します。
• STORAGE_CLASS を、目的の ストレージ クラスに置き換えます。
• LOCATION を、目的のロケーション（ASIA、EU、または US）で置き換えます。
• BUCKET_NAME を、バケット名の要件を満たすバケット名に置き換えます。

gcloud storage buckets create gs://BUCKET_NAME --default-storage-class STORAGE_CLASS --location LOCATION

Vertex AI SDK for Python をインストールして初期化する

このセクションでは、Python 開発環境が設定されているか、Colab（または、設定済みの適切なランタイム）を使用していることを前提としています。

（省略可）仮想環境を設定する

依存関係を分離するために、仮想環境を設定することもおすすめします。

インストール

インストールする必要がある依存関係のセットを最小限に抑えるため、依存関係を次のように分離しました。

• agent_engines: Vertex AI Agent Engine へのデプロイに必要なパッケージのセット。
• adk: 互換性のある Agent Development Kit パッケージのセット。
• langchain: 互換性のある LangChain パッケージと LangGraph パッケージのセット。
• ag2: 互換性のある AG2 パッケージのセット。
• llama_index: 互換性のある LlamaIndex パッケージのセット。

Vertex AI SDK for Python をインストールするときに、必要な依存関係をカンマ区切りで指定できます。すべてをインストールするには次のようにします。

pip install google-cloud-aiplatform[agent_engines,adk,langchain,ag2,llama_index]>=1.112.0

Agent Engine で Agent2Agent（A2A）を使用するには、a2a-sdk パッケージもインストールする必要があります。

pip install a2a-sdk>=0.3.4

認証

Colab

次のコードを実行します。

from google.colab import auth

auth.authenticate_user(project_id="PROJECT_ID")

Cloud Shell

対応は不要です。

ローカルシェル

次のコマンドを実行します。

gcloud auth application-default login

SDK をインポートして初期化する

次のコードを実行して、Vertex AI Agent Engine の SDK のインポートと初期化を行います。

Google Cloud プロジェクト

import vertexai
from vertexai import agent_engines # For the prebuilt templates

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

ここで

• PROJECT_ID は、エージェントを開発してデプロイする Google Cloud プロジェクト ID です。
• LOCATION は、サポートされているリージョンの一つです。

次のステップ

• エージェントを開発する。
• 環境の設定に関するトラブルシューティング。
• サポートを利用する。