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/samples/getting_started/workflows/human-in-the-loop/agents_with_approval_requests.py

@@ -13,9 +13,9 @@ from agent_framework import (
     Executor,
     WorkflowBuilder,
     WorkflowContext,
-    tool,
     executor,
     handler,
+    tool,
 )
 from agent_framework.openai import OpenAIChatClient
 

python/samples/getting_started/workflows/human-in-the-loop/concurrent_request_info.py

@@ -29,11 +29,9 @@ from agent_framework import (
     ChatMessage,
     ConcurrentBuilder,
     RequestInfoEvent,
-    Role,
     WorkflowOutputEvent,
     WorkflowRunState,
     WorkflowStatusEvent,
-    tool,
 )
 from agent_framework._workflows._agent_executor import AgentExecutorResponse
 from agent_framework.azure import AzureOpenAIChatClient
@@ -72,7 +70,7 @@ async def aggregate_with_synthesis(results: list[AgentExecutorResponse]) -> Any:
             # Check for human feedback in the conversation (will be last user message if present)
             if r.full_conversation:
                 for msg in reversed(r.full_conversation):
-                    if msg.role == Role.USER and msg.text and "perspectives" not in msg.text.lower():
+                    if msg.role == "user" and msg.text and "perspectives" not in msg.text.lower():
                         human_guidance = msg.text
                         break
         except Exception:
@@ -82,14 +80,14 @@ async def aggregate_with_synthesis(results: list[AgentExecutorResponse]) -> Any:
     guidance_text = f"\n\nHuman guidance: {human_guidance}" if human_guidance else ""
 
     system_msg = ChatMessage(
-        Role.SYSTEM,
+        "system",
         text=(
             "You are a synthesis expert. Consolidate the following analyst perspectives "
             "into one cohesive, balanced summary (3-4 sentences). If human guidance is provided, "
             "prioritize aspects as directed."
         ),
     )
-    user_msg = ChatMessage(Role.USER, text="\n\n".join(expert_sections) + guidance_text)
+    user_msg = ChatMessage("user", text="\n\n".join(expert_sections) + guidance_text)
 
     response = await _chat_client.get_response([system_msg, user_msg])
     return response.messages[-1].text if response.messages else ""
@@ -174,7 +172,7 @@ async def main() -> None:
                             else event.data.full_conversation
                         )
                         for msg in recent:
-                            name = msg.author_name or msg.role.value
+                            name = msg.author_name or msg.role
                             text = (msg.text or "")[:150]
                             print(f"  [{name}]: {text}...")
                         print("-" * 40)

python/samples/getting_started/workflows/human-in-the-loop/group_chat_request_info.py

@@ -35,7 +35,6 @@ from agent_framework import (
     WorkflowOutputEvent,
     WorkflowRunState,
     WorkflowStatusEvent,
-    tool,
 )
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
@@ -164,7 +163,7 @@ async def main() -> None:
                 if event.data:
                     messages: list[ChatMessage] = event.data
                     for msg in messages:
-                        role = msg.role.value.capitalize()
+                        role = msg.role.capitalize()
                         name = msg.author_name or "unknown"
                         text = (msg.text or "")[:200]
                         print(f"[{role}][{name}]: {text}...")

python/samples/getting_started/workflows/human-in-the-loop/guessing_game_with_human_input.py

@@ -10,7 +10,6 @@ from agent_framework import (
     ChatMessage,  # Chat message structure
     Executor,  # Base class for workflow executors
     RequestInfoEvent,  # Event emitted when human input is requested
-    Role,  # Enum of chat roles (user, assistant, system)
     WorkflowBuilder,  # Fluent builder for assembling the graph
     WorkflowContext,  # Per run context and event bus
     WorkflowOutputEvent,  # Event emitted when workflow yields output
@@ -18,8 +17,7 @@ from agent_framework import (
     WorkflowStatusEvent,  # Event emitted on run state changes
     handler,
     response_handler,  # Decorator to expose an Executor method as a step
-    tool,
-)
+    )
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 from pydantic import BaseModel
@@ -88,7 +86,7 @@ class TurnManager(Executor):
         - Input is a simple starter token (ignored here).
         - Output is an AgentExecutorRequest that triggers the agent to produce a guess.
         """
-        user = ChatMessage(Role.USER, text="Start by making your first guess.")
+        user = ChatMessage("user", text="Start by making your first guess.")
         await ctx.send_message(AgentExecutorRequest(messages=[user], should_respond=True))
 
     @handler
@@ -138,7 +136,7 @@ class TurnManager(Executor):
         # Provide feedback to the agent to try again.
         # We keep the agent's output strictly JSON to ensure stable parsing on the next turn.
         user_msg = ChatMessage(
-            Role.USER,
+            "user",
             text=(f'Feedback: {reply}. Return ONLY a JSON object matching the schema {{"guess": <int 1..10>}}.'),
         )
         await ctx.send_message(AgentExecutorRequest(messages=[user_msg], should_respond=True))

python/samples/getting_started/workflows/human-in-the-loop/sequential_request_info.py

@@ -32,7 +32,6 @@ from agent_framework import (
     WorkflowOutputEvent,
     WorkflowRunState,
     WorkflowStatusEvent,
-    tool,
 )
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
@@ -109,7 +108,7 @@ async def main() -> None:
                             else event.data.full_conversation
                         )
                         for msg in recent:
-                            name = msg.author_name or msg.role.value
+                            name = msg.author_name or msg.role
                             text = (msg.text or "")[:150]
                             print(f"  [{name}]: {text}...")
                         print("-" * 40)
@@ -132,7 +131,7 @@ async def main() -> None:
                 if event.data:
                     messages: list[ChatMessage] = event.data[-3:]
                     for msg in messages:
-                        role = msg.role.value if msg.role else "unknown"
+                        role = msg.role if msg.role else "unknown"
                         print(f"[{role}]: {msg.text}")
                 workflow_complete = True