设置环境

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

如需参考 Terraform 示例来简化 Agent Runtime 环境设置和部署，不妨探索 agent-starter-pack。

通过 Google Cloud设置

您可以通过创建 Google Cloud 项目，使用 Google Cloud 为 Agent Runtime 进行设置。

Google Cloud 项目

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

1. 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

2. Verify that billing is enabled for your Google Cloud project.

3. Enable the Gemini Enterprise Agent Platform, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs.

   Roles required to enable APIs

   To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

   Enable the APIs

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

获取所需的角色

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

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

为代理设置身份和权限

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

• 代理身份（推荐） 在 Agent Runtime 上使用代理时，使用 Identity Access Management (IAM) 代理身份来提供安全和访问权限管理功能。代理身份与每个代理相关联。默认情况下，代理具有 Agent Platform Agent Default Access 角色 (roles/aiplatform.agentDefaultAccess)，该角色仅包含基本的项目级日志记录和模型调用权限；以及 Agent Platform Agent Context Editor 角色 (roles/aiplatform.agentContextEditor)，该角色将代理限制为只能访问自己的会话、记忆和沙盒。

  注意：此角色可访问的部分功能可能处于预览阶段

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

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

代理身份

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

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

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

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

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

默认服务代理

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

如果您的代理需要超出默认设置的权限，您可以向此服务代理授予其他角色：

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

   进入 IAM

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

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

手动生成默认服务代理

虽然 Reasoning Engine Service Agent 会在 Agent Runtime 部署期间自动预配，但在某些情况下，您可能需要事先手动生成 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. 在添加主账号部分的新的主账号字段中，输入 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.。

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

5. 点击保存按钮。

自定义服务账号

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

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

2. 向服务账号授予 Agent Platform User (roles/aiplatform.user) 角色。

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

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

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

跨项目自定义服务账号

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

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

2. 向 Agent Platform Service Agent 授予权限：在服务账号所在的项目中，向您计划部署代理的项目的 Agent Platform Service Agent (service-RESOURCE_PROJECT_NUMBER@gcp-sa-aiplatform.) 授予 Service Account Token Creator (roles/iam.serviceAccountTokenCreator) 角色。

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

（可选）创建 Cloud Storage 存储桶

是否需要 Cloud Storage 存储桶取决于 Agent Platform SDK for Python 是否需要在部署之前暂存您的代理代码：

• 从源文件部署：智能体以文件形式存在。适用于 Python 的 Agent Platform SDK 可以直接将这些文件捆绑并上传到部署服务，因此无需 Cloud Storage 暂存存储桶。

• 从代理对象部署：代理存在于内存中。Agent Platform 适用于 Python 的 SDK 会将此对象打包并上传到 Cloud Storage 存储桶，该存储分区充当部署服务的暂存区。

从源文件部署

如果您从源文件部署代理，则不需要 Cloud Storage 存储桶。

从对象部署

当您从代理对象进行部署时，Agent Runtime 会在部署过程中将已部署代理的制品暂存在 Cloud Storage 存储桶中。确保已通过身份验证以使用 Gemini Enterprise Agent Platform 的主账号（您自己或服务账号）对此存储桶具有 Storage Admin 访问权限。这是因为 Agent Platform SDK for Python 会将您的代码写入此存储桶。

如果您已设置存储桶，则可以跳过此步骤。否则，您可以按照标准说明创建存储桶。

注意： 我们强烈建议您，在将代理部署到 Agent Runtime 的同一项目中创建 Cloud Storage 存储桶。 如果您使用其他项目中的存储桶，则必须手动向 Agent Platform Service Agent (service-PROJECT_NUMBER@gcp-sa-aiplatform.) 授予对 Cloud Storage 存储桶的读取权限。

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

Google Cloud 控制台

1. 在 Google Cloud 控制台中，前往 Cloud Storage 存储分区页面。

   进入“存储桶”

2. 点击 创建。
3. 在创建存储桶页面上，输入您的存储桶信息。要转到下一步，请点击继续。
   1. 在开始使用部分中，执行以下操作：
      • 输入符合存储桶命名要求的全局唯一的名称。
      • 如需添加存储桶标签，请展开标签部分 ()，点击 添加标签，并为标签指定 key 和 value。
   2. 在选择数据存储位置部分，执行以下操作：
      1. 选择位置类型。
      2. 从位置类型下拉菜单中选择一个位置，用于永久存储存储桶的数据。
         • 如果您选择双区域位置类型，还可以通过勾选相关复选框来启用增强型复制。
      3. 如需设置跨存储桶复制，请选择通过 Storage Transfer Service 添加跨存储桶复制，然后按照以下步骤操作：

         设置跨存储桶复制

         1. 在存储桶菜单中，选择一个存储桶。

         2. 在复制设置部分中，点击配置以配置复制作业的设置。

            系统会显示配置跨存储桶复制窗格。

            • 如需按对象名称前缀过滤要复制的对象，请输入要用于包含或排除对象的前缀，然后点击 添加前缀。
            • 如需为复制的对象设置存储类别，请从存储类别菜单中选择一个存储类别。 如果您跳过此步骤，则复制的对象会默认使用目标存储桶的存储类别。
            • 点击完成。
   3. 在选择数据存储方式部分中，执行以下操作：
      1. 为存储桶选择默认存储类别，或者选择 Autoclass 对存储桶数据进行自动存储类别管理。
      2. 如需启用分层命名空间，请在针对数据密集型工作负载优化存储部分中，选择在此存储桶上启用分层命名空间。
         注意：您无法在现有存储分区中启用分层命名空间。
   4. 在选择如何控制对对象的访问权限部分中，选择存储桶是否强制执行禁止公开访问，然后为存储桶对象选择访问权限控制方法。
      注意：如果禁止公开访问设置是在组织政策层面强制执行的，则您无法更改此设置。
   5. 在选择如何保护对象数据部分中，执行以下操作：
      • 在数据保护下，选择您要为存储桶设置的任何选项。
        • 如需启用软删除，请选中软删除政策（用于数据恢复）复选框，然后指定您希望在删除对象后保留对象的天数。
        • 如需设置对象版本控制，请选中对象版本控制（用于版本控制）复选框，然后指定每个对象的最大版本数以及非当前版本过期前的天数。
        • 如需为对象和存储分区启用保留政策，请点击保留（合规性）复选框，然后执行以下操作：
          • 如需启用对象保留锁定，请点击启用对象保留复选框。
          • 如需启用存储桶锁定，请点击设置存储桶保留政策复选框，然后为保留期限选择时间单位和时长。
      • 如需选择对象数据的加密方式，请展开数据加密部分 ()，然后选择数据加密方法。
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

安装并初始化 Agent Platform SDK for Python

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

（可选）设置虚拟环境。

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

安装

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

• agent_engines：部署到 Agent Runtime 所需的软件包集。
• adk：兼容的智能体开发套件软件包集。
• langchain：兼容的 LangChain 和 LangGraph 软件包集。
• ag2：兼容的 AG2 软件包集。
• llama_index：兼容的 LlamaIndex 软件包集。

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

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

如需在 Agent Platform 上使用 Agent2Agent (A2A)，您还必须安装 a2a-sdk 软件包：

pip install google-adk[a2a]

身份验证

Colab

运行以下代码：

from google.colab import auth

auth.authenticate_user(project_id="PROJECT_ID")

Cloud Shell

您无需执行任何操作。

本地 Shell

运行以下命令：

gcloud auth application-default login

导入并初始化 SDK

运行以下代码，以导入并初始化适用于 Agent Runtime 的 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 是支持的区域之一。

（可选）自带容器 (BYOC)

如需查看自带容器 (BYOC) 的示例，请在以下任一环境中运行“在 Agent Runtime 上部署容器化智能体”笔记本：

在 Colab 中打开 | 在 Colab Enterprise 中打开 | 在 Agent Platform Workbench 中打开 | 在 GitHub 上查看

默认情况下，Agent Runtime 会在部署过程中为您构建容器。如果您想构建用于部署的自定义容器，请按照本部分中的说明操作。

如需使用自定义容器部署智能体，请完成以下高级别任务：

1. 构建容器映像并将其推送到 Artifact Registry。
2. 为代理设置身份和权限。
3. 向 Agent Runtime 默认服务代理授予 Artifact Registry Reader 角色。

重要提示： 如果您计划通过 Agent Gateway 路由自带容器 (BYOC) 代理的流量，则必须将自定义容器映像配置为信任网关的根证书授权机构 (CA)。如需了解相关说明，请参阅为 Agent Gateway 配置自定义容器 (BYOC) 代理。

构建并推送容器映像

如需构建和推送容器映像，请按照使用 Cloud Build 构建和推送 Docker 映像中的说明操作。

为 Agent Runtime 设置身份和权限

需要使用 Agent Runtime 默认服务代理才能从 Artifact Registry 代码库导入容器。

默认情况下，系统会在您的项目中自动生成服务代理。如果不存在，请按照为代理设置身份和权限中的说明创建并配置该文件。

授予 Artifact Registry Reader 角色

向默认服务代理 (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.) 授予 Artifact Registry Reader 角色 (roles/artifactregistry.reader)。

运行以下命令，向默认服务代理授予所需的角色：

gcloud projects add-iam-policy-binding PROJECT_NUMBER \
  --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform-re." \
  --role="roles/artifactregistry.reader"

（可选）授予跨项目权限

如果您的容器映像存储在 Artifact Registry 制品库中，但该制品库与代理部署到的项目不同，则需要跨项目权限。 Google Cloud

在这种情况下，请在 Artifact Registry 代码库项目中向 Agent Platform Service Agent (service-PROJECT_NUMBER@gcp-sa-aiplatform.) 授予 Artifact Registry Reader 角色。

gcloud projects add-iam-policy-binding AR_REPO_PROJECT_NUMBER \
  --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform." \
  --role="roles/artifactregistry.reader"

后续步骤

概览

创建代理

了解如何使用 Agent Platform Runtime 创建代理。

问题排查

排查代理创建问题

了解如何解决创建自定义代理时出现的常见错误。

资源

获取支持

查找 Google Agent Platform 的相关资源和支持。