feat(openai-agents): Set system instruction attribute on gen_ai.chat spans (#5370)

Set the system instruction attribute on `gen_ai.chat` spans instead of `gen_ai.invoke_agent` spans in `OpenAIAgentsIntegration`. Extract instructions from string input, content strings and parts-style content lists, since `openai-agents` uses an input schema compatible with the OpenAI Responses API.

Author: alexander-alderman-webb

sentry_sdk/ai/_openai_completions_api.py

@@ -0,0 +1,48 @@
+from collections.abc import Iterable
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sentry_sdk._types import TextPart
+
+    from openai.types.chat import (
+        ChatCompletionMessageParam,
+        ChatCompletionSystemMessageParam,
+    )
+
+
+def _is_system_instruction(message: "ChatCompletionMessageParam") -> bool:
+    return isinstance(message, dict) and message.get("role") == "system"
+
+
+def _get_system_instructions(
+    messages: "Iterable[ChatCompletionMessageParam]",
+) -> "list[ChatCompletionMessageParam]":
+    if not isinstance(messages, Iterable):
+        return []
+
+    return [message for message in messages if _is_system_instruction(message)]
+
+
+def _transform_system_instructions(
+    system_instructions: "list[ChatCompletionSystemMessageParam]",
+) -> "list[TextPart]":
+    instruction_text_parts: "list[TextPart]" = []
+
+    for instruction in system_instructions:
+        if not isinstance(instruction, dict):
+            continue
+
+        content = instruction.get("content")
+
+        if isinstance(content, str):
+            instruction_text_parts.append({"type": "text", "content": content})
+
+        elif isinstance(content, list):
+            for part in content:
+                if isinstance(part, dict) and part.get("type") == "text":
+                    text = part.get("text", None)
+                    if text is not None:
+                        instruction_text_parts.append({"type": "text", "content": text})
+
+    return instruction_text_parts

sentry_sdk/ai/_openai_responses_api.py

@@ -0,0 +1,22 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Union
+
+    from openai.types.responses import ResponseInputParam, ResponseInputItemParam
+
+
+def _is_system_instruction(message: "ResponseInputItemParam") -> bool:
+    if not isinstance(message, dict) or not message.get("role") == "system":
+        return False
+
+    return "type" not in message or message["type"] == "message"
+
+
+def _get_system_instructions(
+    messages: "Union[str, ResponseInputParam]",
+) -> "list[ResponseInputItemParam]":
+    if not isinstance(messages, list):
+        return []
+
+    return [message for message in messages if _is_system_instruction(message)]

sentry_sdk/integrations/openai.py

@@ -11,6 +11,15 @@
     normalize_message_roles,
     truncate_and_annotate_messages,
 )
+from sentry_sdk.ai._openai_completions_api import (
+    _is_system_instruction as _is_system_instruction_completions,
+    _get_system_instructions as _get_system_instructions_completions,
+    _transform_system_instructions,
+)
+from sentry_sdk.ai._openai_responses_api import (
+    _is_system_instruction as _is_system_instruction_responses,
+    _get_system_instructions as _get_system_instructions_responses,
+)
 from sentry_sdk.consts import SPANDATA
 from sentry_sdk.integrations import DidNotEnable, Integration
 from sentry_sdk.scope import should_send_default_pii
@@ -33,11 +42,12 @@
         AsyncIterator,
         Iterator,
         Union,
+        Iterable,
     )
     from sentry_sdk.tracing import Span
     from sentry_sdk._types import TextPart
 
-    from openai.types.responses import ResponseInputParam, ResponseInputItemParam
+    from openai.types.responses import ResponseInputParam
     from openai import Omit
 
 try:
@@ -200,63 +210,6 @@ def _calculate_token_usage(
     )
 
 
-def _is_system_instruction_completions(message: "ChatCompletionMessageParam") -> bool:
-    return isinstance(message, dict) and message.get("role") == "system"
-
-
-def _get_system_instructions_completions(
-    messages: "Iterable[ChatCompletionMessageParam]",
-) -> "list[ChatCompletionMessageParam]":
-    if not isinstance(messages, Iterable):
-        return []
-
-    return [
-        message for message in messages if _is_system_instruction_completions(message)
-    ]
-
-
-def _is_system_instruction_responses(message: "ResponseInputItemParam") -> bool:
-    if not isinstance(message, dict) or not message.get("role") == "system":
-        return False
-
-    return "type" not in message or message["type"] == "message"
-
-
-def _get_system_instructions_responses(
-    messages: "Union[str, ResponseInputParam]",
-) -> "list[ResponseInputItemParam]":
-    if not isinstance(messages, list):
-        return []
-
-    return [
-        message for message in messages if _is_system_instruction_responses(message)
-    ]
-
-
-def _transform_system_instructions(
-    system_instructions: "list[ChatCompletionSystemMessageParam]",
-) -> "list[TextPart]":
-    instruction_text_parts: "list[TextPart]" = []
-
-    for instruction in system_instructions:
-        if not isinstance(instruction, dict):
-            continue
-
-        content = instruction.get("content")
-
-        if isinstance(content, str):
-            instruction_text_parts.append({"type": "text", "content": content})
-
-        elif isinstance(content, list):
-            for part in content:
-                if isinstance(part, dict) and part.get("type") == "text":
-                    text = part.get("text", "")
-                    if text:
-                        instruction_text_parts.append({"type": "text", "content": text})
-
-    return instruction_text_parts
-
-
 def _get_input_messages(
     kwargs: "dict[str, Any]",
 ) -> "Optional[Union[Iterable[Any], list[str]]]":

sentry_sdk/integrations/openai_agents/spans/invoke_agent.py

@@ -18,17 +18,6 @@
     import agents
     from typing import Any, Optional
 
-    from sentry_sdk._types import TextPart
-
-
-def _transform_system_instruction(system_instructions: "str") -> "list[TextPart]":
-    return [
-        {
-            "type": "text",
-            "content": system_instructions,
-        }
-    ]
-
 
 def invoke_agent_span(
     context: "agents.RunContextWrapper", agent: "agents.Agent", kwargs: "dict[str, Any]"
@@ -46,16 +35,16 @@ def invoke_agent_span(
     if should_send_default_pii():
         messages = []
         if agent.instructions:
-            system_instruction = (
+            message = (
                 agent.instructions
                 if isinstance(agent.instructions, str)
                 else safe_serialize(agent.instructions)
             )
-            set_data_normalized(
-                span,
-                SPANDATA.GEN_AI_SYSTEM_INSTRUCTIONS,
-                _transform_system_instruction(system_instruction),
-                unpack=False,
+            messages.append(
+                {
+                    "content": [{"text": message, "type": "text"}],
+                    "role": "system",
+                }
             )
 
         original_input = kwargs.get("original_input")

sentry_sdk/integrations/openai_agents/utils.py

@@ -11,14 +11,20 @@
 from sentry_sdk.scope import should_send_default_pii
 from sentry_sdk.tracing_utils import set_span_errored
 from sentry_sdk.utils import event_from_exception, safe_serialize
+from sentry_sdk.ai._openai_completions_api import _transform_system_instructions
+from sentry_sdk.ai._openai_responses_api import (
+    _is_system_instruction,
+    _get_system_instructions,
+)
 
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from typing import Any
-    from agents import Usage
+    from agents import Usage, TResponseInputItem
 
     from sentry_sdk.tracing import Span
+    from sentry_sdk._types import TextPart
 
 try:
     import agents
@@ -121,19 +127,39 @@ def _set_input_data(
         return
     request_messages = []
 
-    system_instructions = get_response_kwargs.get("system_instructions")
-    if system_instructions:
-        request_messages.append(
+    messages: "str | list[TResponseInputItem]" = get_response_kwargs.get("input", [])
+
+    instructions_text_parts: "list[TextPart]" = []
+    explicit_instructions = get_response_kwargs.get("system_instructions")
+    if explicit_instructions is not None:
+        instructions_text_parts.append(
             {
-                "role": GEN_AI_ALLOWED_MESSAGE_ROLES.SYSTEM,
-                "content": [{"type": "text", "text": system_instructions}],
+                "type": "text",
+                "content": explicit_instructions,
             }
         )
 
-    for message in get_response_kwargs.get("input", []):
+    system_instructions = _get_system_instructions(messages)
+
+    # Deliberate use of function accepting completions API type because
+    # of shared structure FOR THIS PURPOSE ONLY.
+    instructions_text_parts += _transform_system_instructions(system_instructions)
+
+    if len(instructions_text_parts) > 0:
+        set_data_normalized(
+            span,
+            SPANDATA.GEN_AI_SYSTEM_INSTRUCTIONS,
+            instructions_text_parts,
+            unpack=False,
+        )
+
+    non_system_messages = [
+        message for message in messages if not _is_system_instruction(message)
+    ]
+    for message in non_system_messages:
         if "role" in message:
-            normalized_role = normalize_message_role(message.get("role"))
-            content = message.get("content")
+            normalized_role = normalize_message_role(message.get("role"))  # type: ignore
+            content = message.get("content")  # type: ignore
             request_messages.append(
                 {
                     "role": normalized_role,
@@ -145,14 +171,14 @@ def _set_input_data(
                 }
             )
         else:
-            if message.get("type") == "function_call":
+            if message.get("type") == "function_call":  # type: ignore
                 request_messages.append(
                     {
                         "role": GEN_AI_ALLOWED_MESSAGE_ROLES.ASSISTANT,
                         "content": [message],
                     }
                 )
-            elif message.get("type") == "function_call_output":
+            elif message.get("type") == "function_call_output":  # type: ignore
                 request_messages.append(
                     {
                         "role": GEN_AI_ALLOWED_MESSAGE_ROLES.TOOL,