Google ADK: context caching with cached_content (constraints on tools and system instruction)

TL;DR

Separately, the adk web CLI in 1.51.1 had bugs loading cache configs, fixed on the main branch. If the adk web CLI does not load your cache config, update to the latest ADK (an older 1.51.x CLI had bugs fixed on main).

Steps

1. Passing a GenerateContentConfig(cached_content=cache.name) to an ADK LlmAgent failed with a 400 INVALID_ARGUMENT error. The message said tool config, tools, and system instruction should not be set in the request when using cached content. The user wanted to inject an explicitly created cache into the agent, but ADK does not support injecting arbitrary cached content: it has specific requirements on what must be cached. Separately, the adk web CLI in 1.51.1 had bugs loading cache configs, fixed on the main branch.
2. What actually fixes it (verified in the thread):
3. Context caching is supported in ADK now (closed as supported by a maintainer). Two constraints apply: when using cached content, the request must not also set tool config, tools, or system instruction (the Gemini API rejects that combination), and ADK does not support injecting arbitrary cached content , ADK has specific requirements on what must be cached. If the adk web CLI does not load your cache config, update to the latest ADK (an older 1.51.x CLI had bugs fixed on main).

When to use

You are seeing this: The situation: Passing a GenerateContentConfig(cached\content=cache.name) to an ADK LlmAgent failed with a 400 INVALIDARGUMENT error. Use this skill when you run into "Google ADK: context caching with cached_content (constraints on tools and system instruction)".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

Versions mentioned in the source: 1.51.1. If you are on something much newer or older, the details may have shifted.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Someone asked: Passing a GenerateContentConfig(cached_content=cache.name) to an ADK LlmAgent failed with a 400 INVALIDARGUMENT error. The message said tool config, tools, and system instruction should not be set in the request when using cached content. The user wanted to inject an explicitly created cache into the agent, but ADK does not support injecting arbitrary cached content: it has specific requirements on what must be cached. Separately, the adk web CLI in 1.51.1 had bugs loading cache configs, fixed on the main branch. The verified answer: Context caching is supported in ADK now (closed as supported by a maintainer). Two constraints apply: when using cached content, the request must not also set tool config, tools, or system instruction (the Gemini API rejects that combination), and ADK does not support injecting arbitrary cached content , ADK has specific requirements on what must be cached. If the adk web CLI does not load your cache config, update to the latest ADK (an older 1.51.x CLI had bugs fixed on main). Full thread: https://vectle.com/threads/thrBQa-70QHTRNE6-eCsb9VwQ