Add support for OpenAI verbosity parameter in Responses API (#2493)

Co-authored-by: Claude <[email protected]>
Co-authored-by: Douwe Maan <[email protected]>

Author: 3 people

pydantic_ai_slim/pydantic_ai/models/openai.py

@@ -177,6 +177,14 @@ class OpenAIResponsesModelSettings(OpenAIModelSettings, total=False):
         middle of the conversation.
     """
 
+    openai_text_verbosity: Literal['low', 'medium', 'high']
+    """Constrains the verbosity of the model's text response.
+
+    Lower values will result in more concise responses, while higher values will
+    result in more verbose responses. Currently supported values are `low`,
+    `medium`, and `high`.
+    """
+
 
 @dataclass(init=False)
 class OpenAIModel(Model):
@@ -819,6 +827,10 @@ async def _responses_create(
             openai_messages.insert(0, responses.EasyInputMessageParam(role='system', content=instructions))
             instructions = NOT_GIVEN
 
+        if verbosity := model_settings.get('openai_text_verbosity'):
+            text = text or {}
+            text['verbosity'] = verbosity
+
         sampling_settings = (
             model_settings
             if OpenAIModelProfile.from_profile(self.profile).openai_supports_sampling_settings

tests/models/cassettes/test_openai_responses/test_openai_responses_verbosity.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 2+2?
+        role: user
+      instructions: ''
+      model: gpt-5
+      text:
+        format:
+          type: text
+        verbosity: low
+    uri: https://api.openai.com/v1/responses
+  response:
+    headers:
+      content-type:
+      - application/json
+    parsed_body:
+      created_at: 1743075630
+      error: null
+      id: resp_test_verbosity_simple
+      incomplete_details: null
+      instructions: ''
+      max_output_tokens: null
+      metadata: {}
+      model: gpt-5
+      object: response
+      output:
+      - content:
+        - annotations: []
+          text: "4"
+          type: output_text
+        id: msg_test_verbosity_simple
+        role: assistant
+        status: completed
+        type: message
+      parallel_tool_calls: true
+      previous_response_id: null
+      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

@@ -1134,3 +1134,17 @@ async def get_user_country() -> str:
             ),
         ]
     )
+
+
+@pytest.mark.vcr()
+async def test_openai_responses_verbosity(allow_model_requests: None, openai_api_key: str):
+    """Test that verbosity setting is properly passed to the OpenAI API"""
+    # Following GPT-5 + verbosity documentation pattern
+    provider = OpenAIProvider(
+        api_key=openai_api_key,
+        base_url='https://api.openai.com/v1',  # Explicitly set base URL
+    )
+    model = OpenAIResponsesModel('gpt-5', provider=provider)
+    agent = Agent(model=model, model_settings=OpenAIResponsesModelSettings(openai_text_verbosity='low'))
+    result = await agent.run('What is 2+2?')
+    assert result.output == snapshot('4')