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/declarative/agent_framework_declarative/_workflows/_actions_agents.py

@@ -285,11 +285,11 @@ async def handle_invoke_azure_agent(ctx: ActionContext) -> AsyncGenerator[Workfl
         evaluated_input = ctx.state.eval_if_expression(input_messages)
         if evaluated_input:
             if isinstance(evaluated_input, str):
-                messages.append(ChatMessage(role="user", text=evaluated_input))
+                messages.append(ChatMessage("user", [evaluated_input]))
             elif isinstance(evaluated_input, list):
                 for msg_item in evaluated_input:  # type: ignore
                     if isinstance(msg_item, str):
-                        messages.append(ChatMessage(role="user", text=msg_item))
+                        messages.append(ChatMessage("user", [msg_item]))
                     elif isinstance(msg_item, ChatMessage):
                         messages.append(msg_item)
                     elif isinstance(msg_item, dict) and "content" in msg_item:
@@ -297,11 +297,11 @@ async def handle_invoke_azure_agent(ctx: ActionContext) -> AsyncGenerator[Workfl
                         role: str = str(item_dict.get("role", "user"))
                         content: str = str(item_dict.get("content", ""))
                         if role == "user":
-                            messages.append(ChatMessage(role="user", text=content))
+                            messages.append(ChatMessage("user", [content]))
                         elif role == "assistant":
-                            messages.append(ChatMessage(role="assistant", text=content))
+                            messages.append(ChatMessage("assistant", [content]))
                         elif role == "system":
-                            messages.append(ChatMessage(role="system", text=content))
+                            messages.append(ChatMessage("system", [content]))
 
     # Evaluate and include input arguments
     evaluated_args: dict[str, Any] = {}
@@ -348,7 +348,7 @@ async def handle_invoke_azure_agent(ctx: ActionContext) -> AsyncGenerator[Workfl
                         tool_calls.extend(chunk.tool_calls)
 
                 # Build consolidated response from updates
-                response = AgentResponse.from_agent_run_response_updates(updates)
+                response = AgentResponse.from_updates(updates)
                 text = response.text
                 response_messages = response.messages
 
@@ -361,7 +361,7 @@ async def handle_invoke_azure_agent(ctx: ActionContext) -> AsyncGenerator[Workfl
 
                 # Add to conversation history
                 if text:
-                    ctx.state.add_conversation_message(ChatMessage(role="assistant", text=text))
+                    ctx.state.add_conversation_message(ChatMessage("assistant", [text]))
 
                 # Store in output variables (.NET style)
                 if output_messages_var:
@@ -414,7 +414,7 @@ async def handle_invoke_azure_agent(ctx: ActionContext) -> AsyncGenerator[Workfl
 
                 # Add to conversation history
                 if text:
-                    ctx.state.add_conversation_message(ChatMessage(role="assistant", text=text))
+                    ctx.state.add_conversation_message(ChatMessage("assistant", [text]))
 
                 # Store in output variables (.NET style)
                 if output_messages_var:
@@ -560,7 +560,7 @@ async def handle_invoke_prompt_agent(ctx: ActionContext) -> AsyncGenerator[Workf
     # Add input as user message if provided
     if input_value:
         if isinstance(input_value, str):
-            messages.append(ChatMessage(role="user", text=input_value))
+            messages.append(ChatMessage("user", [input_value]))
         elif isinstance(input_value, ChatMessage):
             messages.append(input_value)
 
@@ -581,14 +581,14 @@ async def handle_invoke_prompt_agent(ctx: ActionContext) -> AsyncGenerator[Workf
                     )
 
             # Build consolidated response from updates
-            response = AgentResponse.from_agent_run_response_updates(updates)
+            response = AgentResponse.from_updates(updates)
             text = response.text
             response_messages = response.messages
 
             ctx.state.set_agent_result(text=text, messages=response_messages)
 
             if text:
-                ctx.state.add_conversation_message(ChatMessage(role="assistant", text=text))
+                ctx.state.add_conversation_message(ChatMessage("assistant", [text]))
 
             if output_path:
                 ctx.state.set(output_path, text)
@@ -607,7 +607,7 @@ async def handle_invoke_prompt_agent(ctx: ActionContext) -> AsyncGenerator[Workf
             ctx.state.set_agent_result(text=text, messages=response_messages)
 
             if text:
-                ctx.state.add_conversation_message(ChatMessage(role="assistant", text=text))
+                ctx.state.add_conversation_message(ChatMessage("assistant", [text]))
 
             if output_path:
                 ctx.state.set(output_path, text)

python/packages/declarative/agent_framework_declarative/_workflows/_executors_agents.py

@@ -642,7 +642,7 @@ class InvokeAzureAgentExecutor(DeclarativeActionExecutor):
 
         # Add user input to conversation history first (via state.append only)
         if input_text:
-            user_message = ChatMessage(role="user", text=input_text)
+            user_message = ChatMessage("user", [input_text])
             await state.append(messages_path, user_message)
 
         # Get conversation history from state AFTER adding user message
@@ -711,7 +711,7 @@ class InvokeAzureAgentExecutor(DeclarativeActionExecutor):
                 "Agent '%s': No messages in response, creating simple assistant message",
                 agent_name,
             )
-            assistant_message = ChatMessage(role="assistant", text=accumulated_response)
+            assistant_message = ChatMessage("assistant", [accumulated_response])
             await state.append(messages_path, assistant_message)
 
         # Store results in state - support both schema formats: