I Added Four Lines of Code and Cut My Claude Agent’s Cost by 57%

Anthropic's docs on prompt caching are clear about the mechanics. You cache a stable prefix and pay a small premium the first time you write it. After that every read comes back at roughly a tenth of the normal input price. Search around and you'll find a dozen 2026 blog posts repeating the same 60-90% savings figure and the same breakeven math. What's harder to find is a real before-and-after test on one specific, common shape of agent. Its system prompt carries a large, mostly-static schema description on every single turn, sitting next to a small question that changes each time. That's the exact shape of a BI chat agent. It's the shape I already had built and running.I already had a Claude-based BI assistant built for a separate comparison, tested against a production-scale synthetic retail warehouse: customers, orders, order line items, promotions, returns, a separate wholesale side and sales targets, the kind of multi-table schema an actual retail analytics team would query. Its system prompt describes that whole schema up front on every single turn, because the model needs it to write correct SQL. Instead of trusting the vendor pitch, I took that existing agent and added one cache_control marker to its system prompt. Nothing else changed. Then I ran the same 15 real questions through it twice. What actually happened Both runs used the identical agent code, the identical schema, the identical 15 questions, against Claude Sonnet 5. The only difference was whether the system prompt carried a cache breakpoint. Without caching: 32 total API calls across the 15 questions, $0.1906 total cost, 82.8 seconds of cumulative model latency. With caching: also 32 calls (same conversation lengths, so the comparison is clean), $0.0824 total cost, 70.9 seconds of cumulative latency. That's a 57% drop in cost and a 14% drop in latency. All from adding four lines of code. The token accounting explains why. The cached prefix, schema description plus tool definitions plus the fixed instruction preamble, came out to 1,804 tokens. On the very first call of the entire run, that prefix got written to cache. On every one of the following 31 calls, all of it came back as a cache read instead of a fresh input computation, both across questions and across the follow-up steps within a single question's tool-use loop. The math lines up exactly: 31 calls times 1,804 tokens equals the 55,924 cached tokens the API reported reading back. Every call after the first got a full hit. No partial misses, because nothing in the prefix ever changed between requests. Why it works, and where it can quietly stop working Prompt caching is a prefix match. The API hashes the exact bytes of your request up to each cache_control marker. Any difference anywhere in that prefix invalidates everything after it. It doesn't matter whether that's a single reordered key or a stray timestamp that snuck into the system prompt. Anthropic renders tools before system before messages, which is why one marker at the end of the system prompt was enough to cache the tool definitions too. No second marker was needed on the tools array itself. The part I hadn't seen documented anywhere was the minimum size. Anthropic's own cache-eligibility table lists per-model floors, mostly in the 1,024 to 4,096 token range depending on the model tier. Below that range a cache marker silently does nothing, and the model I tested on isn't even listed in that table yet. My schema-plus-tools prefix landed at 1,804 tokens. That was enough to trigger a real cache write, but the only way I know it is the API's own usage numbers confirming it, not a documented floor I could look up for this specific model. If your schema description is shorter than that, and plenty of narrower single-table agents will be, adding cache_control costs you nothing but also buys you nothing. The only way to know which side of that line you're on is to check cache_creation_input_tokens on the actual response instead of assuming from the byte count of your prompt. How to actually add this The change is genuinely small. Where a system prompt is normally passed as a plain string, wrap it as an array with one text block and a cache marker on that block: const system = cacheEnabled ? [{ type: "text", text: systemPromptText, cache_control: { type: "ephemeral" } }] : systemPromptText; const response = await client.messages.create({ model, max_tokens: 2048, system, tools, messages, }); That's the entire integration, though getting it right in practice took a little longer than the diff suggests. Nothing here breaks loudly. Every mistake below fails silently, which is exactly what makes each one worth calling out. Don't let anything volatile sneak in ahead of the marker. The temptation is to interpolate something like the current date or a user ID into the system prompt for context, but that sits before the breakpoint and invalidates the cache on every request. There's no error for this. Just a cache_creation_input_tokens count that never drops to zero. If you need per-request context, put it in the user message instead, after the cached prefix, not before it. The cost math is the one that actually caught me while building this test. The harness already tracked cache_read_input_tokens and cache_creation_input_tokens in its logging, but the cost calculator only multiplied the plain input_tokens field by the base price. That was fine until this test, because nothing had ever populated those cache fields with a nonzero value before. Anthropic's API response already excludes cached tokens from input_tokens, so a cost function that ignores the cache fields doesn't just miss savings. It silently drops the write premium too and can make caching look cheaper than it actually was. I had to add the 1.25x write multiplier and 0.1x read multiplier back in before the 57% number above meant anything. Check your traffic pattern against the TTL before deciding this is worth it. The default cache window is five minutes, which is fine for a chat session with steady traffic, close to what my sequential 15-question run looked like. If your agent gets one question every twenty minutes instead, the cache goes cold between requests. You end up paying the write premium on nearly every call with no reads to offset it. Anthropic offers a one-hour TTL for exactly that case, at double the write cost. It only pays off if the read volume during that hour is high enough to absorb it. Where this doesn't help None of this matters if your agent's system prompt is short, or if your traffic is too sparse to land within the cache window. It also doesn't help if you're already changing the tool set or system content on every turn, since that resets the cache no matter what else you do. And it's worth saying plainly: a 57% cost drop on one 15-question run against one schema isn't a universal constant. It's what this specific workload produced. The mechanism is general. The percentage isn't something to copy into a slide deck without testing your own prompt. Takeaways What surprised me wasn't that caching worked. Anthropic says it will. It was how little of the "does this actually pay off" question gets answered by reading the pricing page, and how much of it only shows up once you've pointed a real schema at a real API and looked at the actual token counts coming back. The decision rule is simpler than it sounds. Turn the marker on and let a few minutes of real traffic through. Then read cache_creation_input_tokens and cache_read_input_tokens off the response instead of guessing whether it's worth it. A write count that never turns into reads means your traffic is too sparse or your prompt too short, and reverting the one line costs nothing. A write count that stays flat while reads keep climbing means you're looking at savings in the range I measured here, and the four-line change earns a permanent place in the code. That test takes less time than reading this article did.