Class BedrockSystemMessage

java.lang.Object
dev.langchain4j.model.bedrock.BedrockSystemMessage
All Implemented Interfaces:
ChatMessage
public class BedrockSystemMessage extends Object implements ChatMessage
AWS Bedrock-specific system message supporting granular cache points.

Unlike the core SystemMessage which contains a single text block, this class supports multiple content blocks, each with an optional cache point. This enables caching static portions (instructions, examples) while keeping dynamic portions (user context) uncached.

Example usage: 

BedrockSystemMessage systemMessage = BedrockSystemMessage.builder()
    .addText("You are an AI assistant.")
    .addTextWithCachePoint("Here are 50 examples:\n" + examples)  // Cached
    .addText("Current user: " + userName)  // Not cached
    .build();

AWS Bedrock Caching Requirements:

  • Minimum tokens: ~1,024 tokens required for caching to activate
  • Cache TTL: 5-minute default, resets on each cache hit
  • Supported models: Only Claude 3.x and Amazon Nova models
  • Maximum cache points: AWS limits to 4 cache points per request (across all messages including system, user, and tool definitions)

Important limitations:

  • Serialization: This message type is NOT compatible with standard ChatMessageSerializer. If using ChatMemory with persistence, convert to SystemMessage first using toSystemMessage() (cache points will be lost).
  • ChatMemory window: MessageWindowChatMemory and TokenWindowChatMemory will NOT recognize this as a system message for window management (they use instanceof SystemMessage).
  • Static helpers: SystemMessage.findFirst(), findAll(), findLast() will NOT find BedrockSystemMessage instances.
  • Type checking: type() returns ChatMessageType.SYSTEM, but this class does NOT extend SystemMessage. Always use instanceof checks rather than type() checks. WARNING: Code using message.type() == ChatMessageType.SYSTEM will match this class, but code using instanceof SystemMessage will NOT. The codebase has many places using instanceof SystemMessage that will silently ignore BedrockSystemMessage instances.

Thread Safety: Instances of this class are immutable and thread-safe. The BedrockSystemMessage.Builder is NOT thread-safe and should not be shared between threads.

Since:
1.11.0
See Also:

  • Field Details

    • MAX_CONTENT_BLOCKS

      public static final int MAX_CONTENT_BLOCKS
      Maximum number of content blocks per message.
      See Also:

    • MAX_CACHE_POINTS

      public static final int MAX_CACHE_POINTS
      Maximum number of cache points allowed by AWS Bedrock per request.
      See Also:

  • Method Details

    • contents

      public List<BedrockSystemContent> contents()
      Returns an unmodifiable list of content blocks.
      Returns:
      the content blocks

    • type

      public ChatMessageType type()
      Returns ChatMessageType.SYSTEM.

      Note: While this returns SYSTEM, this class does NOT extend SystemMessage. Always use instanceof checks for type safety.

      Specified by:
      type in interface ChatMessage
      Returns:
      ChatMessageType.SYSTEM

    • text

      public String text()
      Returns combined text from all text content blocks, joined by double newlines. Useful for logging or conversion to core SystemMessage.
      Returns:
      combined text from all blocks

    • hasSingleText

      public boolean hasSingleText()
      Returns true if this message contains exactly one text content block.
      Returns:
      true if single text block

    • singleText

      public String singleText()
      Returns text from single content block.
      Returns:
      the single text content
      Throws:
      IllegalStateException - if message has multiple content blocks

    • toSystemMessage

      public SystemMessage toSystemMessage()
      Converts to core SystemMessage (loses cache point information). Use this for ChatMemory persistence where serialization is required.
      Returns:
      equivalent SystemMessage (without cache points)

    • toBuilder

      public BedrockSystemMessage.Builder toBuilder()
      Creates a new builder initialized with this message's contents.
      Returns:
      new builder with current contents

    • builder

      public static BedrockSystemMessage.Builder builder()
      Creates a new builder.
      Returns:
      new builder

    • from

      public static BedrockSystemMessage from(String text)
      Creates a simple message with single text content (no cache point).
      Parameters:
      text - the text content
      Returns:
      new BedrockSystemMessage

    • from

      public static BedrockSystemMessage from(List<BedrockSystemContent> contents)
      Creates a message from list of content blocks.
      Parameters:
      contents - the content blocks
      Returns:
      new BedrockSystemMessage

    • from

      public static BedrockSystemMessage from(SystemMessage systemMessage)
      Converts a core SystemMessage to BedrockSystemMessage (no cache point).
      Parameters:
      systemMessage - the core system message
      Returns:
      new BedrockSystemMessage

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • hasCachePoints

      public boolean hasCachePoints()
      Returns true if any content block has a cache point marker.
      Returns:
      true if this message contains any cache points

    • cachePointCount

      public int cachePointCount()
      Returns the number of cache points in this message.
      Returns:
      the cache point count

    • toString

      public String toString()
      Overrides:
      toString in class Object