adds native json output and strict tool call support for the anthropic model - addresses #3428

Author: dsfaccini

docs/models/anthropic.md

@@ -144,3 +144,31 @@ async def main():
     print(f'Cache write tokens: {usage.cache_write_tokens}')
     print(f'Cache read tokens: {usage.cache_read_tokens}')
 ```
+
+## Structured outputs & strict tool calls
+
+Anthropic offers [Structured Outputs](https://docs.claude.com/en/docs/build-with-claude/structured-outputs), which force the model to emit JSON matching a supplied schema and to validate tool inputs before they reach your code. Pydantic AI enables this automatically:
+
+- When you use [`NativeOutput`][pydantic_ai.output.NativeOutput] (or set `output_mode='native'`), the agent sends Anthropic the JSON schema as an `output_format` payload and adds the required `structured-outputs-2025-11-13` beta header. The model's response will be validated just like on other providers, and `result.output` will contain your typed object.
+- Tool definitions that are strict-compatible are sent with `strict: true`, which enables Anthropic's parameter validation. You can opt out for a specific tool by passing `strict=False` to `Tool(...)` or an agent decorator.
+
+```python {test="skip"}
+from pydantic import BaseModel
+from pydantic_ai import Agent, NativeOutput
+from pydantic_ai.models.anthropic import AnthropicModel
+
+
+class Contact(BaseModel):
+    name: str
+    email: str
+
+
+model = AnthropicModel('claude-sonnet-4-5')
+agent = Agent(model, output_type=NativeOutput(Contact))
+result = agent.run_sync('Extract the contact info for Ada Lovelace.')
+print(result.output)
+#> Contact(name='Ada Lovelace', email='[email protected]')
+```
+
+!!! note
+    Pydantic AI automatically sets the beta headers, so you do not need to modify `model_settings.extra_headers`. If you also need to send custom `extra_body` fields, avoid supplying your own `output_format` as it will be generated for you.

docs/output.md

@@ -308,7 +308,7 @@ _(This example is complete, it can be run "as is")_
 
 #### Native Output
 
-Native Output mode uses a model's native "Structured Outputs" feature (aka "JSON Schema response format"), where the model is forced to only output text matching the provided JSON schema. Note that this is not supported by all models, and sometimes comes with restrictions. For example, Anthropic does not support this at all, and Gemini cannot use tools at the same time as structured output, and attempting to do so will result in an error.
+Native Output mode uses a model's native "Structured Outputs" feature (aka "JSON Schema response format"), where the model is forced to only output text matching the provided JSON schema. Note that this is not supported by all models, and sometimes comes with restrictions. For example, Anthropic requires enabling their Structured Outputs beta (Pydantic AI handles the required headers automatically), while Gemini cannot use tools at the same time as structured output, and attempting to do so will result in an error.
 
 To use this mode, you can wrap the output type(s) in the [`NativeOutput`][pydantic_ai.output.NativeOutput] marker class that also lets you specify a `name` and `description` if the name and docstring of the type or function are not sufficient.
 

pydantic_ai_slim/pydantic_ai/models/anthropic.py

@@ -53,6 +53,9 @@
     'refusal': 'content_filter',
 }
 
+# TODO: remove once anthropic moves it out of beta
+_STRUCTURED_OUTPUTS_BETA = 'structured-outputs-2025-11-13'
+
 
 try:
     from anthropic import NOT_GIVEN, APIStatusError, AsyncStream, omit as OMIT
@@ -307,8 +310,10 @@ 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, model_settings)
+        tools, strict_tools_requested = self._get_tools(model_request_parameters, model_settings)
         tools, mcp_servers, beta_features = self._add_builtin_tools(tools, model_request_parameters)
+        output_format = self._build_output_format(model_request_parameters)
+        structured_output_beta_required = strict_tools_requested or bool(output_format)
 
         tool_choice: BetaToolChoiceParam | None
 
@@ -328,10 +333,18 @@ async def _messages_create(
         try:
             extra_headers = model_settings.get('extra_headers', {})
             extra_headers.setdefault('User-Agent', get_user_agent())
-            if beta_features:
-                if 'anthropic-beta' in extra_headers:
-                    beta_features.insert(0, extra_headers['anthropic-beta'])
-                extra_headers['anthropic-beta'] = ','.join(beta_features)
+            if beta_features or structured_output_beta_required:
+                new_features = list(beta_features)
+                if structured_output_beta_required:
+                    new_features.append(_STRUCTURED_OUTPUTS_BETA)
+                extra_headers['anthropic-beta'] = self._format_beta_header(
+                    extra_headers.get('anthropic-beta'),
+                    new_features,
+                )
+
+            extra_body = cast(dict[str, Any] | None, model_settings.get('extra_body'))
+            if output_format is not None:
+                extra_body = self._merge_output_format_extra_body(extra_body, output_format)
 
             return await self.client.beta.messages.create(
                 max_tokens=model_settings.get('max_tokens', 4096),
@@ -349,7 +362,7 @@ async def _messages_create(
                 timeout=model_settings.get('timeout', NOT_GIVEN),
                 metadata=model_settings.get('anthropic_metadata', OMIT),
                 extra_headers=extra_headers,
-                extra_body=model_settings.get('extra_body'),
+                extra_body=extra_body,
             )
         except APIStatusError as e:
             if (status_code := e.status_code) >= 400:
@@ -431,17 +444,20 @@ async def _process_streamed_response(
 
     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()
-        ]
+    ) -> tuple[list[BetaToolUnionParam], bool]:
+        tools: list[BetaToolUnionParam] = []
+        strict_tools_requested = False
+        for tool_def in model_request_parameters.tool_defs.values():
+            tools.append(self._map_tool_definition(tool_def))
+            if tool_def.strict:
+                strict_tools_requested = True
 
         # Add cache_control to the last tool if enabled
         if tools and model_settings.get('anthropic_cache_tool_definitions'):
             last_tool = tools[-1]
             last_tool['cache_control'] = BetaCacheControlEphemeralParam(type='ephemeral')
 
-        return tools
+        return tools, strict_tools_requested
 
     def _add_builtin_tools(
         self, tools: list[BetaToolUnionParam], model_request_parameters: ModelRequestParameters
@@ -759,11 +775,49 @@ async def _map_user_prompt(
 
     @staticmethod
     def _map_tool_definition(f: ToolDefinition) -> BetaToolParam:
-        return {
+        tool_param: BetaToolParam = {
             'name': f.name,
             'description': f.description or '',
             'input_schema': f.parameters_json_schema,
         }
+        if f.strict is not None:
+            tool_param['strict'] = f.strict  # type: ignore[assignment]
+        return tool_param
+
+    @staticmethod
+    def _build_output_format(model_request_parameters: ModelRequestParameters) -> dict[str, Any] | None:
+        if model_request_parameters.output_mode != 'native':
+            return None
+        output_object = model_request_parameters.output_object
+        if output_object is None:
+            return None
+        return {'type': 'json_schema', 'schema': output_object.json_schema}
+
+    @staticmethod
+    def _merge_output_format_extra_body(
+        existing: dict[str, Any] | None, output_format: dict[str, Any]
+    ) -> dict[str, Any]:
+        merged = dict(existing or {})
+        if 'output_format' in merged:
+            raise UserError(
+                '`model_settings.extra_body` cannot define `output_format` when using native structured output.'
+            )
+        merged['output_format'] = output_format
+        return merged
+
+    @staticmethod
+    def _format_beta_header(existing: str | None, new_features: list[str]) -> str:
+        values: list[str] = []
+        if existing:
+            values.extend(value.strip() for value in existing.split(',') if value.strip())
+        values.extend(new_features)
+        ordered: list[str] = []
+        seen: set[str] = set()
+        for value in values:
+            if value not in seen:
+                ordered.append(value)
+                seen.add(value)
+        return ','.join(ordered)
 
 
 def _map_usage(

pydantic_ai_slim/pydantic_ai/profiles/anthropic.py

@@ -1,8 +1,51 @@
 from __future__ import annotations as _annotations
 
+import importlib
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, cast
+
+from .._json_schema import JsonSchema, JsonSchemaTransformer
 from . import ModelProfile
 
+TransformSchemaFunc = Callable[[Any], JsonSchema]
+
+try:  # pragma: no cover
+    _anthropic_module = importlib.import_module('anthropic')
+except Exception:
+    _anthropic_transform_schema: TransformSchemaFunc | None = None
+else:
+    _anthropic_transform_schema = cast(TransformSchemaFunc | None, getattr(_anthropic_module, 'transform_schema', None))
+
+
+@dataclass(init=False)
+class AnthropicJsonSchemaTransformer(JsonSchemaTransformer):
+    """Transforms schemas to the subset supported by Anthropic structured outputs."""
+
+    def walk(self) -> JsonSchema:
+        schema = super().walk()
+        helper = _anthropic_transform_schema
+        if helper is None:
+            return schema
+        try:  # pragma: no branch
+            # helper may raise if schema already transformed
+            transformed = helper(schema)
+        except Exception:
+            return schema
+        if isinstance(transformed, dict):
+            return transformed
+        return schema
+
+    def transform(self, schema: JsonSchema) -> JsonSchema:
+        schema.pop('title', None)
+        schema.pop('$schema', None)
+        return schema
+
 
 def anthropic_model_profile(model_name: str) -> ModelProfile | None:
     """Get the model profile for an Anthropic model."""
-    return ModelProfile(thinking_tags=('<thinking>', '</thinking>'))
+    return ModelProfile(
+        thinking_tags=('<thinking>', '</thinking>'),
+        supports_json_schema_output=True,
+        json_schema_transformer=AnthropicJsonSchemaTransformer,
+    )