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

1. 简介

上次更新时间：2026 年 6 月 22 日

使用 ADK 构建简单的旅行智能体

欢迎参加本次 ADK Python(*) 研讨会，得益于 Gemini CLI，本次研讨会提供了开箱即用的完整体验！

此 Codelab 分为两个 🏅 里程碑：

1. 常见、简单的学习路线：设置 + 即时满足。
2. 个性化路径，您可以在 Gemini CLI 的协助下选择要解决的任务

第二部分非常适合黑客马拉松（最具创意的解决方案将获得奖品！）

里程碑 1：使用 ADK 和 Gemini CLI 构建您的首个智能体

此里程碑的目标是使用 ADK 逐步构建一个简单的旅行智能体。为此，我们首先要设置 Gemini CLI，以便它帮助我们使用 ADK 编写代码；这样，您的本地 shell 就能选择最新版本的 Python ADK，理解代码和文档，并提供最新/最适合的代码来帮助您实现目标。

这是一个手动引导部分，我们将通过简单的小幅增量，实现一个功能齐全的应用。此过程通常需要一小时左右（不包括安装时间）。

注意 (*)：虽然此 Codelab 假定您使用的是 Python ADK，但实际上，您只需稍作改动，即可使用 Go、Java 或 TypeScript 来完成此 Codelab！事实上，如果您之前只用 Python 编写过 ADK，那么此 Codelab 是一个绝佳的机会，让您尝试使用其他语言来完成这一过程。请通过下方的反馈链接告诉我们您的想法！

里程碑 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 账号，则必须创建一个。

• 项目名称是此项目参与者的显示名称。它是 Google API 尚未使用的字符串。您可以随时对其进行更新。
• 项目 ID 在所有 Google Cloud 项目中是唯一的，并且是不可变的（一经设置便无法更改）。Cloud 控制台会自动生成一个唯一字符串；通常情况下，您无需关注该字符串。在大多数 Codelab 中，您都需要引用项目 ID（通常用 PROJECT_ID 标识）。如果您不喜欢生成的 ID，可以再随机生成一个 ID。或者，您也可以尝试自己的项目 ID，看看是否可用。完成此步骤后便无法更改该 ID，并且此 ID 在项目期间会一直保留。
• 此外，还有第三个值，即部分 API 使用的项目编号，供您参考。如需详细了解所有这三个值，请参阅文档。

注意：项目 ID 具有全局唯一性，您选择它后，其他任何人都不能再使用。您是此 ID 的唯一用户。即使项目被删除，相应 ID 也无法再次使用

注意：如果您使用的是 Gmail 账号，可以将默认位置设置为无组织。如果您使用的是 Google Workspace 账号，请选择对贵组织来说合理的位置。

2. 接下来，您需要在 Cloud 控制台中启用结算功能，以便使用 Cloud 资源/API。运行此 Codelab 应该不会产生太多的费用（如果有的话）。若要关闭资源以避免产生超出本教程范围的结算费用，您可以删除自己创建的资源或删除项目。Google Cloud 新用户符合参与 300 美元免费试用计划的条件。

启动 Cloud Shell

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

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

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

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

3. 前提条件（安装）

注意：如果您决定在 Cloud Shell 中运行此 Codelab，系统会为您预安装 Python、uv 和 Gemini CLI (gemini)。

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

1. Python 和 uv

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

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

为什么选择 uv？虽然您可以使用任何您喜欢的 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。

# Note: This requires having npm or npx installed.
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 在这里为您提供帮助。

Authentication

您需要一个已启用 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/adk-gemini-cli-workshop
cd adk-gemini-cli-workshop/

# 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 init
uv sync

# 4. Call Gemini CLI
gemini  # This runs Gemini CLI under the adk-gemini-cli-workshop/ folder.
# Login with your GMail account.

uv sync 并非严格必需，但如果它失败，您就知道需要修复 Python 或 uv 安装。这应该会将 adk 和其他实用脚本安装到 ./.venv/bin/ 文件夹中。

如需测试您的设置，只需运行 make test-step1 并检查是否未收到 403 PERMISSION DENIED. 即可

重要提示。确保您在 📁 adk-gemini-cli-workshop/ 文件夹中运行 Gemini CLI。IDE 也会将其显示为根名称。这样可以确保 Gemini CLI 采用正确的配置。您随时可以通过 /dir add /your/other/folder 添加外部文件夹，但 📁 adk-gemini-cli-workshop/ 是最佳初始位置。

可用的解决方案

代码全部包含在 📂 steps/ 下。您可以随意从该处复制代码。

本 Codelab 的目的不是学习如何编写优质 ADK 代码，而是设置环境，以便在您的指导下自动编写优质代码。

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

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

4. 第 1 步：基本代理

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

通过添加以下内容来修改名为 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 最适合直观地查看正在发生的情况、使用麦克风 (!) 以及进行问题排查。

提示：在本练习中，除了单元测试之外，其他所有操作都需要使用 Web。太棒了！仅将 CLI 用于自动化测试。

一个能够正确测试步骤 1-2-3-4 的好提示可以是这样的（智能“试金石提示”）：

您好，我想预订明天晚上在巴黎市中心的一家酒店，入住一晚，只有我一个人。最好靠近里昂火车站。预算：每晚 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/

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

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

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

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

请注意，您需要从上层文件夹调用 adk web，具体取决于 CLI 版本。

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

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

将此函数添加到 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

  root_agent = Agent(
        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/

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

google_search。这样，我们的智能体就可以访问来自网络的实时信息。

注意：🚨 gemini-2.x 模型无法原生混合使用 Google 搜索和自定义工具（请参阅问题 #969），因此为简单起见，我们将用 google_search 替换 now()。如需了解详情，请参阅 ISSUES.md。

您的任务是修改第 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 中的代码，并使用 make run-step3b 运行该代码。这完全是可选的。

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

现在，我们已经了解了自定义工具和内置工具，接下来让我们学习更强大的功能：使用 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 限制错误，可以使用 ignore 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"]。

8. 🏅 里程碑 1 已完成！

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

现在，您已经拥有了一个功能齐全的旅行代理，它不仅知道时间，还能在网上搜索信息。一切皆有可能！

现在，我们来使用“Gemini CLI”添加一项新功能。

9. 🏅 里程碑 2：通过 Gemini CLI 使用 ADK 进行氛围编程

现在，我们进入了研讨会的有趣部分。

1. 请确保您已将该代码git commit在安全的地方。您可以对原始代码进行分叉，也可以创建分支：别担心，Gemini CLI 在这方面可以为您提供很大帮助！
2. 寻找要实施的💡创意。您可以查看以下创意，自行寻找一个创意，或问问 Gemini 查看 rag/ 中的文档并提出一些巧妙的创意。
3. 请按照前提条件操作，确保 Gemini 可以读取 ADK 文档，然后就可以开始使用了！

💡 创意

1. 🟢 [easy] Are you a language polyglot? 您想提供 go、java 还是 TypeScript？重构现有代码非常简单！只需确保下载正确的 ADK，并让 Gemini CLI 执行转换即可！
2. 🟢 [简单] 添加表情符号或指定您喜欢的输出格式（例如，一个表格，其中包含酒店表情符号，后跟价格，再后跟 1-5 星表情符号，使用 🌕🌕🌕🌗🌑 表示半星！）。
3. 🟢 [简单] 更改提示，让它了解您特别想要或不想要的东西（宠物友好、非一楼、安静、靠近公共交通等），然后进行测试。也许可以根据上述内容添加个人评分，例如“YOUR_NAME 评分（1-10 分）”，并按该评分排序。
4. 🟢 [easy] Any Operator in the room? 部署到 Cloud Run！或者 Vertex AI Agent Engine！您知道吗？您可以集成此智能体，并直接从新的 Gemini Enterprise 中调用它。
5. 🟢 [简单] 将 adk run 与 🍌 NanoBanana MCP 集成。需要 Gemini API 密钥。在这里，您可以创建图片，但无法直观呈现。请参阅下文，了解难度更高的变体。
6. 🟡 [中] 创建一个执行 HotelSearch 的子代理，并创建一个 BudgetAgent 或 LocationAgent，以便根据您的位置需求（例如“距离 LOCATION 不超过 X 公里”）进一步筛选和迭代酒店。如果 API 不允许这样做，则可能需要通过 Google 搜索进行一些来回交互。注意：Gemini CLI 可以为您提供帮助。
7. 🟡 [中] 实现一个 AirbnbReviewAgent，用于深入分析评价，并以几个颜色编码的要点总结正面和负面评价，针对搜索结果中的 1 家或 N 家酒店。您已经有了 2 个组件（GoogleSearch 和 MCP Airbnb），接下来需要将它们连接到主智能体，并可能需要设计某种协议来让它们进行通信。
8. 🟡 [中] 与 A2A 集成。让它成为 A2A 智能体！同样，问问 Gemini CLI 寻求帮助！
9. 🔴 [复杂] 您可以与航班或其他 MCP 功能集成，打造一个多功能、多维度的旅行智能体。
10. 🔴 [复杂] 将 ADK Web 与 🍌 NanoBanana MCP 集成。这比上面的任务更难，您可以在 https://github.com/palladius/ai-friendly-agents/issues/11 中找到一些提示。作者花了 3 个小时与 Gemini CLI、Gemini 3 反复沟通，并且我们双方都阅读了 rag/ 中的文档/代码，才完成了这项工作！

想寻找更多灵感？

1. 请参阅官方 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”的前提条件

如需通过 Vibe Coding 实现某项功能，我们建议您下载整个 Python ADK（注意：您可以轻松将其调整为您喜欢的语言，例如 Java 或 Go！）

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

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

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

为什么？我们希望 Gemini 能够读取这些文件，同时确保它们被安全地 git-ignored。从技术上讲，您也可以通过将 context.fileFiltering.respectGitIgnore 设置为 false 来取消隐藏所有 .gitignore 文件，但这会打开大量 node_modules/ 和 __pycache__/ 垃圾文件，因此首选方法是明确包含文件夹。

10. 后续步骤

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

经验教训

我们已经学习了如何将 ADK 与 Gemini CLI 搭配使用

附加阅读材料

• 请查看以下两个官方 Antigravity Codelab：
  • Google Antigravity 使用入门
  • 使用 Google Antigravity 进行构建
  • 使用 Antigravity 在 Google Cloud 上构建和部署
• 请参阅官方 ADK 教程，了解一些创意。