bug: Warn about Azure OpenAI completions file-incompatibility

docs/input.md

@@ -118,7 +118,12 @@ Support for file URLs varies depending on type and provider:
 | [`MistralModel`][pydantic_ai.models.mistral.MistralModel] | `ImageUrl`, `DocumentUrl` (PDF) | — | `AudioUrl`, `VideoUrl`, `DocumentUrl` (non-PDF) |
 | [`BedrockConverseModel`][pydantic_ai.models.bedrock.BedrockConverseModel] | S3 URLs (`s3://`) | `ImageUrl`, `DocumentUrl`, `VideoUrl` | `AudioUrl` |
 
-A model API may be unable to download a file (e.g., because of crawling or access restrictions) even if it supports file URLs. For example, [`GoogleModel`][pydantic_ai.models.google.GoogleModel] on Vertex AI limits YouTube video URLs to one URL per request. In such cases, you can instruct Pydantic AI to download the file content locally and send that instead of the URL by setting `force_download` on the URL object:
+!!! warning
+    `DocumentUrl` and `BinaryContent` documents are not supported when using `AzureProvider` with `OpenAIChatModel`. Azure's Chat Completions API does not support document input. Use [`OpenAIResponsesModel`][pydantic_ai.models.openai.OpenAIResponsesModel] with [`AzureProvider`][pydantic_ai.providers.azure.AzureProvider] instead. See the [Azure AI Foundry documentation](openai.md#azure-ai-foundry) for more details.
+
+A model API may be unable to download a file (e.g., because of crawling or access restrictions) even if it supports file URLs. For example, [`GoogleModel`][pydantic_ai.models.google.GoogleModel] on Vertex AI limits YouTube video URLs to one URL per request.
+
+In such cases, you can instruct Pydantic AI to download the file content locally and send that instead of the URL by setting `force_download` on the URL object:
 
 ```py {title="force_download.py" test="skip" lint="skip"}
 from pydantic_ai import ImageUrl, AudioUrl, VideoUrl, DocumentUrl

docs/models/openai.md

@@ -427,6 +427,34 @@ agent = Agent(model)
 ...
 ```
 
+#### Using Azure with the Responses API
+
+Azure AI Foundry also supports the OpenAI Responses API through [`OpenAIResponsesModel`][pydantic_ai.models.openai.OpenAIResponsesModel]. This is particularly recommended when working with document inputs (`DocumentUrl` and `BinaryContent`), as Azure's Chat Completions API does not support these input types.
+
+??? example "Document processing with Azure using Responses API"
+    ```python
+    from pydantic_ai import Agent, BinaryContent
+    from pydantic_ai.models.openai import OpenAIResponsesModel
+    from pydantic_ai.providers.azure import AzureProvider
+
+    pdf_bytes = b'%PDF-1.4 ...'  # Your PDF content
+
+    model = OpenAIResponsesModel(
+        'gpt-5',
+        provider=AzureProvider(
+            azure_endpoint='your-azure-endpoint',
+            api_version='your-api-version',
+        ),
+    )
+    agent = Agent(model)
+    result = agent.run_sync([
+        'Summarize this document',
+        BinaryContent(data=pdf_bytes, media_type='application/pdf'),
+    ])
+    ```
+
+The Responses API provides the same functionality as the Chat Completions API, with additional features and better support for advanced input types. When using Azure, consider using `OpenAIResponsesModel` for the most comprehensive feature support.
+
 ### Vercel AI Gateway
 
 To use [Vercel's AI Gateway](https://vercel.com/docs/ai-gateway), first follow the [documentation](https://vercel.com/docs/ai-gateway) instructions on obtaining an API key or OIDC token.

pydantic_ai_slim/pydantic_ai/models/openai.py

@@ -13,7 +13,7 @@
 
 from pydantic import BaseModel, ValidationError
 from pydantic_core import to_json
-from typing_extensions import assert_never, deprecated
+from typing_extensions import Never, assert_never, deprecated
 
 from .. import ModelAPIError, ModelHTTPError, UnexpectedModelBehavior, _utils, usage
 from .._output import DEFAULT_OUTPUT_TOOL_NAME, OutputObjectDefinition
@@ -1087,6 +1087,8 @@ async def _map_user_prompt(self, part: UserPromptPart) -> chat.ChatCompletionUse
                             audio = InputAudio(data=item.base64, format=item.format)
                         content.append(ChatCompletionContentPartInputAudioParam(input_audio=audio, type='input_audio'))
                     elif item.is_document:
+                        if not profile.openai_chat_supports_file_input:
+                            self._raise_file_input_not_supported_error()
                         content.append(
                             File(
                                 file=FileFile(
@@ -1118,6 +1120,8 @@ async def _map_user_prompt(self, part: UserPromptPart) -> chat.ChatCompletionUse
                             )
                         )
                     else:
+                        if not profile.openai_chat_supports_file_input:
+                            self._raise_file_input_not_supported_error()
                         downloaded_item = await download_item(item, data_format='base64_uri', type_format='extension')
                         content.append(
                             File(
@@ -1137,6 +1141,16 @@ async def _map_user_prompt(self, part: UserPromptPart) -> chat.ChatCompletionUse
                     assert_never(item)
         return chat.ChatCompletionUserMessageParam(role='user', content=content)
 
+    def _raise_file_input_not_supported_error(self) -> Never:
+        if self._provider.name == 'azure':
+            raise UserError(
+                "Azure's Chat Completions API does not support document input. "
+                'Use `OpenAIResponsesModel` with `AzureProvider` instead.'
+            )
+        raise UserError(
+            f'The {self._provider.name!r} provider does not support document input via the Chat Completions API.'
+        )
+
     @staticmethod
     def _is_text_like_media_type(media_type: str) -> bool:
         return (

pydantic_ai_slim/pydantic_ai/profiles/openai.py

@@ -80,6 +80,12 @@ class OpenAIModelProfile(ModelProfile):
     See https://github.com/pydantic/pydantic-ai/issues/3245 for more details.
     """
 
+    openai_chat_supports_file_input: bool = True
+    """Whether the Chat Completions API supports file content parts (type='file').
+
+    Some OpenAI-compatible providers (e.g. Azure) do not support file input via the Chat Completions API.
+    """
+
     def __post_init__(self):  # pragma: no cover
         if not self.openai_supports_sampling_settings:
             warnings.warn(

pydantic_ai_slim/pydantic_ai/providers/azure.py

@@ -67,10 +67,15 @@ def model_profile(self, model_name: str) -> ModelProfile | None:
 
                 # As AzureProvider is always used with OpenAIChatModel, which used to unconditionally use OpenAIJsonSchemaTransformer,
                 # we need to maintain that behavior unless json_schema_transformer is set explicitly
-                return OpenAIModelProfile(json_schema_transformer=OpenAIJsonSchemaTransformer).update(profile)
+                # Azure Chat Completions API doesn't support file input
+                return OpenAIModelProfile(
+                    json_schema_transformer=OpenAIJsonSchemaTransformer,
+                    openai_chat_supports_file_input=False,
+                ).update(profile)
 
         # OpenAI models are unprefixed
-        return openai_model_profile(model_name)
+        # Azure Chat Completions API doesn't support file input
+        return OpenAIModelProfile(openai_chat_supports_file_input=False).update(openai_model_profile(model_name))
 
     @overload
     def __init__(self, *, openai_client: AsyncAzureOpenAI) -> None: ...

tests/providers/test_azure.py

@@ -4,8 +4,10 @@
 from inline_snapshot import snapshot
 from pytest_mock import MockerFixture
 
+from pydantic_ai import BinaryContent
 from pydantic_ai._json_schema import InlineDefsJsonSchemaTransformer
 from pydantic_ai.agent import Agent
+from pydantic_ai.exceptions import UserError
 from pydantic_ai.profiles.cohere import cohere_model_profile
 from pydantic_ai.profiles.deepseek import deepseek_model_profile
 from pydantic_ai.profiles.grok import grok_model_profile
@@ -139,3 +141,24 @@ def test_azure_provider_model_profile(mocker: MockerFixture):
     openai_model_profile_mock.assert_called_with('unknown-model')
     assert unknown_profile is not None
     assert unknown_profile.json_schema_transformer == OpenAIJsonSchemaTransformer
+
+
+async def test_azure_document_input_not_supported(allow_model_requests: None):
+    provider = AzureProvider(
+        azure_endpoint='https://project-id.openai.azure.com/',
+        api_version='2023-03-15-preview',
+        api_key='1234567890',
+    )
+    model = OpenAIChatModel(model_name='gpt-4o', provider=provider)
+    agent = Agent(model)
+
+    with pytest.raises(
+        UserError,
+        match="Azure's Chat Completions API does not support document input.*OpenAIResponsesModel",
+    ):
+        await agent.run(
+            [
+                'Summarize this document',
+                BinaryContent(data=b'%PDF-1.4 test', media_type='application/pdf'),
+            ]
+        )

tests/test_examples.py

@@ -575,6 +575,8 @@ async def model_logic(  # noqa: C901
             return ModelResponse(parts=[TextPart('The company name in the logo is "Pydantic."')])
         elif isinstance(m.content, list) and m.content[0] == 'This is file c6720d:':
             return ModelResponse(parts=[TextPart('The document contains just the text "Dummy PDF file."')])
+        elif isinstance(m.content, list) and m.content[0] == 'Summarize this document':
+            return ModelResponse(parts=[TextPart('This document outlines the PDF specification version 1.4.')])
 
         assert isinstance(m.content, str)
         if m.content == 'Tell me a joke.' and any(t.name == 'joke_factory' for t in info.function_tools):