fix(openai): always use string content for tool messages (#1878)

Co-authored-by: giulio-leone <giulio.leone@users.noreply.github.com>

Author: giulio-leone

src/strands/models/openai.py

@@ -204,13 +204,33 @@ def format_request_tool_message(cls, tool_result: ToolResult, **kwargs: Any) ->
             ],
         )
 
-        formatted_contents = [cls.format_request_message_content(content) for content in contents]
-
-        # If single text content, use string format for better model compatibility
-        if len(formatted_contents) == 1 and formatted_contents[0].get("type") == "text":
-            content: str | list[dict[str, Any]] = formatted_contents[0]["text"]
+        # Merge adjacent text blocks while preserving the order of non-text
+        # (image/document) content.  When all content is text, join into a
+        # single string for broad compatibility with OpenAI-compatible
+        # endpoints (e.g., Kimi K2.5, vLLM, Ollama).
+        # See https://github.com/strands-agents/sdk-python/issues/1696
+        merged: list[dict[str, Any]] = []
+        has_non_text = False
+        for content_block in contents:
+            if "text" in content_block:
+                # Merge with the previous entry if it is also text (adjacent)
+                if merged and merged[-1].get("type") == "text":
+                    merged[-1]["text"] += "\n" + content_block["text"]
+                else:
+                    merged.append({"type": "text", "text": content_block["text"]})
+            elif "image" in content_block or "document" in content_block:
+                has_non_text = True
+                merged.append(cls.format_request_message_content(content_block))
+
+        content: str | list[dict[str, Any]]
+        if has_non_text:
+            # Keep array format when images/documents are present so that
+            # _split_tool_message_images can extract them into a user message.
+            content = merged
         else:
-            content = formatted_contents
+            # All text — the loop already merged adjacent blocks with "\n",
+            # so extract the single resulting entry.
+            content = merged[0]["text"] if merged else ""
 
         return {
             "role": "tool",

tests/strands/models/test_openai.py

@@ -173,7 +173,7 @@ def test_format_request_tool_message():
 
     tru_result = OpenAIModel.format_request_tool_message(tool_result)
     exp_result = {
-        "content": [{"text": "4", "type": "text"}, {"text": '["4"]', "type": "text"}],
+        "content": '4\n["4"]',
         "role": "tool",
         "tool_call_id": "c1",
     }
@@ -197,6 +197,130 @@ def test_format_request_tool_message_single_text_returns_string():
     assert tru_result == exp_result
 
 
+def test_format_request_tool_message_multi_text_returns_joined_string():
+    """Test that multi-content text results are joined into a single string.
+
+    Regression test for https://github.com/strands-agents/sdk-python/issues/1696.
+    OpenAI-compatible endpoints (e.g., Kimi K2.5, vLLM, Ollama) only correctly
+    parse string content for tool messages; array format causes hallucinated results.
+    """
+    tool_result = {
+        "content": [
+            {"text": "Temperature: 72°F"},
+            {"json": {"humidity": 45, "unit": "%"}},
+            {"text": "Wind: 5 mph"},
+        ],
+        "status": "success",
+        "toolUseId": "c1",
+    }
+
+    tru_result = OpenAIModel.format_request_tool_message(tool_result)
+    exp_result = {
+        "content": 'Temperature: 72°F\n{"humidity": 45, "unit": "%"}\nWind: 5 mph',
+        "role": "tool",
+        "tool_call_id": "c1",
+    }
+    assert tru_result == exp_result
+
+
+def test_format_request_tool_message_mixed_text_image_preserves_order():
+    """Test that text and image content blocks preserve their original order."""
+    tool_result = {
+        "content": [
+            {"text": "Before image"},
+            {"image": {"format": "png", "source": {"bytes": b"PNG"}}},
+            {"text": "After image"},
+        ],
+        "status": "success",
+        "toolUseId": "c1",
+    }
+
+    tru_result = OpenAIModel.format_request_tool_message(tool_result)
+    content = tru_result["content"]
+    # Array format since images are present
+    assert isinstance(content, list)
+    assert len(content) == 3
+    # Order preserved: text, image, text
+    assert content[0] == {"type": "text", "text": "Before image"}
+    assert content[1]["type"] == "image_url"
+    assert content[2] == {"type": "text", "text": "After image"}
+
+
+def test_format_request_tool_message_merges_adjacent_text():
+    """Test that adjacent text blocks are merged while non-text order is preserved."""
+    tool_result = {
+        "content": [
+            {"text": "Line 1"},
+            {"text": "Line 2"},
+            {"image": {"format": "png", "source": {"bytes": b"PNG"}}},
+            {"text": "Line 3"},
+        ],
+        "status": "success",
+        "toolUseId": "c1",
+    }
+
+    tru_result = OpenAIModel.format_request_tool_message(tool_result)
+    content = tru_result["content"]
+    assert isinstance(content, list)
+    assert len(content) == 3
+    # Adjacent text merged, image order preserved
+    assert content[0] == {"type": "text", "text": "Line 1\nLine 2"}
+    assert content[1]["type"] == "image_url"
+    assert content[2] == {"type": "text", "text": "Line 3"}
+
+
+def test_format_request_tool_message_image_only():
+    """Test tool message with only non-text content."""
+    tool_result = {
+        "content": [
+            {"image": {"format": "png", "source": {"bytes": b"PNG"}}},
+        ],
+        "status": "success",
+        "toolUseId": "c1",
+    }
+
+    tru_result = OpenAIModel.format_request_tool_message(tool_result)
+    content = tru_result["content"]
+    assert isinstance(content, list)
+    assert len(content) == 1
+    assert content[0]["type"] == "image_url"
+
+
+def test_format_request_tool_message_document_mixed():
+    """Test tool message with document content mixed with text."""
+    tool_result = {
+        "content": [
+            {"text": "Summary"},
+            {"document": {"format": "pdf", "name": "report.pdf", "source": {"bytes": b"PDF"}}},
+            {"text": "Footer"},
+        ],
+        "status": "success",
+        "toolUseId": "c1",
+    }
+
+    tru_result = OpenAIModel.format_request_tool_message(tool_result)
+    content = tru_result["content"]
+    assert isinstance(content, list)
+    assert len(content) == 3
+    assert content[0] == {"type": "text", "text": "Summary"}
+    assert content[1]["type"] == "file"
+    assert content[2] == {"type": "text", "text": "Footer"}
+
+
+def test_format_request_tool_message_empty_content():
+    """Test tool message with empty content list returns empty string."""
+    tool_result = {
+        "content": [],
+        "status": "success",
+        "toolUseId": "c1",
+    }
+
+    tru_result = OpenAIModel.format_request_tool_message(tool_result)
+    assert tru_result["content"] == ""
+    assert tru_result["role"] == "tool"
+    assert tru_result["tool_call_id"] == "c1"
+
+
 def test_split_tool_message_images_with_image():
     """Test that images are extracted from tool messages."""
     tool_message = {