Auto-enable Anthropic Files API beta when messages contain UploadedFile (#5815)

Co-authored-by: Aditya Vardhan <76904033+adtyavrdhn@users.noreply.github.com>
Co-authored-by: adtyavrdhn <aditya@pydantic.dev>

Author: 3 people

docs/input.md

@@ -218,12 +218,12 @@ The `media_type` parameter is optional for [`UploadedFile`][pydantic_ai.messages
 Follow the [Anthropic Files API docs](https://docs.anthropic.com/en/docs/build-with-claude/files) to upload files. You can access the underlying Anthropic client via `provider.client`.
 
 !!! note "Beta Feature"
-    The Anthropic Files API is currently in beta. You need to include the beta header `anthropic-beta: files-api-2025-04-14` when making requests.
+    The Anthropic Files API is currently in beta. `AnthropicModel` automatically adds the required `anthropic-beta: files-api-2025-04-14` header when a request contains an Anthropic [`UploadedFile`][pydantic_ai.messages.UploadedFile], so you don't need to set it yourself.
 
 ```py {title="uploaded_file_anthropic.py" test="skip"}
 import asyncio
 
-from pydantic_ai import Agent, ModelSettings, UploadedFile
+from pydantic_ai import Agent, UploadedFile
 from pydantic_ai.models.anthropic import AnthropicModel
 from pydantic_ai.providers.anthropic import AnthropicProvider
 
@@ -236,14 +236,13 @@ async def main():
     with open('document.pdf', 'rb') as f:
         uploaded_file = await provider.client.beta.files.upload(file=f)
 
-    # Reference the uploaded file, including the required beta header
+    # Reference the uploaded file; the beta header is added automatically
     agent = Agent(model)
     result = await agent.run(
         [
             'Summarize this document',
             UploadedFile(file_id=uploaded_file.id, provider_name=model.system),
-        ],
-        model_settings=ModelSettings(extra_headers={'anthropic-beta': 'files-api-2025-04-14'}),
+        ]
     )
     print(result.output)
     #> The document discusses the main topics and key findings...

pydantic_ai_slim/pydantic_ai/models/anthropic.py

@@ -255,6 +255,7 @@
 
 _ANTHROPIC_SAMPLING_PARAMS = ('temperature', 'top_p', 'top_k')
 _ANTHROPIC_TASK_BUDGETS_BETA = 'task-budgets-2026-03-13'
+_ANTHROPIC_FILES_API_BETA = 'files-api-2025-04-14'
 _ANTHROPIC_COMPACT_EDIT_TYPE = 'compact_20260112'
 
 
@@ -760,7 +761,7 @@ async def _messages_create(
         )
         output_config = self._build_output_config(model_request_parameters, model_settings)
         anthropic_profile = self.profile
-        betas, extra_headers = self._get_betas_and_extra_headers(model_settings, anthropic_profile)
+        betas, extra_headers = self._get_betas_and_extra_headers(model_settings, anthropic_profile, messages)
         betas.update(native_tool_betas)
         context_management = self._add_compaction_params(messages, betas, model_settings)
         self._validate_task_budget_vs_context_management(model_settings, context_management)
@@ -820,10 +821,12 @@ def _get_betas_and_extra_headers(
         self,
         model_settings: AnthropicModelSettings,
         anthropic_profile: AnthropicModelProfile,
+        messages: list[ModelMessage],
     ) -> tuple[set[str], dict[str, str]]:
         """Prepare beta features list and extra headers for API request.
 
-        Handles merging custom `anthropic-beta` header from `extra_headers` into betas set
+        Handles merging custom `anthropic-beta` header from `extra_headers` into betas set,
+        auto-attaching the Files API beta when messages contain an Anthropic `UploadedFile`,
         and ensuring `User-Agent` is set.
         """
         extra_headers = dict(model_settings.get('extra_headers', {}))
@@ -845,8 +848,36 @@ def _get_betas_and_extra_headers(
         if beta_header := extra_headers.pop('anthropic-beta', None):
             betas.update({stripped_beta for beta in beta_header.split(',') if (stripped_beta := beta.strip())})
 
+        if self._messages_use_anthropic_uploaded_file(messages):
+            betas.add(_ANTHROPIC_FILES_API_BETA)
+
         return betas, extra_headers
 
+    def _messages_use_anthropic_uploaded_file(self, messages: list[ModelMessage]) -> bool:
+        """Whether any normalized message contains an Anthropic-hosted `UploadedFile`.
+
+        Used to gate auto-attachment of the `files-api-2025-04-14` beta header.
+        Mirrors the per-item `provider_name == self.system` check the request
+        mappers (`_map_user_prompt`, `_map_message`'s `ToolReturnPart` branch)
+        already perform — so the beta is added exactly when the wire shape
+        requires it. `UploadedFile`s for other providers are intentionally
+        ignored here; they will raise the existing `UserError` later in the
+        request-mapping path.
+        """
+        for message in messages:
+            if not isinstance(message, ModelRequest):
+                continue
+            for part in message.parts:
+                if isinstance(part, UserPromptPart) and not isinstance(part.content, str):
+                    for item in part.content:
+                        if isinstance(item, UploadedFile) and item.provider_name == self.system:
+                            return True
+                elif isinstance(part, ToolReturnPart):
+                    for item in part.content_items(mode='raw'):
+                        if isinstance(item, UploadedFile) and item.provider_name == self.system:
+                            return True
+        return False
+
     def _effective_speed(
         self, model_settings: AnthropicModelSettings, anthropic_profile: AnthropicModelProfile
     ) -> Literal['standard', 'fast'] | Omit:
@@ -932,7 +963,7 @@ async def _messages_count_tokens(
         )
         output_config = self._build_output_config(model_request_parameters, model_settings)
         anthropic_profile = self.profile
-        betas, extra_headers = self._get_betas_and_extra_headers(model_settings, anthropic_profile)
+        betas, extra_headers = self._get_betas_and_extra_headers(model_settings, anthropic_profile, messages)
         betas.update(native_tool_betas)
         context_management = self._add_compaction_params(messages, betas, model_settings)
         self._validate_task_budget_vs_context_management(model_settings, context_management)

tests/models/cassettes/test_multimodal_tool_returns/test_multimodal_tool_return_matrix[direct-uploaded_file-document-anthropic].yaml

@@ -4,7 +4,7 @@ interactions:
       accept:
       - application/json
       accept-encoding:
-      - gzip, deflate, br, zstd
+      - gzip, deflate, br
       connection:
       - keep-alive
       content-length:
@@ -38,30 +38,33 @@ interactions:
       connection:
       - keep-alive
       content-length:
-      - '638'
+      - '664'
       content-security-policy:
       - default-src 'none'; frame-ancestors 'none'
       content-type:
       - application/json
       strict-transport-security:
       - max-age=31536000; includeSubDomains; preload
+      traceresponse:
+      - 00-b5b8443acb69f07557dcea0f187fb6de-667748a1cd0cbfba-01
       transfer-encoding:
       - chunked
       vary:
       - Accept-Encoding
     parsed_body:
       content:
-      - text: I'll retrieve the document file for you.
+      - text: I'll retrieve the document file for you now.
         type: text
       - caller:
           type: direct
-        id: toolu_01AxGWRphgS3hyvLovTfpghj
+        id: toolu_01FThbNViZrZ6SBDCdM9oS8M
         input: {}
         name: get_file
         type: tool_use
-      id: msg_01WUmhzDAnCuJZiVJYTRz7pc
+      id: msg_011Ccn6sCPxkTDtNgYHt5sNu
       model: claude-sonnet-4-5-20250929
       role: assistant
+      stop_details: null
       stop_reason: tool_use
       stop_sequence: null
       type: message
@@ -73,7 +76,7 @@ interactions:
         cache_read_input_tokens: 0
         inference_geo: not_available
         input_tokens: 558
-        output_tokens: 46
+        output_tokens: 47
         service_tier: standard
     status:
       code: 200
@@ -83,11 +86,11 @@ interactions:
       accept:
       - application/json
       accept-encoding:
-      - gzip, deflate, br, zstd
+      - gzip, deflate, br
       connection:
       - keep-alive
       content-length:
-      - '831'
+      - '835'
       content-type:
       - application/json
       host:
@@ -101,21 +104,21 @@ interactions:
           type: text
         role: user
       - content:
-        - text: I'll retrieve the document file for you.
+        - text: I'll retrieve the document file for you now.
           type: text
-        - id: toolu_01AxGWRphgS3hyvLovTfpghj
+        - id: toolu_01FThbNViZrZ6SBDCdM9oS8M
           input: {}
           name: get_file
           type: tool_use
         role: assistant
       - content:
         - content:
           - source:
-              file_id: file_011CYiV4psfMwLCihcy8Ba6m
+              file_id: file_011Ccn6h59825RrtpAAPmrBv
               type: file
             type: document
           is_error: false
-          tool_use_id: toolu_01AxGWRphgS3hyvLovTfpghj
+          tool_use_id: toolu_01FThbNViZrZ6SBDCdM9oS8M
           type: tool_result
         role: user
       model: claude-sonnet-4-5
@@ -135,25 +138,46 @@ interactions:
       connection:
       - keep-alive
       content-length:
-      - '293'
+      - '1168'
       content-security-policy:
       - default-src 'none'; frame-ancestors 'none'
       content-type:
       - application/json
       strict-transport-security:
       - max-age=31536000; includeSubDomains; preload
+      traceresponse:
+      - 00-bff9c26e6128504db428c364a7176089-bb063d9e181ebb95-01
       transfer-encoding:
       - chunked
       vary:
       - Accept-Encoding
     parsed_body:
-      error:
-        message: 'messages.2.content.0.tool_result.content.0.document.source: Input tag ''file'' found using ''type'' does
-          not match any of the expected tags: ''base64'', ''content'', ''text'', ''url'''
-        type: invalid_request_error
-      request_id: req_011CYigKmqHtrr2p2vQY7y4v
-      type: error
+      content:
+      - text: "I received a PDF document file. Here's what I can describe about it:\n\n**Document Type:** PDF (application/pdf)\n\n**Content:**
+          This is a simple, single-page PDF document with minimal content. The page contains only a heading that reads \"Dummy
+          PDF file\" positioned in the upper left portion of the page. The rest of the page appears to be blank/white space.\n\n**Structure:**
+          \n- Single page (page 1)\n- Simple text-based content\n- No complex formatting, images, tables, or other elements\n-
+          Appears to be a test or placeholder PDF file\n\nThis seems to be a sample or test PDF document used for demonstration
+          purposes rather than a document with substantive content."
+        type: text
+      id: msg_011Ccn6sPauiMXjTjsCsSWdr
+      model: claude-sonnet-4-5-20250929
+      role: assistant
+      stop_details: null
+      stop_reason: end_turn
+      stop_sequence: null
+      type: message
+      usage:
+        cache_creation:
+          ephemeral_1h_input_tokens: 0
+          ephemeral_5m_input_tokens: 0
+        cache_creation_input_tokens: 0
+        cache_read_input_tokens: 0
+        inference_geo: not_available
+        input_tokens: 2218
+        output_tokens: 155
+        service_tier: standard
     status:
-      code: 400
-      message: Bad Request
+      code: 200
+      message: OK
 version: 1