此页面由 Cloud Translation API 翻译。

ADK 速成课程 - 从新手到专家

1. 学习内容

欢迎参加 ADK 大师班 - 多智能体系统之旅

您即将踏入令人兴奋的 AI 智能体世界。忘掉只能回答问题的简单聊天机器人吧。我们正在深入研究 Agent Development Kit (ADK)，以构建精密的自主系统，这些系统可以进行推理、规划和使用工具来完成复杂的任务。

课程路线图

学完本教程后，您将能够：

构建您的第一个 AI 代理：从零开始构建一个功能齐全的代理，该代理可以理解用户需求、使用 Google 搜索等工具，并生成详细且实用的回答。
掌握自定义工具：将智能体与您自己的自定义函数和 API 相关联，充分发挥智能体的强大功能。您将教导代理获取实时数据，例如实时天气预报。
构建多智能体系统：了解“智能体即工具”模式，这是一种革命性的概念，其中智能体会将任务委托给其他专业智能体，从而创建一个协同工作的 AI 专家团队。
编排复杂的工作流：除了简单的委托之外，还可以掌握路由器、顺序链、循环和并行执行等高级模式，从而构建强大、高效且智能的应用，以处理几乎所有请求。
为代理提供记忆功能：了解对话记忆的关键作用，使代理能够处理后续问题、从反馈中学习，并顺畅地管理多步骤任务。

现在就开始吧！🚀

2. 设置 GCP 和 Gemini API 密钥

设置 GCP 项目和 Gemini API 密钥

为了让 AI 代理正常运行，我们需要两样东西：一个提供基础的 Google Cloud 项目和一个用于访问 Google 强大模型的 Gemini API 密钥。

第 1 步：启用结算账号

您需要声明拥有 5 美元赠送金额的结算账号，以便进行部署。请务必使用您的 Gmail 账号。

第 2 步：创建新的 GCP 项目

前往 Google Cloud 控制台并创建一个新项目。

创建新的 GCP 账号

前往 Google Cloud 控制台并创建一个新项目。
打开左侧面板，点击 Billing，检查结算账号是否与此 GCP 账号相关联。

将结算账号与 GCP 账号相关联

如果您看到此页面，请选中 manage billing account，选择 Google Cloud 试用版并将其关联。

第 3 步：生成 Gemini API 密钥

您需要先拥有密钥，然后才能保护该密钥。

前往 Google AI Studio：https://aistudio.google.com/
使用您的 Gmail 账号登录。
点击“获取 API 密钥”按钮，该按钮通常位于左侧导航窗格中或右上角。
在 “API 密钥”对话框中，点击“在新项目中创建 API 密钥”图标。
选择您创建的已设置结算账号的新项目。
系统会为您生成新的 API 密钥。立即复制此密钥，并将其暂时存储在安全的地方（例如密码管理工具或安全记事本）。您将在后续步骤中使用此值。

3. 会话 1：使用 Runner 构建首个代理

roadmap1

我们先从基础知识开始。在此，我们创建第一个简单的代理 day_trip_agent。此代理的目的是根据用户的要求（包括预算考虑因素）生成一整天的旅行行程。此示例介绍了 ADK 中任何代理互动的三大核心组件：

代理：操作的核心大脑。它由指令（个性和使命）、使用的 AI 模型（例如 Gemini）以及可访问的工具定义。
会话：对话的记忆。它会存储互动历史记录（用户消息和代理回答），从而实现持续对话。
Runner：执行任务的引擎。它会获取代理和会话，处理新的用户查询，并编排生成回答的步骤。

➡️ 在笔记本中找到它的位置

👉 这对应于第 1 部分：您的第一个代理 - 一日游精灵 🧞 下的单元格。🌟

代理机器人正在阅读

代理定义：查找 create_day_trip_agent() 函数。这是定义代理的位置。请注意详细的指令字符串，这是告知代理如何行动的提示。我们还为其提供了第一个工具：Google 搜索。
辅助函数：此处定义了 run_agent_query() 辅助函数。我们将在整个笔记本中使用此实用程序来简化查询运行。
测试运行：run_day_trip_genie() 函数模拟用户询问“经济实惠”且“轻松愉快”的一日游。智能体使用其指令和 Google 搜索工具来寻找合适的地点，并创建采用 Markdown 格式的行程。

➡️ 操作：检查 day_trip_agent 的指令提示。请注意，测试查询中“实惠”的行程请求与代理的“注重预算”指南直接相关。

4. 会话 2：自定义工具 🛠️

roadmap2

虽然 Google 搜索功能强大，但当您将 AI 代理连接到自己的独特数据源、API 或自定义逻辑时，AI 代理的真正潜力才会得以释放。在本部分中，我们将从一个简单的 Python 函数创建一个自定义工具。

函数工具最关键的部分是其文档字符串。ADK 会自动解析文档字符串，以了解工具的作用、接受的参数 (Args) 以及返回的内容 (Returns)。大语言模型 (LLM) 会读取此说明，以决定何时以及如何使用该工具。

➡️ 在笔记本中找到它的位置

👉 这对应于 2.1 简单 FunctionTool：调用实时天气 API 下的单元格。🌟

ADK 工具

工具定义：get_live_weather_forecast(location: str) 函数是我们自定义工具的核心。它会获取城市名称，调用公共 National Weather Service API，并返回包含温度和天气预报的字典。
代理定义：通过在初始化期间传递 tools=[get_live_weather_forecast]，创建 weather_agent 并为其配备新工具。代理的指令明确告知它在建议户外活动之前使用此工具。
测试运行：查询“我想在太浩湖附近徒步旅行，天气怎么样？”直接触发代理使用 get_live_weather_forecast 工具，因为其指令要求这样做。

➡️ 操作：阅读 get_live_weather_forecast 函数的 docstring 和 weather_agent 的说明。请注意它们之间的直接关系。

5. 第 3 阶段：将代理作为工具使用 🧑‍🍳

roadmap3

既然可以创建专家团队，何必构建单一的单体代理？Agent-as-a-Tool 模式是一种构建复杂系统的强大方式，其中主代理（通常称为 Orchestrator 或 Router）将任务委托给其他更专注的代理。

此模式可让您创建模块化、可重用的代理。例如，您可以让一个智能体擅长数据库查询，另一个智能体擅长创意写作，第三个智能体充当友好的礼宾人员。编排器的任务是了解用户的请求，并将其转给合适的专家。

➡️ 在笔记本中找到它的位置

👉 这与 2.2 将代理作为工具：咨询专家 🧑‍🍳 下的单元格相对应。🌟

行程数据

此示例构建了一个复杂的多层代理系统：

专家：
- food_critic_agent：一种高度专业化的代理，仅提供餐厅建议。
- db_agent：一个模拟代理，假装查询数据库以获取酒店信息。
- concierge_agent：中级代理，充当礼貌的礼宾人员。最重要的是，它将 food_critic_agent 作为自己的工具。
编排器 (trip_data_concierge_agent)：这是用户互动的高级代理。其指令使其成为“旅行规划大师”，并为其提供了两个可调用其他代理的工具：
- call_db_agent：用于调用 db_agent 的函数。
- call_concierge_agent：用于调用 concierge_agent 的函数。
流程：在 run_trip_data_concierge() 中运行的测试演示了完整的委托链。
- 用户向编排器询问酒店和附近的餐厅。
- 编排器的指令会指示它先使用 call_db_agent 工具获取酒店数据。
- 然后，编排器使用 call_concierge_agent 工具获取建议。
- concierge_agent 在收到请求后，会使用自己的工具 food_critic_agent 来获取餐厅创意。

美食评论家的回答会传递回礼宾人员，礼宾人员会以礼貌的方式设置回答的格式，然后将其发送回编排器，编排器最终会将其呈现给用户。

➡️ 操作：在 run_trip_data_concierge() 下的测试运行中跟踪执行流程。请注意，TOOL CALLED 的输出显示了从编排器到专业人员的委托链。这是一系列按顺序执行的命令。

6. 第 4 次会话：代理记忆 🧠

roadmap4

真正智能的代理需要做的不仅仅是回复一次性查询。它需要记住对话内容、理解上下文，并根据反馈进行调整。这是通过适当的会话管理来实现的。您可以将“循环代理”视为一种持续进行对话循环的代理，其动力来自其记忆。

如果您将同一会话对象用于多个连续查询，代理可以“看到”整个对话历史记录。这样，它就可以处理后续问题、根据反馈自行更正，以及规划多步任务。

➡️ 在笔记本中找到它的位置

👉 这对应于第 3 部分：具有记忆的智能体 - 自适应规划器 🗺️ 下的单元格。🌟

智能体记忆

代理定义：create_multi_day_trip_agent() 函数定义了一个旨在逐步规划行程的代理。其指令强调要记住背景信息、处理反馈和每天规划。

方案 3a：具有记忆的代理 (✅)

此测试在 run_adaptive_memory_demonstration() 函数中运行。

系统会创建一个 trip_session，并将其重复用于连续三个回合。
第 1 轮：用户发起 2 天的行程规划。
第 2 轮：用户提供反馈意见（“我不太喜欢城堡”）。由于智能体记住了第 1 轮对话，因此它知道要更改计划的哪个部分，并提供了替代方案。
第 3 轮：用户确认更改并询问下一步。代理会记住所有内容，然后继续规划第 2 天。

方案 3b：没有记忆的代理 (❌)

此测试在 run_memory_failure_demonstration() 函数中运行。

这通过故意犯错来展示会话管理的重要性。系统会为每个回合创建一个新会话。

第 1 次会话：用户在 session_one 中发起行程。代理会正确响应。
第 2 轮对话：用户要求规划第 2 天的行程，但查询是在全新的 session_two 中发送的。由于这个新会话没有历史记录，因此代理感到困惑。它失忆了！它不知道用户正在规划什么行程。

操作：比较 run_adaptive_memory_demonstration() 和 run_memory_failure_demonstration() 中代理的回答。这是笔记本中最重要的概念：一次连续对话需要一个连续会话。

7. 第 5 阶段：路由器代理 🚏

roadmap5

单个代理能做的事情有限。为了处理真正复杂的用户请求，我们需要一支由专业客服人员组成的团队。但我们如何知道应针对特定查询使用哪个代理？这时，路由器代理就派上用场了。

路由器代理充当“主”代理或调度程序。其唯一目的是分析传入的用户查询，并确定哪个专家代理（或代理工作流）最适合完成这项任务。它本身不会回答查询，只会将查询路由到正确的下游代理。

例如，有关“最佳寿司”的查询应发送给 foodie_agent，而有关“本周末的音乐会”的问题应由 weekend_guide_agent 处理。

➡️ 在笔记本中查找此信息的位置：

👉 这个概念是整个笔记本的核心，但它首次出现在第 1 部分：多代理混乱 - 顺序工作流 🧠→🤖→🤖 🌟 中

路由器代理

代理定义：此代码单元定义了多个专业代理（day_trip_agent、foodie_agent、transportation_agent），最重要的是 router_agent。请密切注意 router_agent 的指令提示，它明确要求仅返回最适合该作业的代理的名称。
执行逻辑：run_sequential_app 函数演示了如何先调用 router_agent 来获取决策 (chosen_route)，然后在 if/elif 块中使用该决策来执行相应的专家代理。

8. 第 6 阶段：SequentialAgent ⛓️

roadmap6

有些任务需要按特定顺序执行多个步骤。例如，“在帕洛阿尔托找一家最好的寿司店，然后告诉我怎么去那里。”此流程分为两步：首先，找到餐厅；其次，获取路线。

ADK 提供了一种使用 SequentialAgent 来管理此问题的简洁而强大的方法。这是一种特殊的工作流代理，可按预定义的顺序执行一系列子代理。

神奇之处在于共享状态。序列中一个代理的输出可以自动保存到共享状态字典中，然后用作下一个代理的输入，从而无需使用复杂的手动代码在各个步骤之间传递信息。

➡️ 在笔记本中查找此信息的位置：

👉 这在第 2 部分（ADK 方式）：使用 SequentialAgent 实现多智能体混乱 🧠→⛓️→🤖 中有介绍。🌟

串行智能体

代理重构：在此部分的第一个代码单元中，请注意 foodie_agent 和 transportation_agent 的关键变化：
- foodie_agent 现在有了 output_key="destination"。这会告知 ADK 将其最终答案保存到共享状态中名为 destination 的变量中。
- transportation_agent 现在在其指令提示中包含占位符 {destination}。ADK 会自动将共享状态中的值注入此占位符。
定义工作流：find_and_navigate_agent 定义为 SequentialAgent，其 sub_agents 设置为 [foodie_agent, transportation_agent]，确保它们按该确切顺序运行。
简化执行：查看本部分中的 run_sequential_app 函数。复杂的 if/elif 逻辑已消失！现在，find_and_navigate_agent 被视为一个可调用的单元，ADK 会自动处理内部顺序步骤。

9. 第 7 阶段：LoopAgent 🔁

roadmap7

并非所有问题都能通过简单的一次性解决方案来解决。有时，我们需要提出解决方案、对其进行批判性评估，并对其进行改进，直到其满足特定限制条件。

为此，ADK 提供了 LoopAgent。此工作流代理会重复执行一系列子代理，直到满足特定条件为止。这非常适合构建能够规划、评判和改进自身工作的“完美主义者”代理。

该图显示了 Planner Agent 先创建方案。然后，我们输入 LoopAgent。Critic Agent 检查方案。如果存在缺陷，Refiner Agent 会创建新版本，然后循环重复。如果方案可行，Refiner Agent 会调用 exit_loop 工具，并返回经过验证的最终方案。

Loop Agent

➡️ 在笔记本中查找此信息的位置：

👉 这在使用 LoopAgent 迭代创意 🧠→🔁→🤖 中有说明。🌟

核心代理：工作流使用 planner_agent、critic_agent 和 refiner_agent。
循环定义：refinement_loop 定义为可协调 critic_agent、refiner_agent 和 sets max_iterations=3 的 LoopAgent。
退出条件：当 critic_agent 批准该方案时，循环终止，从而使 refiner_agent 调用自定义 exit_loop 工具。

10. 第 8 阶段：ParallelAgent ⚡️

roadmap8

效率至关重要。如果用户一次性请求多条不相关的信息，逐一运行这些搜索会很慢。

ParallelAgent 是解决方案。此工作流代理会并发执行一系列子代理。所有并行任务完成后，系统可以收集其结果，并将其合成到单个全面的回答中。

此图显示了 ParallelAgent 接受单个查询并将工作分叉为三个并发轨道。museum_finder、concert_finder 和 restaurant_finder 同时运行。当这三个代理都完成任务后，它们各自的结果（保存到共享状态）会联接在一起，并传递给最终的合成代理，该代理会将这些结果合并为一个答案。

➡️ 在笔记本中查找此信息的位置：

👉 此工作流在使用 ParallelAgent 实现并行电源 🧠→⚡️→🤖🤖🤖 部分中进行了详细介绍。🌟

并行代理

专家代理：定义了三个专家代理，每个代理都有一个唯一的 output_key（例如，museum_result）。
并行工作流：parallel_research_agent 定义为 ParallelAgent，其中列出了三个 finder 代理作为其 sub_agents。
合成步骤：在并行步骤之后，最终的 synthesis_agent 会使用占位符（{museum_result}、{concert_result} 等）从共享状态收集所有发现，以生成简洁的总结。

11. 附录：ADK Web - 🍎 适用于 Mac/Linux

roadmap9

本指南将引导您在本地机器上设置和运行 ADK Day Trip Planning Agent。

前提条件

Python 3.8 或更高版本
- Python 3.9 及更高版本：安装 google-adk==1.5.0（具有完整功能的最新版本）
- Python 3.8：安装 google-adk==0.3.0（兼容版本）
Google AI Studio API 密钥
互联网连接

第 1 步：克隆代码库

打开终端并运行：

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

第 2 步：设置虚拟环境并安装依赖项

方法 A：自动设置（推荐）

# Run the setup script
chmod +x setup_venv.sh
./setup_venv.sh

选项 B：手动设置

# Create virtual environment
python3 -m venv .adk_env

# Activate virtual environment
source .adk_env/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

第 3 步：🔥 重要提示 - 创建环境变量

⚠️ 请勿跳过此步骤！在 agent/ 目录中创建一个 .env 文件：

# Create the .env file
touch agent/.env

# Open it in your default text editor
open agent/.env

将以下代码行添加到文件中：

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 重要提示：请将 your_actual_api_key_here 替换为您的实际 API 密钥！

第 4 步：激活虚拟环境（如果尚未激活）

source .adk_env/bin/activate

您应该会在终端提示符的开头看到 (.adk_env)。

第 5 步：运行 ADK 网页界面

adk web

第 6 步：打开浏览器

打开浏览器并前往终端中显示的网址（通常为 http://localhost:8000）
在左上角的下拉菜单中，选择 agent
开始与您的当日游规划助理聊天！

您会看到如下对话： ADK Web 界面示例

停用环境

完成项目后：

deactivate

此命令在 Mac/Linux 和 Windows 上的运行方式相同。您会发现，终端提示中的 (.adk_env) 前缀消失了。

Mac 问题排查

未找到 Python：请使用 python3 而不是 python
权限被拒：在运行脚本之前，请先运行 chmod +x setup_venv.sh

12. 附录：ADK Web - 🪟 适用于 Windows 用户

roadmap9

本指南将引导您在本地机器上设置和运行 ADK Day Trip Planning Agent。

前提条件

Python 3.8 或更高版本
- Python 3.9 及更高版本：安装 google-adk==1.5.0（具有完整功能的最新版本）
- Python 3.8：安装 google-adk==0.3.0（兼容版本）
Google AI Studio API 密钥
互联网连接

第 1 步：克隆代码库

打开命令提示符或 PowerShell，然后运行以下命令：

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

第 2 步：设置虚拟环境并安装依赖项

方法 A：自动设置（推荐）

# Run the setup script in Command Prompt
setup_venv.bat

选项 B：手动设置

对于命令提示符：

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

对于 PowerShell：

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\Activate.ps1

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

第 3 步：🔥 重要提示 - 创建环境变量

⚠️ 请勿跳过此步骤！在 agent/ 目录中创建一个 .env 文件：

# Create the .env file
type nul > agent\.env

# Open it in Notepad
notepad agent\.env

将以下代码行添加到文件中：

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 重要提示：请将 your_actual_api_key_here 替换为您的实际 API 密钥！

第 4 步：激活虚拟环境（如果尚未激活）

命令提示符：

.adk_env\Scripts\activate

PowerShell：

.adk_env\Scripts\Activate.ps1

您应该会在提示开头看到 (.adk_env)。

第 5 步：运行 ADK 网页界面

adk web

第 6 步：打开浏览器

打开浏览器并前往终端中显示的网址（通常为 http://localhost:8000）
在左上角的下拉菜单中，选择 agent
开始与您的当日游规划助理聊天！

Windows 问题排查

PowerShell 执行政策错误：运行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

您会看到如下对话： ADK Web 界面示例

停用环境

完成项目后：

deactivate

此命令在 Mac/Linux 和 Windows 上的运行方式相同。您会发现，终端提示中的 (.adk_env) 前缀消失了。