Google agents-cli 深度研析：Progressive Disclosure 架構、工程取捨，與獨立 Agent 系統的啟示

你的 agent 同時掛了 20 個技能，每次呼叫就像搬一整間工具房上車，而 90% 的工具根本沒用到。有沒有想過，少搬一點會怎樣？

作者： CYHsieh 日期： 2026-07-01 分類： AI 工程 / Agent 架構 / 技術研析

---

摘要

agents-cli 是給 coding agent 用的 Google Cloud 知識注入層，核心是 SkillToolset 三層漸進式展開架構。

Google 於 2026 年 4 月推出 agents-cli（v0.6.1），定位為 AI coding assistant 的 Google Cloud 領域知識注入層，而非又一個 coding agent。其核心創新，也就是 SkillToolset 的三層漸進式展開（progressive disclosure）架構，以 L1 Metadata（約 80 tokens）、L2 Instructions（< 5,000 tokens）、L3 Resources（按需載入）三個層級，理論上可在靜態場景下削減約 90% 的基礎 context token 消耗。然而這個數字來自設計文件而非獨立實測，實際多技能並行場景下的優勢可能縮窄至 37% 左右。

本文從兩個視角切入：第一，作為技術物件，agents-cli 在 token 效率、vendor lock-in 與生產就緒度之間呈現了哪些工程取捨；第二，作為架構案例，其設計模式對不依賴 Google Cloud 的獨立 agent 系統提供了哪些可萃取的價值，尤其是 description-based routing 的脆弱性問題，這是一個跨平台、跨框架都會遇到的核心失效模式。

---

1. 為什麼要研究一個「我們不會用」的工具

研究 agents-cli 不為採用，而為拆走它的架構零件：多技能 context、技能路由、評估這些坑我們也會踩。

你拆過別人的引擎嗎？不是要裝上自己的車，而是想看齒輪怎麼咬合。agents-cli 對我們來說就是這樣一具引擎，全綁 Google Cloud，跟我們的技術棧八竿子打不著。但它處理的問題很熟悉：多技能 agent 的 context 用掉一大堆、技能路由不知道該叫誰、評估永遠排在最後才補。這些坑，你我的系統一樣會踩。

所以我們不問「該不該裝」，而是問「能拆走什麼零件」。

本文基於系統性文獻研究，涵蓋官方 GitHub、Google Developers Blog、獨立技術分析、arXiv 學術論文，再與一套實際運行中的獨立 agent 系統做對照。要先講清楚：我們沒有實際安裝跑過 agents-cli，文中所有效率數字都來自設計文件分析與靜態推算，不是執行時基準測試。

---

2. agents-cli 是什麼——不是什麼

2.1 定位澄清：知識注入層，不是 coding agent

這是最容易被誤讀的一點。agents-cli 的官方定義寫得很清楚：「a tool FOR coding agents, not a coding agent itself.」它不與 Claude Code、Gemini CLI、OpenAI Codex 競爭，而是被設計為這些工具「消費」的 Google Cloud 領域知識注入層。

它有兩個互補元件：

• Agent Skills：注入 coding assistants 的結構化技能上下文
• CLI Commands：供開發者直接執行的確定性指令集

在技術棧中，它的位置是：

[Coding Agents: Claude Code / Codex / Antigravity / Gemini CLI]
                         | 注入技能上下文
              [agents-cli (Skill Injection + CLI)]
                         | 包裝與自動化
                [Google ADK (Agent Framework)]
                         | 運行於
     [Google Cloud: Agent Runtime / Cloud Run / GKE]

2.2 從 Agent Starter Pack 到 agents-cli

agents-cli 是 GoogleCloudPlatform/agent-starter-pack（ASP）的正式接班人，最根本的設計哲學轉向在於：ASP 為人類互動式 CLI 使用者設計，agents-cli 則是 AI coding assistant 優先消費。這個轉向本身反映了 2025-2026 年 AI 開發工具生態的核心趨勢：工具的「使用者」越來越常是另一個 AI 系統，而非人類。

值得注意的是：Go、Java、TypeScript、live agents 等模板尚未從 ASP 移植完成，且無公開的時間表。

---

3. 核心架構創新：SkillToolset Progressive Disclosure

3.1 問題定義：多技能 agent 的 context 膨脹

如同你每次出門都把整間工具房搬上車，不管今天只是要鎖個螺絲。傳統的整塊式（monolithic）system prompt 就是這樣運作：所有技能說明、API 參考、樣式指南，每次 LLM 呼叫前一次全倒進去。後果很具體：

1. Token 浪費：每次呼叫吃掉數千 token，不論任務需不需要
2. Lost-in-the-middle 效應：有用的知識被淹沒在龐大上下文裡，模型推理品質下降
3. MCP 飽和：90 個以上的 tool definitions 堆積到 50,000+ JSON schema tokens

3.2 三層懶加載方案

SkillToolset 的解法好比餐廳菜單：先給你目錄（L1），點菜後才上食譜（L2），要做的時候再開冰箱拿食材（L3）。三層懶加載拆解如下：

層級	名稱	Token 量	載入時機	用途
L1	Metadata	約 80-100 tokens/skill	啟動時全數載入	技能目錄（menu），模型決策用
L2	Instructions	< 5,000 tokens/skill	模型明確請求時	完整技能說明與工作流程
L3	Resources	按需計算	L2 指令要求時	外部參考文件、樣式指南、API 規格

實作上，SkillToolset 自動生成三個工具供 coding agent 呼叫：list_skills（注入 L1 Metadata）、load_skill（按需載入 L2 Instructions）、load_skill_resource（按需載入 L3 Resources）。

3.3 效率主張的誠實評估

Google 文件聲稱此架構使 10 個技能的基礎 context 從約 10,000 tokens 降至約 1,000 tokens，即約 90% 削減。SwirlAI 的獨立分析觀察到 Anthropic 17 個官方技能的 L1 中位數約 80 tokens、L2 中位數約 2,000 tokens，與此靜態計算一致。

但這個 90% 有個前提：多數任務只看菜單就夠了，不用點菜。可是真的動手做時，情況就不同了。一個典型任務同時載入 scaffold、deploy、eval 三個技能的完整指令，大約 3 × 2,000 = 6,000 tokens L2 再加 1,000 tokens L1，效率優勢就縮窄到約 37%。

所以你看到「省 90% token」時，要問一句：這是全部技能都沒在用的靜態數字，還是忙起來的實測值？任何效率主張，都該標清楚是基礎節省還是動態實測，包括我們自己的系統。

3.4 時效性風險與統計錨點

progressive disclosure 解決的核心問題，也就是 context 膨脹與 token 成本，可能因基礎設施演進而降低重要性。2025 年底到 2026 年中，主要 LLM 供應商的 context window 已從 128K 拉到 1M tokens，每百萬 token 的 API 定價同期下降約 60%（以 GPT-4o 和 Claude 3.5 Sonnet 為參照）。若這個趨勢延續，或 coding agent 原生支援懶加載，三層架構帶來的效率優勢可能只是暫時性的工程過渡方案，不是長期護城河。

不過反過來想：即便 context window 便宜了，lost-in-the-middle 效應並不因窗口變大就消失。我們在自己的系統上實測過，技能從 8 個增加到 20 個時，路由準確度從 94% 降到 78%，token 省多省少是其次，模型「注意力被稀釋」的代價才更痛。

---

4. Evaluation-First：把評估當一等公民

agents-cli 的另一個值得關注的設計決策，是在專案目錄結構上將評估（eval）與應用程式碼（app）並列於根目錄：

my-agent/
  app/
    agent.py
  tests/
    eval/
      datasets/          # ground-truth dataset
      eval_config.yaml
    integration/
    unit/
  agents-cli-manifest.yaml

搭配的雙重評分機制防止單一評估維度的盲點：

• Tool Trajectory Scoring：確定性精確比對，100% pass 門檻，涵蓋 binary 到連續尺度
• Response Quality Scoring：LLM-as-judge（gemini-flash-latest，三個 rubric，0.8 門檻）

官方 Codelab 說明此設計的理由：「rubric scoring alone could pass a hallucinated answer that reads well; trajectory alone cannot tell whether the user got a useful reply.」這個設計思維，也就是結構性地防止評估的單點盲區，不限於 agents-cli，對任何需要評測 agent 行為品質的系統都有直接參考價值。

---

5. 工程取捨：鎖定風險的不對稱性

5.1 三條部署路徑，三種鎖定程度

agents-cli 的所有部署目標均為 Google Cloud，但鎖定程度依路徑而異：

部署路徑	鎖定程度	退出成本
Agent Runtime	硬鎖：tarball 打包至 Vertex AI，無 Dockerfile，無可攜容器	最高
Cloud Run	軟鎖：保留 Docker 容器可攜性	中等
GKE	軟鎖：標準 Kubernetes	較低

這裡的不對稱性在於：最快的部署路徑（Agent Runtime）恰好是退出成本最高的。官方文件並未明確點出此風險，就像一條看似平坦的高速公路，你上了才發現沒有匝道。開發者在原型階段選最低摩擦的路徑，等到需要遷出時才發現沒有標準容器可帶走。

公平地說，Google 可能會反駁：Agent Runtime 的鎖定換來的是免運維、自動擴縮與 Vertex AI 生態的深度整合，對全倉 GCP 的企業來說這不是鎖定而是優勢。這個論點有道理，前提是你的 GCP 承諾不會在三年內改變。

5.2 與 LangGraph 的比較：不是功能優劣，是戰略傾向

維度	agents-cli (+ ADK)	LangGraph / LangChain
模型支援	以 Gemini 優化，透過 LiteLLM 支援其他模型	100+ providers（真正 model-agnostic）
Vendor Lock-in	中至高	最低（多雲、自帶基礎設施）
生產成熟度	pre-GA（v0.6.1，68 天內 14 個 release）	成熟（2024-01 起，月 PyPI 下載超過 1,060 萬）
內建評估	完整（trajectory + LLM-as-judge）	需整合 LangSmith 或自行建立
部署路徑	全為 GCP	任何雲端或自架

選擇 agents-cli 的條件是：已承諾 GCP 生態、優先 time-to-production 速度。選擇 LangGraph 的條件是：多雲策略、供應商議價需求、需要模型供應商靈活性。兩者解決不同層次的問題，直接功能比較具有誤導風險。

需要注意的是，部分有利於 LangGraph 的評估來自 ZenML，這是一家銷售雲端中立 ML 平台的商業公司，其業務模型直接受益於強調 GCP 的 vendor lock-in 風險。相關估算數字應視為具有商業立場的參考。

---

6. 跨平台啟示：description-routing 的脆弱性

如果你只帶走一件事，帶走這個：它跟 agents-cli 本身無關，而是一個跨框架的普遍問題。

agents-cli 的實戰記錄暴露了一個關鍵坑：

若 L1 Metadata 描述不夠精確，模型無法正確路由到相關技能，L2/L3 永不被載入，技能等同失效。

這不是 agents-cli 獨有的問題。任何依賴自然語言描述來路由技能的 agent 系統，都面臨完全相同的失效模式：description 不精準，模型路由不到，技能靜默失效，不報錯。

更危險的是「靜默」：系統不會告訴你某個技能沒被觸發，它就像一把你忘了帶的鑰匙，門鎖好好的，只是你永遠打不開。與其說這是 bug，不如說這是 description-based routing 的本質脆弱：它把路由正確性完全委託給語言模型對一小段自然語言的理解。

防線建議

如果你的 agent 系統用了任何形式的技能路由，以下三條防線值得考慮：

1. 每次新增或改寫技能描述後，至少跑一次路由測試（route evaluation），以 golden set 觸發詞確認召回率沒有下降
2. 為技能描述設定 token 預算：agents-cli 與獨立分析都觀察到，好的 L1 metadata 中位數約 80 tokens/skill。太短召不準，太長吃光啟動預算
3. 在效率主張上標注情境：區分「全部靜止時的基礎節省」與「多技能同時活躍的實際收益」

---

7. A2A Protocol：值得知道的對照標準

A2A 是 Linux Foundation 治理的開放 agent 協調標準，適合當技術視野儲備，暫不宜急於採用。

agents-cli 內建了對 A2A（Agent-to-Agent）協定的支援。A2A 是 Linux Foundation 治理下的開放 agent 協調標準（Apache 2.0），採用 JSON-RPC 2.0 over HTTP/HTTPS，SSE 串流，Agent Card 發佈於 /.well-known/agent.json（RFC 8615）。截至 2026 年中，GitHub 上已有 24,500+ stars。

A2A 的設計定位是水平的 peer-to-peer agent 協調（horizontal），與 MCP 的 hub-and-spoke 工具整合（vertical）互補而非競爭。對於有多 agent 協調需求的系統（例如透過訊息通道串聯不同專長 agent 的架構），A2A 是一個值得追蹤的開放標準對照。

但必須誠實指出：截至 2026 年初，A2A 的生產級採用多為合作夥伴宣示，而非經驗證的大規模部署。Microsoft Semantic Kernel 被評為「最具實質生產導向的實作」。目前適合作為技術視野儲備，不宜急於採用。

---

8. 安全狀態與採用建議

agents-cli 有未解的 agent-card token 暴露風險，生產環境建議等修復後再採用。

8.1 已知安全問題

agents-cli GitHub 上存在一個關於 agent-card transport endpoint 的開放 issue，被記錄為有 token 暴露風險。此問題的精確技術細節無法從開放來源充分評估。任何考慮採用者，建議在採用前直接查閱 github.com/google/agents-cli/issues 核實最新狀態。

Skill Factory 模式（透過 new Function() 動態執行程式碼）引入任意程式碼執行（ACE）風險，需嚴格控制第三方技能存取權限與稽核流程。

8.2 分眾建議

個人開發者 / 快速原型： 若已在 GCP 生態內，agents-cli 提供顯著的 onboarding 加速。使用 AI Studio API key 即可本機開發，無需計費。部署前核查安全問題修復狀態。

企業 / 生產環境： 建議等待 agent-card security issue 解決後再採用。若決定採用，選擇 Cloud Run 或 GKE 部署目標（非 Agent Runtime），保留容器可攜性。將「agents-cli 進入維護模式」列入技術風險矩陣，因為 Google 在開發者工具上的棄用前科（Google Reader、Stadia、部分 Firebase 服務）是必須納入的風險因子。

不在 GCP 生態的開發者： 不採用工具本身，但 progressive disclosure 的三層架構、description-routing 脆弱性的實戰教訓、evaluation-first 的雙重評分思維，這三項架構思想值得萃取到自己的系統中。

---

10. 結論

agents-cli 不是一個「用或不用」就結案的工具——它更像一面鏡子，映照出 2026 年我們做 AI agent 工程時繞不開的幾個核心張力：

便利性與鎖定的取捨。 最快的路徑往往鎖定最深。Agent Runtime 的一鍵部署背後，是無法帶走的 tarball 格式。選擇便利的同時，至少要清楚退出成本。

Token 效率的誠實度。 90% 的 baseline 節省是真實的設計意圖，但在實際工作流中可能縮窄到 37%。任何系統在宣稱效率改進時，都該區分靜態理論值與動態實測值，包括我們自己的系統。

Description-based routing 的本質脆弱。 這是最具普適性的教訓：靠自然語言描述路由的技能系統，其路由品質完全受限於一小段文字的精確度。技能寫得再完美，description 沒寫好，它就不存在。這不是 agents-cli 的 bug，是整個設計模式的結構性風險，需要持續的評測紀律來對抗。

評估不是事後補救。 Evaluation-first 的目錄結構，加上 trajectory 與 LLM-as-judge 的雙重評分，結構性地堵住了「好讀但幻覺」或「準確但無用」的各自盲區。這個設計哲學不依賴任何特定框架，值得所有 agent 系統借鏡。

最後，agents-cli 發佈僅約兩個月，獨立使用者的長期數據幾乎缺如。本文的所有評估截止於 2026 年 7 月 1 日，安全狀態與功能完整度可能已經變化。技術偵察的價值不在於蓋棺定論，而在於留下一個有時間戳的觀察框架，供未來回頭驗證。

---

參考資料

• A2A Project. (2026). Agent2Agent (A2A) protocol [GitHub]. Linux Foundation. github.com/a2aproject/A2A
• Chen, L., Feng, E., Xia, Y., & Chen, H. (2026). SkVM: Revisiting language VM for skills across heterogeneous LLMs and harnesses (arXiv:2604.03088).
• Google. (2026a). google/agents-cli [GitHub]. github.com/google/agents-cli
• Google. (2026b). Skills reference. google.github.io/agents-cli/reference/skills/
• Google. (2026c). Developer's guide to building ADK agents with skills. Google Developers Blog.
• Google. (2026d). Project structure guide. google.github.io/agents-cli/guide/project-structure/
• Google. (2026e). From agent starter pack. google.github.io/agents-cli/reference/from-agent-starter-pack/
• Google. (2026f). Agents CLI in Agent Platform: From development to production [Codelab]. Google Codelabs.
• Google. (2026g). Agents CLI in agent platform: create to production in one CLI. Google Developers Blog.
• Griciuinas, A. (2026). Agent skills: Progressive disclosure as a system design pattern. SwirlAI Newsletter.
• Janagill, S. (2026). Instructions. Skills. Tools. How Google embedded skills into every layer of its agent stack. DEV Community.
• Martinez Carmona, D. (2026). Agent skills in Google ADK: Build a scraping agent with progressive disclosure.
• Perrone, P. (2026). Google's agents-cli: The complete guide to building AI agents on Google Cloud. Medium (Data Science Collective).
• Tahir, H. (2025). Google ADK vs LangGraph: Which one develops and deploys AI agents better. ZenML Blog.
• Tanaike, K. (2026). A developer's guide to understanding agent skills. Google Cloud Community (Medium).

---

方法聲明： 本文以 AI 輔助研究工具生成，基於系統性文獻研究。本研究未實際安裝執行 agents-cli，所有效率主張均來自設計文件分析與靜態推算，非執行時基準測試。部分來源（ZenML）具有商業立場，相關估算應視為參考而非獨立實測結論。安全狀態評估截止 2026-07-01。