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/middleware/agent_and_run_level_middleware.py

@@ -34,9 +34,9 @@ The example shows:
 Execution order: Agent middleware (outermost) -> Run middleware (innermost) -> Agent execution
 """
 
+
 # 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 get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],
 ) -> str:

python/samples/getting_started/middleware/chat_middleware.py

@@ -10,7 +10,6 @@ from agent_framework import (
     ChatMessage,
     ChatMiddleware,
     ChatResponse,
-    Role,
     chat_middleware,
     tool,
 )
@@ -36,9 +35,9 @@ The example covers:
 - Middleware registration at run level (applies to specific run only)
 """
 
+
 # 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 get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],
 ) -> str:
@@ -64,7 +63,7 @@ class InputObserverMiddleware(ChatMiddleware):
 
         for i, message in enumerate(context.messages):
             content = message.text if message.text else str(message.contents)
-            print(f"  Message {i + 1} ({message.role.value}): {content}")
+            print(f"  Message {i + 1} ({message.role}): {content}")
 
         print(f"[InputObserverMiddleware] Total messages: {len(context.messages)}")
 
@@ -73,7 +72,7 @@ class InputObserverMiddleware(ChatMiddleware):
         modified_count = 0
 
         for message in context.messages:
-            if message.role == Role.USER and message.text:
+            if message.role == "user" and message.text:
                 original_text = message.text
                 updated_text = original_text
 
@@ -81,7 +80,7 @@ class InputObserverMiddleware(ChatMiddleware):
                     updated_text = self.replacement
                     print(f"[InputObserverMiddleware] Updated: '{original_text}' -> '{updated_text}'")
 
-                modified_message = ChatMessage(role=message.role, text=updated_text)
+                modified_message = ChatMessage(message.role, [updated_text])
                 modified_messages.append(modified_message)
                 modified_count += 1
             else:
@@ -119,7 +118,7 @@ async def security_and_override_middleware(
                     context.result = ChatResponse(
                         messages=[
                             ChatMessage(
-                                role=Role.ASSISTANT,
+                                role="assistant",
                                 text="I cannot process requests containing sensitive information. "
                                 "Please rephrase your question without including passwords, secrets, or other "
                                 "sensitive data.",

python/samples/getting_started/middleware/class_based_middleware.py

@@ -13,7 +13,6 @@ from agent_framework import (
     ChatMessage,
     FunctionInvocationContext,
     FunctionMiddleware,
-    Role,
     tool,
 )
 from agent_framework.azure import AzureAIAgentClient
@@ -34,9 +33,9 @@ This approach is useful when you need stateful middleware or complex logic that
 from object-oriented design patterns.
 """
 
+
 # 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 get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],
 ) -> str:
@@ -63,7 +62,7 @@ class SecurityAgentMiddleware(AgentMiddleware):
                 # Override the result with warning message
                 context.result = AgentResponse(
                     messages=[
-                        ChatMessage(role=Role.ASSISTANT, text="Detected sensitive information, the request is blocked.")
+                        ChatMessage("assistant", ["Detected sensitive information, the request is blocked."])
                     ]
                 )
                 # Simply don't call next() to prevent execution

python/samples/getting_started/middleware/decorator_middleware.py

@@ -41,9 +41,9 @@ Key benefits of decorator approach:
 - Prevents type mismatches
 """
 
+
 # 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 get_current_time() -> str:
     """Get the current time."""
     return f"Current time is {datetime.datetime.now().strftime('%H:%M:%S')}"

python/samples/getting_started/middleware/exception_handling_with_middleware.py

@@ -4,8 +4,7 @@ import asyncio
 from collections.abc import Awaitable, Callable
 from typing import Annotated
 
-from agent_framework import FunctionInvocationContext
-from agent_framework import tool
+from agent_framework import FunctionInvocationContext, tool
 from agent_framework.azure import AzureAIAgentClient
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
@@ -24,6 +23,7 @@ The middleware catches TimeoutError from an unstable data service and replaces i
 a helpful message for the user, preventing raw exceptions from reaching the end user.
 """
 
+
 # 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 unstable_data_service(

python/samples/getting_started/middleware/function_based_middleware.py

@@ -30,9 +30,9 @@ lightweight approach compared to class-based middleware. Both agent and function
 can be implemented as async functions that accept context and next parameters.
 """
 
+
 # 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 get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],
 ) -> str:

python/samples/getting_started/middleware/middleware_termination.py

@@ -10,7 +10,6 @@ from agent_framework import (
     AgentResponse,
     AgentRunContext,
     ChatMessage,
-    Role,
     tool,
 )
 from agent_framework.azure import AzureAIAgentClient
@@ -29,9 +28,9 @@ The example includes:
 This is useful for implementing security checks, rate limiting, or early exit conditions.
 """
 
+
 # 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 get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],
 ) -> str:
@@ -63,7 +62,7 @@ class PreTerminationMiddleware(AgentMiddleware):
                     context.result = AgentResponse(
                         messages=[
                             ChatMessage(
-                                role=Role.ASSISTANT,
+                                role="assistant",
                                 text=(
                                     f"Sorry, I cannot process requests containing '{blocked_word}'. "
                                     "Please rephrase your question."

python/samples/getting_started/middleware/override_result_with_middleware.py

@@ -11,7 +11,6 @@ from agent_framework import (
     AgentRunContext,
     ChatMessage,
     Content,
-    Role,
     tool,
 )
 from agent_framework.azure import AzureAIAgentClient
@@ -35,9 +34,9 @@ then replaces its result with a custom "perfect weather" message. For streaming
 it creates a custom async generator that yields the override message in chunks.
 """
 
+
 # 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 get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],
 ) -> str:
@@ -75,7 +74,7 @@ async def weather_override_middleware(
         else:
             # For non-streaming: just replace with the string message
             custom_message = "".join(chunks)
-            context.result = AgentResponse(messages=[ChatMessage(role=Role.ASSISTANT, text=custom_message)])
+            context.result = AgentResponse(messages=[ChatMessage("assistant", [custom_message])])
 
 
 async def main() -> None:

python/samples/getting_started/middleware/runtime_context_delegation.py

@@ -4,7 +4,7 @@ import asyncio
 from collections.abc import Awaitable, Callable
 from typing import Annotated
 
-from agent_framework import FunctionInvocationContext, tool, function_middleware
+from agent_framework import FunctionInvocationContext, function_middleware, tool
 from agent_framework.openai import OpenAIChatClient
 from pydantic import Field
 

python/samples/getting_started/middleware/shared_state_middleware.py

@@ -26,9 +26,9 @@ The example includes:
 This approach shows how middleware can work together by sharing state within the same class instance.
 """
 
+
 # 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 get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],
 ) -> str:
@@ -36,8 +36,8 @@ def get_weather(
     conditions = ["sunny", "cloudy", "rainy", "stormy"]
     return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
 
-@tool(approval_mode="never_require")
 
+@tool(approval_mode="never_require")
 def get_time(
     timezone: Annotated[str, Field(description="The timezone to get the time for.")] = "UTC",
 ) -> str:

python/samples/getting_started/middleware/thread_behavior_middleware.py

@@ -31,9 +31,9 @@ Key behaviors demonstrated:
 4. After next(): thread contains full conversation history (all previous + current messages)
 """
 
+
 # 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 get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],
 ) -> str: