中文译本。原文见同目录 README.md

第 12 课：开始使用 Vertex AI 与 ADK

关于命名的说明（2026）： 在 Google Cloud Next 2026 上，Vertex AI 已更名为 Gemini Enterprise Agent Platform，原先称为 Agent Engine 的托管运行时现为 Agent Runtime。底层服务、API 与 SDK 未变，因此下文内容仍然适用；你只会在 Cloud 控制台和文档中看到新名称。本指南为与现有教程保持连贯，仍沿用熟悉的「Vertex AI」和「Agent Engine」称谓。

引言

前十一课里，我们打好了 Agent 工作原理的基础——推理、工具、记忆、规划、多 Agent 系统、RAG、评估、安全与生产运维。这些概念都与具体平台无关。

现在转向实践。本课把这些概念映射到 Google Cloud 上可用的具体工具与服务。目标是让你清楚有哪些能力、各部分如何拼在一起，以及构建某类 Agent 时应选用哪项服务。

ELI5：把 Google Cloud AI 技术栈想成一间工坊

想象你在搭建一间木工坊。你需要原材料（木头、金属）、电动工具（锯、钻）、工作台（稳定的操作面）、安全装备（护目镜、手套），以及展示或售卖成品的空间。

Google Cloud AI 技术栈类似：

Gemini 模型是原材料——驱动一切的智能
**ADK（Agent Development Kit）**是电动工具套件——用来构建 Agent 的框架
Vertex AI 平台是工作台——模型托管、评估与部署基础设施
Agent Engine是托管展厅——在生产环境运行 Agent，而无需你管理服务器
Model Armor是安全装备——护栏与内容过滤
Vertex AI Search 与 RAG Engine是参考书库——让 Agent 能访问你的数据

这些组件可单独使用，也可组合使用。并非每个项目都需要全部工具。

核心要点： Google Cloud 提供从模型到托管运行时的完整 Agent 技术栈。弄清各部分职责，有助于为每项工作选对工具。

面向 Agent 的 Google Cloud AI 技术栈

下面是主要组件及其相互关系示意：

+------------------------------------------------------------------+
|                        Your Agent Application                     |
+------------------------------------------------------------------+
|                                                                    |
|  +--------------------+    +----------------------------------+   |
|  |  Agent Development |    |  Agent Engine                    |   |
|  |  Kit (ADK)         |    |  (Managed Runtime)               |   |
|  |                    |    |                                  |   |
|  |  - Build agents    |    |  - Deploy and run agents         |   |
|  |  - Define tools    |--->|  - Session management            |   |
|  |  - Orchestration   |    |  - Scaling and monitoring        |   |
|  +--------------------+    +----------------------------------+   |
|           |                            |                          |
|           v                            v                          |
|  +----------------------------------------------------+          |
|  |              Vertex AI Platform                     |          |
|  |                                                     |          |
|  |  - Model hosting (Gemini, partner models)           |          |
|  |  - Evaluation tools                                 |          |
|  |  - Context caching                                  |          |
|  |  - Grounding with Google Search                     |          |
|  +----------------------------------------------------+          |
|           |                            |                          |
|           v                            v                          |
|  +----------------------+    +------------------------+           |
|  | Vertex AI Search &   |    |  Model Armor           |           |
|  | RAG Engine           |    |  (Safety & Guardrails) |           |
|  +----------------------+    +------------------------+           |
|                                                                    |
+------------------------------------------------------------------+
|                     Gemini Models                                  |
|  Pro (complex reasoning) | Flash (balanced) | Flash-Lite (volume) |
+------------------------------------------------------------------+

Google Cloud AI Stack Explorer

Click any component to learn more. Try the Decision Helper.

Platform Services

🏗️

Agent Engine

Managed Runtime

☁️

Cloud Run

Container Hosting

📊

Monitoring

Observability

▼ ▼ ▼

Developer Tools

🛠️

ADK

Agent Dev Kit

🛡️

Model Armor

Safety & Guardrails

🔍

RAG Engine

Knowledge Retrieval

▼ ▼ ▼

Foundation Models

🧠

Gemini Pro

Complex Reasoning

⚡

Gemini Flash

Balanced

💨

Flash-Lite

High Volume

我们逐一过一遍各组件。

Gemini 模型

Gemini 是 Google 的多模态 AI 模型家族。做 Agent 开发时，你主要会用到三个档位：

模型	最适合	特点
Gemini Pro	复杂推理、多步规划、细微决策	能力最强，延迟更高，成本更高
Gemini Flash	均衡任务——工具调用、摘要、对话	能力不错，速度快，成本适中
Gemini Flash-Lite	高吞吐、较简单任务——分类、路由、抽取	快、成本最低，适合高吞吐场景

截至 2026 年中，这些档位的当前模型 ID 为 gemini-3.1-pro（Pro）、gemini-3.5-flash（Flash）和 gemini-3.1-flash-lite（Flash-Lite）。Gemini 2.5 系列仍可用，但计划于 2026 年 10 月 16 日退役；Gemini 2.0 模型已于 2026 年 6 月 1 日关停——请查阅文档获取最新 ID，或使用如 gemini-flash-latest 这类滚动别名。

选择合适的模型

模型选型可以想成出门选交通工具：

Flash-Lite像自行车——快、便宜，适合短途（简单分类、意图识别、基础抽取）
Flash像汽车——通用，适合大多数行程（一般 Agent 任务、工具调用、RAG、对话）
Pro像卡车——动力足，能扛重活（复杂多步推理、长文档、困难规划）

多数生产 Agent 会通过 model routing（模型路由）（第 11 课已讲）使用多个模型档位。简单步骤用 Flash-Lite，核心逻辑用 Flash，只有任务真正需要时才用 Pro。

多模态能力

Gemini 模型可处理文本、图像、音频和视频。这意味着你的 Agent 可以：

分析用户上传的图像（产品照片、截图、文档）
处理音频输入（语音指令、会议录音）
理解视频内容（教程、演示）
原生处理 PDF 及其他文档格式

相对纯文本模型，这是显著优势，因为你可以构建以更丰富方式与真实世界交互的 Agent。

模型细节与能力见 Gemini 模型文档。

Vertex AI 平台

Vertex AI 是 Google Cloud 的机器学习平台。对 Agent 开发者而言，最相关的能力包括：

模型托管与 API 访问

Vertex AI 提供对 Gemini 以及合作伙伴与开源模型的 API 访问。你可以得到：

托管端点——无需自行管理基础设施
上下文缓存（context caching）——缓存长系统提示词或文档，降低重复调用的成本与延迟
Google Search grounding——让模型用网页搜索结果核验并补充知识
批量预测——高效处理大批量请求

评估工具

Vertex AI 包含与第 9 课所述内容对齐的评估能力：

AutoSxS（Auto Side-by-Side）——自动对比两个模型版本
逐点评估（pointwise evaluation）——按质量维度给单条回复打分
自定义指标——定义自己的评估标准
批量评估——在大规模数据集上跑 eval

这些工具可接入你的 CI/CD，用于评估门控部署（第 11 课）。

Model Garden

Vertex AI Model Garden 提供 Gemini 之外的大量模型——包括开源模型与合作伙伴模型。当你需要面向特定任务的专用模型，或想对比不同选项时很有用。

完整平台概览见 Vertex AI 文档。

Agent Development Kit（ADK）

ADK 是 Google 开源、以代码为先的 AI Agent 构建框架。若 Vertex AI 是工作台，ADK 就是真正用来动手搭建的电动工具套件。

主要特点

特性	说明
开源	发布于 GitHub，Apache 2.0 许可
多语言	Python、TypeScript/JavaScript、Go、Java
模型无关	可用 Gemini，也支持其他 LLM
部署无关	可本地运行，也可跑在 Agent Engine、Cloud Run 或任意容器平台
有主张但灵活	提供结构，但不把你锁死

为什么需要框架？

你也可以直接调用 Gemini API 来构建 Agent——自己写工具调用循环、管理对话状态、处理编排。ADK 帮你免去重复发明这些常见模式：

工具注册与执行
对话状态管理
多轮编排循环
多 Agent 协作
会话与记忆管理
护栏与日志的回调钩子

可以类比：自己写原始 HTTP handler，还是用 Web 框架。两者都行，但框架处理样板代码，让你专注于 Agent 独特的逻辑。

ADK 核心概念

ADK 把 Agent 分成三类：

1. LLM agents

由语言模型驱动，能推理、规划并决定调用哪些工具。这是最常见类型，对应第 4 课讲过的 ReAct 风格 Agent。

from google.adk.agents import Agent
from google.adk.tools import FunctionTool

# Define a tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    # In practice, this would call a weather API
    return f"The weather in {city} is sunny, 72F."

# Create an agent
weather_agent = Agent(
    name="weather_agent",
    model="gemini-3.5-flash",
    instruction="You are a helpful weather assistant. Use the get_weather "
                "tool to answer questions about weather conditions.",
    tools=[get_weather],
)

2. workflow agents

这类 Agent 遵循预定义的编排模式，而不是依赖 LLM 决定流程。ADK 内置三种工作流类型：

工作流类型	工作方式	何时使用
SequentialAgent	按固定顺序依次运行子 Agent	步骤必须按序发生（例如：校验 -> 处理 -> 回复）
ParallelAgent	同时运行子 Agent	步骤彼此独立、可并行（例如：搜索多个来源）
LoopAgent	重复运行子 Agent 直到满足条件	迭代打磨（例如：生成 -> 评估 -> 改进）

from google.adk.agents import SequentialAgent

# A pipeline that validates input, processes it, and formats the response
pipeline = SequentialAgent(
    name="order_pipeline",
    sub_agents=[
        input_validator_agent,
        order_processor_agent,
        response_formatter_agent,
    ],
)

Workflow agents 直接对应第 4 课的 Agent 设计模式。Sequential 对应流水线模式。Parallel 对应 fan-out/fan-in。Loop 对应反思与迭代打磨。

3. custom agents

若编排模式不适合内置类型，可继承基础 Agent 类并实现自定义控制流，创建自定义 Agent。

ADK 工具生态

ADK 最大优势之一是工具生态。工具是 Agent 与外部世界交互的方式（第 3 课），ADK 提供多种定义方式：

工具类型	是什么	示例
Function Tools	装饰为工具的普通 Python/JS 函数	查询数据库的函数
MCP Tools	来自 Model Context Protocol 服务器的工具	连接任意 MCP 兼容工具服务器
OpenAPI Tools	由 OpenAPI/Swagger 规范自动生成	把任意 REST API 包装成 Agent 工具
Built-in Tools	ADK 提供的预构建集成	Google Search、代码执行、RAG

ADK 包含 60+ 预构建工具集成，覆盖常见需求如：

Google Search 与网页浏览
代码执行（沙箱）
文件操作
数据库查询
API 调用
Google Workspace（Gmail、Calendar、Drive）

from google.adk.tools import FunctionTool

# A simple function tool
def search_products(query: str, max_results: int = 5) -> list[dict]:
    """Search the product catalog.

    Args:
        query: The search query string.
        max_results: Maximum number of results to return.

    Returns:
        A list of matching products with name, price, and description.
    """
    # Your implementation here
    return product_database.search(query, limit=max_results)

# ADK automatically generates the tool schema from the function signature
# and docstring, so the LLM knows how to call it correctly.

ADK Skills

Skills 是较新的 ADK 概念，把 Agent 能力打包为自包含、可复用的单元。可以想成 Agent 的「插件」。

Skills 有三个递增复杂度的层级：

层级	包含内容	示例
L1 - Metadata	名称、描述与标签，帮助 Agent 理解何时使用该 skill	「此 skill 处理机票预订」
L2 - Instructions	Agent 应如何使用该 skill 的详细说明	预订流程的逐步指南
L3 - Resources	skill 所需的工具、数据源与子 Agent	航班搜索 API 工具、航司数据库

Skills 让跨团队、跨项目共享与组合 Agent 能力更容易。

完整 ADK 文档见 ADK docs 站点。

Agent Engine

Agent Engine 是 Google Cloud 上用于部署与运行 Agent 的托管运行时服务。若 ADK 是如何构建 Agent，Agent Engine 就是如何在生产中运行它们而无需管理基础设施。

Agent Engine 提供什么

能力	作用
托管托管（Managed hosting）	无需自行开通服务器或容器即可运行 Agent
会话管理	内置对话状态持久化
扩缩容	按流量自动扩缩
监控	与 Cloud Monitoring、Cloud Logging 集成
安全	基于 IAM 的访问控制，支持 VPC Service Controls

何时用 Agent Engine，何时用其他部署选项

部署选项	最适合
Agent Engine	希望托管基础设施、不想自己处理扩缩容、会话管理或部署的生产 Agent
Cloud Run	需要自定义运行时环境、特定依赖或对容器有更多控制的 Agent
GKE（Kubernetes）	已作为更大微服务架构一部分跑在 Kubernetes 上的 Agent
本地 / 自托管	开发、测试，或无法使用云服务时

ADK Agent 可部署到上述任一目标。Agent Engine 是托管程度最高的选项——把 Agent 代码交给它，其余由它处理。

部署细节见 Agent Engine 文档。

Vertex AI Search 与 RAG Engine

第 8 课讲过 Agent 如何用检索增强生成（RAG）访问你的数据。Vertex AI 为此提供托管服务：

Vertex AI Search

可索引并搜索以下内容的托管搜索服务：

网站
非结构化文档（PDF、Word、HTML）
结构化数据（数据库、电子表格）

它处理分块、嵌入、索引与检索——第 8 课讨论的完整 RAG 流水线——并以托管服务形式提供。

RAG Engine

RAG Engine 提供专为把 LLM 回复 grounding 到你的数据而设计的托管检索流水线：

文档摄取——自动上传并处理文档
分块策略——可配置的文档切分方式
向量搜索——托管嵌入与相似度搜索
与 Gemini 集成——对 Gemini 模型调用内置 grounding

这些托管服务的优点是你不必自建向量数据库、管理嵌入或搭建检索流水线。代价是对细节的控制更少。

RAG 能力见 RAG Engine 概览。

Model Armor

Model Armor 是 Google Cloud 的托管护栏服务（第 10 课深入讲过护栏）。它提供：

功能	作用
提示词筛查	在到达模型前检测并拦截有害或对抗性提示
回复过滤	筛查模型输出中的有害、有毒或不恰当内容
提示注入检测	识别试图覆盖模型指令的行为
可配置策略	为不同内容类别设置自己的阈值
集成	可与 Vertex AI 端点配合，并可加入任意生成式 AI 应用

Model Armor 为你提供第 10 课纵深防御模型中的生产级 Layer 2 防御，而无需从零做内容过滤。

快速上手指南

下面说明如何用 ADK 与 Google Cloud 开始 Agent 开发。

前置条件

Google Cloud 账号（可用免费层级起步）
Python 3.9+（Python SDK）
已启用计费的 Google Cloud 项目

步骤 1：安装 ADK

pip install google-adk

步骤 2：配置认证

认证有两种方式：

选项 A：API Key（入门最简单）

export GOOGLE_API_KEY="your-api-key-here"

可从 Google AI Studio 获取 API key。

选项 B：Google Cloud 项目（面向生产与 Vertex AI 功能）

# Install the Google Cloud CLI
# https://cloud.google.com/sdk/docs/install

# Authenticate
gcloud auth application-default login

# Set your project
gcloud config set project YOUR_PROJECT_ID

步骤 3：创建第一个 Agent

创建文件 agent.py：

from google.adk.agents import Agent

root_agent = Agent(
    name="greeting_agent",
    model="gemini-3.5-flash",
    instruction="You are a friendly assistant that greets users "
                "and answers basic questions.",
)

步骤 4：本地运行

adk web

这会启动本地 Web 界面，你可以与 Agent 对话并观察其行为。ADK 开发 UI 会展示 Agent 的推理步骤、工具调用与状态——对调试非常有价值。

步骤 5：添加工具与复杂度

从这里开始，你可以添加工具、创建多 Agent 系统、集成 RAG，最终部署到 Agent Engine 或 Cloud Run。ADK 入门指南会详细走完这些步骤。

决策树：该用哪项服务？

构建 Agent 时，用这棵决策树选择合适的 Google Cloud 服务：

"I want to build..."
    |
    +-- "A simple chatbot with no tools"
    |       --> Gemini API directly (no framework needed)
    |
    +-- "An agent with tools and reasoning"
    |       --> ADK + Gemini Flash
    |       |
    |       +-- "...and I need it in production"
    |               --> Deploy to Agent Engine or Cloud Run
    |
    +-- "An agent that searches my documents"
    |       --> ADK + Vertex AI Search or RAG Engine
    |
    +-- "A multi-agent system"
    |       --> ADK (multi-agent orchestration built in)
    |
    +-- "An agent with strict safety requirements"
    |       --> ADK + Model Armor + custom guardrails
    |
    +-- "A high-volume, cost-sensitive application"
    |       --> Model routing (Flash-Lite for simple tasks,
    |           Flash for complex) + context caching
    |
    +-- "An agent that needs to use external APIs"
            --> ADK with OpenAPI tools or MCP tools

快速参考表

我需要……	使用……
可调用的 LLM	通过 Vertex AI 或 AI Studio 使用 Gemini 模型
构建 Agent 的框架	Agent Development Kit（ADK）
托管 Agent 托管	Agent Engine
自定义容器托管	Cloud Run 或 GKE
文档搜索 / RAG	Vertex AI Search 或 RAG Engine
内容安全护栏	Model Armor
模型评估	Vertex AI Evaluation 工具
提示词管理	Vertex AI prompt management
与外部工具互操作	ADK 中的 MCP tools
与其他 Agent 互操作	A2A 协议（第 14 课）

各部分如何连接：完整示例

下面是一个典型生产 Agent 如何组合使用多项 Google Cloud 服务：

User asks: "What is the return policy for my recent order?"

1. [ADK Agent] receives the request
       |
2. [Model Armor] screens the input for safety
       |
3. [Gemini Flash] reasons about the request:
       "I need to look up the order and find the return policy"
       |
4. [ADK Tool: Order Lookup] calls your order database
       |
5. [RAG Engine] searches your policy documents
       for the relevant return policy
       |
6. [Gemini Flash] synthesizes a response from
       the order details and policy documents
       |
7. [Model Armor] screens the output for safety
       |
8. [Agent Engine] manages the session state
       and returns the response to the user

每项 Google Cloud 服务负责拼图的一块。ADK 编排流程。Gemini 提供推理。RAG Engine 提供知识。Model Armor 提供安全。Agent Engine 提供运行时。

各课概念如何映射到 Google Cloud

下面是把前面课程概念对应到具体 Google Cloud 服务的参考：

课程	概念	Google Cloud 服务
2 - Agent 如何思考	LLM 推理	Gemini 模型
3 - 工具	Function calling	ADK Function Tools、MCP Tools、OpenAPI Tools
4 - 设计模式	编排	ADK Sequential/Parallel/Loop Agents
5 - 记忆	会话状态、长期记忆	ADK session management、Agent Engine
6 - 规划	多步推理	复杂规划用 Gemini Pro
7 - 多 Agent	Agent 协作	ADK 多 Agent 支持
8 - RAG	知识检索	Vertex AI Search、RAG Engine
9 - 评估	测试 Agent	Vertex AI Evaluation
10 - 安全	护栏	Model Armor
11 - 生产	部署、CI/CD	Agent Engine、Cloud Run、Agent Starter Pack

关键要点

Google Cloud 提供完整的 Agent 技术栈。 从底层的 Gemini 模型到顶层的 Agent Engine，你可以构建并部署完整的 Agent 系统。
ADK 是以代码为先的框架。 开源、多语言、模型无关、部署无关。它处理常见模式（工具调用、编排、状态管理），让你专注于 Agent 逻辑。
选对模型档位。 简单任务用 Flash-Lite，多数 Agent 工作用 Flash，复杂推理用 Pro。跨档位的模型路由是关键成本优化策略。
托管服务降低运维负担。 Agent Engine、RAG Engine 与 Model Armor 处理基础设施与运维，让你专注于构建。代价是对实现细节的控制更少。
一切可组合。 你可以不用 Agent Engine 只用 ADK，不用 ADK 只用 Vertex AI，或整栈一起用。从所需部分起步，随需求增长再加服务。
ADK Agent 直接对应本课程概念。 LLM Agents 负责推理，Workflow Agents 负责编排模式，工具负责外部交互，skills 负责可复用能力。

第 12 课：开始使用 Vertex AI 与 ADK

引言

ELI5：把 Google Cloud AI 技术栈想成一间工坊

面向 Agent 的 Google Cloud AI 技术栈

Gemini 模型

选择合适的模型

多模态能力

Vertex AI 平台

模型托管与 API 访问

评估工具

Model Garden

Agent Development Kit（ADK）

主要特点

为什么需要框架？

ADK 核心概念

1. LLM agents

2. workflow agents

3. custom agents

ADK 工具生态

ADK Skills

Agent Engine

Agent Engine 提供什么

何时用 Agent Engine，何时用其他部署选项

Vertex AI Search 与 RAG Engine

Vertex AI Search

RAG Engine

Model Armor

快速上手指南

前置条件

步骤 1：安装 ADK

步骤 2：配置认证

步骤 3：创建第一个 Agent

步骤 4：本地运行

步骤 5：添加工具与复杂度

决策树：该用哪项服务？

快速参考表

各部分如何连接：完整示例

各课概念如何映射到 Google Cloud

关键要点

延伸阅读

评论