fix(openai): safe handle None tools value in responses api (#3447)

Author: galkleinman

packages/opentelemetry-instrumentation-openai/opentelemetry/instrumentation/openai/v1/responses_wrappers.py

@@ -144,6 +144,10 @@ def parse_response(response: Union[LegacyAPIResponse, Response]) -> Response:
 
 def get_tools_from_kwargs(kwargs: dict) -> list[ToolParam]:
     tools_input = kwargs.get("tools", [])
+    # Handle case where tools key exists but value is None
+    # (e.g., when wrappers like openai-guardrails pass tools=None)
+    if tools_input is None:
+        tools_input = []
     tools = []
 
     for tool in tools_input:

packages/opentelemetry-instrumentation-openai/tests/traces/test_responses.py

@@ -2,6 +2,9 @@
 
 from openai import AsyncOpenAI, OpenAI
 from opentelemetry.instrumentation.openai.utils import is_reasoning_supported
+from opentelemetry.instrumentation.openai.v1.responses_wrappers import (
+    get_tools_from_kwargs,
+)
 from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
 
 
@@ -384,3 +387,79 @@ async def test_responses_streaming_async_with_context_manager(
     assert span.attributes["gen_ai.prompt.0.role"] == "user"
     assert span.attributes["gen_ai.completion.0.role"] == "assistant"
     assert span.attributes["gen_ai.completion.0.content"] == full_text
+
+
+def test_get_tools_from_kwargs_with_none():
+    """Test that get_tools_from_kwargs handles None tools value correctly.
+
+    This reproduces the bug reported when openai-guardrails or other wrappers
+    pass tools=None explicitly, causing TypeError: 'NoneType' object is not iterable.
+    """
+    # Test case 1: tools key exists but value is None
+    kwargs_with_none = {"tools": None, "model": "gpt-4", "input": "test"}
+    result = get_tools_from_kwargs(kwargs_with_none)
+    assert result == [], "Should return empty list when tools is None"
+
+    # Test case 2: tools key doesn't exist
+    kwargs_without_tools = {"model": "gpt-4", "input": "test"}
+    result = get_tools_from_kwargs(kwargs_without_tools)
+    assert result == [], "Should return empty list when tools key is missing"
+
+    # Test case 3: tools is an empty list
+    kwargs_empty_list = {"tools": [], "model": "gpt-4", "input": "test"}
+    result = get_tools_from_kwargs(kwargs_empty_list)
+    assert result == [], "Should return empty list when tools is empty list"
+
+    # Test case 4: tools with valid function tools
+    kwargs_with_tools = {
+        "tools": [{"type": "function", "name": "test_func", "description": "test"}],
+        "model": "gpt-4",
+        "input": "test",
+    }
+    result = get_tools_from_kwargs(kwargs_with_tools)
+    assert len(result) == 1, "Should return list with one tool"
+
+
+def test_response_stream_init_with_none_tools():
+    """Test ResponseStream initialization when tools=None is in request_kwargs.
+
+    This reproduces the customer issue where openai-guardrails wraps the client
+    and may pass tools=None, causing TypeError in ResponseStream.__init__.
+    """
+    from unittest.mock import MagicMock
+    from opentelemetry.instrumentation.openai.v1.responses_wrappers import (
+        ResponseStream,
+    )
+
+    # Create a mock response object
+    mock_response = MagicMock()
+
+    # Create a mock span
+    mock_span = MagicMock()
+
+    # Create a mock tracer
+    mock_tracer = MagicMock()
+
+    # Test that ResponseStream can be initialized with tools=None
+    # This should not raise TypeError: 'NoneType' object is not iterable
+    request_kwargs_with_none_tools = {
+        "model": "gpt-4",
+        "input": "test",
+        "tools": None,  # This is what causes the bug
+        "stream": True,
+    }
+
+    # This should not raise an exception
+    stream = ResponseStream(
+        span=mock_span,
+        response=mock_response,
+        start_time=1234567890,
+        request_kwargs=request_kwargs_with_none_tools,
+        tracer=mock_tracer,
+    )
+
+    # Verify the stream was created successfully
+    assert stream is not None
+    assert stream._traced_data is not None
+    # Tools should be an empty list, not None
+    assert stream._traced_data.tools == [] or stream._traced_data.tools is None