trace update for system instructions (#45138)

* trace update for system instructions

* update changelog

* update to re-trigger ci

* update to re-trigger ci

Author: M-Hietala

sdk/ai/azure-ai-projects/CHANGELOG.md

@@ -26,7 +26,7 @@
 * Tracing: response generation span names changed from "responses {model_name}" to "chat {model_name}" for model calls and from "responses {agent_name}" to "invoke_agent {agent_name}" for agent calls.
 * Tracing: response generation operation names changed from "responses" to "chat" for model calls and from "responses" to "invoke_agent" for agent calls.
 * Tracing: response generation uses gen_ai.input.messages and gen_ai.output.messages attributes directly under the span instead of events.
-* Tracing: agent creation uses gen_ai.system.instructions attribute directly under the span instead of an event.
+* Tracing: agent creation uses gen_ai.system_instructions attribute directly under the span instead of an event. Note that the attribute name is gen_ai.system_instructions not gen_ai.system.instructions.
 * Tracing: "gen_ai.provider.name" attribute value changed to "microsoft.foundry".
 * Tracing: the format of the function tool call related traces in input and output messages changed to {"type": "tool_call", "id": "...", "name": "...", "arguments": {...}} and {"type": "tool_call_response", "id": "...", "result": "..."}
 

sdk/ai/azure-ai-projects/azure/ai/projects/telemetry/_ai_project_instrumentor.py

@@ -34,6 +34,7 @@
     GEN_AI_OUTPUT_MESSAGES,
     GEN_AI_PROVIDER_NAME,
     GEN_AI_SYSTEM_MESSAGE,
+    GEN_AI_SYSTEM_INSTRUCTION_EVENT,
     GEN_AI_THREAD_ID,
     GEN_AI_THREAD_RUN_ID,
     GEN_AI_USAGE_INPUT_TOKENS,
@@ -633,9 +634,10 @@ def _add_instructions_event(
             return
 
         content_array: List[Dict[str, Any]] = []
-        if _trace_agents_content:
-            # Add instructions if provided
-            if instructions:
+
+        # Add instructions if provided
+        if instructions:
+            if _trace_agents_content:
                 # Combine instructions if both exist
                 if additional_instructions:
                     combined_text = f"{instructions} {additional_instructions}"
@@ -644,9 +646,13 @@ def _add_instructions_event(
 
                 # Use optimized format with consistent "content" field
                 content_array.append({"type": "text", "content": combined_text})
+            else:
+                # Content recording disabled, but indicate that text instructions exist
+                content_array.append({"type": "text"})
 
-            # Add response schema if provided
-            if response_schema is not None:
+        # Add response schema if provided
+        if response_schema is not None:
+            if _trace_agents_content:
                 # Convert schema to JSON string if it's a dict/object
                 if isinstance(response_schema, dict):
                     schema_str = json.dumps(response_schema, ensure_ascii=False)
@@ -663,6 +669,9 @@ def _add_instructions_event(
                     schema_str = str(response_schema)
 
                 content_array.append({"type": "response_schema", "content": schema_str})
+            else:
+                # Content recording disabled, but indicate that response schema exists
+                content_array.append({"type": "response_schema"})
 
         use_events = _get_use_message_events()
 
@@ -671,14 +680,11 @@ def _add_instructions_event(
             attributes = self._create_event_attributes(agent_id=agent_id, thread_id=thread_id)
             # Store as JSON array directly without outer wrapper
             attributes[GEN_AI_EVENT_CONTENT] = json.dumps(content_array, ensure_ascii=False)
-            span.span_instance.add_event(name=GEN_AI_SYSTEM_MESSAGE, attributes=attributes)
+            span.span_instance.add_event(name=GEN_AI_SYSTEM_INSTRUCTION_EVENT, attributes=attributes)
         else:
             # Use attributes for instructions tracing
-            # System instructions use the same attribute name as the event
-            message_json = json.dumps(
-                [{"role": "system", "parts": content_array}] if content_array else [{"role": "system"}],
-                ensure_ascii=False,
-            )
+            # System instructions format: array of content objects without role/parts wrapper
+            message_json = json.dumps(content_array, ensure_ascii=False)
             if span and span.span_instance.is_recording:
                 span.add_attribute(GEN_AI_SYSTEM_MESSAGE, message_json)
 

sdk/ai/azure-ai-projects/azure/ai/projects/telemetry/_utils.py

@@ -45,7 +45,7 @@
 GEN_AI_REQUEST_RESPONSE_FORMAT = "gen_ai.request.response_format"
 GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens"
 GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens"
-GEN_AI_SYSTEM_MESSAGE = "gen_ai.system.instructions"
+GEN_AI_SYSTEM_MESSAGE = "gen_ai.system_instructions"
 GEN_AI_EVENT_CONTENT = "gen_ai.event.content"
 GEN_AI_RUN_STEP_START_TIMESTAMP = "gen_ai.run_step.start.timestamp"
 GEN_AI_RUN_STEP_END_TIMESTAMP = "gen_ai.run_step.end.timestamp"

sdk/ai/azure-ai-projects/tests/agents/telemetry/test_ai_agents_instrumentor.py

@@ -239,13 +239,8 @@ def _test_agent_creation_with_tracing_content_recording_enabled_impl(self, use_e
             expected_system_message = json.dumps(
                 [
                     {
-                        "role": "system",
-                        "parts": [
-                            {
-                                "type": "text",
-                                "content": "You are a helpful AI assistant. Be polite and provide accurate information.",
-                            }
-                        ],
+                        "type": "text",
+                        "content": "You are a helpful AI assistant. Be polite and provide accurate information.",
                     }
                 ],
                 ensure_ascii=False,
@@ -279,15 +274,12 @@ def _test_agent_creation_with_tracing_content_recording_enabled_impl(self, use_e
             system_message_json = span.attributes[GEN_AI_SYSTEM_MESSAGE]
             system_message = json.loads(system_message_json)
 
-            # Verify structure
+            # Verify structure (new format without role/parts wrapper)
             assert isinstance(system_message, list)
             assert len(system_message) == 1
-            assert system_message[0]["role"] == "system"
-            assert "parts" in system_message[0]
-            assert len(system_message[0]["parts"]) == 1
-            assert system_message[0]["parts"][0]["type"] == "text"
+            assert system_message[0]["type"] == "text"
             assert (
-                system_message[0]["parts"][0]["content"]
+                system_message[0]["content"]
                 == "You are a helpful AI assistant. Be polite and provide accurate information."
             )
 
@@ -349,25 +341,27 @@ def _test_agent_creation_with_tracing_content_recording_disabled_impl(self, use_
         ]
 
         # When using attributes (regardless of content recording), add system message attribute
-        # When content recording is disabled, it will have empty content (just role)
+        # When content recording is disabled, it will have type indicator without content
         if not use_events:
             from azure.ai.projects.telemetry._utils import GEN_AI_SYSTEM_MESSAGE
             import json
 
-            # Empty system message (no parts, just role)
-            expected_system_message = json.dumps([{"role": "system"}], ensure_ascii=False)
+            # Empty system message (type indicator only, no content)
+            expected_system_message = json.dumps([{"type": "text"}], ensure_ascii=False)
             expected_attributes.append((GEN_AI_SYSTEM_MESSAGE, expected_system_message))
 
         attributes_match = GenAiTraceVerifier().check_span_attributes(span, expected_attributes)
         assert attributes_match == True
 
         if use_events:
+            import json
+
             expected_events = [
                 {
                     "name": GEN_AI_SYSTEM_INSTRUCTION_EVENT,
                     "attributes": {
                         GEN_AI_PROVIDER_NAME: AGENTS_PROVIDER,
-                        GEN_AI_EVENT_CONTENT: "[]",
+                        GEN_AI_EVENT_CONTENT: json.dumps([{"type": "text"}]),
                     },
                 }
             ]
@@ -383,12 +377,11 @@ def _test_agent_creation_with_tracing_content_recording_disabled_impl(self, use_
 
             system_message_json = span.attributes[GEN_AI_SYSTEM_MESSAGE]
             system_message = json.loads(system_message_json)
-            # Should have empty content (just role, no parts)
+            # Should have type indicator when content recording is disabled
             assert isinstance(system_message, list)
             assert len(system_message) == 1
-            assert system_message[0]["role"] == "system"
-            # No parts field when content recording is disabled
-            assert "parts" not in system_message[0]
+            assert system_message[0]["type"] == "text"
+            assert "content" not in system_message[0]
 
     @pytest.mark.usefixtures("instrument_without_content")
     @servicePreparer()
@@ -594,21 +587,19 @@ def _test_agent_with_structured_output_with_instructions_impl(
                 expected_system_msg = json.dumps(
                     [
                         {
-                            "role": "system",
-                            "parts": [
-                                {
-                                    "type": "text",
-                                    "content": "You are a helpful assistant that extracts person information.",
-                                },
-                                {"type": "response_schema", "content": json.dumps(test_schema)},
-                            ],
-                        }
+                            "type": "text",
+                            "content": "You are a helpful assistant that extracts person information.",
+                        },
+                        {"type": "response_schema", "content": json.dumps(test_schema)},
                     ],
                     ensure_ascii=False,
                 )
             else:
-                # When content recording disabled, attribute has empty structure
-                expected_system_msg = json.dumps([{"role": "system"}], ensure_ascii=False)
+                # When content recording disabled, type indicators without content
+                expected_system_msg = json.dumps(
+                    [{"type": "text"}, {"type": "response_schema"}],
+                    ensure_ascii=False,
+                )
             expected_attributes.append((GEN_AI_SYSTEM_MESSAGE, expected_system_msg))
 
         attributes_match = GenAiTraceVerifier().check_span_attributes(span, expected_attributes)
@@ -634,7 +625,12 @@ def _test_agent_with_structured_output_with_instructions_impl(
                 assert "name" in schema_obj["properties"]
                 assert "age" in schema_obj["properties"]
             else:
-                assert len(event_content) == 0  # Empty when content recording disabled
+                # Type indicators without content when content recording disabled
+                assert len(event_content) == 2
+                assert event_content[0]["type"] == "text"
+                assert "content" not in event_content[0]
+                assert event_content[1]["type"] == "response_schema"
+                assert "content" not in event_content[1]
         else:
             # When using attributes, verify attribute
             from azure.ai.projects.telemetry._utils import GEN_AI_SYSTEM_MESSAGE
@@ -646,25 +642,26 @@ def _test_agent_with_structured_output_with_instructions_impl(
             system_message = json.loads(system_message_json)
 
             assert isinstance(system_message, list)
-            assert len(system_message) == 1
-            assert system_message[0]["role"] == "system"
 
             if content_recording_enabled:
-                assert "parts" in system_message[0]
-                assert len(system_message[0]["parts"]) == 2
+                assert len(system_message) == 2
 
                 # Check instruction part
-                assert system_message[0]["parts"][0]["type"] == "text"
-                assert "helpful assistant" in system_message[0]["parts"][0]["content"]
+                assert system_message[0]["type"] == "text"
+                assert "helpful assistant" in system_message[0]["content"]
 
                 # Check schema part
-                assert system_message[0]["parts"][1]["type"] == "response_schema"
-                schema_obj = json.loads(system_message[0]["parts"][1]["content"])
+                assert system_message[1]["type"] == "response_schema"
+                schema_obj = json.loads(system_message[1]["content"])
                 assert schema_obj["type"] == "object"
                 assert "name" in schema_obj["properties"]
             else:
-                # When content recording disabled, no parts field
-                assert "parts" not in system_message[0]
+                # When content recording disabled, type indicators without content
+                assert len(system_message) == 2
+                assert system_message[0]["type"] == "text"
+                assert "content" not in system_message[0]
+                assert system_message[1]["type"] == "response_schema"
+                assert "content" not in system_message[1]
 
     @pytest.mark.usefixtures("instrument_with_content")
     @servicePreparer()
@@ -776,12 +773,12 @@ def _test_agent_with_structured_output_without_instructions_impl(
 
             if content_recording_enabled:
                 expected_system_msg = json.dumps(
-                    [{"role": "system", "parts": [{"type": "response_schema", "content": json.dumps(test_schema)}]}],
+                    [{"type": "response_schema", "content": json.dumps(test_schema)}],
                     ensure_ascii=False,
                 )
             else:
-                # When content recording disabled, attribute has empty structure
-                expected_system_msg = json.dumps([{"role": "system"}], ensure_ascii=False)
+                # When content recording disabled, type indicator without content
+                expected_system_msg = json.dumps([{"type": "response_schema"}], ensure_ascii=False)
             expected_attributes.append((GEN_AI_SYSTEM_MESSAGE, expected_system_msg))
 
         attributes_match = GenAiTraceVerifier().check_span_attributes(span, expected_attributes)
@@ -804,7 +801,10 @@ def _test_agent_with_structured_output_without_instructions_impl(
                 assert schema_obj["type"] == "object"
                 assert "result" in schema_obj["properties"]
             else:
-                assert len(event_content) == 0  # Empty when content recording disabled
+                # Type indicator without content when content recording disabled
+                assert len(event_content) == 1
+                assert event_content[0]["type"] == "response_schema"
+                assert "content" not in event_content[0]
         else:
             # When using attributes, verify attribute
             from azure.ai.projects.telemetry._utils import GEN_AI_SYSTEM_MESSAGE
@@ -816,21 +816,20 @@ def _test_agent_with_structured_output_without_instructions_impl(
             system_message = json.loads(system_message_json)
 
             assert isinstance(system_message, list)
-            assert len(system_message) == 1
-            assert system_message[0]["role"] == "system"
 
             if content_recording_enabled:
-                assert "parts" in system_message[0]
-                assert len(system_message[0]["parts"]) == 1
+                assert len(system_message) == 1
 
                 # Check schema part
-                assert system_message[0]["parts"][0]["type"] == "response_schema"
-                schema_obj = json.loads(system_message[0]["parts"][0]["content"])
+                assert system_message[0]["type"] == "response_schema"
+                schema_obj = json.loads(system_message[0]["content"])
                 assert schema_obj["type"] == "object"
                 assert "result" in schema_obj["properties"]
             else:
-                # When content recording disabled, no parts field
-                assert "parts" not in system_message[0]
+                # When content recording disabled, type indicator without content
+                assert len(system_message) == 1
+                assert system_message[0]["type"] == "response_schema"
+                assert "content" not in system_message[0]
 
     @pytest.mark.usefixtures("instrument_with_content")
     @servicePreparer()