trace update for system instructions

[M-Hietala]

trace update for system instructions

[Copilot]

Pull request overview

Updates the Azure AI Projects telemetry “system instructions” tracing to use a new attribute key and a spec-aligned JSON payload shape, and adjusts agent telemetry tests and documentation accordingly.

Changes:

• Renamed the system-instructions span attribute from gen_ai.system.instructions to gen_ai.system_instructions.
• Changed the system-instructions payload format to a JSON array of content objects (e.g., [{ "type": "text", "content": "..." }]), and emits type-only indicators when content recording is disabled.
• Updated agent telemetry tests and release notes to match the new tracing behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
sdk/ai/azure-ai-projects/tests/agents/telemetry/test_responses_instrumentor_async.py	Minor formatting/whitespace cleanup in async response streaming tests.
sdk/ai/azure-ai-projects/tests/agents/telemetry/test_ai_agents_instrumentor_async.py	Updates async agent telemetry expectations for the new system-instructions attribute/event payload shapes.
sdk/ai/azure-ai-projects/tests/agents/telemetry/test_ai_agents_instrumentor.py	Updates sync agent telemetry expectations for the new system-instructions attribute/event payload shapes.
sdk/ai/azure-ai-projects/azure/ai/projects/telemetry/_utils.py	Renames GEN_AI_SYSTEM_MESSAGE attribute key to gen_ai.system_instructions.
sdk/ai/azure-ai-projects/azure/ai/projects/telemetry/_ai_project_instrumentor.py	Emits system-instructions as an event named gen_ai.system.instructions (when events enabled) or as an attribute gen_ai.system_instructions (when attributes mode), using the new JSON array-of-content-objects format.
sdk/ai/azure-ai-projects/CHANGELOG.md	Adds a breaking-change note about the attribute rename and format change.

Comments suppressed due to low confidence (1)

sdk/ai/azure-ai-projects/tests/agents/telemetry/test_ai_agents_instrumentor_async.py:245

• json is imported at the top of this helper (line 179), but it’s imported again later in the else branch. Consider removing the later import json and reusing the existing import to avoid redundancy.

        import json

        self.cleanup()
        _set_use_message_events(use_events)
        os.environ.update({CONTENT_TRACING_ENV_VARIABLE: "False"})
        self.setup_telemetry()
        assert False == AIProjectInstrumentor().is_content_recording_enabled()
        assert True == AIProjectInstrumentor().is_instrumented()

        project_client = self.create_async_client(operation_group="agents", **kwargs)
        model = kwargs.get("azure_ai_model_deployment_name")

        async with project_client:
            agent_definition = PromptAgentDefinition(
                model=model,
                instructions="You are a helpful AI assistant. Always be polite and provide accurate information.",
            )

            agent = await project_client.agents.create_version(agent_name="myagent", definition=agent_definition)
            version = agent.version
            await project_client.agents.delete_version(agent_name=agent.name, agent_version=agent.version)

        # ------------------------- Validate "create_agent" span ---------------------------------
        self.exporter.force_flush()
        spans = self.exporter.get_spans_by_name("create_agent myagent")
        assert len(spans) == 1
        span = spans[0]
        expected_attributes = [
            (GEN_AI_PROVIDER_NAME, AGENTS_PROVIDER),
            (GEN_AI_OPERATION_NAME, "create_agent"),
            (SERVER_ADDRESS, ""),
            (GEN_AI_REQUEST_MODEL, model),
            (GEN_AI_AGENT_NAME, "myagent"),
            (GEN_AI_AGENT_ID, "myagent:" + str(version)),
            (GEN_AI_AGENT_VERSION, str(version)),
            (GEN_AI_AGENT_TYPE, AGENT_TYPE_PROMPT),
        ]

        # When using attributes, add empty system message attribute
        if not use_events:
            from azure.ai.projects.telemetry._utils import GEN_AI_SYSTEM_MESSAGE

            # The system message should have type indicator without content when content recording is disabled

            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:
            expected_events = [
                {
                    "name": GEN_AI_SYSTEM_INSTRUCTION_EVENT,
                    "attributes": {
                        GEN_AI_PROVIDER_NAME: AGENTS_PROVIDER,
                        GEN_AI_EVENT_CONTENT: json.dumps([{"type": "text"}]),
                    },
                }
            ]
            events_match = GenAiTraceVerifier().check_span_events(span, expected_events)
            assert events_match == True
        else:
            # When using attributes and content recording disabled, verify empty structure
            from azure.ai.projects.telemetry._utils import GEN_AI_SYSTEM_MESSAGE
            import json