Enum Class AnthropicCacheStrategy

java.lang.Object
java.lang.Enum<AnthropicCacheStrategy>
org.springframework.ai.anthropic.api.AnthropicCacheStrategy
All Implemented Interfaces:
Serializable, Comparable<AnthropicCacheStrategy>, Constable
public enum AnthropicCacheStrategy extends Enum<AnthropicCacheStrategy>
Defines the caching strategy for Anthropic prompt caching. Anthropic allows up to 4 cache breakpoints per request, and the cache hierarchy follows the order: tools → system → messages.
Since:
1.1.0
Author:
Mark Pollack, Soby Chacko

  • Enum Constant Details

    • NONE

      public static final AnthropicCacheStrategy NONE
      No caching (default behavior). All content is processed fresh on each request.

      Use this when:

      • Requests are one-off or highly variable
      • Content doesn't meet minimum token requirements (1024+ tokens)
      • You want to avoid caching overhead

    • TOOLS_ONLY

      public static final AnthropicCacheStrategy TOOLS_ONLY
      Cache tool definitions only. Places a cache breakpoint on the last tool, while system messages and conversation history remain uncached and are processed fresh on each request.

      Use this when:

      • Tool definitions are large and stable (5000+ tokens)
      • System prompts change frequently or are small (<500 tokens)
      • You want to share cached tools across different system contexts (e.g., multi-tenant applications, A/B testing system prompts)
      • Tool definitions rarely change

      Important: Changing any tool definition will invalidate this cache entry. Due to Anthropic's cascade invalidation, tool changes will also invalidate any downstream cache breakpoints (system, messages) if used in combination with other strategies.

    • SYSTEM_ONLY

      public static final AnthropicCacheStrategy SYSTEM_ONLY
      Cache system instructions only. Places a cache breakpoint on the system message content. Tools are cached implicitly via Anthropic's automatic ~20-block lookback mechanism (content before the cache breakpoint is included in the cache).

      Use this when:

      • System prompts are large and stable (1024+ tokens)
      • Tool definitions are relatively small (<20 tools)
      • You want simple, single-breakpoint caching

      Note: Changing tools will invalidate the cache since tools are part of the cache prefix (they appear before system in the request hierarchy).

    • SYSTEM_AND_TOOLS

      public static final AnthropicCacheStrategy SYSTEM_AND_TOOLS
      Cache system instructions and tool definitions. Places cache breakpoints on the last tool (breakpoint 1) and system message content (breakpoint 2).

      Use this when:

      • Both tools and system prompts are large and stable
      • You have many tools (20+ tools, beyond the automatic lookback window)
      • You want deterministic, explicit caching of both components
      • System prompts may change independently of tools

      Behavior:

      • If only tools change: Both caches invalidated (tools + system)
      • If only system changes: Tools cache remains valid, system cache invalidated
      This allows efficient reuse of tool cache when only system prompts are updated.

    • CONVERSATION_HISTORY

      public static final AnthropicCacheStrategy CONVERSATION_HISTORY
      Cache the entire conversation history up to (but not including) the current user question. Places a cache breakpoint on the last user message in the conversation history, enabling incremental caching as the conversation grows.

      Use this when:

      • Building multi-turn conversational applications (chatbots, assistants)
      • Conversation history is large and grows over time
      • You want to reuse conversation context while asking new questions
      • Using chat memory advisors or conversation persistence

      Behavior: Each turn builds on the previous cached prefix. The cache grows incrementally: Request 1 caches [Message1], Request 2 caches [Message1 + Message2], etc. This provides significant cost savings (90%+) and performance improvements for long conversations.

      Important: Changing tools or system prompts will invalidate the entire conversation cache due to cascade invalidation. Tool and system stability is critical for this strategy.

  • Method Details

    • values

      public static AnthropicCacheStrategy[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static AnthropicCacheStrategy valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null