環境をセットアップする

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 プロジェクトを設定する

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

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

    Enable the APIs

    5.

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

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

    Enable the APIs

    8.

    必要なロールを取得する

    Vertex AI Agent Engine の使用に必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

    ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

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

    サービス エージェントの権限を設定する

    Vertex AI Agent Engine にデプロイするエージェントは、AI Platform Reasoning Engine サービス エージェントのサービス アカウントを使用して実行されます。このアカウントには、デプロイされたエージェントに必要なデフォルトの権限を付与する Vertex AI Reasoning Engine サービス エージェント ロールが割り当てられています。デフォルトの権限の一覧については、IAM のドキュメントをご覧ください。

    追加の権限が必要な場合は、次の手順を実行することで、このサービス エージェントに追加のロールを付与できます。

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

      [IAM] に移動

    2. service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com に一致するプリンシパルを見つけます。

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

    サービス エージェントを手動で生成する

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

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

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

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

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

      [IAM] に移動

    3. [プリンシパルの追加] セクションの [新しいプリンシパル] フィールドに「service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com」と入力します。

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

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

    Cloud Storage バケットを作成する

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

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

    Google Cloud コンソール

    1. In the Google Cloud console, go to the Cloud Storage Buckets page.

      Go to Buckets

    2. Click Create.
    3. On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.
      1. In the Get started section, do the following:
        • Enter a globally unique name that meets the bucket naming requirements.
        • To add a bucket label, expand the Labels section (), click Add label, and specify a key and a value for your label.
      2. In the Choose where to store your data section, do the following:
        1. Select a Location type.
        2. Choose a location where your bucket's data is permanently stored from the Location type drop-down menu.
        3. To set up cross-bucket replication, select Add cross-bucket replication via Storage Transfer Service and follow these steps:

          Set up cross-bucket replication

          1. In the Bucket menu, select a bucket.

          2. In the Replication settings section, click Configure to configure settings for the replication job.

            The Configure cross-bucket replication pane appears.

            • To filter objects to replicate by object name prefix, enter a prefix that you want to include or exclude objects from, then click Add a prefix.
            • To set a storage class for the replicated objects, select a storage class from the Storage class menu. If you skip this step, the replicated objects will use the destination bucket's storage class by default.
            • Click Done.
      3. In the Choose how to store your data section, do the following:
        1. Select a default storage class for the bucket or Autoclass for automatic storage class management of your bucket's data.
        2. To enable hierarchical namespace, in the Optimize storage for data-intensive workloads section, select Enable hierarchical namespace on this bucket.
      4. In the Choose how to control access to objects section, select whether or not your bucket enforces public access prevention, and select an access control method for your bucket's objects.
      5. In the Choose how to protect object data section, do the following:
        • Select any of the options under Data protection that you want to set for your bucket.
          • To enable soft delete, click the Soft delete policy (For data recovery) checkbox, and specify the number of days you want to retain objects after deletion.
          • To set Object Versioning, click the Object versioning (For version control) checkbox, and specify the maximum number of versions per object and the number of days after which the noncurrent versions expire.
          • To enable the retention policy on objects and buckets, click the Retention (For compliance) checkbox, and then do the following:
            • To enable Object Retention Lock, click the Enable object retention checkbox.
            • To enable Bucket Lock, click the Set bucket retention policy checkbox, and choose a unit of time and a length of time for your retention period.
        • To choose how your object data will be encrypted, expand the Data encryption section (), and select a Data encryption method.
    4. Click Create.

    コマンドライン

      Create a Cloud Storage bucket and configure it as follows:
      • 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.88.0

    認証

    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 をインポートして初期化します。

    import vertexai
from vertexai import agent_engines

vertexai.init(
    project="PROJECT_ID",
    location="LOCATION",
    staging_bucket="gs://BUCKET_NAME",
)

    ここで

    次のステップ