[DOCS] Clarify and standardize usage of 1-hour Cache Lifetime in SDK documentation and examples

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://platform.claude.com/docs/en/about-claude/pricing - https://platform.claude.com/docs/en/build-with-claude/prompt-caching - https://platform.claude.com/docs/en/agent-sdk/python

Section/Topic

The configuration of Prompt Caching TTL (Time-to-Live), specifically the 1-hour cache duration tier.

Current Documentation

The Pricing page explicitly lists a "1h Cache Writes" tier with distinct pricing. The Prompt Caching guide mentions:

"By default, the cache has a 5-minute lifetime... Anthropic also offers a 1-hour cache duration at additional cost."

However, nearly all "how-to" examples in the documentation and the Python SDK README use the simplified syntax:
"cache_control": {"type": "ephemeral"}

What's Wrong or Missing?

There is a disconnect between the billing capabilities and the instructional examples. While the types.py file in the Python SDK correctly defines ttl as optional "5m" or "1h", the documentation fails to prominently feature the syntax required to access the 1-hour tier.

For long-running agents (the primary use case for the Agent SDK), a 5-minute cache is often too short for complex task loops. Developers rely on the documentation's "Quick Start" and "Basic Usage" snippets, which currently omit the ttl parameter, leading to unexpected cache evictions and higher costs for long-horizon tasks.

Suggested Improvement

Update the Prompt Caching guide and the Agent SDK Python reference to include explicit examples of the 1-hour TTL syntax.

Suggested example addition for the Python SDK:

# Enable 1-hour cache for long-running agent workflows
system_prompt=[
    {
        "type": "text",
        "text": "Extremely long technical documentation...",
        "cache_control": {"type": "ephemeral", "ttl": "1h"}
    }
]

Additionally, the "Best practices for effective caching" section should explicitly recommend the 1-hour TTL for Agent SDK users who are performing multi-step iterations that exceed 5 minutes.

Impact

High - Prevents users from using a feature

Additional Context

• In src/claude_agent_sdk/types.py, the CacheControlEphemeral class correctly supports ttl, but this isn't reflected in the high-level README.md or examples/system_prompt.py.
• Related documentation on extended thinking notes that thinking tasks often take longer than 5 minutes, yet the example there doesn't show the 1-hour TTL configuration.

---