设置环境

在使用 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进行设置

您可以通过以下方式设置 Google Cloud Vertex AI Agent Engine：创建 Google Cloud 项目或注册快速模式下的 Vertex AI：

Google Cloud 项目

每个项目都可以通过项目编号和项目 ID 这两种方式来识别。PROJECT_NUMBER 由系统在您创建项目时自动创建，PROJECT_ID 则是由您或项目创建者创建的。如需设置项目，请执行以下操作：

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.

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, and Cloud Trace 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, and Cloud Trace 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

注意：您需要拥有 serviceusage.services.enable 权限才能启用 API。如果您没有此权限，请让您的管理员为您授予 Service Usage Admin (roles/serviceusage.serviceUsageAdmin) 角色。

快速模式

按照快速模式下的 Vertex AI 中的说明，以快速模式设置 Vertex AI Agent Engine。

在快速模式下设置 Vertex AI Agent Engine 后，您可以跳至安装并初始化 Python 版 Vertex AI SDK 这一步。

获取所需的角色

如需获得使用 Vertex AI Agent Engine 所需的权限，请让您的管理员为您授予项目的 Vertex AI User (roles/aiplatform.user) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

为代理设置身份和权限

设置身份和权限时，您可以选择以下选项：

• 代理身份（推荐）（预览版）：在 Vertex AI Agent Engine 运行时中使用代理时，使用 Identity Access Management (IAM) 代理身份来提供安全性和访问管理功能。代理身份与每个代理相关联。

• 服务账号：服务账号在您部署到 Vertex AI Agent Engine 的代理之间共享。您可以选择以下两种服务账号：

  • 默认服务代理：默认情况下，代理使用 AI Platform Reasoning Engine Service Agent。Google 管理的此服务账号具有 Vertex AI Reasoning Engine Service Agent 角色 (roles/aiplatform.reasoningEngineServiceAgent)，其中包括部署的代理所需的默认权限。
  • 自定义服务账号：您可以指定自己的服务账号供代理使用。这样一来，您就可以更精细地控制授予代理的权限。

代理身份

预览版

此功能 受服务专用条款的约束。 非正式版功能“按原样”提供，且可能仅提供有限支持。 如需了解详情，请参阅发布阶段说明。

如需在部署代理之前设置 IAM 政策，您可以创建代理身份，而无需部署代理代码。为此，请创建一个仅包含 identity_type 字段的 Agent Engine 实例：

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

使用代理身份创建 Agent Engine 实例后，您可以执行以下操作：

1. 为代理身份配置以下建议的角色：

   • roles/aiplatform.expressUser：授予对运行推理、会话和内存的访问权限。

   • roles/serviceusage.serviceUsageConsumer：授予代理使用项目配额和 Vertex AI SDK 的权限。

2. 根据您的使用情形，向代理身份授予其他角色。

3. 使用 agent_engine.update(...) 添加代理代码。

默认服务代理

默认情况下，系统会使用 AI Platform Reasoning Engine Service Agent。您可以在 IAM 文档中查看默认权限的完整列表。

如果您的代理需要超出默认权限集的权限，您可以向此 Service Agent 授予其他角色：

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

   进入 IAM

2. 找到与 [e-mail] 匹配的主账号。

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

   注意：Google Cloud CLI 命令的响应可能仅显示 Vertex AI Service Agent。但是，系统还会创建 Reasoning Engine Service Agent。

2. 前往 IAM 页面，然后点击授予访问权限。

   进入 IAM

3. 在添加主账号部分的新的主账号字段中，输入 [e-mail]。

4. 在分配角色部分，找到并选择您需要的角色。

5. 点击保存按钮。

自定义服务账号

如需使用您自己的服务账号，您需要向其授予运行代理所需的必要权限。您的自定义服务账号可能需要 Vertex AI User 角色 (roles/aiplatform.user)。

1. 如果您没有服务账号，请创建一个。请参阅创建服务账号。

2. 向该服务账号授予 Vertex AI User (roles/aiplatform.user) 角色。

3. 向服务账号授予代理代码所需的任何其他角色。

4. 如需使用此服务账号部署代理，请向您自己授予此自定义服务账号的 Service Account User 角色 (roles/iam.serviceAccountUser)。

5. 部署代理时，请指定自定义服务账号的邮箱。如需了解详情，请参阅配置自定义服务账号。

跨项目自定义服务账号

如果您的自定义服务账号来自其他项目，则需要在服务账号所在的项目和部署代理的项目中进行额外的配置。

1. 停用“停用跨项目服务账号使用情况”组织政策：在服务账号所在的项目中，确保未强制执行 iam.disableCrossProjectServiceAccountUsage 组织政策。如需了解详情，请参阅停用跨项目服务账号使用情况强制执行。

2. 向 Vertex AI Service Agent 授予权限：在服务账号所在的项目中，向您计划部署代理的项目中的 Vertex AI Service Agent ([e-mail]) 授予 Service Account Token Creator (roles/iam.serviceAccountTokenCreator) 角色。

3. 向自定义服务账号授予权限：在您计划部署代理的项目中，向自定义服务账号授予必要的角色。这通常包括 Vertex AI User 角色 (roles/aiplatform.user) 以及代理代码所需的任何其他角色。

（可选）创建 Cloud Storage 存储桶

是否需要 Cloud Storage 存储桶取决于 Vertex AI SDK for Python 在部署之前是否需要一个位置来暂存您的代理代码：

• 从源文件部署：智能体以文件形式存在。Vertex AI SDK for Python 可以直接将这些文件打包并上传到部署服务，因此无需 Cloud Storage 暂存存储桶。

• 从代理对象部署：代理存在于内存中。Python 版 Vertex AI SDK 会将此对象打包并上传到 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 Service Agent ([e-mail]) 授予对 Cloud Storage 存储桶的读取权限。

请让您的管理员向您授予项目的 Storage Admin (roles/storage.admin) IAM 角色。

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

Go to Buckets

Click Create.

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.
      • If you select the dual-region location type, you can also choose to enable turbo replication by using the relevant checkbox.
   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.
      Note: You cannot enable hierarchical namespace in existing buckets.
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.
   Note: You cannot change the Prevent public access setting if this setting is enforced at an organization policy.
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.

Click Create.

安装并初始化 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.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

您无需执行任何操作。

本地 Shell

运行以下命令：

gcloud auth application-default login

快速模式

如果您使用的是快速模式下的 Vertex AI，则无需执行任何操作。

导入并初始化 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 是支持的区域之一。

快速模式

如果您使用的是快速模式下的 Vertex AI，请运行以下代码：

import vertexai
from vertexai import agent_engines # For the prebuilt ADK template

client = vertexai.Client(  # For service interactions via client.agent_engines
    api_key="API_KEY"
)

其中 API_KEY 是您用于对代理进行身份验证的 API 密钥。

后续步骤

• 开发代理。
• 排查环境设置问题。
• 获取支持。