Add anthropic_cache_tools and anthropic_cache_instructions settings

This commit addresses maintainer feedback on the Anthropic prompt caching PR:

- Add anthropic_cache_tools field to cache last tool definition
- Add anthropic_cache_instructions field to cache system prompts
- Rewrite existing CachePoint tests to use snapshot() assertions
- Add comprehensive tests for new caching settings
- Remove standalone example file, add docs section instead
- Move imports to top of test files
- Remove ineffective Google CachePoint test
- Add "Supported by: Anthropic" to CachePoint docstring
- Add Anthropic docs link in cache_control method

Tests are written but snapshots not yet generated (will be done in next commit).

Author: ronakrm

docs/models/anthropic.md

@@ -77,3 +77,111 @@ model = AnthropicModel(
 agent = Agent(model)
 ...
 ```
+
+## Prompt Caching
+
+Anthropic supports [prompt caching](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching) to reduce costs by caching parts of your prompts. PydanticAI provides three ways to use prompt caching:
+
+### 1. Cache User Messages with `CachePoint`
+
+Insert a [`CachePoint`][pydantic_ai.messages.CachePoint] marker in your user messages to cache everything before it:
+
+```python
+from pydantic_ai import Agent, CachePoint
+
+agent = Agent('anthropic:claude-sonnet-4-5')
+
+# Everything before CachePoint will be cached
+result = await agent.run([
+    "Long context that should be cached...",
+    CachePoint(),
+    "Your question here"
+])
+```
+
+### 2. Cache System Instructions
+
+Use `anthropic_cache_instructions=True` to cache your system prompt:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.anthropic import AnthropicModelSettings
+
+agent = Agent(
+    'anthropic:claude-sonnet-4-5',
+    system_prompt='Long detailed instructions...',
+    model_settings=AnthropicModelSettings(
+        anthropic_cache_instructions=True
+    ),
+)
+
+result = await agent.run("Your question")
+```
+
+### 3. Cache Tool Definitions
+
+Use `anthropic_cache_tools=True` to cache your tool definitions:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.anthropic import AnthropicModelSettings
+
+agent = Agent(
+    'anthropic:claude-sonnet-4-5',
+    model_settings=AnthropicModelSettings(
+        anthropic_cache_tools=True
+    ),
+)
+
+@agent.tool
+def my_tool() -> str:
+    """Tool definition will be cached."""
+    return "result"
+
+result = await agent.run("Use the tool")
+```
+
+### Combining Cache Strategies
+
+You can combine all three caching strategies for maximum savings:
+
+```python
+from pydantic_ai import Agent, CachePoint
+from pydantic_ai.models.anthropic import AnthropicModelSettings
+
+agent = Agent(
+    'anthropic:claude-sonnet-4-5',
+    system_prompt='Detailed instructions...',
+    model_settings=AnthropicModelSettings(
+        anthropic_cache_instructions=True,
+        anthropic_cache_tools=True,
+    ),
+)
+
+@agent.tool
+def search_docs(query: str) -> str:
+    """Search documentation."""
+    return f"Results for {query}"
+
+# First call - writes to cache
+result1 = await agent.run([
+    "Long context from documentation...",
+    CachePoint(),
+    "First question"
+])
+
+# Subsequent calls - read from cache (90% cost reduction)
+result2 = await agent.run([
+    "Long context from documentation...",  # Same content
+    CachePoint(),
+    "Second question"
+])
+```
+
+Access cache usage statistics via `result.usage()`:
+
+```python
+usage = result.usage()
+print(f"Cache write tokens: {usage.cache_write_tokens}")
+print(f"Cache read tokens: {usage.cache_read_tokens}")
+```

examples/pydantic_ai_examples/anthropic_prompt_caching.py

@@ -618,6 +618,10 @@ class CachePoint:
 
     Can be inserted into UserPromptPart.content to mark cache boundaries.
     Models that don't support caching will filter these out.
+
+    Supported by:
+
+    - Anthropic
     """
 
     kind: Literal['cache-point'] = 'cache-point'

pydantic_ai_slim/pydantic_ai/messages.py

@@ -150,6 +150,22 @@ class AnthropicModelSettings(ModelSettings, total=False):
     See [the Anthropic docs](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking) for more information.
     """
 
+    anthropic_cache_tools: bool
+    """Whether to add cache_control to the last tool definition.
+
+    When enabled, the last tool in the tools array will have cache_control set,
+    allowing Anthropic to cache tool definitions and reduce costs.
+    See https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching for more information.
+    """
+
+    anthropic_cache_instructions: bool
+    """Whether to add cache_control to the last system prompt block.
+
+    When enabled, the last system prompt will have cache_control set,
+    allowing Anthropic to cache system instructions and reduce costs.
+    See https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching for more information.
+    """
+
 
 @dataclass(init=False)
 class AnthropicModel(Model):
@@ -291,7 +307,7 @@ async def _messages_create(
         model_request_parameters: ModelRequestParameters,
     ) -> BetaMessage | AsyncStream[BetaRawMessageStreamEvent]:
         # standalone function to make it easier to override
-        tools = self._get_tools(model_request_parameters)
+        tools = self._get_tools(model_request_parameters, model_settings)
         tools, mcp_servers, beta_features = self._add_builtin_tools(tools, model_request_parameters)
 
         tool_choice: BetaToolChoiceParam | None
@@ -307,7 +323,7 @@ async def _messages_create(
             if (allow_parallel_tool_calls := model_settings.get('parallel_tool_calls')) is not None:
                 tool_choice['disable_parallel_tool_use'] = not allow_parallel_tool_calls
 
-        system_prompt, anthropic_messages = await self._map_message(messages, model_request_parameters)
+        system_prompt, anthropic_messages = await self._map_message(messages, model_request_parameters, model_settings)
 
         try:
             extra_headers = model_settings.get('extra_headers', {})
@@ -413,8 +429,19 @@ async def _process_streamed_response(
             _provider_url=self._provider.base_url,
         )
 
-    def _get_tools(self, model_request_parameters: ModelRequestParameters) -> list[BetaToolUnionParam]:
-        return [self._map_tool_definition(r) for r in model_request_parameters.tool_defs.values()]
+    def _get_tools(
+        self, model_request_parameters: ModelRequestParameters, model_settings: AnthropicModelSettings
+    ) -> list[BetaToolUnionParam]:
+        tools: list[BetaToolUnionParam] = [
+            self._map_tool_definition(r) for r in model_request_parameters.tool_defs.values()
+        ]
+
+        # Add cache_control to the last tool if enabled
+        if tools and model_settings.get('anthropic_cache_tools'):
+            last_tool = cast(dict[str, Any], tools[-1])
+            last_tool['cache_control'] = BetaCacheControlEphemeralParam(type='ephemeral')
+
+        return tools
 
     def _add_builtin_tools(
         self, tools: list[BetaToolUnionParam], model_request_parameters: ModelRequestParameters
@@ -466,8 +493,11 @@ def _add_builtin_tools(
         return tools, mcp_servers, beta_features
 
     async def _map_message(  # noqa: C901
-        self, messages: list[ModelMessage], model_request_parameters: ModelRequestParameters
-    ) -> tuple[str, list[BetaMessageParam]]:
+        self,
+        messages: list[ModelMessage],
+        model_request_parameters: ModelRequestParameters,
+        model_settings: AnthropicModelSettings,
+    ) -> tuple[str | list[BetaTextBlockParam], list[BetaMessageParam]]:
         """Just maps a `pydantic_ai.Message` to a `anthropic.types.MessageParam`."""
         system_prompt_parts: list[str] = []
         anthropic_messages: list[BetaMessageParam] = []
@@ -642,11 +672,24 @@ async def _map_message(  # noqa: C901
         if instructions := self._get_instructions(messages, model_request_parameters):
             system_prompt_parts.insert(0, instructions)
         system_prompt = '\n\n'.join(system_prompt_parts)
+
+        # If anthropic_cache_instructions is enabled, return system prompt as a list with cache_control
+        if system_prompt and model_settings.get('anthropic_cache_instructions'):
+            system_prompt_blocks = [
+                BetaTextBlockParam(
+                    type='text', text=system_prompt, cache_control=BetaCacheControlEphemeralParam(type='ephemeral')
+                )
+            ]
+            return system_prompt_blocks, anthropic_messages
+
         return system_prompt, anthropic_messages
 
     @staticmethod
     def _add_cache_control_to_last_param(params: list[BetaContentBlockParam]) -> None:
-        """Add cache control to the last content block param."""
+        """Add cache control to the last content block param.
+
+        See https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching for more information.
+        """
         if not params:
             raise UserError(
                 'CachePoint cannot be the first content in a user message - there must be previous content to attach the CachePoint to.'