update tests and docs

Author: GDaamn

docs/models/openai.md

@@ -143,6 +143,8 @@ As of 7:48 AM on Wednesday, April 2, 2025, in Tokyo, Japan, the weather is cloud
 
 You can learn more about the differences between the Responses API and Chat Completions API in the [OpenAI API docs](https://platform.openai.com/docs/guides/responses-vs-chat-completions).
 
+#### Referencing earlier responses
+
 The Responses API also supports referencing earlier model responses in a new request. This is available through the `openai_previous_response_id` field in
 [`OpenAIResponsesModelSettings`][pydantic_ai.models.openai.OpenAIResponsesModelSettings].
 
@@ -164,8 +166,32 @@ print(result.output)
 
 By passing the `provider_response_id` from an earlier run, you can allow the model to build on its own prior reasoning without needing to resend the full message history.
 
-If message history is provided and all responses come from the same OpenAI model,
-Pydantic AI will automatically only send the the latest request and the `previous_response_id` from the latest response to the API for efficiency.
+Alternatively, `openai_previous_response_id` field also supports `auto` mode. When enabled, Pydantic AI automatically selects the latest request and the most recent `provider_response_id` from message history to send to OpenAI API, leveraging server-side history instead, for improved efficiency. If `openai_previous_response_id` is not set, full history is sent.
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.openai import OpenAIResponsesModel, OpenAIResponsesModelSettings
+
+model = OpenAIResponsesModel('gpt-4o')
+agent = Agent(model=model)
+
+result1 = agent.run_sync('Tell me a joke.')
+print(result1.output)
+#> Did you hear about the toothpaste scandal? They called it Colgate.
+
+# When set to 'auto', only the latest request and the most recent provider_response_id
+# from history is sent to OpenAI API.
+model_settings = OpenAIResponsesModelSettings(openai_previous_response_id='auto')
+result2 = agent.run_sync(
+    'Explain?',
+    message_history=result1.new_messages(),
+    model_settings=model_settings
+)
+print(result2.output)
+#> This is an excellent joke invented by Samuel Colvin, it needs no explanation.
+```
+It is recommended to use `auto` mode only when the history comes from a single, uninterrupted run,
+with all responses coming from the same OpenAI model (e.g like internal tool calls), as the server-side history will override any locally modified history.
 
 ## OpenAI-compatible Models
 

pydantic_ai_slim/pydantic_ai/models/openai.py

@@ -211,9 +211,12 @@ class OpenAIResponsesModelSettings(OpenAIChatModelSettings, total=False):
     `medium`, and `high`.
     """
 
-    openai_previous_response_id: str
+    openai_previous_response_id: Literal['auto'] | str
     """The identifier of the most recent response to include in the API request.
 
+    When set to `auto`, the request automatically uses the most recent
+    `provider_response_id` along with the latest request from the message history.
+
     This enables the model to reference previous reasoning traces.
     See the [OpenAI Responses API documentation](https://platform.openai.com/docs/guides/reasoning#keeping-reasoning-items-in-context)
     for more information.
@@ -932,11 +935,14 @@ async def _responses_create(
             tool_choice = 'required'
         else:
             tool_choice = 'auto'
-
+        print(messages)
+        print('-------')
         previous_response_id = model_settings.get('openai_previous_response_id')
-        if not previous_response_id:
+        if previous_response_id == 'auto':
             messages, previous_response_id = self._get_response_id_and_trim(messages)
-
+        print(messages)
+        print(previous_response_id)
+        print('==========')
         instructions, openai_messages = await self._map_messages(messages)
         reasoning = self._get_reasoning(model_settings)
 

tests/models/cassettes/test_openai_responses/test_openai_previous_response_id_auto_mode.yaml

@@ -0,0 +1,67 @@
+interactions:
+- request:
+    headers:
+      accept:
+      - application/json
+      accept-encoding:
+      - gzip, deflate
+      connection:
+      - keep-alive
+      content-type:
+      - application/json
+      host:
+      - api.openai.com
+    method: POST
+    parsed_body:
+      input:
+      - content: What is the first secret key?
+        role: user
+      instructions: ''
+      model: gpt-5
+      text:
+        format:
+          type: text
+      previous_response_id: resp_68b9bda81f5c8197a5a51a20a9f4150a000497db2a4c777b
+    uri: https://api.openai.com/v1/responses
+  response:
+    headers:
+      content-type:
+      - application/json
+    parsed_body:
+      created_at: 1743075630
+      error: null
+      id: resp_a4168b9bda81f5c8197a5a51a20a9f4150a000497db2a4c5
+      incomplete_details: null
+      instructions: ''
+      max_output_tokens: null
+      metadata: {}
+      model: gpt-5
+      object: response
+      output:
+      - content:
+        - annotations: []
+          text: "sesame"
+          type: output_text
+        id: msg_test_previous_response_id_auto
+        role: assistant
+        status: completed
+        type: message
+      parallel_tool_calls: true
+      previous_response_id: resp_68b9bda81f5c8197a5a51a20a9f4150a000497db2a4c777b
+      reasoning: null
+      status: complete
+      status_details: null
+      tool_calls: null
+      total_tokens: 15
+      usage:
+        input_tokens: 10
+        input_tokens_details:
+          cached_tokens: 0
+        output_tokens: 1
+        output_tokens_details:
+          reasoning_tokens: 0
+        total_tokens: 11
+    status:
+      code: 200
+      message: OK
+version: 1

tests/models/test_openai_responses.py

@@ -1146,7 +1146,50 @@ async def test_openai_previous_response_id(allow_model_requests: None, openai_ap
     assert result.output == snapshot('sesame')
 
 
-async def test_previous_response_id_mixed_model_history(allow_model_requests: None, openai_api_key: str):
+@pytest.mark.vcr()
+async def test_openai_previous_response_id_auto_mode(allow_model_requests: None, openai_api_key: str):
+    """Test if invalid previous response id is ignored when history contains non-OpenAI responses"""
+    history = [
+        ModelRequest(
+            parts=[
+                UserPromptPart(
+                    content='The first secret key is sesame',
+                ),
+            ],
+        ),
+        ModelResponse(
+            parts=[
+                TextPart(content='Open sesame! What would you like to unlock?'),
+            ],
+            model_name='gpt-5',
+            provider_name='openai',
+            provider_response_id='resp_68b9bd97025c8195b443af591ca2345c08cb6072affe6099',
+        ),
+        ModelRequest(
+            parts=[
+                UserPromptPart(
+                    content='The second secret key is olives',
+                ),
+            ],
+        ),
+        ModelResponse(
+            parts=[
+                TextPart(content='Understood'),
+            ],
+            model_name='gpt-5',
+            provider_name='openai',
+            provider_response_id='resp_68b9bda81f5c8197a5a51a20a9f4150a000497db2a4c777b',
+        ),
+    ]
+
+    model = OpenAIResponsesModel('gpt-5', provider=OpenAIProvider(api_key=openai_api_key))
+    agent = Agent(model=model)
+    settings = OpenAIResponsesModelSettings(openai_previous_response_id='auto')
+    result = await agent.run('what is the first secret key', message_history=history, model_settings=settings)
+    assert result.output == snapshot('sesame')
+
+
+async def test_openai_previous_response_id_mixed_model_history(allow_model_requests: None, openai_api_key: str):
     """Test if invalid previous response id is ignored when history contains non-OpenAI responses"""
     history = [
         ModelRequest(
@@ -1216,7 +1259,7 @@ async def test_previous_response_id_mixed_model_history(allow_model_requests: No
     )
 
 
-async def test_previous_response_id_same_model_history(allow_model_requests: None, openai_api_key: str):
+async def test_openai_previous_response_id_same_model_history(allow_model_requests: None, openai_api_key: str):
     """Test if message history is trimmed when model responses are from same model"""
     history = [
         ModelRequest(