✨ Add support for OpenAI and Gemini File Search Tools

- Add FileSearchTool builtin tool class
- Implement OpenAI FileSearch tool support in OpenAIResponsesModel
  - Add _map_file_search_tool_call mapping function
  - Handle FileSearch in streaming and non-streaming responses
  - Add FileSearch to builtin tools list
  - Handle FileSearch in round-trip message conversion
- Implement Gemini File Search tool support in GoogleModel
  - Add FileSearchTool handling in _get_tools method
- Export FileSearchTool in __init__.py
- Add comprehensive documentation in builtin-tools.md
- Add tests for unsupported models

This implements the feature requested in issue #3358.

Fixes #3358

Author: gorkachea

docs/builtin-tools.md

@@ -12,6 +12,7 @@ Pydantic AI supports the following built-in tools:
 - **[`UrlContextTool`][pydantic_ai.builtin_tools.UrlContextTool]**: Enables agents to pull URL contents into their context
 - **[`MemoryTool`][pydantic_ai.builtin_tools.MemoryTool]**: Enables agents to use memory
 - **[`MCPServerTool`][pydantic_ai.builtin_tools.MCPServerTool]**: Enables agents to use remote MCP servers with communication handled by the model provider
+- **[`FileSearchTool`][pydantic_ai.builtin_tools.FileSearchTool]**: Enables agents to search through uploaded files using vector search (RAG)
 
 These tools are passed to the agent via the `builtin_tools` parameter and are executed by the model provider's infrastructure.
 
@@ -566,6 +567,99 @@ _(This example is complete, it can be run "as is")_
 | `description`         | ✅ | ❌ |
 | `headers`             | ✅ | ❌ |
 
+## File Search Tool
+
+The [`FileSearchTool`][pydantic_ai.builtin_tools.FileSearchTool] enables your agent to search through uploaded files using vector search, providing a fully managed Retrieval-Augmented Generation (RAG) system. This tool handles file storage, chunking, embedding generation, and context injection into prompts.
+
+### Provider Support
+
+| Provider | Supported | Notes |
+|----------|-----------|-------|
+| OpenAI Responses | ✅ | Full feature support. Requires files to be uploaded to vector stores via the [OpenAI Files API](https://platform.openai.com/docs/api-reference/files). Vector stores must be created and file IDs added before using the tool. |
+| Google (Gemini) | ✅ | Requires files to be uploaded via the [Gemini Files API](https://ai.google.dev/gemini-api/docs/files). Files are automatically deleted after 48 hours. Supports up to 2 GB per file and 20 GB per project. Using built-in tools and function tools (including [output tools](output.md#tool-output)) at the same time is not supported; to use structured output, use [`PromptedOutput`](output.md#prompted-output) instead. |
+| Anthropic | ❌ | Not supported |
+| Groq | ❌ | Not supported |
+| OpenAI Chat Completions | ❌ | Not supported |
+| Bedrock | ❌ | Not supported |
+| Mistral | ❌ | Not supported |
+| Cohere | ❌ | Not supported |
+| HuggingFace | ❌ | Not supported |
+| Outlines | ❌ | Not supported |
+
+### Usage
+
+#### OpenAI Responses
+
+With OpenAI, you need to first upload files to a vector store, then reference the vector store IDs when using the `FileSearchTool`:
+
+```py {title="file_search_openai.py"}
+from pydantic_ai import Agent, FileSearchTool
+
+agent = Agent(
+    'openai-responses:gpt-5',
+    builtin_tools=[FileSearchTool(vector_store_ids=['vs_abc123'])]  # (1)
+)
+
+result = agent.run_sync('What information is in my documents about pydantic?')
+print(result.output)
+#> Based on your documents, Pydantic is a data validation library for Python...
+```
+
+1. Replace `vs_abc123` with your actual vector store ID from the OpenAI API.
+
+_(This example is complete, it can be run "as is")_
+
+#### Google (Gemini)
+
+With Gemini, you need to first upload files via the Files API, then reference the file resource names:
+
+```py {title="file_search_google.py"}
+from pydantic_ai import Agent, FileSearchTool
+
+agent = Agent(
+    'google-gla:gemini-2.5-flash',
+    builtin_tools=[FileSearchTool(vector_store_ids=['files/abc123'])]  # (1)
+)
+
+result = agent.run_sync('Summarize the key points from my uploaded documents.')
+print(result.output)
+#> The documents discuss the following key points: ...
+```
+
+1. Replace `files/abc123` with your actual file resource name from the Gemini Files API.
+
+_(This example is complete, it can be run "as is")_
+
+!!! note "Gemini File Search API Status"
+    The File Search Tool for Gemini was announced on November 6, 2025. The implementation may require adjustment as the official `google-genai` SDK is updated to fully support this feature.
+
+### Configuration
+
+The `FileSearchTool` accepts a list of vector store IDs:
+
+- **OpenAI**: Vector store IDs created via the [OpenAI Files API](https://platform.openai.com/docs/api-reference/files)
+- **Google**: File resource names from the [Gemini Files API](https://ai.google.dev/gemini-api/docs/files)
+
+```py {title="file_search_configured.py"}
+from pydantic_ai import Agent, FileSearchTool
+
+agent = Agent(
+    'openai-responses:gpt-5',
+    builtin_tools=[
+        FileSearchTool(
+            vector_store_ids=['vs_store1', 'vs_store2']  # (1)
+        )
+    ]
+)
+
+result = agent.run_sync('Find information across all my document collections.')
+print(result.output)
+```
+
+1. You can provide multiple vector store IDs to search across different collections.
+
+_(This example is complete, it can be run "as is")_
+
 ## API Reference
 
 For complete API documentation, see the [API Reference](api/builtin_tools.md).

pydantic_ai_slim/pydantic_ai/__init__.py

@@ -11,6 +11,7 @@
 )
 from .builtin_tools import (
     CodeExecutionTool,
+    FileSearchTool,
     ImageGenerationTool,
     MCPServerTool,
     MemoryTool,
@@ -210,13 +211,14 @@
     'ToolsetTool',
     'WrapperToolset',
     # builtin_tools
-    'WebSearchTool',
-    'WebSearchUserLocation',
-    'UrlContextTool',
     'CodeExecutionTool',
+    'FileSearchTool',
     'ImageGenerationTool',
-    'MemoryTool',
     'MCPServerTool',
+    'MemoryTool',
+    'UrlContextTool',
+    'WebSearchTool',
+    'WebSearchUserLocation',
     # output
     'ToolOutput',
     'NativeOutput',

pydantic_ai_slim/pydantic_ai/builtin_tools.py

@@ -17,6 +17,7 @@
     'ImageGenerationTool',
     'MemoryTool',
     'MCPServerTool',
+    'FileSearchTool',
 )
 
 _BUILTIN_TOOL_TYPES: dict[str, type[AbstractBuiltinTool]] = {}
@@ -334,6 +335,30 @@ def unique_id(self) -> str:
         return ':'.join([self.kind, self.id])
 
 
+@dataclass(kw_only=True)
+class FileSearchTool(AbstractBuiltinTool):
+    """A builtin tool that allows your agent to search through uploaded files using vector search.
+
+    This tool provides a fully managed Retrieval-Augmented Generation (RAG) system that handles
+    file storage, chunking, embedding generation, and context injection into prompts.
+
+    Supported by:
+
+    * OpenAI Responses
+    * Google (Gemini)
+    """
+
+    vector_store_ids: list[str]
+    """List of vector store IDs to search through.
+
+    For OpenAI, these are the IDs of vector stores created via the OpenAI API.
+    For Google, these are file resource names that have been uploaded and processed.
+    """
+
+    kind: str = 'file_search'
+    """The kind of tool."""
+
+
 def _tool_discriminator(tool_data: dict[str, Any] | AbstractBuiltinTool) -> str:
     if isinstance(tool_data, dict):
         return tool_data.get('kind', AbstractBuiltinTool.kind)

pydantic_ai_slim/pydantic_ai/models/google.py

@@ -13,7 +13,7 @@
 from .. import UnexpectedModelBehavior, _utils, usage
 from .._output import OutputObjectDefinition
 from .._run_context import RunContext
-from ..builtin_tools import CodeExecutionTool, ImageGenerationTool, UrlContextTool, WebSearchTool
+from ..builtin_tools import CodeExecutionTool, FileSearchTool, ImageGenerationTool, UrlContextTool, WebSearchTool
 from ..exceptions import UserError
 from ..messages import (
     BinaryContent,
@@ -342,6 +342,13 @@ def _get_tools(self, model_request_parameters: ModelRequestParameters) -> list[T
                     tools.append(ToolDict(url_context=UrlContextDict()))
                 elif isinstance(tool, CodeExecutionTool):
                     tools.append(ToolDict(code_execution=ToolCodeExecutionDict()))
+                elif isinstance(tool, FileSearchTool):
+                    # File Search Tool for Gemini API
+                    # The file_search tool uses file resource names (vector_store_ids) to search through uploaded files
+                    # Note: This requires files to be uploaded via the Files API first
+                    # The structure below is based on the Gemini File Search Tool announcement (Nov 2025)
+                    # and may require adjustment when the official google-genai SDK is updated
+                    tools.append(ToolDict(file_search={'file_names': tool.vector_store_ids}))  # type: ignore[reportGeneralTypeIssues]
                 elif isinstance(tool, ImageGenerationTool):  # pragma: no branch
                     if not self.profile.supports_image_output:
                         raise UserError(

pydantic_ai_slim/pydantic_ai/models/openai.py

@@ -18,7 +18,7 @@
 from .._run_context import RunContext
 from .._thinking_part import split_content_into_text_and_thinking
 from .._utils import guard_tool_call_id as _guard_tool_call_id, now_utc as _now_utc, number_to_datetime
-from ..builtin_tools import CodeExecutionTool, ImageGenerationTool, MCPServerTool, WebSearchTool
+from ..builtin_tools import CodeExecutionTool, FileSearchTool, ImageGenerationTool, MCPServerTool, WebSearchTool
 from ..exceptions import UserError
 from ..messages import (
     AudioUrl,
@@ -1070,9 +1070,10 @@ def _process_response(  # noqa: C901
             elif isinstance(item, responses.response_output_item.LocalShellCall):  # pragma: no cover
                 # Pydantic AI doesn't yet support the `codex-mini-latest` LocalShell built-in tool
                 pass
-            elif isinstance(item, responses.ResponseFileSearchToolCall):  # pragma: no cover
-                # Pydantic AI doesn't yet support the FileSearch built-in tool
-                pass
+            elif isinstance(item, responses.ResponseFileSearchToolCall):
+                call_part, return_part = _map_file_search_tool_call(item, self.system)
+                items.append(call_part)
+                items.append(return_part)
             elif isinstance(item, responses.response_output_item.McpCall):
                 call_part, return_part = _map_mcp_call(item, self.system)
                 items.append(call_part)
@@ -1267,6 +1268,11 @@ def _get_builtin_tools(self, model_request_parameters: ModelRequestParameters) -
                         type='approximate', **tool.user_location
                     )
                 tools.append(web_search_tool)
+            elif isinstance(tool, FileSearchTool):
+                file_search_tool = responses.FileSearchToolParam(
+                    type='file_search', vector_store_ids=tool.vector_store_ids
+                )
+                tools.append(file_search_tool)
             elif isinstance(tool, CodeExecutionTool):
                 has_image_generating_tool = True
                 tools.append({'type': 'code_interpreter', 'container': {'type': 'auto'}})
@@ -1404,6 +1410,7 @@ async def _map_messages(  # noqa: C901
                 message_item: responses.ResponseOutputMessageParam | None = None
                 reasoning_item: responses.ResponseReasoningItemParam | None = None
                 web_search_item: responses.ResponseFunctionWebSearchParam | None = None
+                file_search_item: responses.ResponseFileSearchToolCallParam | None = None
                 code_interpreter_item: responses.ResponseCodeInterpreterToolCallParam | None = None
                 for item in message.parts:
                     if isinstance(item, TextPart):
@@ -1473,6 +1480,18 @@ async def _map_messages(  # noqa: C901
                                     type='web_search_call',
                                 )
                                 openai_messages.append(web_search_item)
+                            elif (
+                                item.tool_name == FileSearchTool.kind
+                                and item.tool_call_id
+                                and (args := item.args_as_dict())
+                            ):
+                                file_search_item = responses.ResponseFileSearchToolCallParam(
+                                    id=item.tool_call_id,
+                                    action=cast(responses.response_file_search_tool_call_param.Action, args),
+                                    status='completed',
+                                    type='file_search_call',
+                                )
+                                openai_messages.append(file_search_item)
                             elif item.tool_name == ImageGenerationTool.kind and item.tool_call_id:
                                 # The cast is necessary because of https://github.com/openai/openai-python/issues/2648
                                 image_generation_item = cast(
@@ -1532,6 +1551,14 @@ async def _map_messages(  # noqa: C901
                                 and (status := content.get('status'))
                             ):
                                 web_search_item['status'] = status
+                            elif (
+                                item.tool_name == FileSearchTool.kind
+                                and file_search_item is not None
+                                and isinstance(item.content, dict)  # pyright: ignore[reportUnknownMemberType]
+                                and (content := cast(dict[str, Any], item.content))  # pyright: ignore[reportUnknownMemberType]
+                                and (status := content.get('status'))
+                            ):
+                                file_search_item['status'] = status
                             elif item.tool_name == ImageGenerationTool.kind:
                                 # Image generation result does not need to be sent back, just the `id` off of `BuiltinToolCallPart`.
                                 pass
@@ -1845,6 +1872,11 @@ async def _get_event_iterator(self) -> AsyncIterator[ModelResponseStreamEvent]:
                     yield self._parts_manager.handle_part(
                         vendor_part_id=f'{chunk.item.id}-call', part=replace(call_part, args=None)
                     )
+                elif isinstance(chunk.item, responses.ResponseFileSearchToolCall):
+                    call_part, _ = _map_file_search_tool_call(chunk.item, self.provider_name)
+                    yield self._parts_manager.handle_part(
+                        vendor_part_id=f'{chunk.item.id}-call', part=replace(call_part, args=None)
+                    )
                 elif isinstance(chunk.item, responses.ResponseCodeInterpreterToolCall):
                     call_part, _, _ = _map_code_interpreter_tool_call(chunk.item, self.provider_name)
 
@@ -1913,6 +1945,17 @@ async def _get_event_iterator(self) -> AsyncIterator[ModelResponseStreamEvent]:
                 elif isinstance(chunk.item, responses.ResponseFunctionWebSearch):
                     call_part, return_part = _map_web_search_tool_call(chunk.item, self.provider_name)
 
+                    maybe_event = self._parts_manager.handle_tool_call_delta(
+                        vendor_part_id=f'{chunk.item.id}-call',
+                        args=call_part.args,
+                    )
+                    if maybe_event is not None:  # pragma: no branch
+                        yield maybe_event
+
+                    yield self._parts_manager.handle_part(vendor_part_id=f'{chunk.item.id}-return', part=return_part)
+                elif isinstance(chunk.item, responses.ResponseFileSearchToolCall):
+                    call_part, return_part = _map_file_search_tool_call(chunk.item, self.provider_name)
+
                     maybe_event = self._parts_manager.handle_tool_call_delta(
                         vendor_part_id=f'{chunk.item.id}-call',
                         args=call_part.args,
@@ -2216,6 +2259,34 @@ def _map_web_search_tool_call(
     )
 
 
+def _map_file_search_tool_call(
+    item: responses.ResponseFileSearchToolCall, provider_name: str
+) -> tuple[BuiltinToolCallPart, BuiltinToolReturnPart]:
+    args: dict[str, Any] | None = None
+
+    result = {
+        'status': item.status,
+    }
+
+    if action := item.action:
+        args = action.model_dump(mode='json')
+
+    return (
+        BuiltinToolCallPart(
+            tool_name=FileSearchTool.kind,
+            tool_call_id=item.id,
+            args=args,
+            provider_name=provider_name,
+        ),
+        BuiltinToolReturnPart(
+            tool_name=FileSearchTool.kind,
+            tool_call_id=item.id,
+            content=result,
+            provider_name=provider_name,
+        ),
+    )
+
+
 def _map_image_generation_tool_call(
     item: responses.response_output_item.ImageGenerationCall, provider_name: str
 ) -> tuple[BuiltinToolCallPart, BuiltinToolReturnPart, FilePart | None]:

tests/test_builtin_tools.py

@@ -3,7 +3,7 @@
 import pytest
 
 from pydantic_ai.agent import Agent
-from pydantic_ai.builtin_tools import CodeExecutionTool, WebSearchTool
+from pydantic_ai.builtin_tools import CodeExecutionTool, FileSearchTool, WebSearchTool
 from pydantic_ai.exceptions import UserError
 from pydantic_ai.models import Model
 
@@ -40,3 +40,24 @@ async def test_builtin_tools_not_supported_code_execution_stream(model: Model, a
     with pytest.raises(UserError):
         async with agent.run_stream('What day is tomorrow?'):
             ...  # pragma: no cover
+
+
+@pytest.mark.parametrize(
+    'model', ('bedrock', 'mistral', 'cohere', 'huggingface', 'groq', 'anthropic', 'test', 'outlines'), indirect=True
+)
+async def test_builtin_tools_not_supported_file_search(model: Model, allow_model_requests: None):
+    agent = Agent(model=model, builtin_tools=[FileSearchTool(vector_store_ids=['test-id'])])
+
+    with pytest.raises(UserError):
+        await agent.run('Search my files')
+
+
+@pytest.mark.parametrize(
+    'model', ('bedrock', 'mistral', 'huggingface', 'groq', 'anthropic', 'outlines'), indirect=True
+)
+async def test_builtin_tools_not_supported_file_search_stream(model: Model, allow_model_requests: None):
+    agent = Agent(model=model, builtin_tools=[FileSearchTool(vector_store_ids=['test-id'])])
+
+    with pytest.raises(UserError):
+        async with agent.run_stream('Search my files'):
+            ...  # pragma: no cover