How can I explicitly enable context caching for a custom agent, and does automatic caching work for custom agents?

[wltnrhkd123]

I’m trying to understand how to properly enable context caching for a custom agent.

Specifically, I’d like to know:

1. How can explicit context caching be configured for a custom agent?
2. Does automatic caching work for custom agents at all?

My confusion comes from the fact that a custom agent does not have an instruction field. Because of this, I’m not sure whether caching is applied to the sub-agents inside the custom agent. I also tried converting my custom agent into an app and setting a ContextCacheConfig, but I wasn’t able to observe any cached values being generated.

I’ve searched through the Google ADK documentation and related materials, but I couldn’t find any examples that address this scenario.

If anyone has successfully set up caching for a custom agent—or can confirm that it’s not supported—I’d appreciate your insights.

Additional Questions

How does context caching behave when an agent’s instruction includes state values in the {key} placeholder format?
Specifically, does caching exclude only the {key} value itself?
Or is caching applied only up to the portion of the instruction that precedes the placeholder?
Or does the presence of {key} prevent caching from occurring at all?

A related question: how does caching behave when placeholders are used in a different way—for example, using Python-side variable replacement rather than the {key} state placeholder mechanism?
In other words, if I manually inject values into the instruction string (instead of relying on the agent’s state-based {key} placeholders), does context caching work differently?

[maheshwaritanay]

Having similar questions. Also are only static instructions cached or instructions are also cached implicitly?

[wltnrhkd123]

@adk-bot Can you answer?

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: Context caching is configured at the App level, not on individual agents. It works for custom agents by caching the LlmRequest calls made by the sub-agents they orchestrate. Caching is based on the final instruction content, so any change to a value injected via {key} placeholders or manual formatting will result in a cache miss.

---

Hello! Here are detailed answers to your questions based on the ADK documentation.

1. How can explicit context caching be configured for a custom agent?

Context caching in ADK is enabled and configured on the App object, and the settings apply to all agents within that app, including custom agents and their sub-agents. You can enable it by passing a ContextCacheConfig object when you create your app. [1]

Since a custom agent can be the root_agent of an app, this configuration will apply to the LLM calls made by any agents it contains.

Here is an example of how to configure it:

from adk.context import ContextCacheConfig
from adk.api import App

# Configure caching to last for 10 minutes
cache_config = ContextCacheConfig(ttl_seconds=600)

# app is an instance of adk.api.App
app = App(
    root_agent=my_custom_agent, # Your custom agent instance
    context_cache_config=cache_config
)

2. Does automatic caching work for custom agents?

Yes, the ADK’s explicit caching mechanism works for the operations within a custom agent. A custom agent itself doesn't make LLM calls, but it orchestrates other agents (like LlmAgent) that do. [2] The caching mechanism intercepts the LlmRequest objects generated by these sub-agents and stores the responses. The fact that a custom agent has no instruction field is not a problem, because caching applies to the underlying LLM calls, not the custom agent itself.

3. How does caching behave with {key} placeholders and manual variable injection?

Both {key} placeholders and manual Python string formatting (e.g., f-strings) are resolved before the instruction is sent to the model. The caching system works by checking the content of the final LlmRequest. [1]

This means:

• If the value changes: If a state value in a {key} placeholder (or a variable you manually inject) changes from one run to the next, the final instruction string will be different. This will cause a cache miss, and a new request will be sent to the LLM.
• If the value stays the same: If the resolved value is identical to a previous run, the instruction string will also be identical, leading to a cache hit. The cached response will be returned without calling the LLM.

In short, there is no functional difference between using {key} placeholders and manual variable injection as far as caching behavior is concerned. Any dynamic part of your instruction will influence whether you get a cache hit or miss.

[1] https://google.github.io/adk-docs/context/caching/
[2] https://google.github.io/adk-docs/agents/custom-agents/

[wltnrhkd123]

@hangfei

This is very directly related to cost.

Although adk-bot provided an answer, there was no supporting evidence at all, so it is not trustworthy.
A response from a developer is required.

I have one additional question.
If using placeholders or {key} requires a new cache value every time, then we will not be able to use {key} going forward.

As a countermeasure, is it possible to separate the cacheable part and the variable part and use them within the instruction?
When using the Gemini SDK directly, it is possible to split messages and effectively split the prompt.
However, in Google ADK, I cannot find any functionality that allows instructions to be split.

I would appreciate a prompt response.