Day 3 把 gcloud、adk、agents-cli 都裝上機器了，照理說該直接進 agents-cli scaffold create 動手寫 agent。結果第一步就卡住：全機裝好的 adk 版本，跟 scaffold 產出的專案要求的版本對不上。這種「同一個生態圈往前走，但版本衝突不會自己消失」的情況，我在整理 LangChain 筆記時也遇過同一種模式，這篇一起講。

版本落差：1.23.0 對 2.5.0

這件事我卡了一下。全機的 adk --version 是 1.23.0，pip list 也顯示 google-adk 1.23.0。但 scaffold 產出的 pyproject.toml 寫的是：

dependencies = [
    "google-adk[gcp,otel-gcp]>=2.5.0,<3.0.0",
    "a2a-sdk[http-server]>=1.0,<2",
    "google-cloud-aiplatform[evaluation,agent-engines]>=1.156.0",
    ...
]
requires-python = ">=3.11,<3.14"

要 2.5.0 以上，我只有 1.23.0。看起來像是要先升級全機的 ADK。

實際上不用。在專案目錄跑

agents-cli install

它會建一個專案自己的 .venv 並解好依賴。裝完進去確認：

$ .venv/Scripts/python.exe -c "import google.adk; print(google.adk.__version__)"
google-adk 2.5.0

專案裡是 2.5.0，全機還是 1.23.0，兩者並存。

這個並存會咬你一次

你在專案外面打 adk，拿到的是全機那支 1.23.0。你在專案裡想用對的版本，要走

uv run adk <子命令>

或直接叫 .venv 裡的執行檔。README 也是這樣寫的：「You can also use features from the ADK CLI with uv run adk」。

我第一次沒注意，對照文件時一直覺得某個參數不存在，其實是叫到舊版那支。查 ADK 相關問題時，先確認你叫的是哪一個 Python 環境裡的 ADK，再去懷疑文件寫錯。

requires-python 是 >=3.11,<3.14，我的 3.11.9 在範圍內。如果你用 3.14，agents-cli install 會在解依賴時失敗。

別的框架也有一樣的病

ADK 這次的版本落差不是特例。我另外整理 LangChain 生態圈的筆記時，也碰過同一種問題：舊教學文章示範的是 from langchain.agents import initialize_agent 這種寫法，現在推薦的做法已經換成用 LangGraph 建 agent，AgentExecutor、initialize_agent、LLMChain、SequentialChain、各種 Memory 類別全部被取代，套件本身也從「一包大 langchain 裝全部」拆成 langchain-core 加上各家 partner 套件各自獨立版本。搜到一篇 2023、2024 年的舊文章，照抄開頭那行 import 就會卡住，跟我這次全機 adk 對不上 scaffold 要求的版本，是同一種「生態圈往前走，但舊教學跟舊環境沒跟著動」的情況。

LangChain 那邊處理這件事的習慣，是動手之前先跑一行指令確認手上是哪個版本：

pip show langchain langchain-core langgraph

我把這個習慣搬過來用在 ADK 上：先驗版，再去查文件、去問是不是自己哪裡裝錯。遇到「文件寫的行為跟我看到的不一樣」也一樣，第一件事是確認自己叫到的到底是哪一個環境裡的套件版本，而不是先假設文件錯了。pip show 這段是 LangChain 那邊的做法，ADK 的 1.23.0 對 2.5.0 是我自己這台機器實測到的數字，兩件事只是互相對照，不是同一個套件的紀錄。