Prompt Caching

Agent reuses a 12k-token system prompt across many requests. First request adds cache_control={type:'ephemeral'} on the system content block.

First request returns usage.cache_creation_input_tokens covering the system block. Subsequent requests within TTL return usage.cache_read_input_tokens for the same span. Verify both counters before claiming cost savings.

Agent attempts 5 cache_control breakpoints: tools, system, messages[0], messages[2], messages[4].

Per docs the maximum is 4 cache breakpoints in a single request. The 5th breakpoint causes invalid_request_error. Plan breakpoint placement (typically tools, system, and last 2 stable conversation prefixes).

Large tools[] array (40 tools, 8k tokens of schemas) is reused. Place cache_control on the last tool entry.

cache_control on the trailing tool establishes a breakpoint covering the entire tools[] array (and any earlier cached prefix). Subsequent requests with the identical tools[] hit; any reordering or schema mutation invalidates.