Python: [BREAKING] Types API Review improvements (#3647)

* Replace Role and FinishReason classes with NewType + Literal

- Remove EnumLike metaclass from _types.py
- Replace Role class with NewType('Role', str) + RoleLiteral
- Replace FinishReason class with NewType('FinishReason', str) + FinishReasonLiteral
- Update all usages across codebase to use string literals
- Remove .value access patterns (direct string comparison now works)
- Add backward compatibility for legacy dict serialization format
- Update tests to reflect new string-based types

Addresses #3591, #3615

* Simplify ChatResponse and AgentResponse type hints (#3592)

- Remove overloads from ChatResponse.__init__
- Remove text parameter from ChatResponse.__init__
- Remove | dict[str, Any] from finish_reason and usage_details params
- Remove **kwargs from AgentResponse.__init__
- Both now accept ChatMessage | Sequence[ChatMessage] | None for messages
- Update docstrings and examples to reflect changes
- Fix tests that were using removed kwargs
- Fix Role type hint usage in ag-ui utils

* Remove text parameter from ChatResponseUpdate and AgentResponseUpdate (#3597)

- Remove text parameter from ChatResponseUpdate.__init__
- Remove text parameter from AgentResponseUpdate.__init__
- Remove **kwargs from both update classes
- Simplify contents parameter type to Sequence[Content] | None
- Update all usages to use contents=[Content.from_text(...)] pattern
- Fix imports in test files
- Update docstrings and examples

* Rename from_chat_response_updates to from_updates (#3593)

- ChatResponse.from_chat_response_updates → ChatResponse.from_updates
- ChatResponse.from_chat_response_generator → ChatResponse.from_update_generator
- AgentResponse.from_agent_run_response_updates → AgentResponse.from_updates

* Remove try_parse_value method from ChatResponse and AgentResponse (#3595)

- Remove try_parse_value method from ChatResponse
- Remove try_parse_value method from AgentResponse
- Remove try_parse_value calls from from_updates and from_update_generator methods
- Update samples to use try/except with response.value instead
- Update tests to use response.value pattern
- Users should now use response.value with try/except for safe parsing

* Add agent_id to AgentResponse and clarify author_name documentation (#3596)

- Add agent_id parameter to AgentResponse class
- Document that author_name is on ChatMessage objects, not responses
- Update ChatResponse docstring with author_name note
- Update AgentResponse docstring with author_name note

* Simplify ChatMessage.__init__ signature (#3618)

- Make contents a positional argument accepting Sequence[Content | str]
- Auto-convert strings in contents to TextContent
- Remove overloads, keep text kwarg for backward compatibility with serialization
- Update _parse_content_list to handle string items
- Update all usages across codebase to use new format: ChatMessage("role", ["text"])

* Allow Content as input on run and get_response

- Update prepare_messages and normalize_messages to accept Content
- Update type signatures in _agents.py and _clients.py
- Add tests for Content input handling

* Fix ChatMessage usage across packages and samples

Update all remaining ChatMessage(role=..., text=...) to use new
ChatMessage('role', ['text']) signature.

* Fix Role string usage and response format parsing

- Fix redis provider: remove .value access on string literals
- Fix durabletask ensure_response_format: set _response_format before accessing .value

* Fix ollama .value and ai_model_id issues, handle None in content list

- Fix ollama _chat_client: remove .value on string literals
- Fix ollama _chat_client: rename ai_model_id to model_id
- Fix _parse_content_list: skip None values gracefully

* Fix A2AAgent type signature to include Content

* Fix Role/FinishReason NewType dict annotations and improve test coverage to 95%

* Fix mypy errors for Role/FinishReason NewType usage

* Fix Role.TOOL and Role.ASSISTANT usage in _orchestrator_helpers.py

* Fix Role NewType usage in durabletask _models.py

python/packages/devui/tests/test_mapper.py

@@ -15,7 +15,6 @@ import pytest
 from agent_framework._types import (
     AgentResponseUpdate,
     Content,
-    Role,
 )
 
 # Import real workflow event classes - NOT mocks!
@@ -84,7 +83,7 @@ def create_test_content(content_type: str, **kwargs: Any) -> Any:
 
 def create_test_agent_update(contents: list[Any]) -> AgentResponseUpdate:
     """Create test AgentResponseUpdate."""
-    return AgentResponseUpdate(contents=contents, role=Role.ASSISTANT, message_id="test_msg", response_id="test_resp")
+    return AgentResponseUpdate(contents=contents, role="assistant", message_id="test_msg", response_id="test_resp")
 
 
 # =============================================================================
@@ -450,13 +449,13 @@ async def test_magentic_agent_run_update_event_with_agent_delta_metadata(
     This tests the ACTUAL event format Magentic emits - not a fake MagenticAgentDeltaEvent class.
     Magentic uses AgentRunUpdateEvent with additional_properties containing magentic_event_type.
     """
-    from agent_framework._types import AgentResponseUpdate, Role
+    from agent_framework._types import AgentResponseUpdate
     from agent_framework._workflows._events import AgentRunUpdateEvent
 
     # Create the REAL event format that Magentic emits
     update = AgentResponseUpdate(
         contents=[Content.from_text(text="Hello from agent")],
-        role=Role.ASSISTANT,
+        role="assistant",
         author_name="Writer",
         additional_properties={
             "magentic_event_type": "agent_delta",
@@ -481,13 +480,13 @@ async def test_magentic_orchestrator_message_event(mapper: MessageMapper, test_r
     Magentic emits orchestrator planning/instruction messages using AgentRunUpdateEvent
     with additional_properties containing magentic_event_type='orchestrator_message'.
     """
-    from agent_framework._types import AgentResponseUpdate, Role
+    from agent_framework._types import AgentResponseUpdate
     from agent_framework._workflows._events import AgentRunUpdateEvent
 
     # Create orchestrator message event (REAL format from Magentic)
     update = AgentResponseUpdate(
         contents=[Content.from_text(text="Planning: First, the writer will create content...")],
-        role=Role.ASSISTANT,
+        role="assistant",
         author_name="Orchestrator",
         additional_properties={
             "magentic_event_type": "orchestrator_message",
@@ -517,21 +516,21 @@ async def test_magentic_events_use_same_event_class_as_other_workflows(
     additional_properties. Any mapper code checking for 'MagenticAgentDeltaEvent'
     class names is dead code.
     """
-    from agent_framework._types import AgentResponseUpdate, Role
+    from agent_framework._types import AgentResponseUpdate
     from agent_framework._workflows._events import AgentRunUpdateEvent
 
     # Create events the way different workflows do it
     # 1. Regular workflow (no additional_properties)
     regular_update = AgentResponseUpdate(
         contents=[Content.from_text(text="Regular workflow response")],
-        role=Role.ASSISTANT,
+        role="assistant",
     )
     regular_event = AgentRunUpdateEvent(executor_id="regular_executor", data=regular_update)
 
     # 2. Magentic workflow (with additional_properties)
     magentic_update = AgentResponseUpdate(
         contents=[Content.from_text(text="Magentic workflow response")],
-        role=Role.ASSISTANT,
+        role="assistant",
         additional_properties={"magentic_event_type": "agent_delta"},
     )
     magentic_event = AgentRunUpdateEvent(executor_id="magentic_executor", data=magentic_update)
@@ -598,13 +597,13 @@ async def test_workflow_output_event(mapper: MessageMapper, test_request: AgentF
 
 async def test_workflow_output_event_with_list_data(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
     """Test WorkflowOutputEvent with list data (common for sequential/concurrent workflows)."""
-    from agent_framework import ChatMessage, Role
+    from agent_framework import ChatMessage
     from agent_framework._workflows._events import WorkflowOutputEvent
 
     # Sequential/Concurrent workflows often output list[ChatMessage]
     messages = [
-        ChatMessage(role=Role.USER, contents=[Content.from_text(text="Hello")]),
-        ChatMessage(role=Role.ASSISTANT, contents=[Content.from_text(text="World")]),
+        ChatMessage("user", [Content.from_text(text="Hello")]),
+        ChatMessage("assistant", [Content.from_text(text="World")]),
     ]
     event = WorkflowOutputEvent(data=messages, executor_id="complete")
     events = await mapper.convert_event(event, test_request)