设置环境

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

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

使用进行设置 Google Cloud

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

Google Cloud 项目

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

登录您的 Google Cloud 账号。如果您是新手 Google Cloud，请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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 Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

获取所需的角色

如需获得使用 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 实例后，您可以执行以下操作：

根据您的应用场景，向代理身份授予其他角色。
使用 agent_engine.update(...)添加代理代码。

默认服务代理

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

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

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

进入 IAM
找到与 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com 匹配的主账号。
依次点击“编辑”按钮和“保存”按钮，向主账号添加所需的角色。

手动生成默认服务代理

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

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

使用 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。
前往 IAM 页面，然后点击授予访问权限。

进入 IAM
在添加主账号部分的新的主账号字段中，输入 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com。
在分配角色部分，找到并选择您需要的角色。
点击保存按钮。

自定义服务帐号

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

如果您没有服务帐号，请创建一个。请参阅创建服务账号。
向服务帐号授予 Agent Platform User (roles/aiplatform.user) 角色。
向服务帐号授予代理代码所需的任何其他角色。
如需使用此服务账号部署代理，请向您自己授予此自定义服务账号的 Service Account User 角色 (roles/iam.serviceAccountUser)。
部署代理时，请指定自定义服务账号的邮箱。如需了解详情，请参阅配置自定义服务账号。

跨项目自定义服务帐号

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

停用跨项目服务帐号使用组织政策：在服务帐号所在的项目中，确保未强制执行 iam.disableCrossProjectServiceAccountUsage组织政策。未强制执行。如需了解详情，请参阅停用跨项目服务帐号使用强制执行。
向 Agent Platform Service Agent 授予权限：在服务帐号所在的项目中，向您计划部署代理的项目的 Agent Platform Service Agent (service-RESOURCE_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) 授予Service Account Token Creator (roles/iam.serviceAccountTokenCreator) 角色。
向自定义服务帐号授予权限 ：在您计划部署代理的项目中，向自定义服务帐号授予必要的角色。这通常包括 Agent Platform User 角色 (roles/aiplatform.user) 以及代理代码所需的任何其他角色。

（可选）创建 Cloud Storage 存储桶

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

从源文件部署：代理以文件形式存在。Agent Platform SDK for Python 可以直接将这些文件捆绑并上传到部署服务，因此不需要 Cloud Storage 暂存存储桶。
从代理对象部署：代理存在于内存中。Agent Platform SDK for Python 会打包此对象并将其上传到 Cloud Storage 存储桶，该存储分区充当部署服务的暂存区。

从源文件部署

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

从对象部署

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

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

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

Google Cloud 控制台

在 Google Cloud 控制台中，前往 Cloud Storage 存储分区 页面。
进入“存储分区”
点击创建。
在创建存储桶 页面上，输入您的存储桶信息。要转到下一步，请点击继续。
1. 在开始使用 部分中，执行以下操作：
  - 输入符合存储桶命名要求的全局唯一的名称。
  - 如需添加存储桶标签，请展开标签部分 ()，点击 添加标签，并为标签指定 key 和 value。
2. 在选择存储数据的位置 部分中，执行以下操作：
  1. 选择位置类型。
  2. 从位置类型下拉菜单中选择一个位置，用于永久存储存储桶的数据。
    - 如果您选择双区域位置类型，还可以通过勾选相关复选框来启用增强型复制。
  3. 如需设置跨存储桶复制，请选择 通过 Storage Transfer Service 添加跨存储桶复制 ，然后按照以下步骤操作：
    设置跨存储桶复制
    
    在存储桶 菜单中，选择一个存储桶。
    
    在复制设置 部分中，点击配置以配置复制作业的设置。
    
    系统会显示配置跨存储桶复制 窗格显示。
    
    如需按对象名称前缀过滤要复制的对象，请输入要用于包含或排除对象的前缀，然后点击 添加前缀。
    
    如需为复制的对象设置存储类别，请从存储类别菜单中选择一个存储类别。如果您跳过此步骤，则复制的对象会默认使用目标存储桶的存储类别。
    
    点击完成。
3. 在选择存储数据的方式 部分中，执行以下操作：
  1. 为存储桶选择默认存储类别，或者选择Autoclass对存储桶数据进行自动存储类别管理。
  2. 如需启用分层命名空间，请在 针对数据密集型工作负载优化存储 部分中，选择 在此存储桶上启用分层命名空间。
    注意：您无法在现有存储分区中启用分层命名空间。
4. 在选择如何控制对对象的访问权限 部分中，选择存储桶是否强制执行禁止公开访问，然后为存储桶对象选择访问权限控制方法。
  注意：如果组织政策强制执行了禁止公开访问设置，则您无法更改此设置。
5. 在选择如何保护对象数据 部分中，执行以下操作：
  - 在数据保护 下，选择您要为存储桶设置的任何选项。
    - 如需启用软删除，请点击 软删除政策（用于数据恢复） 复选框，然后指定您希望在删除对象后保留对象的天数。
    - 如需设置对象版本控制，请点击 对象版本控制（用于版本控制） 复选框，然后指定每个对象的最大版本数以及非当前版本过期的天数。
    - 如需在对象和存储分区上启用保留政策，请点击保留（用于合规性） 复选框，然后执行以下操作：
      - 如需启用对象保留锁定，请点击 启用对象保留 复选框。
      - 如需启用存储桶锁定，请点击 设置存储桶保留政策 复选框，然后为保留期限选择时间单位和时间长度。
  - 如需选择对象数据的加密方式，请展开 数据加密 部分 ()，然后选择 数据加密 方法。
点击创建。

命令行

将 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 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

导入并初始化 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)

Agent Runtime 会在部署过程中为您构建容器。如果您打算构建自己的容器以进行部署，则需要按照以下子部分中的说明进行操作。概括来讲，包括以下步骤：

构建容器映像并将其推送到 Artifact Registry。
为 Agent Runtime 设置与用户项目（在为代理设置身份和权限中）和租户项目（运行时在其中运行）对应的服务账号。
向用户项目服务帐号和租户项目服务帐号授予 roles/artifactregistry.reader 角色。

构建并推送容器映像

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

为 Agent Runtime 设置服务账号

如需设置服务账号，请部署一个用于输出租户服务帐号的代理。

首先，为代理设置源代码：

打开一个终端窗口
创建一个名为 byoc_setup 的新目录
```
mkdir byoc_setup
```

在 byoc_setup 目录中创建一个名为 metadata_agent.py 的文件，其中包含以下内容：

class MetadataAgent:

  def query(self):
    import requests
    url = "http://metadata.google.internal/computeMetadata/v1/project/numeric-project-id"
    try:
        response = requests.get(url, headers={"Metadata-Flavor": "Google"})
        response.raise_for_status()
        return f"service-{response.text}@serverless-robot-prod.iam.gserviceaccount.com"
    except Exception:
        return None

root_agent = MetadataAgent()

在 byoc_setup 目录中创建另一个名为 requirements.txt 的文件，其中包含以下内容：
```
google-cloud-aiplatform[agent_engines]
```

如果您尚未安装并初始化 Agent Platform SDK for Python，请先安装并初始化。在初始化 Agent Platform SDK for Python 的同一 Python 会话中，运行以下代码以输出 TENANT_SERVICE_ACCOUNT：

remote_agent = client.agent_engines.create( # This deploys the agent
    config={
        "source_packages": ["byoc_setup"],
        "entrypoint_module": "byoc_setup.metadata_agent",
        "entrypoint_object": "root_agent",
        "requirements_file": "byoc_setup/requirements.txt",
        "class_methods": [{'api_mode': '', 'name': 'query'}],
    },
)
# This prints the tenant service account
# service-{tenant_project_number}@serverless-robot-prod.iam.gserviceaccount.com
print(remote_agent.query())
# This cleans up the resources
remote_agent.delete(force=True)

在为代理设置身份和权限中查找 USER_SERVICE_ACCOUNT。如果您使用的是默认服务代理，则此值应与 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com 匹配。

授予 Artifact Registry Reader 角色

通过运行以下命令来授予所需的角色：

gcloud projects add-iam-policy-binding <var>PROJECT_NUMBER</var> \
  --member="serviceAccount:USER_SERVICE_ACCOUNT" \
  --role="roles/artifactregistry.reader"
gcloud projects add-iam-policy-binding <var>PROJECT_NUMBER</var> \
  --member="serviceAccount:TENANT_SERVICE_ACCOUNT" \
  --role="roles/artifactregistry.reader"

后续步骤

概览

设置环境

使用进行设置 Google Cloud

Google Cloud 项目

获取所需的角色

为代理设置身份和权限

代理身份

默认服务代理

手动生成默认服务代理

自定义服务帐号

跨项目自定义服务帐号

（可选）创建 Cloud Storage 存储桶

从源文件部署

从对象部署

Google Cloud 控制台

设置跨存储桶复制

命令行

安装并初始化 Agent Platform SDK for Python

（可选）设置虚拟环境。

安装

身份验证

Colab

Cloud Shell

本地 Shell

导入并初始化 SDK

Google Cloud 项目

（可选）自带容器 (BYOC)

构建并推送容器映像

为 Agent Runtime 设置服务账号

授予 Artifact Registry Reader 角色

后续步骤

创建代理

排查代理创建问题

获取支持

设置环境 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

使用进行设置 Google Cloud

Google Cloud 项目

获取所需的角色

为代理设置身份和权限

代理身份

默认服务代理

手动生成默认服务代理

自定义服务帐号

跨项目自定义服务帐号

（可选）创建 Cloud Storage 存储桶

从源文件部署

从对象部署

Google Cloud 控制台

设置跨存储桶复制

命令行

安装并初始化 Agent Platform SDK for Python

（可选）设置虚拟环境。

安装

身份验证

Colab

Cloud Shell

本地 Shell

导入并初始化 SDK

Google Cloud 项目

（可选）自带容器 (BYOC)

构建并推送容器映像

为 Agent Runtime 设置服务账号

授予 Artifact Registry Reader 角色

后续步骤

创建代理

排查代理创建问题

获取支持

设置环境