feat(bedrock): add TTL support to auto-injected tool and system/user cache points

[kpx-dev]

Description

Extends prompt caching TTL coverage beyond the user-supplied cachePoint path (already fixed in #1660) to the two SDK-managed auto-injected paths on BedrockModel.

Previously, only cache points that users passed directly inside message content could carry a ttl field — the formatter preserved it end-to-end. However, when the SDK auto-injected cache points on the user's behalf, the ttl was hardcoded away:

1. cache_tools — BedrockModel(cache_tools="default") appends {"cachePoint": {"type": "default"}} to toolConfig.tools with no way to set a TTL.
2. _inject_cache_point — when cache_config=CacheConfig(strategy="auto") is set, the SDK appends {"cachePoint": {"type": "default"}} to the last user message with no way to set a TTL.

Because Bedrock processes cache checkpoints in order toolConfig → system → messages and requires TTLs to be non-increasing, a user who wanted to run 1h caching end-to-end could not — the SDK-managed checkpoints would implicitly be 5m and violate the ordering rule (see #2121 Bug 2).

Changes

• BedrockModel: added cache_tools_ttl: str | None config option. When set together with cache_tools, the TTL is propagated into the toolConfig cache point.
• CacheConfig: added ttl: str | None field. When set, _inject_cache_point includes the TTL in the cache point appended to the last user message.

Users can now align all three cache checkpoint TTLs consistently:

from strands.models.bedrock import BedrockModel
from strands.models.model import CacheConfig

model = BedrockModel(
    model_id="us.anthropic.claude-haiku-4-5-20251001-v1:0",
    cache_tools="default",
    cache_tools_ttl="1h",
    cache_config=CacheConfig(strategy="auto", ttl="1h"),
)

API reference: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_CachePointBlock.html
Launch announcement: https://aws.amazon.com/about-aws/whats-new/2026/01/amazon-bedrock-one-hour-duration-prompt-caching/

Related Issues

Closes #1243 (longer TTL for prompt caching) — together with the already-merged #1660 (user-supplied cachePoint.ttl), this PR completes TTL coverage across all three Bedrock cache checkpoint paths (toolConfig, system, messages), so users can opt into Bedrock's 1h TTL end-to-end.

Partially addresses #2121 (Bug 2: cache_tools ordering violation with 1h TTL). Bug 1 from #2121 (user-supplied ttl being dropped) was resolved by #1660.

Documentation PR

Type of Change

New feature

Testing

Added 4 unit tests:

• test_inject_cache_point_with_ttl — verifies CacheConfig(ttl="5m") propagates into the auto-injected message cache point.
• test_inject_cache_point_without_ttl — backward compat: CacheConfig(strategy="auto") with no TTL still works.
• test_format_request_cache_tools_with_ttl — verifies cache_tools_ttl propagates into toolConfig cache point.
• test_format_request_cache_tools_without_ttl — backward compat: cache_tools without TTL still works.

Verified:

• I ran hatch run prepare (lint, format, mypy all clean; pre-existing local env test failures unrelated to this change)
• All 4 new tests pass

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[kpx-dev]

Added 3 integration tests covering the new paths. Ran locally against us-east-1 with us.anthropic.claude-haiku-4-5-20251001-v1:0:

tests_integ/models/test_model_bedrock.py::test_prompt_caching_cache_tools_ttl               PASSED
tests_integ/models/test_model_bedrock.py::test_prompt_caching_cache_config_auto_with_ttl    PASSED
tests_integ/models/test_model_bedrock.py::test_prompt_caching_aligned_1h_ttl_across_checkpoints  PASSED

Coverage matrix:

Test	What it proves
test_prompt_caching_cache_tools_ttl	cache_tools_ttl is accepted by Bedrock on the toolConfig cache checkpoint without ValidationException.
test_prompt_caching_cache_config_auto_with_ttl	CacheConfig(strategy="auto", ttl="5m") propagates TTL to the auto-injected message cache point and produces a cacheWrite.
test_prompt_caching_aligned_1h_ttl_across_checkpoints	Regression test for #2121: 1h TTL on all three cache checkpoints (toolConfig → system → messages) satisfies Bedrock's non-increasing TTL ordering rule. This was the specific scenario that was impossible before this PR.

[kpx-dev]

@mkmeral this is an addition to merged PR #1660

can the team help review this PR? Thanks!

[pgrayy]

I would recommend expanding the type of cache_tools to ensure that ttl is configured with the cache tools type. So something like:

cache_tools: str | CacheToolsConfig | None
...
@dataclass
class CacheToolsConfig:
    type: str = "default"
    ttl: str | None = None

[kpx-dev]

Good call — refactored in cc32ea8. Added a CacheToolsConfig dataclass with type (default "default") and ttl fields, and changed cache_tools to str | CacheToolsConfig | None. Removed the standalone cache_tools_ttl field so TTL can only be set together with the type. The plain str form still works for back-compat.

BedrockModel(cache_tools=CacheToolsConfig(type="default", ttl="1h"))
# or, unchanged:
BedrockModel(cache_tools="default")

[pgrayy]

I would recommend defining and exporting this from model.py for consistency with CacheConfig.

[kpx-dev]

Resolved by 8759076 — went with your other suggestion (drop CacheToolsConfig entirely and reuse cache_config.ttl for the tool checkpoint), so there's no new dataclass to move.

[pgrayy]

Does this mean you can't have say 5m for tools and 1h for messages? But the opposite would be allowed since it would be decreasing? Do you have a link to the docs that outlines these rules?

[kpx-dev]

Good point — pivoted in 8759076. Dropped CacheToolsConfig entirely. The toolConfig cache point now picks up its TTL from cache_config.ttl, so a single knob covers both SDK-managed checkpoints. Bedrock's non-increasing rule is satisfied trivially since both checkpoints share one value.

BedrockModel(
    cache_tools="default",
    cache_config=CacheConfig(strategy="auto", ttl="1h"),
)
# toolConfig cache point AND last-user-message cache point both get ttl="1h"

This also resolves your other comment about moving the dataclass to model.py — there's no new dataclass to move now.