Python: Fix AG-UI reasoning role and multimodal media parsing to follow specification (#5389)

* Fix AG-UI reasoning role and multimodal media value field parsing

Fix two spec compliance issues in the AG-UI integration:

1. ReasoningMessageStartEvent now uses role='reasoning' instead of
   role='assistant', matching the AG-UI specification for reasoning
   messages.

2. _parse_multimodal_media_part now reads the 'value' field from source
   dicts (with fallback to 'data' for backward compatibility), matching
   the current AG-UI InputContentSource specification.

Bump ag-ui-protocol dependency from ==0.1.13 to >=0.1.16,<0.2 to pick
up the SDK fix that accepts role='reasoning' in ReasoningMessageStartEvent.

Fix pre-existing pyright reportMissingImports errors for orjson in sample
files, and fix import ordering in foundry-hosted-agents sample.

Fixes #5340

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Python: Fix AG-UI reasoning role and multimodal media parsing to follow specification

Fixes #5340

* Remove unintended .maf-runtime-ready marker file

Address PR review feedback: the .maf-runtime-ready file is not referenced anywhere in the repo and was left over from automation.

Fixes #5340

* Python: Fix duplicate AG-UI multimodal 'value' parsing in snapshot path

The snapshot normalization path used a second copy of the multimodal source
parsing logic that still read the deprecated 'data' field. When clients sent
base64 media with source={"type": "base64", "value": ...}, the snapshot event
emitted by the server dropped the payload, causing AG-UI-compatible clients
to crash on ingest.

Extract the shared source-field extraction into _extract_multimodal_source_fields
so both _parse_multimodal_media_part and the snapshot _legacy_binary_part stay
in sync with the AG-UI spec. Add snapshot-path regression tests covering
value-only, value-preferred-over-data, and the legacy data-field fallback.

Addresses review feedback on #5389 from @Rickyneer.

---------

Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

python/packages/ag-ui/tests/ag_ui/test_message_adapters.py

@@ -536,6 +536,77 @@ def test_agui_snapshot_format_preserves_multimodal_content():
     assert content_parts[1]["url"] == "https://example.com/image.png"
 
 
+def test_agui_snapshot_format_reads_base64_value_field():
+    """Snapshot normalization reads the spec 'value' field for base64 sources."""
+    payload = base64.b64encode(b"abc").decode("utf-8")
+    normalized = agui_messages_to_snapshot_format(
+        [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image",
+                        "source": {"type": "base64", "value": payload, "mimeType": "image/png"},
+                    },
+                ],
+            }
+        ]
+    )
+
+    binary_part = normalized[0]["content"][0]
+    assert binary_part["type"] == "binary"
+    assert binary_part["mimeType"] == "image/png"
+    assert binary_part["data"] == payload
+
+
+def test_agui_snapshot_format_base64_value_preferred_over_data():
+    """Snapshot normalization prefers 'value' when both 'value' and 'data' are set."""
+    value_payload = base64.b64encode(b"new-spec").decode("utf-8")
+    data_payload = base64.b64encode(b"legacy").decode("utf-8")
+    normalized = agui_messages_to_snapshot_format(
+        [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image",
+                        "source": {
+                            "type": "base64",
+                            "value": value_payload,
+                            "data": data_payload,
+                            "mimeType": "image/png",
+                        },
+                    },
+                ],
+            }
+        ]
+    )
+
+    binary_part = normalized[0]["content"][0]
+    assert binary_part["data"] == value_payload
+
+
+def test_agui_snapshot_format_base64_data_field_backward_compat():
+    """Snapshot normalization still reads the legacy 'data' field when 'value' is absent."""
+    payload = base64.b64encode(b"legacy").decode("utf-8")
+    normalized = agui_messages_to_snapshot_format(
+        [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image",
+                        "source": {"type": "base64", "data": payload, "mimeType": "image/png"},
+                    },
+                ],
+            }
+        ]
+    )
+
+    binary_part = normalized[0]["content"][0]
+    assert binary_part["data"] == payload
+
+
 def test_agui_with_tool_calls_to_agent_framework():
     """Assistant message with tool_calls is converted to FunctionCallContent."""
     agui_msg = {
@@ -1760,3 +1831,67 @@ class TestReasoningRoundTrip:
         assert "First answer" in texts
         assert "Follow-up question" in texts
         assert "Prior reasoning" not in texts
+
+
+def test_parse_multimodal_media_part_base64_value_field():
+    """Source with type='base64' reads data from the 'value' field per AG-UI spec."""
+    from agent_framework_ag_ui._message_adapters import _parse_multimodal_media_part
+
+    result = _parse_multimodal_media_part(
+        {"type": "image", "source": {"type": "base64", "value": "aGVsbG8=", "mimeType": "image/png"}}
+    )
+    assert result is not None
+    assert "aGVsbG8=" in result.uri
+
+
+def test_parse_multimodal_media_part_data_source_value_field():
+    """Source with type='data' reads data from the 'value' field per AG-UI spec."""
+    from agent_framework_ag_ui._message_adapters import _parse_multimodal_media_part
+
+    result = _parse_multimodal_media_part(
+        {"type": "image", "source": {"type": "data", "value": "aGVsbG8=", "mimeType": "image/png"}}
+    )
+    assert result is not None
+    assert "aGVsbG8=" in result.uri
+
+
+def test_parse_multimodal_media_part_base64_data_field_backward_compat():
+    """Source with type='base64' still supports deprecated 'data' field."""
+    from agent_framework_ag_ui._message_adapters import _parse_multimodal_media_part
+
+    result = _parse_multimodal_media_part(
+        {"type": "image", "source": {"type": "base64", "data": "aGVsbG8=", "mimeType": "image/png"}}
+    )
+    assert result is not None
+    assert "aGVsbG8=" in result.uri
+
+
+def test_parse_multimodal_media_part_value_preferred_over_data():
+    """When both 'value' and 'data' are present, 'value' takes precedence."""
+    from agent_framework_ag_ui._message_adapters import _parse_multimodal_media_part
+
+    result = _parse_multimodal_media_part(
+        {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "value": "dmFsdWU=",
+                "data": "ZGF0YQ==",
+                "mimeType": "image/png",
+            },
+        }
+    )
+    assert result is not None
+    # 'value' field content should be used (base64 of "value")
+    assert "dmFsdWU=" in result.uri
+
+
+def test_parse_multimodal_media_part_unknown_source_value_fallback():
+    """Unknown source type falls back to 'value' field before 'data' field."""
+    from agent_framework_ag_ui._message_adapters import _parse_multimodal_media_part
+
+    result = _parse_multimodal_media_part(
+        {"type": "image", "source": {"type": "custom", "value": "aGVsbG8=", "mimeType": "image/png"}}
+    )
+    assert result is not None
+    assert "aGVsbG8=" in result.uri

python/packages/ag-ui/tests/ag_ui/test_run.py

@@ -1244,7 +1244,7 @@ class TestEmitTextReasoning:
         assert events[0].message_id == "reason_1"
         assert isinstance(events[1], ReasoningMessageStartEvent)
         assert events[1].message_id == "reason_1"
-        assert events[1].role == "assistant"
+        assert events[1].role == "reasoning"
         assert isinstance(events[2], ReasoningMessageContentEvent)
         assert events[2].message_id == "reason_1"
         assert events[2].delta == "The user is asking about weather, so I should call the weather tool."
@@ -1642,6 +1642,37 @@ class TestReasoningInSnapshot:
         assert close[0].message_id == "block2"
 
 
+class TestReasoningEventRole:
+    """Tests that reasoning events use role='reasoning' per AG-UI spec."""
+
+    def test_reasoning_role_without_flow(self):
+        """ReasoningMessageStartEvent uses role='reasoning' in non-flow mode."""
+        content = Content.from_text_reasoning(
+            id="reason_role_1",
+            text="Thinking about the question.",
+        )
+
+        events = _emit_text_reasoning(content)
+
+        msg_starts = [e for e in events if isinstance(e, ReasoningMessageStartEvent)]
+        assert len(msg_starts) == 1
+        assert msg_starts[0].role == "reasoning"
+
+    def test_reasoning_role_with_flow(self):
+        """ReasoningMessageStartEvent uses role='reasoning' in streaming flow mode."""
+        flow = FlowState()
+        content = Content.from_text_reasoning(
+            id="reason_role_2",
+            text="Reasoning in streaming mode.",
+        )
+
+        events = _emit_text_reasoning(content, flow)
+
+        msg_starts = [e for e in events if isinstance(e, ReasoningMessageStartEvent)]
+        assert len(msg_starts) == 1
+        assert msg_starts[0].role == "reasoning"
+
+
 async def test_session_id_matches_thread_id():
     """Session created by run_agent_stream uses the client thread_id as session_id."""
     from conftest import StubAgent