设置环境

在使用 Agent Engine 之前，您需要确保已设置环境。您需要有启用了结算功能的 Google Cloud 项目，具有所需的权限，设置 Cloud Storage 存储桶，并安装 Vertex AI SDK for Python。请参阅以下主题，确保您已准备好开始使用 Agent Engine。

如需查看用于简化 Agent Engine 环境设置和部署的参考 Terraform 示例，不妨探索 agent-starter-pack。

设置您的 Google Cloud 项目

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.

   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

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

4. Enable the Vertex AI and Cloud Storage APIs.

   Enable the APIs

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

   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

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

7. Enable the Vertex AI and Cloud Storage APIs.

   Enable the APIs

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

获取所需的角色

如需获取使用 Agent Engine 所需的权限，请让您的管理员为您授予项目的以下 IAM 角色：

• Vertex AI User (roles/aiplatform.user)
• Storage Admin (roles/storage.admin)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

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

设置您的服务代理权限

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

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

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

   进入 IAM

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

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

手动生成服务代理

虽然 Reasoning Engine Service Agent 会在 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. 点击保存按钮。

创建 Cloud Storage 存储桶

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 page

2. Click Create bucket.
3. On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.
   • For Name your bucket, enter a name that meets the bucket naming requirements.
   • For Choose where to store your data, do the following:
     • Select a Location type option.
     • Select a Location option.
   • For Choose a default storage class for your data, select a storage class.
   • For Choose how to control access to objects, select an Access control option.
   • For Advanced settings (optional), specify an encryption method, a retention policy, or bucket labels.
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：部署到 Agent Engine 所需的软件包集。
• langchain：兼容的 LangChain 软件包集。
• langgraph：兼容的 LangGraph 软件包集。

安装 Vertex AI SDK for Python 时，您可以指定所需的依赖项（以英文逗号分隔）。如需安装所有这些内容，请执行以下操作：

pip install google-cloud-aiplatform[agent_engines,langchain,langgraph]

身份验证

Colab

运行以下代码：

from google.colab import auth

auth.authenticate_user()

Cloud Shell

您无需执行任何操作。

本地 Shell

运行以下命令：

gcloud auth application-default login

导入并初始化 SDK

运行以下代码，以导入并初始化适用于 Agent Engine 的 SDK：

import vertexai
from vertexai import agent_engines

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

• PROJECT_ID：您的项目 ID。
• LOCATION：您的云区域。
• BUCKET_NAME：您的 Google Cloud 存储桶。

后续步骤

• 开发应用。