[FEATURE] Prompt Caching Support in Claude Agent SDK

[rajeshwarmanthena]

[Feature Request] Support Bedrock Prompt Caching in Claude Agent SDK

Description

I am currently using the Claude Agent SDK with Amazon Bedrock as the model provider. I am unable to enable Prompt Caching via the SDK because the current ClaudeAgentOptions (and the underlying Bedrock provider) do not support the injection of cache control metadata into the message payload.

To leverage Bedrock's prompt caching, the payload must allow for cache_control or cachePoint blocks within the messages or system prompts.

Proposed Change

Update the ClaudeAgentOptions and the Bedrock model provider logic to support the following structures in the request payload:

For Ephemeral Caching:

"cache_control": {
    "type": "ephemeral"
}

For Cache Points:

"cachePoint": {
    "type": "default"
}

---

1. Documentation Links

• Main Guide: Amazon Bedrock Prompt Caching User Guide
• API Reference: Amazon Bedrock Runtime - InvokeModel
• Model Specifics: Anthropic Claude Models on Bedrock

---

[yaniv5678]

Hi,
So that means that by default prompt caching won't work for Claude Agent SDK + Bedrock?

[ottowatt]

Please prioritize this, thanks

[adtendo]

+1 with empirical data from the Anthropic-API provider side (not Bedrock), which I believe strengthens the cross-provider case for this feature.

We migrated an LLM pipeline (synthetic-persona project, ~5 callers across reply + posting + classifier paths) from direct anthropic.Anthropic().messages.create() to claude_agent_sdk.query() to take advantage of the Max subscription credit pool. The migration works as intended for cost-pool routing, but the inability to attach cache_control to a custom system_prompt: str has two observable consequences in our usage logs:

1. Zero cache hits across all post-migration calls

Across 161 post-migration calls covering 4 actions (relevance_3d, draft_validation, draft_perspectives, draft_orchestrate):

• cache_creation_input_tokens: 0 in every row
• cache_read_input_tokens: 0 in every row

Same system prompts were re-used hundreds of times — clear caching candidate, no caching happening.

2. Output-token inflation (separate but related concern)

Median output tokens, pre-migration (direct SDK) vs post-migration (Agent SDK), same system prompts, same models:

Action	Pre (direct SDK)	Post (Agent SDK)	Factor
draft_orchestrate	256	2393	9.35×
draft_perspectives	662	3738	5.65×
relevance_3d	323	1767	5.47×

(N: 135/6, 135/6, 1040/14 — post-sample is small but factor is reproducible across three independent actions.)

I assume this is intentional (agentic-loop architecture emits intermediate reasoning that the direct SDK omits), but it compounds the cost asymmetry: not only is caching unavailable, but the per-call output cost is also higher. With caching restored on the input side, the asymmetry would be much more tolerable.

Concrete API ask

The SystemPromptPreset variant with exclude_dynamic_sections: True already documents a caching mechanism ("stays static and cacheable across users") for the claude_code preset. Extending the same primitive to custom system_prompt: str (either by accepting list[dict] with native cache_control blocks, or by adding an opt-in cache_system_prompt: bool to ClaudeAgentOptions) would close the gap with zero conceptual overhead for users already familiar with the underlying Messages API.

Happy to provide redacted usage-log samples if helpful.