Repository navigation
Expand explicit context caching to agent tools and sub agents #3230
Description
The new feature explicit context caching now only works on root agent while many LLM requests are happened within agent tools or sub agents.
Please expand the feature to also support agent tools or sub agents that can help to save cost.
Activity
klateefa commentedon Nov 24, 2025
@danhnguyen-ct Thank you for reporting this. I understand the request is currently under review. Please keep me posted if anything else is needed. Thanks for your patience.
chelsealong commentedon Oct 7, 2026
@klateefa I investigated a related, narrower use case: an opt-in continuation/review branch that preserves an eligible parent's request prefix. Could this fit under #3230, or would you prefer a separate design issue?
I pinned ADK main at
6854b88272f84a6ca9b1e4dec979a6476a00e0d7(reports 2.11.0), with google-genai 2.22.0 and Python 3.11.13. The offline reproducer uses real ADK runners/processors, identical configured static instructions and a read-only tool, and 102,889 characters of synthetic shared evidence. Model replies are simulated; requests are captured at theBaseLlmboundary before any provider API call.Observed behavior in the tested configurations:
SequentialAgent, explicitly chat-mode agentsWorkflow, default single-turn nodesAgentToolSeparately, seeded parent cache metadata is found for the parent but not for another agent name. Transferring that metadata alone to the ordinary chat-mode child fails ADK's local Gemini cache-validity check. A deep copy of the assembled parent request with an appended review task passes that same check and retains the synthetic cache reference when cache application runs. This is a request-level positive control, not an implemented safe agent fork or evidence of a provider cache hit.
Reproducer and pinned dependencies, including structured results and validation commands: 130 checks passed (9 reproduction checks plus 121 existing cache, identity and AgentTool checks). This is focused validation, not the full supported-Python matrix.
Would you be open to discussing an optional same-policy continuation/fork mechanism? It would need a completed immutable history boundary, compatibility checks for effective instructions/tools/model/provider scope and applicable configuration, isolated child execution, and explicit cache ownership/lifetime handling. Agent authorization, tool scope, and untrusted-history fencing must take priority; incompatibility should fall back to ordinary execution. I would not propose removing the current fencing or relabeling arbitrary specialist history just to obtain cache reuse.
For context, app-level caching already reaches the SequentialAgent and Workflow requests tested here. Propagating cache configuration into AgentTool is a separate concern from sharing a compatible parent prefix/resource.
I have not measured live cached tokens, latency, cost or task quality, and am not claiming savings or a missing feature across all providers/execution paths. No ADK runtime code is changed in this research branch. These ordinary-handoff observations do not establish that a manually configured pattern using existing APIs cannot meet the use case. Guidance or a supported sample would also be helpful. If a core change is appropriate, I can work on a focused implementation after we agree on the semantics and scope.
AI assistance: this investigation and reproducer were prepared with Codex; the validation above was executed locally.
chelsealong commentedon Oct 8, 2026
Hi @DeanChensj (Shangjie), if you have a moment, I would appreciate your perspective on the offline findings above and whether an opt-in, cache-compatible continuation/review fork would fit ADK's direction.
There are some relevant precedents: DeepSeek Harness documents a completed-history fork backend that preserves an eligible parent prefix; Claude Code uses cache-safe forking for compaction; and OpenAI describes Codex's stable request prefixes and append-only updates. These are specific patterns, rather than a claim that every subagent handoff works this way or guarantees a cache hit.
The pinned ADK reproducer captures request differences in the tested handoff paths, with 130 focused checks passing. No live cache hits or savings have been measured. Any proposed mechanism would need to respect Gemini's explicit-cache lifecycle and ADK's authorization and history-fencing boundaries.
Would you recommend an existing supported pattern, a sample, or a separate design proposal for this use case? I would be happy to narrow the scope based on your guidance. Thank you for your time!
GWeale commentedon Oct 26, 2026
hi @danhnguyen-ct, thanks for raising this and bearing with us while we sorted it out. as of 81311b7 (in v2.13.0), AgentTool passes the app's context cache config down to the agent it wraps, with the ttl capped at 300s. sub agents run via transfer, SequentialAgent, ParallelAgent, and LoopAgent were already using the app's config. one thing to keep in mind is that each AgentTool call starts a fresh session, so gemini's explicit cache only kicks in from the wrapped agent's second model call within that invocation. and @chelsealong, thanks for suggesting the prefix-preserving fork. that's a separate design, so it'd be great if you could open a dedicated issue for it.
github-actions commentedon Oct 26, 2026
Are you satisfied with the resolution of your issue?
Yes
No