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/bedrock/agent_framework_bedrock/_chat_client.py

@@ -16,9 +16,7 @@ from agent_framework import (
     ChatResponse,
     ChatResponseUpdate,
     Content,
-    FinishReason,
     FunctionTool,
-    Role,
     ToolProtocol,
     UsageDetails,
     get_logger,
@@ -185,20 +183,20 @@ TBedrockChatOptions = TypeVar("TBedrockChatOptions", bound=TypedDict, default="B
 # endregion
 
 
-ROLE_MAP: dict[Role, str] = {
-    Role.USER: "user",
-    Role.ASSISTANT: "assistant",
-    Role.SYSTEM: "user",
-    Role.TOOL: "user",
+ROLE_MAP: dict[str, str] = {
+    "user": "user",
+    "assistant": "assistant",
+    "system": "user",
+    "tool": "user",
 }
 
-FINISH_REASON_MAP: dict[str, FinishReason] = {
-    "end_turn": FinishReason.STOP,
-    "stop_sequence": FinishReason.STOP,
-    "max_tokens": FinishReason.LENGTH,
-    "length": FinishReason.LENGTH,
-    "content_filtered": FinishReason.CONTENT_FILTER,
-    "tool_use": FinishReason.TOOL_CALLS,
+FINISH_REASON_MAP: dict[str, str] = {
+    "end_turn": "stop",
+    "stop_sequence": "stop",
+    "max_tokens": "length",
+    "length": "length",
+    "content_filtered": "content_filter",
+    "tool_use": "tool_calls",
 }
 
 
@@ -397,7 +395,7 @@ class BedrockChatClient(BaseChatClient[TBedrockChatOptions], Generic[TBedrockCha
         conversation: list[dict[str, Any]] = []
         pending_tool_use_ids: deque[str] = deque()
         for message in messages:
-            if message.role == Role.SYSTEM:
+            if message.role == "system":
                 text_value = message.text
                 if text_value:
                     prompts.append({"text": text_value})
@@ -414,7 +412,7 @@ class BedrockChatClient(BaseChatClient[TBedrockChatOptions], Generic[TBedrockCha
                     for block in content_blocks
                     if isinstance(block, MutableMapping) and "toolUse" in block
                 )
-            elif message.role == Role.TOOL:
+            elif message.role == "tool":
                 content_blocks = self._align_tool_results_with_pending(content_blocks, pending_tool_use_ids)
                 pending_tool_use_ids.clear()
                 if not content_blocks:
@@ -574,7 +572,7 @@ class BedrockChatClient(BaseChatClient[TBedrockChatOptions], Generic[TBedrockCha
         message = output.get("message", {})
         content_blocks = message.get("content", []) or []
         contents = self._parse_message_contents(content_blocks)
-        chat_message = ChatMessage(role=Role.ASSISTANT, contents=contents, raw_representation=message)
+        chat_message = ChatMessage("assistant", contents, raw_representation=message)
         usage_details = self._parse_usage(response.get("usage") or output.get("usage"))
         finish_reason = self._map_finish_reason(output.get("completionReason") or response.get("stopReason"))
         response_id = response.get("responseId") or message.get("id")
@@ -642,7 +640,7 @@ class BedrockChatClient(BaseChatClient[TBedrockChatOptions], Generic[TBedrockCha
             logger.debug("Ignoring unsupported Bedrock content block: %s", block)
         return contents
 
-    def _map_finish_reason(self, reason: str | None) -> FinishReason | None:
+    def _map_finish_reason(self, reason: str | None) -> str | None:
         if not reason:
             return None
         return FINISH_REASON_MAP.get(reason.lower())

python/packages/bedrock/tests/test_bedrock_client.py

@@ -6,7 +6,7 @@ import asyncio
 from typing import Any
 
 import pytest
-from agent_framework import ChatMessage, Content, Role
+from agent_framework import ChatMessage, Content
 from agent_framework.exceptions import ServiceInitializationError
 
 from agent_framework_bedrock import BedrockChatClient
@@ -42,8 +42,8 @@ def test_get_response_invokes_bedrock_runtime() -> None:
     )
 
     messages = [
-        ChatMessage(role=Role.SYSTEM, contents=[Content.from_text(text="You are concise.")]),
-        ChatMessage(role=Role.USER, contents=[Content.from_text(text="hello")]),
+        ChatMessage("system", [Content.from_text(text="You are concise.")]),
+        ChatMessage("user", [Content.from_text(text="hello")]),
     ]
 
     response = asyncio.run(client.get_response(messages=messages, options={"max_tokens": 32}))
@@ -63,7 +63,7 @@ def test_build_request_requires_non_system_messages() -> None:
         client=_StubBedrockRuntime(),
     )
 
-    messages = [ChatMessage(role=Role.SYSTEM, contents=[Content.from_text(text="Only system text")])]
+    messages = [ChatMessage("system", [Content.from_text(text="Only system text")])]
 
     with pytest.raises(ServiceInitializationError):
         client._prepare_options(messages, {})

python/packages/bedrock/tests/test_bedrock_settings.py

@@ -10,7 +10,6 @@ from agent_framework import (
     ChatOptions,
     Content,
     FunctionTool,
-    Role,
 )
 from pydantic import BaseModel
 
@@ -47,7 +46,7 @@ def test_build_request_includes_tool_config() -> None:
         "tools": [tool],
         "tool_choice": {"mode": "required", "required_function_name": "get_weather"},
     }
-    messages = [ChatMessage(role=Role.USER, contents=[Content.from_text(text="hi")])]
+    messages = [ChatMessage("user", [Content.from_text(text="hi")])]
 
     request = client._prepare_options(messages, options)
 
@@ -59,15 +58,15 @@ def test_build_request_serializes_tool_history() -> None:
     client = _build_client()
     options: ChatOptions = {}
     messages = [
-        ChatMessage(role=Role.USER, contents=[Content.from_text(text="how's weather?")]),
+        ChatMessage("user", [Content.from_text(text="how's weather?")]),
         ChatMessage(
-            role=Role.ASSISTANT,
+            role="assistant",
             contents=[
                 Content.from_function_call(call_id="call-1", name="get_weather", arguments='{"location": "SEA"}')
             ],
         ),
         ChatMessage(
-            role=Role.TOOL,
+            role="tool",
             contents=[Content.from_function_result(call_id="call-1", result={"answer": "72F"})],
         ),
     ]