Add chat tool output fallback warning

Author: Aphroq

src/agents/models/chatcmpl_converter.py

@@ -47,6 +47,7 @@
 from ..exceptions import AgentsException, UserError
 from ..handoffs import Handoff
 from ..items import TResponseInputItem, TResponseOutputItem
+from ..logger import logger
 from ..model_settings import MCPToolChoice
 from ..tool import (
     FunctionTool,
@@ -66,6 +67,8 @@
     ResponseInputContentParam | ResponseInputAudioParam | dict[str, Any]
 )
 
+_OMITTED_TOOL_OUTPUT_PLACEHOLDER = "[tool output omitted]"
+
 
 class Converter:
     @classmethod
@@ -751,13 +754,19 @@ def ensure_assistant_message() -> ChatCompletionAssistantMessageParam:
                             for c in all_output_content
                             if c.get("type") == "text"
                         ]
-                        if not tool_result_content and all_output_content:
+                        if not tool_result_content:
+                            message = (
+                                "Chat Completions tool outputs cannot be empty or contain only "
+                                "non-text content unless preserve_tool_output_all_content=True."
+                            )
                             if strict_feature_validation:
-                                raise UserError(
-                                    "Chat Completions tool outputs cannot contain only non-text "
-                                    "content unless preserve_tool_output_all_content=True"
-                                )
-                            tool_result_content = "[non-text tool output omitted]"
+                                raise UserError(message)
+                            logger.warning(
+                                "%s Replacing the tool output with a placeholder; enable strict "
+                                "feature validation to raise an error instead.",
+                                message,
+                            )
+                            tool_result_content = _OMITTED_TOOL_OUTPUT_PLACEHOLDER
                 msg: ChatCompletionToolMessageParam = {
                     "role": "tool",
                     "tool_call_id": func_output["call_id"],

tests/models/test_openai_chatcompletions.py

@@ -320,6 +320,110 @@ async def patched_fetch_response(self, *args, **kwargs):
         )
 
 
+@pytest.mark.allow_call_model_methods
+@pytest.mark.asyncio
+async def test_get_response_rejects_non_text_tool_output_in_strict_mode() -> None:
+    class DummyCompletions:
+        async def create(self, **kwargs: Any) -> Any:
+            raise AssertionError("chat.completions.create should not run")
+
+    class DummyClient:
+        def __init__(self) -> None:
+            self.chat = type("_Chat", (), {"completions": DummyCompletions()})()
+            self.base_url = httpx.URL("http://fake")
+
+    model = OpenAIChatCompletionsModel(
+        model="gpt-4",
+        openai_client=DummyClient(),  # type: ignore[arg-type]
+        strict_feature_validation=True,
+    )
+
+    with pytest.raises(UserError, match="cannot be empty or contain only non-text content"):
+        await model.get_response(
+            system_instructions=None,
+            input=[
+                {
+                    "type": "function_call_output",
+                    "call_id": "call_image",
+                    "output": [
+                        {
+                            "type": "input_image",
+                            "image_url": "https://example.com/image.png",
+                        }
+                    ],
+                }
+            ],
+            model_settings=ModelSettings(),
+            tools=[],
+            output_schema=None,
+            handoffs=[],
+            tracing=ModelTracing.DISABLED,
+            previous_response_id=None,
+            conversation_id=None,
+            prompt=None,
+        )
+
+
+@pytest.mark.allow_call_model_methods
+@pytest.mark.asyncio
+async def test_get_response_warns_and_sends_placeholder_for_non_text_tool_output(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    class DummyCompletions:
+        def __init__(self) -> None:
+            self.kwargs: dict[str, Any] = {}
+
+        async def create(self, **kwargs: Any) -> Any:
+            self.kwargs = kwargs
+            return _minimal_chat_completion()
+
+    class DummyClient:
+        def __init__(self) -> None:
+            self.completions = DummyCompletions()
+            self.chat = type("_Chat", (), {"completions": self.completions})()
+            self.base_url = httpx.URL("http://fake")
+
+    client = DummyClient()
+    model = OpenAIChatCompletionsModel(
+        model="gpt-4",
+        openai_client=client,  # type: ignore[arg-type]
+    )
+
+    with caplog.at_level(logging.WARNING, logger="openai.agents"):
+        await model.get_response(
+            system_instructions=None,
+            input=[
+                {
+                    "type": "function_call_output",
+                    "call_id": "call_image",
+                    "output": [
+                        {
+                            "type": "input_image",
+                            "image_url": "https://example.com/image.png",
+                        }
+                    ],
+                }
+            ],
+            model_settings=ModelSettings(),
+            tools=[],
+            output_schema=None,
+            handoffs=[],
+            tracing=ModelTracing.DISABLED,
+            previous_response_id=None,
+            conversation_id=None,
+            prompt=None,
+        )
+
+    assert client.completions.kwargs["messages"] == [
+        {
+            "role": "tool",
+            "tool_call_id": "call_image",
+            "content": "[tool output omitted]",
+        }
+    ]
+    assert "Replacing the tool output with a placeholder" in caplog.text
+
+
 @pytest.mark.allow_call_model_methods
 @pytest.mark.asyncio
 async def test_get_response_attaches_logprobs(monkeypatch) -> None:

tests/models/test_openai_chatcompletions_converter.py

@@ -23,6 +23,7 @@
 
 from __future__ import annotations
 
+import logging
 from typing import Literal, cast
 
 import pytest
@@ -356,7 +357,9 @@ def test_items_to_messages_with_function_output_item():
     assert tool_msg["content"] == func_output_item["output"]
 
 
-def test_items_to_messages_with_non_text_only_function_output_uses_placeholder_by_default():
+def test_items_to_messages_with_non_text_only_function_output_uses_placeholder_by_default(
+    caplog: pytest.LogCaptureFixture,
+):
     """Default conversion should keep running without sending an empty tool message."""
     func_output_item: FunctionCallOutput = {
         "type": "function_call_output",
@@ -369,13 +372,15 @@ def test_items_to_messages_with_non_text_only_function_output_uses_placeholder_b
         ],
     }
 
-    messages = Converter.items_to_messages([func_output_item])
+    with caplog.at_level(logging.WARNING, logger="openai.agents"):
+        messages = Converter.items_to_messages([func_output_item])
 
     assert len(messages) == 1
     tool_msg = messages[0]
     assert tool_msg["role"] == "tool"
     assert tool_msg["tool_call_id"] == func_output_item["call_id"]
-    assert tool_msg["content"] == "[non-text tool output omitted]"
+    assert tool_msg["content"] == "[tool output omitted]"
+    assert "Replacing the tool output with a placeholder" in caplog.text
 
 
 def test_items_to_messages_with_non_text_only_function_output_raises_in_strict_mode():
@@ -391,11 +396,46 @@ def test_items_to_messages_with_non_text_only_function_output_raises_in_strict_m
         ],
     }
 
-    with pytest.raises(UserError, match="cannot contain only non-text content"):
+    with pytest.raises(UserError, match="cannot be empty or contain only non-text content"):
+        Converter.items_to_messages([func_output_item], strict_feature_validation=True)
+
+
+def test_items_to_messages_with_empty_function_output_uses_placeholder_by_default(
+    caplog: pytest.LogCaptureFixture,
+):
+    """Default conversion should not send an empty tool message."""
+    func_output_item: FunctionCallOutput = {
+        "type": "function_call_output",
+        "call_id": "somecall",
+        "output": [],
+    }
+
+    with caplog.at_level(logging.WARNING, logger="openai.agents"):
+        messages = Converter.items_to_messages([func_output_item])
+
+    assert len(messages) == 1
+    tool_msg = messages[0]
+    assert tool_msg["role"] == "tool"
+    assert tool_msg["tool_call_id"] == func_output_item["call_id"]
+    assert tool_msg["content"] == "[tool output omitted]"
+    assert "Replacing the tool output with a placeholder" in caplog.text
+
+
+def test_items_to_messages_with_empty_function_output_raises_in_strict_mode():
+    """Strict validation should fail explicitly instead of sending empty output."""
+    func_output_item: FunctionCallOutput = {
+        "type": "function_call_output",
+        "call_id": "somecall",
+        "output": [],
+    }
+
+    with pytest.raises(UserError, match="cannot be empty or contain only non-text content"):
         Converter.items_to_messages([func_output_item], strict_feature_validation=True)
 
 
-def test_items_to_messages_with_mixed_function_output_keeps_text_by_default():
+def test_items_to_messages_with_mixed_function_output_keeps_text_by_default(
+    caplog: pytest.LogCaptureFixture,
+):
     """Default conversion should preserve text parts and omit unsupported non-text parts."""
     func_output_item: FunctionCallOutput = {
         "type": "function_call_output",
@@ -409,13 +449,15 @@ def test_items_to_messages_with_mixed_function_output_keeps_text_by_default():
         ],
     }
 
-    messages = Converter.items_to_messages([func_output_item])
+    with caplog.at_level(logging.WARNING, logger="openai.agents"):
+        messages = Converter.items_to_messages([func_output_item])
 
     assert len(messages) == 1
     tool_msg = messages[0]
     assert tool_msg["role"] == "tool"
     assert tool_msg["tool_call_id"] == func_output_item["call_id"]
     assert tool_msg["content"] == [{"type": "text", "text": "visible text"}]
+    assert "tool output omitted" not in caplog.text
 
 
 def test_items_to_messages_can_preserve_non_text_function_output() -> None: