Feature Request
Allow callers to place an Anthropic prompt-cache breakpoint (cache_control) at a chosen position in the message history, instead of only the fixed positions used by with_prompt_caching / with_automatic_caching.
Motivation
The CacheControl type and per-block cache_control wire fields already exist in the provider, but request conversion always emits cache_control: None for content blocks — the only way to get markers is the model-level flags, which pin them to the system prompt and the latest message. Callers with a large stable prefix mid-history (a big document, a long tool manifest, an agent scaffold) can't mark it, so they can't use Anthropic prompt caching effectively from rig. We've been running this internally as a patch and are offering it upstream.
Proposal
A documented additional_params key, ANTHROPIC_CACHE_CONTROL_KEY ("anthropic_cache_control"), set on a generic message::Text / Image / Document block to a CacheControl payload. Request conversion extracts it onto the corresponding content block's cache_control field; an invalid payload under the key fails conversion. Marker presence is the opt-in — no model-level flag. This follows the existing pattern of per-block provider metadata in additional_params (like the Anthropic document title / context / citations keys).
PR to follow. Design note: we made some speculative API decisions here (the additional_params carrier, the public key const, interaction contract with with_prompt_caching) and are happy to redo it differently if you'd prefer another shape.
Alternatives
- A first-class
cache_control-like field on the generic message types — cleaner but leaks provider-specific structure into the provider-agnostic surface.
- Typed attach helpers (
anthropic_text_with_cache_control(...)) — better ergonomics/validation but new API surface in a style the library doesn't use elsewhere; we prototyped this and backed it out in favor of the raw-key pattern.
Feature Request
Allow callers to place an Anthropic prompt-cache breakpoint (
cache_control) at a chosen position in the message history, instead of only the fixed positions used bywith_prompt_caching/with_automatic_caching.Motivation
The
CacheControltype and per-blockcache_controlwire fields already exist in the provider, but request conversion always emitscache_control: Nonefor content blocks — the only way to get markers is the model-level flags, which pin them to the system prompt and the latest message. Callers with a large stable prefix mid-history (a big document, a long tool manifest, an agent scaffold) can't mark it, so they can't use Anthropic prompt caching effectively from rig. We've been running this internally as a patch and are offering it upstream.Proposal
A documented
additional_paramskey,ANTHROPIC_CACHE_CONTROL_KEY("anthropic_cache_control"), set on a genericmessage::Text/Image/Documentblock to aCacheControlpayload. Request conversion extracts it onto the corresponding content block'scache_controlfield; an invalid payload under the key fails conversion. Marker presence is the opt-in — no model-level flag. This follows the existing pattern of per-block provider metadata inadditional_params(like the Anthropic documenttitle/context/citationskeys).PR to follow. Design note: we made some speculative API decisions here (the
additional_paramscarrier, the public key const, interaction contract withwith_prompt_caching) and are happy to redo it differently if you'd prefer another shape.Alternatives
cache_control-like field on the generic message types — cleaner but leaks provider-specific structure into the provider-agnostic surface.anthropic_text_with_cache_control(...)) — better ergonomics/validation but new API surface in a style the library doesn't use elsewhere; we prototyped this and backed it out in favor of the raw-key pattern.