Lance Martin, developer advocate at Anthropic, presents the prompt caching mechanism for the Claude API and announces the new auto-caching feature that considerably simplifies its use. Tokens using the cache cost only 10% of the normal price, representing a critical saving for agentic applications.
The fundamental problem is that the Claude messages API is stateless: it retains nothing between calls. An agent running actions in a loop must repackage, at every turn, the new context along with the history of actions, tool descriptions, and general instructions. Without caching, one pays the full price of the entire context window at every turn, even though most of the content is identical.
Prompt caching solves this problem by exploiting the two phases of LLM inference: prefill (prompt processing) and decode (generation). The prefill computation can be performed once, saved, then reused if part of the future prompt is identical. This is what frameworks such as vLLM and SGLang do.
Technically, caching uses a cache_control parameter that acts as a breakpoint. This breakpoint creates a cryptographic hash of all content blocks up to that point, scoped to the user's workspace. On subsequent requests, Claude looks backward (up to 20 blocks) to find a match. The match must be exact: a single character of difference produces a different hash and a cache miss.
The major new feature is auto-caching: a single cache_control: {"type": "ephemeral"} parameter placed at the request level (rather than at each block) causes the breakpoint to automatically move to the last cacheable block. As the conversation grows longer, the breakpoint follows automatically. This feature remains compatible with block-by-block caching for cases where one wants to set specific breakpoints (for example on the system prompt).
Martin cites @peakji of Manus, who considers the cache hit rate to be "the single most important metric for an AI agent in production," and points to the companion post by @trq212, which details the practical lessons drawn from Claude Code: how to structure the prompt to maximize hits, why one should never change tools or the model mid-session, and how to design features (plan mode, compaction) while respecting cache constraints. Together, the two articles form a complete guide to building cache-optimized agents on the Claude API.