设置环境

在使用 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 Service Agent 服务账号运行。此账号具有 Vertex AI Reasoning Engine Service Agent 角色，该角色可授予部署的代理所需的默认权限。您可以在 IAM 文档中查看默认权限的完整列表。

    如果您需要其他权限，可以通过执行以下步骤向此 Service Agent 授予其他角色：

    1. 前往 IAM 页面，然后勾选“包括 Google 提供的角色授权”复选框。

      进入 IAM

    2. 找到与 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com 匹配的主账号。

    3. 依次点击“编辑”按钮和“保存”按钮，向主账号添加所需的角色。

    手动生成服务代理

    虽然 Reasoning Engine Service Agent 会在 Vertex AI Agent Engine 部署期间自动预配，但在某些情况下，您可能需要事先手动生成 Reasoning Engine Service Agent。如果您需要向相应服务代理授予特定角色，以确保部署过程具有必要的权限并避免可能发生的部署失败，则这一点尤为重要。

    以下是手动生成 Reasoning Engine Service Agent 的步骤：

    1. 使用 Google Cloud CLI 生成 Reasoning Engine Service Agent。

      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

    安装并初始化 Python 版 Vertex AI SDK

    本部分假定您已设置 Python 开发环境，或者正在使用 Colab（或已为您设置开发环境的任何其他合适运行时）。

    （可选）设置虚拟环境。

    我们还建议您设置虚拟环境来隔离依赖项。

    安装

    为了尽可能减少您�����安装的���赖项，��们将依赖项分为以下几类：

    • agent_engines：部署到 Vertex AI Agent Engine 所需的软件包集。
    • adk：兼容的智能体开发套件软件包集。
    • 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

    您无需执行任何操作。

    本地 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",
)

    其中

    后续步骤