# Google Cloud：Agent harness 用固定前綴降低多輪輸入 token

> 📖 本站完整內容索引（documentation index）：[llms.txt](/llms.txt)

> 原作者：Google Cloud Tech (@GoogleCloudTech) · 策展與摘要：EasyVibeCoding · 平台：X (Twitter) · 熱度：🔥🔥🔥 · 日期：2026-09-03

> 原始來源：https://x.com/GoogleCloudTech/status/2095201318348722507

## 證據與延伸閱讀

- [Google Cloud：Agent harness 用固定前綴降低多輪輸入 token。](https://x.com/i/article/2095196413630296064) — 官方文件 · 最後核對：2026-09-03 · 支持主張：Adds concrete cache-safety rules and cost examples: the static prompt must match byte-for-byte from token zero; mutable runtime metadata breaks the cache; dynamic variables belong at the end; cached reads are billed at a 75% discount; a five-turn modernization scenario reports a 79.46% transmitted-token reduction; and the article advises against caching below 32,768 tokens or three turns.
- [Gemini Enterprise Agent Platform context caching — docs.cloud.google.com](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/context-cache/context-cache-overview) — 官方文件 · 最後核對：2026-09-03 · 支持主張：補充 context caching 的可實作與計費邊界：implicit caching 預設啟用且 cached tokens 可享 90% 折扣；explicit caching 在 Gemini 2.5 或更新模型為 90%、Gemini 2.0 為 75%，預設有效期 60 分鐘並可更新 TTL，另有模型依賴的最小 token 數與 10 MB 最大 blob/text 大小。
- [Gemini Enterprise Agent Platform context caching — docs.cloud.google.com](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/context-cache/context-cache-create) — 官方文件 · 最後核對：2026-09-03 · 支持主張：補充 context caching 的可實作與計費邊界：implicit caching 預設啟用且 cached tokens 可享 90% 折扣；explicit caching 在 Gemini 2.5 或更新模型為 90%、Gemini 2.0 為 75%，預設有效期 60 分鐘並可更新 TTL，另有模型依賴的最小 token 數與 10 MB 最大 blob/text 大小。
- [Gemini Enterprise Agent Platform context caching — docs.cloud.google.com](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/context-cache/context-cache-use) — 官方文件 · 最後核對：2026-09-03 · 支持主張：補充 context caching 的可實作與計費邊界：implicit caching 預設啟用且 cached tokens 可享 90% 折扣；explicit caching 在 Gemini 2.5 或更新模型為 90%、Gemini 2.0 為 75%，預設有效期 60 分鐘並可更新 TTL，另有模型依賴的最小 token 數與 10 MB 最大 blob/text 大小。
- [Gemini Enterprise Agent Platform context caching — cloud.google.com（貼文明示來源）](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) — 一手來源 · 支持主張：補充 context caching 的可實作與計費邊界：implicit caching 預設啟用且 cached tokens 可享 90% 折扣；explicit caching 在 Gemini 2.5 或更新模型為 90%、Gemini 2.0 為 75%，預設有效期 60 分鐘並可更新 TTL，另有模型依賴的最小 token 數與 10 MB 最大 blob/text 大小。

## 中文摘要

Google Cloud：Agent harness 用固定前綴降低多輪輸入 token。

**Agent harness 快取規則** 靜態 prompt 必須從第 0 個 token 起逐位元組完全一致；若 mutable runtime metadata 放在靜態內容前方或其中，prompt hash 會改變，導致 cache miss，整份 prompt 依標準費率計價。dynamic variables 應一律放在 prompt 最後。文章以五輪「Multi-Target Batch Modernization」為例：未快取基準為 190,139 個 input tokens，快取後傳輸 39,503 個 tokens（37,659 個寫入 tokens 加上 1,844 個 dynamic suffixes），減少 150,636 個 tokens；分項數字換算約為 79.22%，圖表四捨五入標為 79.2%，而文章文字另寫 79.46%，同一案例的數值不一致。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/fb751ab7d15b668f.jpg)
> 多對話 loop 中的 context 累積顯示，共享程式碼庫（37,500 tokens）於每輪重複傳送，使總計費 prompt tokens 線性成長至 189,000 tokens。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/cab439a2bcc0d786.jpg)
> Prefix Invariance: Broken vs. Correct Prompt Layout 的對比圖表，左側為會造成 cache miss 的錯誤排版，右側為能觸發 cache hit 的正確排版，藉此說明將動態變數與可變執行期 metadata 放置在 prompt 結尾以維持 token zero 保持不變的重要規則。

**成本與採用門檻** 在文章所述的 Agent Platform 情境中，cached content reads 可享 75% 折扣，也就是以標準 prompt 費率的 0.25 倍計價。文章建議，context 小於 32,768 tokens，或輪數少於三輪時不要加入快取管理，因為傳輸成本有限，且單輪與兩輪請求無法攤平 1.0 倍的快取建立成本。不過該情境未提供端到端延遲或總成本測量，也未指明折扣與門檻對應的確切產品版本或區域。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/347d182c5ab705b9.jpg)
> Gemini Enterprise Agent Platform 的 Context Caching Lifecycle 架構時序圖，分為寫入靜態程式碼庫與疊代查詢循環兩個步驟，展示 Agent Harness 與 Context Cache、Gemini Core 之間的互動與 token 快取機制。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/936ece459b11dc2e.jpg)
> 深色背景的程式碼編輯器視窗，展示名為 CachePayloadBuilder 的 Python 類別，內含 compute_sha256、assemble_static_prefix、assemble_dynamic_suffix 與 verify_prefix_invariance 等函式，用於處理 static prefix 與 dynamic execution variables 的快取分離。

**Gemini Enterprise Agent Platform** 文件則區分 implicit caching 與 explicit caching。implicit caching 預設啟用，cached tokens 相較標準 input tokens 可享 90% 折扣；explicit caching 在 Gemini 2.5 或更新模型為 90%，Gemini 2.0 則為 75%。implicit caching 應把大型且共用的內容放在 prompt 開頭，並在短時間內送出相似 prefix 以提高命中機會，但文件沒有保證命中率，也沒有提供除成本以外的延遲改善數據。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/75f19188309e0595.jpg)
> Context Cache Manager Architecture & Lifecycle 的流程圖展示了從接收 context 請求到計算 SHA-256 hash、檢查 cache 是否存在與 TTL 是否有效，並依條件執行重複使用 active cache handle 或建立新 cache 紀錄、返回 cache record、執行 inference 及擷取 usage metadata 與 telemetry 的完整生命週期。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/43d7ded26cfe0365.jpg)
> ContextCacheManager 類別的 Python 程式碼，展示如何透過 GEAP SDK 實作快取生命週期管理、取得或建立快取以及帶入快取進行生成。

**實作與限制** 應用程式可透過 REST 或 Google Gen AI SDK 建立、引用、查詢、更新 TTL 及刪除 explicit cache。建立快取的 API 路徑為 `POST /v1/projects/PROJECT_ID/locations/LOCATION/cachedContents`，請求需提供 model 與 contents；後續以完整 cache resource name 搭配新 prompt 呼叫 generation request，並監看 `cachedContentTokenCount`、`createTime`、`updateTime` 與 `expireTime`。預設有效期為 60 分鐘，過期後必須重建，也可延長 TTL；Gemini 3 family 最少需要 4,096 tokens、Gemini 2 family 最少 2,048 tokens，cached blob 或 text 上限為 10 MB，內容亦可由 CMEK 保護。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/4153912b1ffa060c.jpg)
> 以 Python 撰寫的批次現代化程式碼，定義了 run_batch_modernization 函式，透過 ContextCacheManager 處理快取與未快取的推論調用，並計算 token 使用量與 telemetry 數值。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/debb52792da982a2.jpg)
> 5-Turn Modernization 情境在 190,139 個總 token 中，Saved Ingestion 以 150,636 個 token（79.2%）占據最高比例，Initial Cache Write 與 Dynamic Suffixes 則分別占 37,659 個 token（19.8%）與 1,844 個 token（1.0%）。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/be73ce94287413f8.jpg)
> 關於 agent task 執行快取策略的決策流程圖，透過條件判斷引導使用者選擇是否啟用快取或進行 harness 重構。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/cb8bf14267779298.png)
> 含有標題列與三個視窗控制按鈕的深色終端機視窗，展示執行單元測試、離線 mock 分析以及針對 GEAP 進行線上分析的 pytest 與 python 指令碼與環境變數設定指令。

## 標籤

功能更新, Google, Gemini Enterprise Agent Platform