使用 ADK 和 Gemini CLI 构建简单的旅游代理

1. 简介

9344c1d1a9f221b7.png

上次更新时间：2026-02-02

使用 ADK 构建简单的旅行代理

欢迎参加本次 ADK Python(*) 研讨会，借助 Gemini CLI，您可以立即开始使用！

此 Codelab 分为两个 🏅 里程碑：

  1. 一种常见且简单的学习途径：设置 + 即时满足。
  2. 个性化学习路线，您可选择一个任务，在 Gemini CLI 的帮助下完成该任务

第二部分让此 Codelab 非常适合黑客马拉松（最具创意的解决方案还有奖品！）

里程碑 1：使用 ADK 和 Gemini CLI 构建您的第一个代理

此里程碑的目标是使用 ADK 逐步构建一个简单的旅行代理。

为此，我们首先要设置 Gemini CLI，以便它帮助我们使用 ADK 进行编码；这样一来，您的本地 shell 就能选择最新版本的 Python ADK，并根据您的目标提供最新/最佳代码来处理代码和文档。

这是一个手动引导的部分，我们将通过简单的小增量实现一个功能齐全的应用。此过程通常需要大约 1 小时（外加安装时间）。

里程碑 2：扩展智能体

之后，我们会提供十几种选项（难度各不相同），让您根据自己的喜好扩展应用。这样，您就可以探索不同的方面（界面、运营、复杂的代理互动等）

构建内容

在此 Codelab 中，您将使用 ADK 和 Gemini CLI 构建一个旅行助理应用。您的应用将：

  • 通过 Airbnb MCP 连接到 Airbnb API。
  • 在线搜索最新信息（天气、日期等）
  • 执行自定义工具。
  • 使用 NanoBanana 创建公寓/房间的图片。

Gemini CLI 将引导您完成所有这些操作：在 ADK 代码库的本地镜像中（以 Python 或您喜爱的语言）编写/检查代码并查找最新文档。

学习内容

  • 如何使用 ADK 创建应用
  • 如何使用 Gemini CLI 基于本地文档编写应用代码！
  • 如何与 MCP 服务器互动以连接到实时外部数据源，例如：

所需条件

  • 允许您安装软件包（例如 npm install ..）的计算机
  • 具备 Python、TypeScript、Go、Java 的基本编码能力。
  • 强烈建议使用某种 IDE（Antigravity、vscode、IntelliJ、vim）。

为什么选择 ADK + Gemini CLI？

有些用户可能会有疑问：为什么需要将 ADK（代理构建器 SDK）与本地代理代码助手（例如 Gemini CLI）搭配使用？原因是，这两款工具都非常强大，但它们的互动并非微不足道；许多人曾尝试同时使用这两款工具，但都失败了（主要是由于“循环中的循环”问题）。此 Codelab 旨在分享一些技巧，帮助您实现这种共存。

2. 准备工作

选择以下选项之一：如果您想运行此

在您自己的机器上完成此 Codelab，或者；如果您想完全在云端完成此 Codelab，请启动 Cloud Shell。

自定进度的环境设置

  1. 登录 Google Cloud 控制台，然后创建一个新项目或重复使用现有项目。如果您还没有 Gmail 或 Google Workspace 账号，则必须创建一个。

295004821bab6a87.png

37d264871000675d.png

96d86d3d5655cdbe.png

  • 项目名称是此项目参与者的显示名称。它是 Google API 尚未使用的字符串。您可以随时对其进行更新。
  • 项目 ID 在所有 Google Cloud 项目中是唯一的，并且是不可变的（一经设置便无法更改）。Cloud 控制台会自动生成一个唯一字符串；通常情况下，您无需关注该字符串。在大多数 Codelab 中，您都需要引用项目 ID（通常用 PROJECT_ID 标识）。如果您不喜欢生成的 ID，可以再随机生成一个 ID。或者，您也可以尝试自己的项目 ID，看看是否可用。完成此步骤后便无法更改该 ID，并且此 ID 在项目期间会一直保留。
  • 此外，还有第三个值，即部分 API 使用的项目编号，供您参考。如需详细了解所有这三个值，请参阅文档。
  1. 接下来，您需要在 Cloud 控制台中启用结算功能，以便使用 Cloud 资源/API。运行此 Codelab 应该不会产生太多的费用（如果有的话）。若要关闭资源以避免产生超出本教程范围的结算费用，您可以删除自己创建的资源或删除项目。Google Cloud 新用户符合参与 300 美元免费试用计划的条件。

启动 Cloud Shell

虽然可以通过笔记本电脑对 Google Cloud 进行远程操作，但在此 Codelab 中，您将使用 Google Cloud Shell，这是一个在云端运行的命令行环境。

在 Google Cloud 控制台 中，点击右上角工具栏中的 Cloud Shell 图标：

激活 Cloud Shell

预配和连接到环境应该只需要片刻时间。完成后，您应该会看到如下内容：

Google Cloud Shell 终端的屏幕截图，显示环境已连接

这个虚拟机已加载了您需要的所有开发工具。它提供了一个持久的 5 GB 主目录，并且在 Google Cloud 中运行，大大增强了网络性能和身份验证功能。您在此 Codelab 中的所有工作都可以在浏览器中完成。您无需安装任何程序。

前提条件（安装）

在本教程中，您需要安装：

1. Python 和 uv

python 和 uv（Python 的软件包管理器）。ADK 需要此权限。确保您已安装 uv：

$ curl -LsSf https://astral.sh/uv/install.sh | sh

为什么是紫外线？虽然您可以使用自己喜欢的任何 Python 管理器，但使用 uv 可确保您和 Gemini CLI 的 Python ENV/PATH 设置相同，因此您的 shell 体验将与 Gemini CLI 的基本相同。如果您使用 virtualenv，Gemini CLI 将被迫执行“source .env/venv/bin/activate && my-original-command”等操作来模拟您的环境。

2. Gemini CLI

如需了解 gemini CLI 的安装说明，请访问：https://github.com/google-gemini/gemini-cli。

注意：这需要安装 npm 或 npx。

npm install -g @google/gemini-cli

  1. 在 Mac 上，您可以按照官方文档使用 brew。
  2. 在 Windows 上，您可以使用 chocolatey，也可以直接从 https://nodejs.org/en/download 下载可执行文件

对于第 4 步（稍后），您还需要安装 npx。npm 和 npx 都应自然而然地成为 Gemini CLI 的一部分。如果不是，请让 Gemini CLI 在此处为您提供帮助。

您也可以选择安装 just，它是一个更高级且可自我记录的 Makefile。您还可以让 Gemini CLI 帮助您安装此工具，它会为您完成安装！

efade99623113f1.png

身份验证。

您需要拥有一个启用了 Vertex AI 的 Google Cloud 项目，或者拥有一个 Google AI Studio API 密钥。

选项 A（建议在研讨会中使用）：导出您的 API 密钥：

export GOOGLE_API_KEY="your-api-key"

选项 B (Vertex AI)：使用 gcloud 进行身份验证：

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
export GOOGLE_GENAI_USE_VERTEXAI=true
gcloud auth application-default login

设置工作环境

您将在 mysolution/ 下创建自己的解决方案，因此我们来创建所需的文件夹和两个文件。

现在，您可以打开 IDE（Visual Studio Code、IntelliJ、RubyMine 等）并打开该文件夹。

# 1. Find an empty directory, and download this repo.
git clone https://github.com/palladius/ai-friendly-agents/
cd ai-friendly-agents/adk/workshops/simple-travel-agent/

# 2. Create your solution empty skeleton
mkdir -p mysolution/
touch mysolution/__init__.py mysolution/agent.py

# 3. This installs ADK and MCP via `uv` by reading pyproject.toml
uv sync

# 4. Call Gemini CLI
gemini  # This runs Gemini CLI under the simple-travel-agent/ folder.
# Login with your GMail account.

uv sync 不是严格必需的，但如果失败，则表示您需要修复 Python 或 uv 安装。

可用的解决方案

所有代码都包含在 📂 steps/ 下。您可以随意复制其中的代码。

此 Codelab 并非旨在学习如何编写优质的 ADK 代码，而是旨在设置环境，以便在您的指导下自动生成优质代码。

  1. 安装软件
  2. 配置 / 使其正常运行，以及
  3. 进入良性反馈循环

这才是我们真正希望您在此处学到的内容。您还可以通过 $ just web-4steps 同时测试所有这些功能！

3. 第 1 步：基本代理

abfef47ab2ff0c98.png

我们先来创建一个可以进行对话的基本代理。

修改名为 mysolution/__init__.py 的文件，添加以下内容：

from .agent import root_agent

就是这么简单！这样，ADK 就能知道您的代码位于 agent.py 中。

修改名为 mysolution/agent.py 的文件，添加以下内容：

from google.adk.agents import Agent

root_agent = Agent(
    name="travel_basic",
    model="gemini-2.5-flash",
    instruction="You are a helpful travel assistant." +
    "You can help with general travel advice based on your knowledge.",
)

测试代理

所有步骤都是如此。ADK 允许您通过两种方式测试智能体：CLI 和 Web。

  • CLI 最适合快速测试和自动化测试
  • 网页版最适合直观地了解情况、使用麦克风 (!) 和进行问题排查。

提示：在本练习中，为了完成任何任务（单元测试除外），请使用 Web。这真是太棒了！仅将 CLI 用于自动化测试。

一个能妥善测试步骤 1-2-3-4 的优质提示可以是以下内容（智能“石蕊提示”）：

# <!– litmus prompt –> 你好，我想预订巴黎市中心明天晚上的酒店，一晚。最好靠近里昂火车站。预算：每晚低于 200 欧元。

  1. 告诉我明天的 YYYYMMDD 和星期几。
  2. 告诉我您看到了哪些酒店（至少 3 家）的明日价格。我想看到：> 价格、地址、部分评分（以 XX/YY 的形式，例如“4.7/5” - 来自 Google 酒店、Booking 或 Airbnb）、评价数量。请以表格格式提供这些信息。理想情况下，酒店名称应与酒店的某种网址相关联（无需添加网址列）。确保链接有效（可正常使用且指向酒店信息页面）

这是一个智能提示，因为它会测试时间和酒店，并且在第 1、2、3 步中会以不同的方式失败，只有在第 4 步中才会完全成功。当然，您可以使用任何想要的提示！

从 bash (CLI) 运行：

# 1. If ADK was installed:
adk run mysolution/
# ... but if you get: -bash: adk: command not found"
# 2. Call ADK cli script through UV to avoid python install nightmares.
uv run adk run mysolution/

不妨尝试使用上文中的“试金石提示”。

它很可能无法知道具体日期。我们需要教它识别日期！

对于网页，您可以执行以下操作：

  1. uv run adk web .：运行相应文件夹下的所有代理。您希望将其指向“mysolution/”子文件夹
  2. 选择右上角的 mysolution/（请参见旁边的图片）
  3. 以文字或通过麦克风提出问题，问题内容应与“试纸提示”类似。

TODO(ricc)：<此处为图片>

请注意，您需要根据 CLI 版本从上层文件夹调用 adk web。

以下是一种可能的解决方案，其中包含日期半幻觉。注意：5 个预订链接中有 3 个可正常使用！不错。

4. 第 2 步：添加 now() 工具

代理不知道“今天”是哪一天。我们为它提供一个工具。

TODO(image)：ricc 在此处放置第 2 步的图片。

将此函数添加到 agent.py 中，紧邻 root_agent 定义之前：

from datetime import datetime

def now() -> dict:
    """Returns the current date and time."""
    my_datetime = ... # Ask Gemini CLI to help you!
    return {
        "status": "success",
        "current_time": my_datetime
    }

更新代理定义以包含该工具：

  # file XXX.py

  travel_agent = LlmAgent(
        name="..",
        model="..",
        instruction="..",
        tools=[now] # <== This is the only line you want to add.
    )

再次运行该应用，并提出相同的问题。现在，它应该知道日期（好），但对酒店一无所知（不好）！

您还可以使用类似如下的代码进行测试：

# Let's pretend we're in Milan. This should call the tool
# and respond correctly (possibly with some TZ math issues)

echo "What time is it in Milan?" | uv run adk run mysolution/

5. 第 3 步：让我们换个话题：google_search

现在，我们已经了解了如何创建自定义工具，接下来我们来探索如何使用 ADK 提供的一款强大的内置工具：google_search。这样一来，我们的代理就可以访问网络上的实时信息。

3cd72c019b8b225f.png

您的任务是修改第 2 步中的代理。您将从 ADK 库中导入并使用 google_search 工具，而不是使用 now 工具。

# Full Code: `steps/step03_search/agent.py`
# Remember to REMOVE the now() tool here. See above why.
from google.adk.agents import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name="travel_agent",
    model="gemini-2.5-flash",
    tools=[google_search],
    instruction="""You are a travel agent.
Your job is to help the user plan a trip.
You have access to a search engine.
If you don't know the answer, you can use the search engine.
When you are done, reply with "DONE".""",
)

如何跑步

与第 1 步相同。

仅限专家。如需更高级的集成（同时使用 google_search 和 now），请检查 steps/step03b_search_and_tool/agent.py 中的代码并使用 just run-step3b 运行该代码。这完全是可选的。

6. 第 4 步：更复杂的工具：MCP

TODO(ricc)：添加图片 4

现在，我们已经了解了自定义工具和内置工具，接下来让我们学习更强大的工具：使用 Model Context Protocol (MCP) 的模型即工具模式。

为了让此步骤侧重于 MCP 的强大功能，我们将再次替换之前的工具 (google_search)。我们将重新引入简单的 now 工具，使其与 airbnb_mcp 工具一起运行。此示例演示了代理如何使用多个兼容的工具（在本例中为 FunctionTool 和 MCPToolset）来执行复杂的任务。

# Full Code: steps/step04_mcp/agent.py
# ... Imports as before
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

def now() -> dict:
    # ... as before

# Configure the Airbnb MCP Toolset
airbnb_mcp = MCPToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(
            command='npx',
            args=["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"],
        ),
    )
)

root_agent = Agent(
    name="travel_mcp",
    model="gemini-2.5-flash",
    instruction="You are a helpful travel assistant. You can find accommodation using Airbnb, and have access to the current time.",
    tools=[now, airbnb_mcp],
)

如何跑步

此步骤要求在您的系统上安装 npx。其余部分与上述内容相同。

注意事项/ 错误

  1. 如果您收到 robots.txt 限制错误，可以使用忽略 robots 指令修补 MCP。如需了解更多详情，请参阅文档：https://github.com/openbnb-org/mcp-server-airbnb
  2. 如果您收到 timeout 错误（5 秒对于 Airbnb 获取响应来说太短），请查看 ADK 文档，了解如何将超时时间增加到 30 秒（例如）。或者，使用 Gemini CLI 来完成此操作！请注意，在 3dec25m 上，Cloud Shell 给了我一个超时错误，我修复了该超时错误，但仍然收到错误，直到我强制将其恢复到之前的版本：args=["-y", "@openbnb/mcp-server-airbnb@0.1.2", "--ignore-robots-txt"]。

7. 🏅 里程碑 1 已完成！

🏅 恭喜！🏅 您现在是 ADK 专家了！您已完成研讨会的第一部分，并成功构建和测试了使用自定义工具、内置工具和高级 MCP 工具的 AI 智能体。现在，您可以使用 Google 智能体开发套件构建自己的出色智能体了！

现在，您拥有了一个功能齐全的旅行助理，它知道时间并且可以搜索网络。现在，天空才是极限！

现在，您可以使用“Gemini CLI”添加其他功能了。

8. 🏅 里程碑 2：通过 Gemini CLI 随心所欲地进行 ADK 氛围编程

现在，我们进入讲座的有趣部分。

  1. 确保您已将代码git commit在安全的地方。您可以派生原始代码，也可以创建分支：别担心，Gemini CLI 在这方面非常擅长！
  2. 寻找要实现的 💡 创意。您可以查看以下想法，自行寻找一个，也可以让 Gemini 查看 rag/ 中的文档并提出一些智能想法。
  3. 请先满足前提条件，确保 Gemini 可以读取 ADK 文档，然后就可以开始使用了！

💡 创意

以下菜单包含了一些不同复杂程度的创意。

  1. 🟢 [简单] 您是语言通才吗？您想赠送 go、java还是 Typescript？重构现有代码非常简单！只需确保下载合适的 ADK，然后让 Gemini CLI 执行翻译即可！
  2. 🟢 [简单] 添加表情符号或指定您喜欢的某种输出格式（例如，包含酒店表情符号的表格，后跟价格，再后跟 1-5 星表情符号，其中还可以使用 🌕🌕🌕🌗🌑 来表示半星！）。
  3. 🟢 [简单] 更改提示，让模型了解您具体需要或不需要的条件（宠物友好型、非一楼、安静、靠近公共交通工具等），然后进行测试。也许可以根据上述内容添加个人评分（例如“YOUR_NAME 的评分，范围为 1-10”），并按该评分进行排序。
  4. 🟢 [简单] 聊天室中有任何客服人员吗？部署到 Cloud Run！或者 Vertex AI Agent Engine！您是否知道，您可以集成此代理，并直接从新的 Gemini Enterprise 调用它？
  5. 🟢 [简单] 将 `adk run` 与 🍌 NanoBanana MCP 集成。需要 Gemini API 密钥。您可以在此处创建图片，但无法直观呈现图片。如需难度更高的变体，请参阅下文。
  6. 🟡 [中等] 创建一个执行 HotelSearch 的子代理，并创建一个 BudgetAgent 或 LocationAgent，该子代理可以加倍努力并迭代酒店，同时满足您的位置需求，例如“距离 LOCATION 不超过 X 公里”。如果 API 不允许这样做，GoogleSearch 可能会提供一些来回帮助。注意：Gemini CLI 可以为您提供帮助。
  7. 🟡 [中] 实现一个 AirbnbReviewAgent，用于查看评价并以几个彩色编码的要点总结正面和负面评价，适用于搜索结果中的 1 家或 N 家酒店。您已经有 2 种成分（GoogleSearch 和 MCP Airbnb），然后需要将它们连接到主代理，并可能发明某种协议供它们进行通信。
  8. 🟡 [中] 与 A2A 集成。将其设为 A2A 代理！再次向 Gemini CLI 寻求帮助！
  9. 🔴 [复杂] 您可以与 Flights 或其他 MCP 功能集成，以创建多方面多功能的旅行代理。
  10. 🔴 [复杂] 将 ADK Web 与 🍌 NanoBanana MCP 集成。这比上面的方法更难，您可以在 https://github.com/palladius/ai-friendly-agents/issues/11 中找到一些提示。作者花了 3 个小时与 Gemini CLI、Gemini3 来回沟通，我们两人都阅读了 rag/ 中的文档/代码！

想寻找更多灵感？

  1. 您可以查看 Maurizio 的精彩 ADK 教程，获取一些灵感。
  2. 让 Gemini CLI 通过查看 rag/ 下的文档来寻找创意：可能的提示可能是 Is there a feature in here which seems very succulent to you? Give me 3 proposals and let's implement together the one I choose。

ADK“RAG”的前提条件

如需通过振动编码实现某项功能，我们建议您下载整个 ADK Python ADK（注意：这可以非常轻松地适应您喜欢的语言，例如 Java 或 Go！）。

代码位于 ./rag 下，可使用 ./download-adk.sh 下载。

由于 rag 文件夹已在 .gitignore 文件中列出，请确保您的 .gemini/settings.json 包含以下内容：

{
 "context": {
   "includeDirectories": ["rag"]
 }
}

为什么？我们希望 Gemini 能够读取这些文件，同时确保这些文件被安全地忽略。从技术上讲，您还可以通过将 context.fileFiltering.respectGitIgnore 设置为 false 来取消隐藏所有 .gitignore 文件，但这会产生大量 node_modules/ 和 __pycache__/ 垃圾内容，因此显式包含文件夹是首选选项。

9. 后续步骤

好奇心：本讲座是在 Gemini CLI 的帮助下构建的。如果您有兴趣，可以查看此文件夹中的 GEMINI.md 和 WORKSHOP_PLAN.md，了解我是如何做到的。

经验教训

我们已了解如何将 ADK 与 Gemini CLI 配对

其他读物

6d05afb6b8b235d8.png