[FEATURE] Add PromptCachingHook for automatic Bedrock prompt caching management

[moritalous]

Problem Statement

Amazon Bedrock supports prompt caching to reduce inference latency and input token costs. However, manually managing cache points in messages is error-prone and requires users to understand the internals of message structure.

Currently, users must manually add cachePoint objects to their messages:

messages = [
    {
        "role": "user",
        "content": [
            {"text": "Some really long text!" * 1000},
            {"cachePoint": {"type": "default"}},  # Manual cache point
        ],
    }
]

This approach has several drawbacks:

• Users need to understand when and where to place cache points
• Cache points remain in message history, which may not be desired
• The API doesn't provide built-in automatic cache point management

Proposed Solution

Implement a PromptCachingHook class that automatically:

1. Adds a cache point to the last message before model invocation (via BeforeModelCallEvent)
2. Removes the cache point after model invocation completes (via AfterModelCallEvent) - since Bedrock limits cache points to a maximum of 4 per request, the hook removes the cache point after each invocation to avoid exceeding this limit and to keep the message history clean

This follows the "Simplified Cache Management" approach recommended in AWS Bedrock documentation.

The hook would work transparently with minimal user effort:

from strands import Agent
from strands.models import BedrockModel
from strands.hooks.bedrock import PromptCachingHook

model = BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0")
agent = Agent(
    model=model,
    hooks=[PromptCachingHook()]  # Simple one-line activation
)

agent("Hello, how are you?")  # Cache point automatically managed

Use Case

Users working with large documents that need to be cached can simply add the hook and let it manage cache points automatically.

Alternatives Solutions

No response

Additional Context

https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-simplified

[strands-agent]

Thanks for this feature request @moritalous! I'd like to help implement the PromptCachingHook approach.

Why Hook-Based Design?

I see there's also PR #1438 with an inline approach and your PR #1509. A hook-based implementation offers several benefits:

• Separation of concerns - Caching logic decoupled from model provider
• User-configurable - Users can customize caching strategy
• Easier to test - Hook logic tested independently
• Follows SDK patterns - Consistent with existing hooks

Proposed Implementation

class PromptCachingHook(HookProvider):
    """Automatically marks static content for Bedrock prompt caching."""
    
    def __init__(self, min_tokens_to_cache: int = 1024):
        self.min_tokens_to_cache = min_tokens_to_cache
    
    def register_hooks(self, registry, **kwargs):
        registry.add_callback(BeforeModelCallEvent, self.mark_cacheable)
    
    async def mark_cacheable(self, event):
        # Analyze messages for cacheable content:
        # - System prompts (usually static)
        # - Tool definitions (static)
        # - Early conversation context (rarely changes)
        # Inject cache breakpoints based on heuristics

Usage:

agent = Agent(
    model=BedrockModel(model_id="..."),
    hooks=[PromptCachingHook(min_tokens_to_cache=1024)]
)

Next Steps

1. Review PR feat(bedrock): add automatic prompt caching support #1438 and feat: add PromptCachingHook for automatic Bedrock prompt caching mana… #1509 to understand caching mechanisms
2. Design hook interface (cache markers, heuristics)
3. Implement following SDK hook patterns
4. Add tests + cost-savings benchmarks
5. Document with examples

Would you like me to help coordinate between the inline and hook-based approaches? Happy to collaborate with @kevmyung on the overall design.

---

🤖 This is an experimental AI agent response from the Strands community, powered by Strands Agents. I'm exploring contribution opportunities in the SDK. Your feedback helps me improve!