Raise error when WebSearchTool is used with OpenAIChatModel and unsupported model (#2824)

Author: safina57

pydantic_ai_slim/pydantic_ai/models/openai.py

@@ -568,6 +568,12 @@ def _get_tools(self, model_request_parameters: ModelRequestParameters) -> list[c
     def _get_web_search_options(self, model_request_parameters: ModelRequestParameters) -> WebSearchOptions | None:
         for tool in model_request_parameters.builtin_tools:
             if isinstance(tool, WebSearchTool):  # pragma: no branch
+                if not OpenAIModelProfile.from_profile(self.profile).openai_chat_supports_web_search:
+                    raise UserError(
+                        f'WebSearchTool is not supported with `OpenAIChatModel` and model {self.model_name!r}. '
+                        f'Please use `OpenAIResponsesModel` instead.'
+                    )
+
                 if tool.user_location:
                     return WebSearchOptions(
                         search_context_size=tool.search_context_size,
@@ -579,7 +585,7 @@ def _get_web_search_options(self, model_request_parameters: ModelRequestParamete
                 return WebSearchOptions(search_context_size=tool.search_context_size)
             else:
                 raise UserError(
-                    f'`{tool.__class__.__name__}` is not supported by `OpenAIModel`. If it should be, please file an issue.'
+                    f'`{tool.__class__.__name__}` is not supported by `OpenAIChatModel`. If it should be, please file an issue.'
                 )
 
     async def _map_messages(self, messages: list[ModelMessage]) -> list[chat.ChatCompletionMessageParam]:

pydantic_ai_slim/pydantic_ai/profiles/openai.py

@@ -38,6 +38,9 @@ class OpenAIModelProfile(ModelProfile):
     openai_system_prompt_role: OpenAISystemPromptRole | None = None
     """The role to use for the system prompt message. If not provided, defaults to `'system'`."""
 
+    openai_chat_supports_web_search: bool = False
+    """Whether the model supports web search in Chat Completions API."""
+
     def __post_init__(self):  # pragma: no cover
         if not self.openai_supports_sampling_settings:
             warnings.warn(
@@ -50,6 +53,9 @@ def __post_init__(self):  # pragma: no cover
 def openai_model_profile(model_name: str) -> ModelProfile:
     """Get the model profile for an OpenAI model."""
     is_reasoning_model = model_name.startswith('o') or model_name.startswith('gpt-5')
+    # Check if the model supports web search (only specific search-preview models)
+    supports_web_search = '-search-preview' in model_name
+
     # Structured Outputs (output mode 'native') is only supported with the gpt-4o-mini, gpt-4o-mini-2024-07-18, and gpt-4o-2024-08-06 model snapshots and later.
     # We leave it in here for all models because the `default_structured_output_mode` is `'tool'`, so `native` is only used
     # when the user specifically uses the `NativeOutput` marker, so an error from the API is acceptable.
@@ -77,6 +83,7 @@ def openai_model_profile(model_name: str) -> ModelProfile:
         supports_json_object_output=True,
         openai_unsupported_model_settings=openai_unsupported_model_settings,
         openai_system_prompt_role=openai_system_prompt_role,
+        openai_chat_supports_web_search=supports_web_search,
     )
 
 

tests/models/test_openai.py

@@ -13,7 +13,7 @@
 from pydantic import AnyUrl, BaseModel, ConfigDict, Discriminator, Field, Tag
 from typing_extensions import NotRequired, TypedDict
 
-from pydantic_ai import Agent, ModelHTTPError, ModelRetry, UnexpectedModelBehavior
+from pydantic_ai import Agent, ModelHTTPError, ModelRetry, UnexpectedModelBehavior, UserError
 from pydantic_ai.builtin_tools import WebSearchTool
 from pydantic_ai.messages import (
     AudioUrl,
@@ -2105,7 +2105,7 @@ async def test_openai_web_search_tool_model_not_supported(allow_model_requests:
         m, instructions='You are a helpful assistant.', builtin_tools=[WebSearchTool(search_context_size='low')]
     )
 
-    with pytest.raises(ModelHTTPError, match='.*Web search options not supported with this model.*'):
+    with pytest.raises(UserError, match=r'WebSearchTool is not supported with `OpenAIChatModel` and model.*'):
         await agent.run('What day is today?')