安裝

gcloud 走官方安裝程式。裝完 gcloud auth login 加 gcloud auth application-default login，兩個都要，前者給 CLI 用，後者給 SDK 用。

這兩個指令看起來很像，容易讓人以為裝一次就好。但認證的對象不一樣。gcloud auth login 產生的憑證給 gcloud 這支命令列工具自己用，你在終端機打的每一條 gcloud 指令都靠它認證。gcloud auth application-default login 產生的是應用程式預設憑證，寫進使用者目錄底下一個固定路徑，任何用 Google 官方 SDK（包含 Python 的 google-cloud-* 系列套件）寫的程式，只要沒有明確指定服務帳號金鑰，都會去讀這份憑證。兩者分開設計，我猜是因為 CLI 工具跟你寫的程式是兩個不同的呼叫者，各自要能獨立撤銷，不該共用同一份憑證。少裝其中一個，症狀通常不會報錯說「沒登入」，而是 SDK 那邊丟出權限不足或找不到憑證的錯誤，看起來跟認證完全無關。這段推測我還沒撞過反例，先擺著，踩到再回來補。

ADK 與 agents-cli 用 uv：

uv tool install google-agents-cli

adk 這支我機器上是在 AppData\Local\Programs\Python\Python311\Scripts\adk，agents-cli 在 .local\bin\agents-cli。兩個路徑來源不同，查問題時要知道自己叫到哪一支。

這個落差大概是安裝方式不同造成的：其中一支可能透過某個安裝程式或全域 Python 環境裝進系統慣用的 Scripts 目錄，另一支是 uv tool install 這種比較新的做法，統一放進使用者自己的 .local\bin。沒去翻兩邊的安裝腳本確認來源，讀者查得到更準確的原因歡迎補正，先標成未查證。

agents-cli 每次啟動都提醒升級

跑任何 agents-cli 子命令，輸出最前面會有：

⚠️  Update available: 1.3.1 → 1.4.1
Run `uv tool upgrade google-agents-cli` to update.

這行會混在正常輸出裡，第一次看會以為是錯誤。我暫時停在 1.3.1，因為我要讓 30 天的輸出可重現，中途升版會讓前面幾篇的檔案結構跟後面不一致。這是刻意的選擇，不是懶。

這種每次啟動都檢查升級的設計也有代價。如果哪天離線，或者公司網路擋掉版本檢查打的那個端點，這行警告理論上會拖成連線逾時，拖慢每一次呼叫的啟動速度。這只是看到機制之後的疑慮，還沒真的撞過，先寫下來，之後遇到再回來更新。

小結

這篇都還沒碰到 ADK 版本本身的問題。下一篇要處理更麻煩的一個：全機的 adk 明明是 1.23.0，scaffold 產出的專案卻寫死要 2.5.0 以上，這兩個數字要怎麼並存。