使用 ADK 和 Gemini CLI 建構簡單的旅遊代理

1. 簡介

9344c1d1a9f221b7.png

上次更新時間：2026 年 2 月 2 日

使用 ADK 建構簡單的旅遊代理

歡迎參加 ADK Python(*) 工作坊，透過 Gemini CLI，您將能輕鬆上手！

本程式碼研究室分為兩個里程碑：

  1. 常見的簡單學習路徑：設定 + 即時滿足。
  2. 個人化路徑：選擇要使用 Gemini CLI 解決的任務

第二部分則非常適合黑客松 (最富創意的解決方案還能獲得獎勵！)

里程碑 1：使用 ADK 和 Gemini CLI 建立第一個代理程式

這個里程碑的目標是逐步使用 ADK 建構簡單的旅行社代理。

為此，我們首先要設定 Gemini CLI，以便透過 ADK 協助我們編寫程式碼；這樣一來，本機殼層就能選取最新版本的 Python ADK、編寫程式碼和文件，並提供最新/最佳的程式碼，以達成目標。

這是手動引導的部分，我們會透過簡單的小增量，完成可正常運作的應用程式。這項作業通常需要約 一小時 (加上安裝時間)。

里程碑 2：擴充代理

接著，我們會提供十多種選項 (難度各異)，讓您隨心所欲擴充應用程式。您可以藉此探索不同層面 (UI、作業、複雜的代理程式互動等)。

建構項目

在本程式碼研究室中，您將使用 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)？原因在於這兩項工具都非常強大，但互動方式並非微不足道；許多人嘗試同時使用這兩項工具，但都失敗了 (主要是因為「迴圈中的迴圈」問題)。本程式碼研究室將分享幾項訣竅，協助您達成這項共存目標。

2. 開始設定

選擇下列其中一個選項：自行設定環境 (如要執行這項操作)

在自己的電腦上執行程式碼研究室，或啟動 Cloud Shell，完全在雲端執行程式碼研究室。

自行設定環境

  1. 登入 Google Cloud 控制台，然後建立新專案或重複使用現有專案。如果沒有 Gmail 或 Google Workspace 帳戶，請先建立帳戶。

295004821bab6a87.png

37d264871000675d.png

96d86d3d5655cdbe.png

  • 「專案名稱」是這個專案參與者的顯示名稱。這是 Google API 未使用的字元字串。你隨時可以更新。
  • 專案 ID 在所有 Google Cloud 專案中都是不重複的，而且設定後即無法變更。Cloud 控制台會自動產生專屬字串，通常您不需要在意該字串為何。在大多數程式碼研究室中，您需要參照專案 ID (通常標示為 PROJECT_ID)。如果您不喜歡產生的 ID，可以產生另一個隨機 ID。你也可以嘗試使用自己的名稱，看看是否可用。完成這個步驟後就無法變更，且專案期間會維持不變。
  • 請注意，有些 API 會使用第三個值，也就是「專案編號」。如要進一步瞭解這三種值，請參閱說明文件。
  1. 接著，您需要在 Cloud 控制台中啟用帳單，才能使用 Cloud 資源/API。完成這個程式碼研究室的費用不高，甚至可能完全免費。如要關閉資源，避免在本教學課程結束後繼續產生費用，您可以刪除建立的資源或專案。Google Cloud 新使用者可參加價值$300 美元的免費試用計畫。

啟動 Cloud Shell

雖然可以透過筆電遠端操作 Google Cloud，但在本程式碼研究室中，您將使用 Google Cloud Shell，這是可在雲端執行的指令列環境。

在 Google Cloud 控制台中，點選右上工具列的 Cloud Shell 圖示：

啟用 Cloud Shell

佈建並連線至環境的作業需要一些時間才能完成。完成後，您應該會看到如下的內容：

Google Cloud Shell 終端機的螢幕截圖，顯示環境已連線

這部虛擬機器搭載各種您需要的開發工具，並提供永久的 5GB 主目錄，而且在 Google Cloud 運作，能大幅提升網路效能並強化驗證功能。您可以在瀏覽器中完成本程式碼研究室的所有作業。您不需要安裝任何軟體。

必要條件 (安裝)

在本教學課程中，您需要安裝：

1. Python 和 uv

python 和 uv (Python 的套件管理工具)。這是 ADK 的必要資訊。確認已安裝 uv：

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

為什麼是 uv？雖然您可以使用偏好的 Python 管理工具，但使用 uv 可確保 Python 的 ENV/PATH 設定對您和 Gemini CLI 而言都相同，因此您的殼層體驗與 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 下載可執行檔

您也需要安裝 npx，才能完成後續步驟 4。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/ 下。您可以從該處複製代碼。

本程式碼研究室並非要教您如何編寫優質的 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 和網頁。

  • CLI 最適合快速和自動化測試
  • 網頁版最適合用來查看畫面、使用麥克風 (!) 及進行疑難排解。

提示：為完成本練習中的任何作業 (單元測試除外)，請使用 Web。這真的很棒！請將 CLI 僅用於自動化測試。

以下是可妥善測試步驟 1 到 4 的優質提示 (智慧「石蕊提示」)：

# <!– litmus prompt –> Hi, I'd like to book a hotel in Paris for tomorrow evening alone, one night, in Paris city center. 最好靠近里昂車站。預算：每晚 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)：<image here>

請注意，您需要從上層資料夾呼叫 adk web，並遵守 CLI 版本。

這裡提供可能的解決方法，但日期可能不正確。請注意，5 個預訂連結中有 3 個正常運作！還不錯。

4. 步驟 2：新增 now() 工具

服務專員不知道「今天」是哪一天，因此我們提供工具給他。

TODO(image)：ricc put here image of step2.

在 root_agent 定義前，將這個函式新增至 agent.py：

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) 的 Model-as-a-Tool 模式。

為了讓這個步驟著重於 MCP 的強大功能，我們將再次取代先前的工具 (google_search)。我們會重新推出簡單的 now 工具，與 airbnb_mcp 工具並行運作。這項範例說明 AI 代理如何使用多個相容工具 (本例中為 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 錯誤 (Airbnb 取得回應的時間過短，只有 5 秒)，請參閱 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 Agent Development Kit 建構自己的專屬代理了！

現在您已擁有可正常運作的旅遊服務專員，他知道時間並可搜尋網路。現在可以盡情發揮創意！

現在請使用「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. 🟢 [簡單] 變更提示，教導 AI 尋找或排除特定條件 (例如寵物友善、非一樓、安靜、鄰近大眾運輸等)，然後進行測試。您可以根據上述內容新增個人評分，例如「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. 🟡 [medium] Create a subagent who does the HotelSearch and create a BudgetAgent or a LocationAgent which can double down and iterate over hotels respecting your location needs, eg "not more than X km from LOCATION". 如果 API 不允許，Google 搜尋可能會提供一些來回協助。注意：Gemini CLI 可以提供協助。
  7. 🟡 [medium] Implement a AirbnbReviewAgent which goes into the reviews and summarize positives and negatives in a few color-coded bullets, for 1 or N hotels reslting from a search. 您已經有 2 項要素 (Google 搜尋和 MCP Airbnb)，接著需要將這兩項要素連結至主要代理程式，並發明某種通訊協定，讓兩者可以溝通。
  8. 🟡 [medium] Integrate with A2A. 將其設為 A2A 代理！再次請 Gemini CLI 幫忙！
  9. 🔴 [複雜] 您可以整合 Flights 或其他 MCP 功能，建立多面向的多功能旅遊代理。
  10. 🔴 [complex] Integrate ADK web with 🍌 NanoBanana MCP. 這比上述練習更難，您可以在 https://github.com/palladius/ai-friendly-agents/issues/11 找到一些提示。作者與 Gemini CLI 和 Gemini 3 來回溝通，並與我一起閱讀 rag/ 中的文件/程式碼，總共花了 3 個小時！

需要更多靈感嗎？

  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」的先決條件

如要以 Vibe 程式碼編寫功能，建議您下載整個 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