ADK：从基础知识到多工具智能体

1. 简介

本 Codelab 从基础知识入手，逐步介绍如何开发多工具智能体，全面介绍了如何使用 ADK 构建智能体。

最简单来说，AI 智能体是一种软件系统，它使用大语言模型 (LLM) 作为“推理引擎”，通过自主执行一系列任务来实现目标。

如果说 LLM 是一位能够为您提供建议的高效顾问，那么 AI 智能体就是一位能够使用工具来执行这些建议的主动工程师。

LLM 与智能体

大脑 (LLM)：提供推理、规划和自然语言理解功能。它决定需要做什么。

双手（工具）：这些是 API、SDK 和自定义函数，可让智能体与现实世界互动。它执行计划。

智能体开发套件 (ADK)

智能体开发套件 (ADK) 是一种专门的框架，旨在简化 AI 智能体的创建、部署和编排。它提供了将静态大语言模型转换为动态智能体所需的标准化构建块，该智能体能够执行代码、调用 API 和管理多步骤工作流。

多工具智能体是一种编排器，可以选择和排序不同的专用功能（例如搜索引擎、数据库和计算器）来解决复杂问题。它会智能地确定每个步骤要使用的工具，并且可以将一个操作的输出作为下一个操作的输入，以实现最终目标。

构建内容

在本 Codelab 中，您将构建“健康提示”智能体，这是一款智能营养顾问，可从简单的文本推理过渡到多工具强力智能体。您将首先创建一个能够理解营养概念的基本对话智能体，然后逐步为其配备 Storage SDK 工具以归档成分图片，并配备 Vision 工具以“读取”和分析这些图片。在本实验结束时，您将拥有一个功能齐全的编排器，该编排器可以接收上传的食品标签照片，将其存储在云存储分区中以供记录，并立即为每种成分提供“健康提示”。

2. 前提条件

启用了结算功能的 Google Cloud 项目
网络浏览器

创建项目

在 Google Cloud 控制台的项目选择器页面上，选择或创建一个 Google Cloud 项目。
确保您的云项目已启用结算功能。了解如何检查项目是否已启用结算功能。

激活 Cloud Shell

您将使用 Cloud Shell，它是在 Google Cloud 控制台中运行的命令行环境，并且预加载了已安装的必需语言。在 Cloud 控制台中，点击右上角的激活 Cloud Shell ：

在连接到 Cloud Shell 后，您应该会看到自己已通过身份验证，并且相关项目已设置为您的项目 ID。在 Cloud Shell 中运行以下命令，以确认您已通过身份验证：

gcloud auth list

在 Cloud Shell 中运行以下命令，以确认 gcloud 命令了解您的项目：

gcloud config list project

如果项目未设置，请使用以下命令进行设置：

gcloud config set project <YOUR_PROJECT_ID>

如需了解 gcloud 命令和用法，请参阅文档。

打开编辑器

在本 Codelab 中，我们将使用内置的 Cloud 编辑器。在 Cloud Shell 窗口中，点击右上角的“打开编辑器”按钮。系统随即会为您打开 VSCode 编辑器。

3. ADK 设置

接下来，我们前往上一部分中激活的 Cloud Shell 终端：

创建并激活虚拟环境（推荐）

在 Cloud Shell 终端中，创建虚拟环境：

python -m venv .venv

激活虚拟环境：

source .venv/bin/activate

安装 ADK

pip install google-adk

4. Google API 密钥

使用 AI Studio 创建 Google API 密钥：

访问 https://aistudio.google.com/，然后在左下角菜单中，点击 Get API Key

您会看到“API 密钥”窗口，点击此窗口中的“创建 API 密钥”：

您会看到一个用于创建新密钥的弹出式窗口。将密钥命名为： healthy-hints-key

前往“选择导入的项目”下拉列表

点击 Import Project，系统会显示一个侧边窗口，其中列出了您的所有 Google Cloud 项目，选择您要使用的项目。

点击“导入”

下拉列表现在会更新为您刚刚导入的项目。从下拉列表中选择项目。点击“立即创建密钥”。您现在会看到已创建的 API 密钥列表。点击刚刚创建的 API 密钥的复制图标。

5. 示例智能体

在 Cloud Shell 终端中，在所需项目位置为智能体创建一个根目录：

adk create healthy_hints

您可以选择任何模型，但对于本 Codelab，我们将使用 gemini-2.5-flash

在本 Codelab 中，我们将使用 Google AI。粘贴您在上一步中创建的 API 密钥。

我们来打开刚刚创建的文件夹。在最左侧的菜单中，点击图标，然后依次点击“文件”->“打开文件夹”。选择刚刚创建的文件夹 healthy_hints，该文件夹通常位于 /home/<username> 文件夹中。
healthy_hints 文件夹结构通常如下所示：

您会看到一个 .env 文件，其中包含您的 Google API 密钥。您可以使用此文件设置任何环境变量。
系统还会创建另一个名为 agent.py 的文件，这是我们的主要智能体文件。您可以在此处创建示例根智能体。我们来仔细查看此文件的内容，首先从 ADK 导入 llm_agent。然后，我们使用 ADK DSL 创建根智能体。我们将模型名称指定为 Gemini-2.5-flash，为智能体命名，并提供简洁的说明。说明是这里最重要的内容，我们可以在其中以自然语言告知智能体需要做什么。
此示例智能体非常通用，它只会回答用户提出的任何问题。
现在，我们来在本地运行此智能体。您可以通过两种方式与此智能体互动：CLI 和 Web。
CLI：从 healthy_hints 目录外部运行以下命令

adk run healthy_hints

或者，如果您位于 healthy_hints 目录中，请运行以下命令：

adk run .

您会看到类似如下的输出：

继续输入“hi”或您提出的任何问题。对于每个人来说，答案可能有所不同，这就是 GenAI 的本质。

Web：从 healthy_hints 的父目录运行以下命令：

adk web

6. 多工具智能体

工具是一段模块化代码（通常是函数或 API），可让智能体与内部知识以外的世界互动。

ADK 中的工具类型

函数工具：您自己编写的自定义逻辑。例如，连接到特定数据库的函数，或针对您公司特有格式的自定义“日志解析器”。
内置工具：由 Google 或 ADK 提供的即用型功能，例如 Google 搜索、代码解释器或 Google RAG 引擎。
Agents-as-Tools:：在高级“多工具”或“多智能体”系统中，一个专用智能体可以充当另一个智能体的工具。例如，“搜索智能体”可以是“研究经理智能体”使用的工具。

在本 Codelab 中，我们将介绍函数工具。现在，我们来升级智能体，使其成为多工具智能体。

我们来在 get_weather 中添加一个新方法 agent.py

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

我们来修改 agent.py，并更改智能体的名称、说明和说明：

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

到目前为止，我们只创建了一个工具。现在，我们来创建多个工具：

我们来创建另一个名为 get_current_time 的方法：

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

我们来修改智能体，使其也能调用此工具：

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

我们已相应地修改了说明、说明和工具。现在，我们来运行此更新后的智能体。这一次，智能体还会回答当前时间和天气。

7. SDK 集成

现在，我们已经了解如何使用多个工具。我们来使用一些真实示例。我们来创建健康提示智能体。我们的目标是，将包含成分列表的任何图片上传到智能体，智能体将告知我们每种成分是否健康。

我们首先在 Google Cloud Storage 中创建一个存储分区，以上传图片。我们来打开一个新标签页，然后前往 https://console.cloud.google.com/，并在搜索栏中输入“Cloud Storage”。现在，在“产品和页面”下选择“Cloud Storage”：

系统会将您转到 Google Cloud Storage 的概览页面。点击 Create bucket 按钮。在“创建存储分区”页面中，输入存储分区的名称。名称可以是任何内容，但对于本 Codelab，我们将使用 healthy-hints-bucket-kolkata。将所有其他内容保留原样，然后点击 Create 按钮。

我们来创建一个名为 requirements.txt 的新文件，并在其中添加 google-cloud-storage。我们将使用 Python Storage SDK 在 Storage 中上传图片。

我们首先安装依赖项：

pip install -r requirements.txt

您可能需要先启用 Storage API。在终端中运行以下命令即可：

gcloud services enable storage.googleapis.com

现在，我们来添加一个新工具来上传图片。

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

现在，我们来更新智能体，使其使用新工具：

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

现在，我们来添加另一个工具，以从图片中读取成分。我们来在 requirements.txt 中添加 google-cloud-vision，并安装新的依赖项。

pip install -r requirements.txt

同样，您可能需要先启用 Vision API。在终端中运行以下命令即可：

gcloud services enable vision.googleapis.com

现在，我们来添加一个新工具 read_ingredients：

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

现在，我们来更新智能体以使用此工具

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

8. 总结

恭喜您完成健康提示 Codelab！您已成功将标准 AI 从文本生成工具转换为主动多工具智能体。通过使用 ADK 集成 Vision API 和 Cloud Storage SDK，您为智能体提供了“眼睛”来读取标签，并提供了“记忆”来归档标签。您已经了解了智能体如何自主决定何时保存文件，以及如何解读原始数据以提供现实世界的健康建议。

展望未来，这些原则将成为任何自动化系统的蓝图。无论您是管理云基础架构还是构建个人助理，核心内容都保持不变：定义专用工具，并让智能体编排逻辑。作为下一步，请尝试添加更多工具（例如“营养数据库”或“电子邮件工具”）来扩大智能体的影响力。