Align GenAI main-agent span processor with upstream OpenTelemetry SDK (>= 1.43) immutable BoundedAttributes on span end, fixing TypeErrors (#47796)

* Align GenAI main-agent span processor with upstream OpenTelemetry SDK (>= 1.43) immutable BoundedAttributes on span end, fixing TypeErrors

* Update CHANGELOG

Author: rads-1996

sdk/monitor/azure-monitor-opentelemetry-exporter/CHANGELOG.md

@@ -7,6 +7,10 @@
 ### Breaking Changes
 
 ### Bugs Fixed
+- Align GenAI main-agent span processor with upstream OpenTelemetry SDK (>= 1.43)
+  immutable `BoundedAttributes` on span end, fixing a `TypeError` when writing
+  `microsoft.gen_ai.main_agent.*` attributes in `on_end`
+  ([#47796](https://github.com/Azure/azure-sdk-for-python/pull/47796))
 
 ### Other Changes
 

sdk/monitor/azure-monitor-opentelemetry-exporter/azure/monitor/opentelemetry/exporter/_gen_ai/_processor.py

@@ -61,11 +61,39 @@ def on_end(self, span: ReadableSpan) -> None:
             if key.startswith(_MAIN_AGENT_PREFIX):
                 return
 
+        # Access the internal mutable attributes mapping. on_end receives a
+        # ReadableSpan which has no set_attribute, so we write to the underlying
+        # BoundedAttributes mapping directly.
+        mutable = getattr(span, "_attributes", None)
+        if mutable is None:
+            return
+
+        # Build the attributes to write before touching the (now frozen) span.
+        updates = {}
         # Self-attribute from the span's own gen_ai attributes
         for target, source in _MAIN_AGENT_SELF_ATTRIBUTES:
             value = attributes.get(source)
             if value is not None:
-                span._attributes[target] = value  # type: ignore
+                updates[target] = value
+
+        if not updates:
+            return
+
+        # OTel SDK >= 1.43 freezes span attributes (_immutable = True) inside
+        # end() *before* invoking on_end. Writing then raises TypeError.
+        # Temporarily lift the freeze for our own synchronous writes and always
+        # restore it so the exported ReadableSpan snapshot stays frozen.
+        was_immutable = getattr(mutable, "_immutable", False)
+        if was_immutable:
+            mutable._immutable = False  # type: ignore # pylint: disable=protected-access
+            try:
+                for target, value in updates.items():
+                    mutable[target] = value
+            finally:
+                mutable._immutable = True  # type: ignore # pylint: disable=protected-access
+        else:
+            for target, value in updates.items():
+                mutable[target] = value
 
     def shutdown(self):
         pass

sdk/monitor/azure-monitor-opentelemetry-exporter/tests/test_gen_ai_processor.py

@@ -4,6 +4,7 @@
 import unittest
 from unittest.mock import MagicMock, patch
 
+from opentelemetry.attributes import BoundedAttributes
 from opentelemetry.context import Context
 from opentelemetry.trace import INVALID_SPAN_CONTEXT, SpanContext, TraceFlags
 
@@ -221,6 +222,51 @@ def test_on_end_partial_self_attribution(self):
         self.assertNotIn("microsoft.gen_ai.main_agent.version", span._attributes)
         self.assertNotIn("microsoft.gen_ai.main_agent.conversation_id", span._attributes)
 
+    def test_on_end_writes_to_immutable_attributes(self):
+        """on_end must self-attribute even when span attributes are frozen.
+
+        OTel SDK >= 1.43 sets BoundedAttributes._immutable = True inside
+        Span.end() *before* invoking on_end. The processor must temporarily lift
+        the freeze to write and restore it afterwards, without raising.
+        """
+        attributes = BoundedAttributes(
+            immutable=False,
+            attributes={
+                "gen_ai.operation.name": "invoke_agent",
+                "gen_ai.agent.name": "RootAgent",
+                "gen_ai.agent.id": "agent-001",
+                "gen_ai.agent.version": "3.0",
+                "gen_ai.conversation.id": "conv-xyz",
+            },
+        )
+        # Simulate the frozen state Span.end() leaves the attributes in.
+        attributes._immutable = True
+
+        span = MagicMock()
+        span.attributes = attributes
+        span._attributes = attributes
+
+        # Must not raise even though the mapping is immutable.
+        self.processor.on_end(span)
+
+        self.assertEqual(attributes["microsoft.gen_ai.main_agent.name"], "RootAgent")
+        self.assertEqual(attributes["microsoft.gen_ai.main_agent.id"], "agent-001")
+        self.assertEqual(attributes["microsoft.gen_ai.main_agent.version"], "3.0")
+        self.assertEqual(attributes["microsoft.gen_ai.main_agent.conversation_id"], "conv-xyz")
+        # The freeze must be restored so the exported snapshot stays immutable.
+        self.assertTrue(attributes._immutable)
+
+    def test_immutable_attributes_reject_direct_write(self):
+        """Regression guard: proves the failure the fix guards against.
+
+        A direct write to frozen BoundedAttributes (the pre-fix behavior)
+        raises TypeError. This is why on_end must lift the freeze first.
+        """
+        attributes = BoundedAttributes(immutable=False, attributes={})
+        attributes._immutable = True
+        with self.assertRaises(TypeError):
+            attributes["microsoft.gen_ai.main_agent.name"] = "RootAgent"
+
 
 class TestGenAIMainAgentLogRecordProcessor(unittest.TestCase):
     def setUp(self):