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/durabletask/agent_framework_durabletask/_durable_agent_state.py

@@ -797,7 +797,7 @@ class DurableAgentStateMessage:
             DurableAgentStateMessage with converted content items and metadata
         """
         return DurableAgentStateMessage(
-            role=request.role.value,
+            role=request.role,
             contents=[DurableAgentStateTextContent(text=request.message)],
             created_at=_parse_created_at(request.created_at) if request.created_at else None,
         )
@@ -817,7 +817,7 @@ class DurableAgentStateMessage:
         ]
 
         return DurableAgentStateMessage(
-            role=chat_message.role.value,
+            role=chat_message.role,
             contents=contents_list,
             author_name=chat_message.author_name,
             extension_data=dict(chat_message.additional_properties) if chat_message.additional_properties else None,

python/packages/durabletask/agent_framework_durabletask/_entities.py

@@ -14,7 +14,6 @@ from agent_framework import (
     AgentResponseUpdate,
     ChatMessage,
     Content,
-    Role,
     get_logger,
 )
 from durabletask.entities import DurableEntity
@@ -176,7 +175,7 @@ class AgentEntity:
             logger.exception("[AgentEntity.run] Agent execution failed.")
 
             error_message = ChatMessage(
-                role=Role.ASSISTANT, contents=[Content.from_error(message=str(exc), error_code=type(exc).__name__)]
+                role="assistant", contents=[Content.from_error(message=str(exc), error_code=type(exc).__name__)]
             )
             error_response = AgentResponse(messages=[error_message])
 
@@ -247,7 +246,7 @@ class AgentEntity:
             await self._notify_stream_update(update, callback_context)
 
         if updates:
-            response = AgentResponse.from_agent_run_response_updates(updates)
+            response = AgentResponse.from_updates(updates)
         else:
             logger.debug("[AgentEntity] No streaming updates received; creating empty response")
             response = AgentResponse(messages=[])

python/packages/durabletask/agent_framework_durabletask/_executors.py

@@ -16,7 +16,7 @@ from abc import ABC, abstractmethod
 from datetime import datetime, timezone
 from typing import Any, Generic, TypeVar
 
-from agent_framework import AgentResponse, AgentThread, ChatMessage, Content, Role, get_logger
+from agent_framework import AgentResponse, AgentThread, ChatMessage, Content, get_logger
 from durabletask.client import TaskHubGrpcClient
 from durabletask.entities import EntityInstanceId
 from durabletask.task import CompletableTask, CompositeTask, OrchestrationContext, Task
@@ -180,7 +180,7 @@ class DurableAgentExecutor(ABC, Generic[TaskT]):
             AgentResponse: Acceptance response with correlation ID
         """
         acceptance_message = ChatMessage(
-            role=Role.SYSTEM,
+            role="system",
             contents=[
                 Content.from_text(
                     f"Request accepted for processing (correlation_id: {correlation_id}). "
@@ -361,7 +361,7 @@ class ClientAgentExecutor(DurableAgentExecutor[AgentResponse]):
                     correlation_id,
                 )
                 error_message = ChatMessage(
-                    role=Role.SYSTEM,
+                    role="system",
                     contents=[
                         Content.from_error(
                             message=f"Error processing agent response: {e}",
@@ -376,7 +376,7 @@ class ClientAgentExecutor(DurableAgentExecutor[AgentResponse]):
                 correlation_id,
             )
             error_message = ChatMessage(
-                role=Role.SYSTEM,
+                role="system",
                 contents=[
                     Content.from_error(
                         message=f"Timeout waiting for agent response after {self.max_poll_retries} attempts",

python/packages/durabletask/agent_framework_durabletask/_models.py

@@ -16,7 +16,7 @@ from datetime import datetime, timezone
 from importlib import import_module
 from typing import TYPE_CHECKING, Any, cast
 
-from agent_framework import AgentThread, Role
+from agent_framework import AgentThread
 
 from ._constants import REQUEST_RESPONSE_FORMAT_TEXT
 
@@ -115,7 +115,7 @@ class RunRequest:
     message: str
     request_response_format: str
     correlation_id: str
-    role: Role = Role.USER
+    role: str = "user"
     response_format: type[BaseModel] | None = None
     enable_tool_calls: bool = True
     wait_for_response: bool = True
@@ -128,7 +128,7 @@ class RunRequest:
         message: str,
         correlation_id: str,
         request_response_format: str = REQUEST_RESPONSE_FORMAT_TEXT,
-        role: Role | str | None = Role.USER,
+        role: str | None = "user",
         response_format: type[BaseModel] | None = None,
         enable_tool_calls: bool = True,
         wait_for_response: bool = True,
@@ -148,16 +148,14 @@ class RunRequest:
         self.options = options if options is not None else {}
 
     @staticmethod
-    def coerce_role(value: Role | str | None) -> Role:
-        """Normalize various role representations into a Role instance."""
-        if isinstance(value, Role):
-            return value
+    def coerce_role(value: str | None) -> str:
+        """Normalize various role representations into a role string."""
         if isinstance(value, str):
             normalized = value.strip()
             if not normalized:
-                return Role.USER
-            return Role(value=normalized.lower())
-        return Role.USER
+                return "user"
+            return normalized.lower()
+        return "user"
 
     def to_dict(self) -> dict[str, Any]:
         """Convert to dictionary for JSON serialization."""
@@ -165,7 +163,7 @@ class RunRequest:
             "message": self.message,
             "enable_tool_calls": self.enable_tool_calls,
             "wait_for_response": self.wait_for_response,
-            "role": self.role.value,
+            "role": self.role,
             "request_response_format": self.request_response_format,
             "correlationId": self.correlation_id,
             "options": self.options,

python/packages/durabletask/agent_framework_durabletask/_response_utils.py

@@ -55,9 +55,12 @@ def ensure_response_format(
     Raises:
         ValueError: If response_format is specified but response.value cannot be parsed
     """
-    if response_format is not None and not isinstance(response.value, response_format):
-        response.try_parse_value(response_format)
+    if response_format is not None:
+        # Set the response format on the response so .value knows how to parse
+        response._response_format = response_format
+        response._value_parsed = False  # Reset to allow re-parsing with new format
 
+        # Access response.value to trigger parsing (may raise ValidationError)
         # Validate that parsing succeeded
         if not isinstance(response.value, response_format):
             raise ValueError(