openai[patch]: allow specification of output format for Responses API (#31686)

Author: ccurme

libs/langchain/tests/unit_tests/chat_models/test_base.py

@@ -113,6 +113,7 @@ def test_configurable() -> None:
             "openai_api_base": None,
             "openai_organization": None,
             "openai_proxy": None,
+            "output_version": "v0",
             "request_timeout": None,
             "max_retries": None,
             "presence_penalty": None,

libs/partners/openai/langchain_openai/chat_models/_compat.py

@@ -128,6 +128,8 @@ def _convert_to_v03_ai_message(
             else:
                 new_content.append(block)
         message.content = new_content
+        if isinstance(message.id, str) and message.id.startswith("resp_"):
+            message.id = None
     else:
         pass
 
@@ -137,13 +139,29 @@ def _convert_to_v03_ai_message(
 def _convert_from_v03_ai_message(message: AIMessage) -> AIMessage:
     """Convert an old-style v0.3 AIMessage into the new content-block format."""
     # Only update ChatOpenAI v0.3 AIMessages
-    if not (
+    # TODO: structure provenance into AIMessage
+    is_chatopenai_v03 = (
         isinstance(message.content, list)
         and all(isinstance(b, dict) for b in message.content)
-    ) or not any(
-        item in message.additional_kwargs
-        for item in ["reasoning", "tool_outputs", "refusal", _FUNCTION_CALL_IDS_MAP_KEY]
-    ):
+    ) and (
+        any(
+            item in message.additional_kwargs
+            for item in [
+                "reasoning",
+                "tool_outputs",
+                "refusal",
+                _FUNCTION_CALL_IDS_MAP_KEY,
+            ]
+        )
+        or (
+            isinstance(message.id, str)
+            and message.id.startswith("msg_")
+            and (response_id := message.response_metadata.get("id"))
+            and isinstance(response_id, str)
+            and response_id.startswith("resp_")
+        )
+    )
+    if not is_chatopenai_v03:
         return message
 
     content_order = [

libs/partners/openai/langchain_openai/chat_models/base.py

@@ -649,6 +649,25 @@ class BaseChatOpenAI(BaseChatModel):
     .. versionadded:: 0.3.9
     """
 
+    output_version: Literal["v0", "responses/v1"] = "v0"
+    """Version of AIMessage output format to use.
+
+    This field is used to roll-out new output formats for chat model AIMessages
+    in a backwards-compatible way.
+
+    Supported values:
+
+    - ``"v0"``: AIMessage format as of langchain-openai 0.3.x.
+    - ``"responses/v1"``: Formats Responses API output
+      items into AIMessage content blocks.
+
+    Currently only impacts the Responses API. ``output_version="responses/v1"`` is
+    recommended.
+
+    .. versionadded:: 0.3.25
+
+    """
+
     model_config = ConfigDict(populate_by_name=True)
 
     @model_validator(mode="before")
@@ -903,6 +922,7 @@ def _stream_responses(
                     schema=original_schema_obj,
                     metadata=metadata,
                     has_reasoning=has_reasoning,
+                    output_version=self.output_version,
                 )
                 if generation_chunk:
                     if run_manager:
@@ -957,6 +977,7 @@ async def _astream_responses(
                     schema=original_schema_obj,
                     metadata=metadata,
                     has_reasoning=has_reasoning,
+                    output_version=self.output_version,
                 )
                 if generation_chunk:
                     if run_manager:
@@ -1096,7 +1117,10 @@ def _generate(
                 else:
                     response = self.root_client.responses.create(**payload)
             return _construct_lc_result_from_responses_api(
-                response, schema=original_schema_obj, metadata=generation_info
+                response,
+                schema=original_schema_obj,
+                metadata=generation_info,
+                output_version=self.output_version,
             )
         elif self.include_response_headers:
             raw_response = self.client.with_raw_response.create(**payload)
@@ -1109,6 +1133,8 @@ def _generate(
     def _use_responses_api(self, payload: dict) -> bool:
         if isinstance(self.use_responses_api, bool):
             return self.use_responses_api
+        elif self.output_version == "responses/v1":
+            return True
         elif self.include is not None:
             return True
         elif self.reasoning is not None:
@@ -1327,7 +1353,10 @@ async def _agenerate(
                 else:
                     response = await self.root_async_client.responses.create(**payload)
             return _construct_lc_result_from_responses_api(
-                response, schema=original_schema_obj, metadata=generation_info
+                response,
+                schema=original_schema_obj,
+                metadata=generation_info,
+                output_version=self.output_version,
             )
         elif self.include_response_headers:
             raw_response = await self.async_client.with_raw_response.create(**payload)
@@ -3540,6 +3569,7 @@ def _construct_lc_result_from_responses_api(
     response: Response,
     schema: Optional[type[_BM]] = None,
     metadata: Optional[dict] = None,
+    output_version: Literal["v0", "responses/v1"] = "v0",
 ) -> ChatResult:
     """Construct ChatResponse from OpenAI Response API response."""
     if response.error:
@@ -3676,7 +3706,10 @@ def _construct_lc_result_from_responses_api(
         tool_calls=tool_calls,
         invalid_tool_calls=invalid_tool_calls,
     )
-    message = _convert_to_v03_ai_message(message)
+    if output_version == "v0":
+        message = _convert_to_v03_ai_message(message)
+    else:
+        pass
     return ChatResult(generations=[ChatGeneration(message=message)])
 
 
@@ -3688,6 +3721,7 @@ def _convert_responses_chunk_to_generation_chunk(
     schema: Optional[type[_BM]] = None,
     metadata: Optional[dict] = None,
     has_reasoning: bool = False,
+    output_version: Literal["v0", "responses/v1"] = "v0",
 ) -> tuple[int, int, int, Optional[ChatGenerationChunk]]:
     def _advance(output_idx: int, sub_idx: Optional[int] = None) -> None:
         """Advance indexes tracked during streaming.
@@ -3756,12 +3790,15 @@ def _advance(output_idx: int, sub_idx: Optional[int] = None) -> None:
     elif chunk.type == "response.output_text.done":
         content.append({"id": chunk.item_id, "index": current_index})
     elif chunk.type == "response.created":
-        response_metadata["id"] = chunk.response.id
+        id = chunk.response.id
+        response_metadata["id"] = chunk.response.id  # Backwards compatibility
     elif chunk.type == "response.completed":
         msg = cast(
             AIMessage,
             (
-                _construct_lc_result_from_responses_api(chunk.response, schema=schema)
+                _construct_lc_result_from_responses_api(
+                    chunk.response, schema=schema, output_version=output_version
+                )
                 .generations[0]
                 .message
             ),
@@ -3773,7 +3810,10 @@ def _advance(output_idx: int, sub_idx: Optional[int] = None) -> None:
             k: v for k, v in msg.response_metadata.items() if k != "id"
         }
     elif chunk.type == "response.output_item.added" and chunk.item.type == "message":
-        id = chunk.item.id
+        if output_version == "v0":
+            id = chunk.item.id
+        else:
+            pass
     elif (
         chunk.type == "response.output_item.added"
         and chunk.item.type == "function_call"
@@ -3868,9 +3908,13 @@ def _advance(output_idx: int, sub_idx: Optional[int] = None) -> None:
         additional_kwargs=additional_kwargs,
         id=id,
     )
-    message = cast(
-        AIMessageChunk, _convert_to_v03_ai_message(message, has_reasoning=has_reasoning)
-    )
+    if output_version == "v0":
+        message = cast(
+            AIMessageChunk,
+            _convert_to_v03_ai_message(message, has_reasoning=has_reasoning),
+        )
+    else:
+        pass
     return (
         current_index,
         current_output_index,

libs/partners/openai/tests/cassettes/test_mcp_builtin_zdr.yaml.gz

@@ -2,7 +2,7 @@
 
 import json
 import os
-from typing import Annotated, Any, Optional, cast
+from typing import Annotated, Any, Literal, Optional, cast
 
 import openai
 import pytest
@@ -50,15 +50,11 @@ def _check_response(response: Optional[BaseMessage]) -> None:
     assert response.usage_metadata["total_tokens"] > 0
     assert response.response_metadata["model_name"]
     assert response.response_metadata["service_tier"]
-    for tool_output in response.additional_kwargs["tool_outputs"]:
-        assert tool_output["id"]
-        assert tool_output["status"]
-        assert tool_output["type"]
 
 
 @pytest.mark.vcr
 def test_web_search() -> None:
-    llm = ChatOpenAI(model=MODEL_NAME)
+    llm = ChatOpenAI(model=MODEL_NAME, output_version="responses/v1")
     first_response = llm.invoke(
         "What was a positive news story from today?",
         tools=[{"type": "web_search_preview"}],
@@ -111,6 +107,11 @@ def test_web_search() -> None:
     )
     _check_response(response)
 
+    for msg in [first_response, full, response]:
+        assert isinstance(msg, AIMessage)
+        block_types = [block["type"] for block in msg.content]  # type: ignore[index]
+        assert block_types == ["web_search_call", "text"]
+
 
 @pytest.mark.flaky(retries=3, delay=1)
 async def test_web_search_async() -> None:
@@ -133,6 +134,12 @@ async def test_web_search_async() -> None:
     assert isinstance(full, AIMessageChunk)
     _check_response(full)
 
+    for msg in [response, full]:
+        assert msg.additional_kwargs["tool_outputs"]
+        assert len(msg.additional_kwargs["tool_outputs"]) == 1
+        tool_output = msg.additional_kwargs["tool_outputs"][0]
+        assert tool_output["type"] == "web_search_call"
+
 
 @pytest.mark.flaky(retries=3, delay=1)
 def test_function_calling() -> None:
@@ -288,20 +295,32 @@ def multiply(x: int, y: int) -> int:
     assert set(ai_msg.tool_calls[0]["args"]) == {"x", "y"}
 
 
-def test_reasoning() -> None:
-    llm = ChatOpenAI(model="o3-mini", use_responses_api=True)
+@pytest.mark.default_cassette("test_reasoning.yaml.gz")
+@pytest.mark.vcr
+@pytest.mark.parametrize("output_version", ["v0", "responses/v1"])
+def test_reasoning(output_version: Literal["v0", "responses/v1"]) -> None:
+    llm = ChatOpenAI(
+        model="o4-mini", use_responses_api=True, output_version=output_version
+    )
     response = llm.invoke("Hello", reasoning={"effort": "low"})
     assert isinstance(response, AIMessage)
-    assert response.additional_kwargs["reasoning"]
 
     # Test init params + streaming
-    llm = ChatOpenAI(model="o3-mini", reasoning_effort="low", use_responses_api=True)
+    llm = ChatOpenAI(
+        model="o4-mini", reasoning={"effort": "low"}, output_version=output_version
+    )
     full: Optional[BaseMessageChunk] = None
     for chunk in llm.stream("Hello"):
         assert isinstance(chunk, AIMessageChunk)
         full = chunk if full is None else full + chunk
     assert isinstance(full, AIMessage)
-    assert full.additional_kwargs["reasoning"]
+
+    for msg in [response, full]:
+        if output_version == "v0":
+            assert msg.additional_kwargs["reasoning"]
+        else:
+            block_types = [block["type"] for block in msg.content]
+            assert block_types == ["reasoning", "text"]
 
 
 def test_stateful_api() -> None:
@@ -355,20 +374,37 @@ def test_file_search() -> None:
     _check_response(full)
 
 
-def test_stream_reasoning_summary() -> None:
+@pytest.mark.default_cassette("test_stream_reasoning_summary.yaml.gz")
+@pytest.mark.vcr
+@pytest.mark.parametrize("output_version", ["v0", "responses/v1"])
+def test_stream_reasoning_summary(
+    output_version: Literal["v0", "responses/v1"],
+) -> None:
     llm = ChatOpenAI(
         model="o4-mini",
         # Routes to Responses API if `reasoning` is set.
         reasoning={"effort": "medium", "summary": "auto"},
+        output_version=output_version,
     )
-    message_1 = {"role": "user", "content": "What is 3^3?"}
+    message_1 = {
+        "role": "user",
+        "content": "What was the third tallest buliding in the year 2000?",
+    }
     response_1: Optional[BaseMessageChunk] = None
     for chunk in llm.stream([message_1]):
         assert isinstance(chunk, AIMessageChunk)
         response_1 = chunk if response_1 is None else response_1 + chunk
     assert isinstance(response_1, AIMessageChunk)
-    reasoning = response_1.additional_kwargs["reasoning"]
-    assert set(reasoning.keys()) == {"id", "type", "summary"}
+    if output_version == "v0":
+        reasoning = response_1.additional_kwargs["reasoning"]
+        assert set(reasoning.keys()) == {"id", "type", "summary"}
+    else:
+        reasoning = next(
+            block
+            for block in response_1.content
+            if block["type"] == "reasoning"  # type: ignore[index]
+        )
+        assert set(reasoning.keys()) == {"id", "type", "summary", "index"}
     summary = reasoning["summary"]
     assert isinstance(summary, list)
     for block in summary:
@@ -462,11 +498,11 @@ def test_mcp_builtin() -> None:
     )
 
 
-@pytest.mark.skip
+@pytest.mark.vcr
 def test_mcp_builtin_zdr() -> None:
     llm = ChatOpenAI(
         model="o4-mini",
-        use_responses_api=True,
+        output_version="responses/v1",
         store=False,
         include=["reasoning.encrypted_content"],
     )

libs/partners/openai/tests/cassettes/test_reasoning.yaml.gz

@@ -24,6 +24,7 @@
       }),
       'openai_api_type': 'azure',
       'openai_api_version': '2021-10-01',
+      'output_version': 'v0',
       'request_timeout': 60.0,
       'stop': list([
       ]),

libs/partners/openai/tests/cassettes/test_stream_reasoning_summary.yaml.gz

@@ -18,6 +18,7 @@
         'lc': 1,
         'type': 'secret',
       }),
+      'output_version': 'v0',
       'request_timeout': 60.0,
       'stop': list([
       ]),