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

1. 簡介

上次更新時間：2026 年 6 月 22 日

使用 ADK 建構簡單的旅行社

歡迎參加這場 ADK Python(*) 工作坊，Gemini CLI 將提供您所需的一切資源！

本程式碼實驗室分為兩個 🏅 里程碑：

1. 常見且簡單的學習路徑：設定 + 立即獲得滿足感。
2. 個人化路徑：選擇要透過 Gemini CLI 解決的任務

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

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

這個里程碑的目標是使用 ADK 逐步建構簡單的旅行社。首先，我們要設定 Gemini CLI，以便使用 ADK 編寫程式碼。這樣一來，本機殼層就能選取最新版本的 Python ADK、解讀程式碼和文件，並提供最新/最佳程式碼，協助您達成目標。

在這個部分，我們會逐步引導您，透過簡單的小步驟，完成一個功能完整的應用程式。這項作業通常需要一小時左右 (不含安裝時間)。

注意 (*)：雖然程式碼實驗室假設您使用的是 Python ADK，但實際上您也可以使用 Go、Java 或 TypeScript，只需稍作修改即可！事實上，如果您只用 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、VS Code、IntelliJ、Vim)。

為什麼要使用 ADK + Gemini CLI？

您可能會想：為什麼需要搭配使用 ADK (代理建構工具 SDK) 和本機代理式程式碼輔助工具 (例如 Gemini CLI)？這是因為這兩項工具都非常強大，但兩者之間的互動並非易事；許多人曾嘗試同時使用這兩項工具，但都失敗了 (主要是因為「迴圈中的迴圈」問題)。本程式碼實驗室將分享一些訣竅，說明如何讓兩者並存。

2. 開始設定

選擇下列其中一個選項：如要在自己的機器上執行這個程式碼實驗室，請選取「Self-paced environment setup」；如要完全在雲端執行這個程式碼實驗室，請選取「Start Cloud Shell」。

自修實驗室環境設定

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

• 「專案名稱」是專案參與者的顯示名稱。這是一串 Google API 無法識別的字元。你隨時可以更新。
• 專案 ID 在所有 Google Cloud 專案中都是不重複的，且設定後即無法變更。Cloud 控制台會自動產生一組不重複的字串，通常您不需要知道這組字串。在大多數程式碼實驗室中，您必須參照專案 ID (通常會標示為 PROJECT_ID)。如果您不喜歡系統產生的 ID，可以再產生一組隨機 ID。或者，您也可以嘗試使用自己的名稱，看看是否可用。這個步驟完成後即無法變更，且在專案期間會保持不變。
• 此外，還有第三個值，也就是「專案編號」，某些 API 會使用這個值。如要進一步瞭解這三個值，請參閱說明文件。

注意：專案 ID 是全域專屬 ID，一經選用即無法由他人使用。你是該 ID 的唯一使用者。即使專案已刪除，也無法再次使用該 ID

注意：如果您使用 Gmail 帳戶，可以將預設位置設為「No organization」(無組織)。如果你使用 Google Workspace 帳戶，請選擇適合貴機構的位置。

2. 接著，您必須在 Cloud 控制台中啟用計費功能，才能使用 Cloud 資源/API。執行這個程式碼實驗室的費用極低，甚至可能完全免費。如要關閉資源，避免產生本教學課程以外的費用，可以刪除建立的資源或刪除專案。新註冊 Google Cloud 的使用者可獲得價值 $300 美元的免費試用。

啟動 Cloud Shell

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

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

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

這個虛擬機器已預先安裝所有必要的開發人員工具，提供永久的 5 GB 主目錄，而且在 Google Cloud 中運作，大幅提升網路效能並強化驗證功能。本程式碼實驗室的所有工作都可以在瀏覽器中完成。您不需要安裝任何項目。

3. 事前準備 (安裝)

注意：如果您決定在 Cloud Shell 執行這個程式碼實驗室，系統會預先安裝 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 設定相同，因此您的殼層體驗會與 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 協助。

驗證

您必須具備已啟用 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/ 中。您可以自由複製該處的程式碼。

本程式碼實驗室的目的不是教您如何編寫優質 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 和網頁。

• CLI 最適合快速和自動化測試
• 網頁最適合用來查看實際情況、使用麥克風 (!) 和排解問題。

提示：在本練習中，除了單元測試以外，請使用網頁版完成所有操作。這真的很棒！CLI 僅用於自動化測試。

以下是能妥善測試步驟 1 到 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/

請嘗試使用上方的「試金石提示詞」。

但可能無法提供特定日期。我們需要教它辨識日期！

在網頁上，您可以執行以下操作：

1. uv run adk web .：執行這個資料夾中的所有代理。您想將其指向「mysolution/」子資料夾
2. 選擇右上方的 mysolution/ (請參閱旁邊的圖片)
3. 透過文字或麥克風提出問題，類似「試金石提示」

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

以下是可能的解決方案，其中包含日期半幻覺。請注意，5 個預訂連結中有 3 個正常運作！還不錯。

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

在 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

  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)，因此我們會將 now() 替換為 google_search，以簡化作業。詳情請參閱 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 限制錯誤，可以使用忽略漫遊器指令修補 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 Agent Development Kit，建構自己的強大代理！

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

現在，我們要使用「Gemini CLI」新增功能。

9. 🏅 里程碑 2：透過 Gemini CLI 使用 ADK 進行直覺式程式開發

現在進入工作坊的有趣部分。

1. 請務必將備用碼git commit儲存在安全的地方。您可以建立原始程式碼的分支版本，或建立分支。別擔心，Gemini CLI 非常擅長協助您完成這項工作！
2. 找出要實作的 💡 idea。您可以參考下列構想、自行發想，或請 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 不允許，Google 搜尋可能會協助來回確認。注意：Gemini CLI 可以提供協助。
7. 🟡 [中] 實作 AirbnbReviewAgent，用於分析評論，並以幾點不同顏色的項目符號，總結 1 或 N 間飯店的優缺點。您已有 2 項要素 (Google 搜尋和 MCP Airbnb)，接著需要將這些要素連結至主要代理，並可能需要建立某種通訊協定，讓這些要素能互相通訊。
8. 🟡 [中] 整合 A2A。設為 A2A 代理！再次向 Gemini CLI 尋求協助！
9. 🔴 [複雜] 您可以整合 Flights 或其他 MCP 功能，打造多面向、多功能的旅行社。
10. 🔴 [複雜] 將 ADK 網頁與 🍌 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」的必要條件

如要透過直覺式程式開發建構功能，建議您下載完整的 ADK Python ADK (注意：您可以輕鬆將其轉換為偏好的語言，例如 Java 或 Go！)。

程式碼位於 ./rag，可使用 ./download-adk.sh 下載。

由於 .gitignore 檔案中列有 rag 資料夾，請確認 .gemini/settings.json 包含下列內容：

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

為什麼？我們希望 Gemini 能讀取這些檔案，同時安全地忽略 git。技術上，您也可以將 context.fileFiltering.respectGitIgnore 設為 false，取消隱藏所有 .gitignore 檔案，但這會開啟許多 node_modules/ 和 __pycache__/ 垃圾檔案，因此建議明確納入資料夾。

10. 後續步驟

趣味知識：這個工作坊是使用 Gemini CLI 建立。如果您想瞭解做法，可以查看這個資料夾中的 GEMINI.md 和 WORKSHOP_PLAN.md。

經驗談

我們已瞭解如何搭配使用 ADK 和 Gemini CLI，

延伸閱讀

• 請參閱以下兩個官方 Antigravity 程式碼實驗室：
  • 開始使用 Google Antigravity
  • 使用 Google Antigravity 建構
  • 使用 Antigravity 建構及部署至 Google Cloud
• 請參閱官方 ADK 教學課程，瞭解一些做法。