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/tools/function_invocation_configuration.py

@@ -3,8 +3,8 @@
 import asyncio
 from typing import Annotated
 
-from agent_framework.openai import OpenAIResponsesClient
 from agent_framework import tool
+from agent_framework.openai import OpenAIResponsesClient
 
 """
 This sample demonstrates how to configure function invocation settings
@@ -13,6 +13,7 @@ for an client and use a simple tool as a tool in an agent.
 This behavior is the same for all chat client types.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def add(

python/samples/getting_started/tools/function_tool_recover_from_failures.py

@@ -3,8 +3,7 @@
 import asyncio
 from typing import Annotated
 
-from agent_framework import FunctionCallContent, FunctionResultContent
-from agent_framework import tool
+from agent_framework import FunctionCallContent, FunctionResultContent, tool
 from agent_framework.openai import OpenAIResponsesClient
 
 """
@@ -14,6 +13,7 @@ Shows how a tool that throws an exception creates gracefull recovery and can kee
 The LLM decides whether to retry the call or to respond with something else, based on the exception.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def greet(name: Annotated[str, "Name to greet"]) -> str:

python/samples/getting_started/tools/function_tool_with_approval.py

@@ -59,14 +59,14 @@ async def handle_approvals(query: str, agent: "AgentProtocol") -> AgentResponse:
             )
 
             # Add the assistant message with the approval request
-            new_inputs.append(ChatMessage(role="assistant", contents=[user_input_needed]))
+            new_inputs.append(ChatMessage("assistant", [user_input_needed]))
 
             # Get user approval
             user_approval = await asyncio.to_thread(input, "\nApprove function call? (y/n): ")
 
             # Add the user's approval response
             new_inputs.append(
-                ChatMessage(role="user", contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")])
+                ChatMessage("user", [user_input_needed.to_function_approval_response(user_approval.lower() == "y")])
             )
 
         # Run again with all the context
@@ -109,14 +109,14 @@ async def handle_approvals_streaming(query: str, agent: "AgentProtocol") -> None
                 )
 
                 # Add the assistant message with the approval request
-                new_inputs.append(ChatMessage(role="assistant", contents=[user_input_needed]))
+                new_inputs.append(ChatMessage("assistant", [user_input_needed]))
 
                 # Get user approval
                 user_approval = await asyncio.to_thread(input, "\nApprove function call? (y/n): ")
 
                 # Add the user's approval response
                 new_inputs.append(
-                    ChatMessage(role="user", contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")])
+                    ChatMessage("user", [user_input_needed.to_function_approval_response(user_approval.lower() == "y")])
                 )
 
             # Update input with all the context for next iteration

python/samples/getting_started/tools/function_tool_with_approval_and_threads.py

@@ -55,7 +55,7 @@ async def approval_example() -> None:
 
             # Step 2: Send approval response
             approval_response = request.to_function_approval_response(approved=approved)
-            result = await agent.run(ChatMessage(role="user", contents=[approval_response]), thread=thread)
+            result = await agent.run(ChatMessage("user", [approval_response]), thread=thread)
 
     print(f"Agent: {result}\n")
 
@@ -88,7 +88,7 @@ async def rejection_example() -> None:
 
             # Send rejection response
             rejection_response = request.to_function_approval_response(approved=False)
-            result = await agent.run(ChatMessage(role="user", contents=[rejection_response]), thread=thread)
+            result = await agent.run(ChatMessage("user", [rejection_response]), thread=thread)
 
     print(f"Agent: {result}\n")