Anthropic Prompt Caching: Fix SYSTEM_ONLY cache strategy to not explicitly cache tools

This commit fixes a bug where the SYSTEM_ONLY cache strategy was incorrectly placing cache_control on tool definitions, making it functionally identical to SYSTEM_AND_TOOLS. Problem: - SYSTEM_ONLY and SYSTEM_AND_TOOLS both placed cache breakpoints on tools AND system messages, using 2 breakpoints - This violated the documented behavior and wasted breakpoints - The strategies were functionally identical Root Cause: - CacheEligibilityResolver.resolveToolCacheControl() checked if eligible message types included SYSTEM, which both strategies have - It should have checked the strategy directly instead Solution: - Changed resolveToolCacheControl() to use allowlist approach - Only SYSTEM_AND_TOOLS and CONVERSATION_HISTORY explicitly cache tools - SYSTEM_ONLY now places cache_control only on system message - Tools still get cached implicitly via Anthropic's cache hierarchy (tools → system → messages) Impact: - SYSTEM_ONLY: Uses 1 breakpoint (system only) instead of 2 - SYSTEM_AND_TOOLS: Uses 2 breakpoints (last tool + system) as before - Users can now optimize breakpoint usage more effectively Changes: - Fix CacheEligibilityResolver.resolveToolCacheControl() to check strategy directly instead of eligible message types - Enhance testSystemOnlyCacheStrategy() to include tools and verify they don't have cache_control - Update toolCacheControlRespectsStrategy() test to verify all strategies behave correctly Signed-off-by: Soby Chacko <soby.chacko@broadcom.com>

Author: sobychacko

models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/api/utils/CacheEligibilityResolver.java

@@ -108,11 +108,16 @@ public AnthropicApi.ChatCompletionRequest.CacheControl resolve(MessageType messa
 }
 
 public AnthropicApi.ChatCompletionRequest.CacheControl resolveToolCacheControl() {
-// Tool definitions are only cache-eligible when caching is enabled and
-// the strategy includes SYSTEM messages (SYSTEM_ONLY, SYSTEM_AND_TOOLS, or
-// CONVERSATION_HISTORY). When NONE, tools must not be cached.
-if (!isCachingEnabled() || !this.cacheEligibleMessageTypes.contains(TOOL_DEFINITION_MESSAGE_TYPE)
-|| this.cacheBreakpointTracker.allBreakpointsAreUsed()) {
+// Tool definitions are only cache-eligible for SYSTEM_AND_TOOLS and
+// CONVERSATION_HISTORY strategies. SYSTEM_ONLY caches only system messages,
+// relying on Anthropic's cache hierarchy to implicitly cache tools.
+if (this.cacheStrategy != AnthropicCacheStrategy.SYSTEM_AND_TOOLS
+&& this.cacheStrategy != AnthropicCacheStrategy.CONVERSATION_HISTORY) {
+logger.debug("Caching not enabled for tool definition, cacheStrategy={}", this.cacheStrategy);
+return null;
+}
+
+if (this.cacheBreakpointTracker.allBreakpointsAreUsed()) {
 logger.debug("Caching not enabled for tool definition, usedBreakpoints={}",
 this.cacheBreakpointTracker.getCount());
 return null;

models/spring-ai-anthropic/src/test/java/org/springframework/ai/anthropic/AnthropicPromptCachingMockTest.java

@@ -104,9 +104,17 @@ void testSystemOnlyCacheStrategy() throws Exception {
 this.mockWebServer
 .enqueue(new MockResponse().setBody(mockResponse).setHeader("Content-Type", "application/json"));
 
+// Create tool callback to test that tools are NOT cached with SYSTEM_ONLY
+var toolMethod = ReflectionUtils.findMethod(TestTools.class, "getWeather", String.class);
+MethodToolCallback toolCallback = MethodToolCallback.builder()
+.toolDefinition(ToolDefinitions.builder(toolMethod).description("Get weather for a location").build())
+.toolMethod(toolMethod)
+.build();
+
 // Test with SYSTEM_ONLY cache strategy
 AnthropicChatOptions options = AnthropicChatOptions.builder()
 .cacheOptions(AnthropicCacheOptions.builder().strategy(AnthropicCacheStrategy.SYSTEM_ONLY).build())
+.toolCallbacks(List.of(toolCallback))
 .build();
 
 Prompt prompt = new Prompt(
@@ -130,6 +138,18 @@ void testSystemOnlyCacheStrategy() throws Exception {
 assertThat(lastSystemBlock.get("cache_control").get("type").asText()).isEqualTo("ephemeral");
 }
 
+// Verify tools exist but DO NOT have cache_control (key difference from
+// SYSTEM_AND_TOOLS)
+if (requestBody.has("tools")) {
+JsonNode toolsArray = requestBody.get("tools");
+assertThat(toolsArray.isArray()).isTrue();
+// Verify NO tool has cache_control
+for (int i = 0; i < toolsArray.size(); i++) {
+JsonNode tool = toolsArray.get(i);
+assertThat(tool.has("cache_control")).isFalse();
+}
+}
+
 // Verify response
 assertThat(response).isNotNull();
 assertThat(response.getResult().getOutput().getText()).contains("Hello!");

models/spring-ai-anthropic/src/test/java/org/springframework/ai/anthropic/api/utils/CacheEligibilityResolverTests.java

@@ -78,14 +78,26 @@ void toolCacheControlRespectsStrategy() {
 .from(AnthropicCacheOptions.builder().strategy(AnthropicCacheStrategy.NONE).build());
 assertThat(none.resolveToolCacheControl()).isNull();
 
-// SYSTEM_ONLY -> tool caching enabled (uses SYSTEM TTL)
+// SYSTEM_ONLY -> no explicit tool caching (tools cached implicitly via hierarchy)
 CacheEligibilityResolver sys = CacheEligibilityResolver.from(AnthropicCacheOptions.builder()
 .strategy(AnthropicCacheStrategy.SYSTEM_ONLY)
 .messageTypeTtl(MessageType.SYSTEM, AnthropicCacheTtl.ONE_HOUR)
 .build());
-var cc = sys.resolveToolCacheControl();
+assertThat(sys.resolveToolCacheControl()).isNull();
+
+// SYSTEM_AND_TOOLS -> tool caching enabled (uses SYSTEM TTL)
+CacheEligibilityResolver sysAndTools = CacheEligibilityResolver.from(AnthropicCacheOptions.builder()
+.strategy(AnthropicCacheStrategy.SYSTEM_AND_TOOLS)
+.messageTypeTtl(MessageType.SYSTEM, AnthropicCacheTtl.ONE_HOUR)
+.build());
+var cc = sysAndTools.resolveToolCacheControl();
 assertThat(cc).isNotNull();
 assertThat(cc.ttl()).isEqualTo(AnthropicCacheTtl.ONE_HOUR.getValue());
+
+// CONVERSATION_HISTORY -> tool caching enabled
+CacheEligibilityResolver history = CacheEligibilityResolver
+.from(AnthropicCacheOptions.builder().strategy(AnthropicCacheStrategy.CONVERSATION_HISTORY).build());
+assertThat(history.resolveToolCacheControl()).isNotNull();
 }
 
 }