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
2026-06-16 21:04:09 +08:00 · 2026-02-04 11:13:23 +01:00
parent ef798629e5
commit 838a7fd61d
341 changed files with 3766 additions and 3228 deletions
@@ -303,7 +303,7 @@ class InMemoryConversationStore(ConversationStore):
            content = item.get("content", [])
            text = content[0].get("text", "") if content else ""

-            chat_msg = ChatMessage(role=role, contents=[{"type": "text", "text": text}])
+            chat_msg = ChatMessage(role, [{"type": "text", "text": text}])
            chat_messages.append(chat_msg)

        # Add messages to AgentThread
@@ -315,7 +315,7 @@ class InMemoryConversationStore(ConversationStore):
            item_id = f"item_{uuid.uuid4().hex}"

            # Extract role - handle both string and enum
-            role_str = msg.role.value if hasattr(msg.role, "value") else str(msg.role)
+            role_str = msg.role if hasattr(msg.role, "value") else str(msg.role)
            role = cast(MessageRole, role_str)  # Safe: Agent Framework roles match OpenAI roles

            # Convert ChatMessage contents to OpenAI TextContent format
@@ -373,7 +373,7 @@ class InMemoryConversationStore(ConversationStore):
            # Convert each AgentFramework ChatMessage to appropriate ConversationItem type(s)
            for i, msg in enumerate(af_messages):
                item_id = f"item_{i}"
-                role_str = msg.role.value if hasattr(msg.role, "value") else str(msg.role)
+                role_str = msg.role if hasattr(msg.role, "value") else str(msg.role)
                role = cast(MessageRole, role_str)  # Safe: Agent Framework roles match OpenAI roles

                # Process each content item in the message
@@ -760,7 +760,7 @@ class AgentFrameworkExecutor:
        if not contents:
            contents.append(Content.from_text(text=""))

-        chat_message = ChatMessage(role=Role.USER, contents=contents)
+        chat_message = ChatMessage("user", contents)

        logger.info(f"Created ChatMessage with {len(contents)} contents:")
        for idx, content in enumerate(contents):
@@ -7,7 +7,7 @@ import tempfile
 from pathlib import Path

 import pytest
-from agent_framework import AgentResponse, ChatMessage, Content, Role
+from agent_framework import AgentResponse, ChatMessage, Content

 from agent_framework_devui import register_cleanup
 from agent_framework_devui._discovery import EntityDiscovery
@@ -36,7 +36,7 @@ class MockAgent:
    async def run_stream(self, messages=None, *, thread=None, **kwargs):
        """Mock streaming run method."""
        yield AgentResponse(
-            messages=[ChatMessage(role=Role.ASSISTANT, contents=[Content.from_text(text="Test response")])],
+            messages=[ChatMessage("assistant", [Content.from_text(text="Test response")])],
        )


@@ -279,7 +279,7 @@ class TestAgent:

    async def run_stream(self, messages=None, *, thread=None, **kwargs):
        yield AgentResponse(
-            messages=[ChatMessage(role=Role.ASSISTANT, content=[Content.from_text(text="Test")])],
+            messages=[ChatMessage("assistant", [Content.from_text(text="Test")])],
            inner_messages=[],
        )

@@ -199,7 +199,7 @@ async def test_list_items_pagination():
@pytest.mark.asyncio
 async def test_list_items_converts_function_calls():
    """Test that list_items properly converts function calls to ResponseFunctionToolCallItem."""
-    from agent_framework import ChatMessage, ChatMessageStore, Role
+    from agent_framework import ChatMessage, ChatMessageStore

    store = InMemoryConversationStore()

@@ -216,9 +216,9 @@ async def test_list_items_converts_function_calls():

    # Simulate messages from agent execution with function calls
    messages = [
-        ChatMessage(role=Role.USER, contents=[{"type": "text", "text": "What's the weather in SF?"}]),
+        ChatMessage("user", [{"type": "text", "text": "What's the weather in SF?"}]),
        ChatMessage(
-            role=Role.ASSISTANT,
+            role="assistant",
            contents=[
                {
                    "type": "function_call",
@@ -229,7 +229,7 @@ async def test_list_items_converts_function_calls():
            ],
        ),
        ChatMessage(
-            role=Role.TOOL,
+            role="tool",
            contents=[
                {
                    "type": "function_result",
@@ -238,7 +238,7 @@ async def test_list_items_converts_function_calls():
                }
            ],
        ),
-        ChatMessage(role=Role.ASSISTANT, contents=[{"type": "text", "text": "The weather is sunny, 65°F"}]),
+        ChatMessage("assistant", [{"type": "text", "text": "The weather is sunny, 65°F"}]),
    ]

    # Add messages to thread
@@ -284,7 +284,7 @@ async def test_list_items_converts_function_calls():
@pytest.mark.asyncio
 async def test_list_items_handles_images_and_files():
    """Test that list_items properly converts data content (images/files) to OpenAI types."""
-    from agent_framework import ChatMessage, ChatMessageStore, Role
+    from agent_framework import ChatMessage, ChatMessageStore

    store = InMemoryConversationStore()

@@ -301,7 +301,7 @@ async def test_list_items_handles_images_and_files():
    # Simulate message with image and file
    messages = [
        ChatMessage(
-            role=Role.USER,
+            role="user",
            contents=[
                {"type": "text", "text": "Check this image and PDF"},
                {"type": "data", "uri": "data:image/png;base64,iVBORw0KGgo=", "media_type": "image/png"},
@@ -94,7 +94,7 @@ class NonStreamingAgent:
    async def run(self, messages=None, *, thread=None, **kwargs):
        return AgentResponse(
            messages=[ChatMessage(
-                role=Role.ASSISTANT,
+                role="assistant",
                contents=[Content.from_text(text="response")]
            )],
            response_id="test"
@@ -210,7 +210,7 @@ class TestAgent:

    async def run(self, messages=None, *, thread=None, **kwargs):
        return AgentResponse(
-            messages=[ChatMessage(role=Role.ASSISTANT, contents=[Content.from_text(text="test")])],
+            messages=[ChatMessage("assistant", [Content.from_text(text="test")])],
            response_id="test"
        )

@@ -566,7 +566,7 @@ def test_extract_workflow_hil_responses_handles_stringified_json():

 async def test_executor_handles_non_streaming_agent():
    """Test executor can handle agents with only run() method (no run_stream)."""
-    from agent_framework import AgentResponse, AgentThread, ChatMessage, Content, Role
+    from agent_framework import AgentResponse, AgentThread, ChatMessage, Content

    class NonStreamingAgent:
        """Agent with only run() method - does NOT satisfy full AgentProtocol."""
@@ -577,9 +577,7 @@ async def test_executor_handles_non_streaming_agent():

        async def run(self, messages=None, *, thread=None, **kwargs):
            return AgentResponse(
-                messages=[
-                    ChatMessage(role=Role.ASSISTANT, contents=[Content.from_text(text=f"Processed: {messages}")])
-                ],
+                messages=[ChatMessage("assistant", [Content.from_text(text=f"Processed: {messages}")])],
                response_id="test_123",
            )

@@ -29,7 +29,6 @@ from agent_framework import (
    ChatResponseUpdate,
    ConcurrentBuilder,
    Content,
-    Role,
    SequentialBuilder,
    use_chat_middleware,
 )
@@ -79,7 +78,7 @@ class MockChatClient:
        self.call_count += 1
        if self.responses:
            return self.responses.pop(0)
-        return ChatResponse(messages=ChatMessage(role="assistant", text="test response"))
+        return ChatResponse(messages=ChatMessage("assistant", ["test response"]))

    async def get_streaming_response(
        self,
@@ -91,7 +90,7 @@ class MockChatClient:
            for update in self.streaming_responses.pop(0):
                yield update
        else:
-            yield ChatResponseUpdate(text=Content.from_text(text="test streaming response"), role="assistant")
+            yield ChatResponseUpdate(contents=[Content.from_text(text="test streaming response")], role="assistant")


@use_chat_middleware
@@ -122,7 +121,7 @@ class MockBaseChatClient(BaseChatClient[TOptions_co], Generic[TOptions_co]):
        self.received_messages.append(list(messages))
        if self.run_responses:
            return self.run_responses.pop(0)
-        return ChatResponse(messages=ChatMessage(role="assistant", text="Mock response from ChatAgent"))
+        return ChatResponse(messages=ChatMessage("assistant", ["Mock response from ChatAgent"]))

    @override
    async def _inner_get_streaming_response(
@@ -139,10 +138,10 @@ class MockBaseChatClient(BaseChatClient[TOptions_co], Generic[TOptions_co]):
                yield update
        else:
            # Simulate realistic streaming chunks
-            yield ChatResponseUpdate(text=Content.from_text(text="Mock "), role="assistant")
-            yield ChatResponseUpdate(text=Content.from_text(text="streaming "), role="assistant")
-            yield ChatResponseUpdate(text=Content.from_text(text="response "), role="assistant")
-            yield ChatResponseUpdate(text=Content.from_text(text="from ChatAgent"), role="assistant")
+            yield ChatResponseUpdate(contents=[Content.from_text(text="Mock ")], role="assistant")
+            yield ChatResponseUpdate(contents=[Content.from_text(text="streaming ")], role="assistant")
+            yield ChatResponseUpdate(contents=[Content.from_text(text="response ")], role="assistant")
+            yield ChatResponseUpdate(contents=[Content.from_text(text="from ChatAgent")], role="assistant")


 # =============================================================================
@@ -172,9 +171,7 @@ class MockAgent(BaseAgent):
        **kwargs: Any,
    ) -> AgentResponse:
        self.call_count += 1
-        return AgentResponse(
-            messages=[ChatMessage(role=Role.ASSISTANT, contents=[Content.from_text(text=self.response_text)])]
-        )
+        return AgentResponse(messages=[ChatMessage("assistant", [Content.from_text(text=self.response_text)])])

    async def run_stream(
        self,
@@ -185,7 +182,7 @@ class MockAgent(BaseAgent):
    ) -> AsyncIterable[AgentResponseUpdate]:
        self.call_count += 1
        for chunk in self.streaming_chunks:
-            yield AgentResponseUpdate(contents=[Content.from_text(text=chunk)], role=Role.ASSISTANT)
+            yield AgentResponseUpdate(contents=[Content.from_text(text=chunk)], role="assistant")


 class MockToolCallingAgent(BaseAgent):
@@ -203,7 +200,7 @@ class MockToolCallingAgent(BaseAgent):
        **kwargs: Any,
    ) -> AgentResponse:
        self.call_count += 1
-        return AgentResponse(messages=[ChatMessage(role=Role.ASSISTANT, text="done")])
+        return AgentResponse(messages=[ChatMessage("assistant", ["done"])])

    async def run_stream(
        self,
@@ -216,7 +213,7 @@ class MockToolCallingAgent(BaseAgent):
        # First: text
        yield AgentResponseUpdate(
            contents=[Content.from_text(text="Let me search for that...")],
-            role=Role.ASSISTANT,
+            role="assistant",
        )
        # Second: tool call
        yield AgentResponseUpdate(
@@ -227,7 +224,7 @@ class MockToolCallingAgent(BaseAgent):
                    arguments={"query": "weather"},
                )
            ],
-            role=Role.ASSISTANT,
+            role="assistant",
        )
        # Third: tool result
        yield AgentResponseUpdate(
@@ -237,12 +234,12 @@ class MockToolCallingAgent(BaseAgent):
                    result={"temperature": 72, "condition": "sunny"},
                )
            ],
-            role=Role.TOOL,
+            role="tool",
        )
        # Fourth: final text
        yield AgentResponseUpdate(
            contents=[Content.from_text(text="The weather is sunny, 72°F.")],
-            role=Role.ASSISTANT,
+            role="assistant",
        )


@@ -295,7 +292,7 @@ def create_mock_tool_agent(id: str = "tool_agent", name: str = "ToolAgent") -> M

 def create_agent_run_response(text: str = "Test response") -> AgentResponse:
    """Create an AgentResponse with the given text."""
-    return AgentResponse(messages=[ChatMessage(role=Role.ASSISTANT, contents=[Content.from_text(text=text)])])
+    return AgentResponse(messages=[ChatMessage("assistant", [Content.from_text(text=text)])])


 def create_agent_executor_response(
@@ -308,8 +305,8 @@ def create_agent_executor_response(
        executor_id=executor_id,
        agent_response=agent_response,
        full_conversation=[
-            ChatMessage(role=Role.USER, contents=[Content.from_text(text="User input")]),
-            ChatMessage(role=Role.ASSISTANT, contents=[Content.from_text(text=response_text)]),
+            ChatMessage("user", [Content.from_text(text="User input")]),
+            ChatMessage("assistant", [Content.from_text(text=response_text)]),
        ],
    )

@@ -391,8 +388,8 @@ async def create_sequential_workflow() -> tuple[AgentFrameworkExecutor, str, Moc
    """
    mock_client = MockBaseChatClient()
    mock_client.run_responses = [
-        ChatResponse(messages=ChatMessage(role=Role.ASSISTANT, text="Here's the draft content about the topic.")),
-        ChatResponse(messages=ChatMessage(role=Role.ASSISTANT, text="Review: Content is clear and well-structured.")),
+        ChatResponse(messages=ChatMessage("assistant", ["Here's the draft content about the topic."])),
+        ChatResponse(messages=ChatMessage("assistant", ["Review: Content is clear and well-structured."])),
    ]

    writer = ChatAgent(
@@ -434,9 +431,9 @@ async def create_concurrent_workflow() -> tuple[AgentFrameworkExecutor, str, Moc
    """
    mock_client = MockBaseChatClient()
    mock_client.run_responses = [
-        ChatResponse(messages=ChatMessage(role=Role.ASSISTANT, text="Research findings: Key data points identified.")),
-        ChatResponse(messages=ChatMessage(role=Role.ASSISTANT, text="Analysis: Trends indicate positive growth.")),
-        ChatResponse(messages=ChatMessage(role=Role.ASSISTANT, text="Summary: Overall outlook is favorable.")),
+        ChatResponse(messages=ChatMessage("assistant", ["Research findings: Key data points identified."])),
+        ChatResponse(messages=ChatMessage("assistant", ["Analysis: Trends indicate positive growth."])),
+        ChatResponse(messages=ChatMessage("assistant", ["Summary: Overall outlook is favorable."])),
    ]

    researcher = ChatAgent(
@@ -15,7 +15,6 @@ import pytest
 from agent_framework._types import (
    AgentResponseUpdate,
    Content,
-    Role,
 )

 # Import real workflow event classes - NOT mocks!
@@ -84,7 +83,7 @@ def create_test_content(content_type: str, **kwargs: Any) -> Any:

 def create_test_agent_update(contents: list[Any]) -> AgentResponseUpdate:
    """Create test AgentResponseUpdate."""
-    return AgentResponseUpdate(contents=contents, role=Role.ASSISTANT, message_id="test_msg", response_id="test_resp")
+    return AgentResponseUpdate(contents=contents, role="assistant", message_id="test_msg", response_id="test_resp")


 # =============================================================================
@@ -450,13 +449,13 @@ async def test_magentic_agent_run_update_event_with_agent_delta_metadata(
    This tests the ACTUAL event format Magentic emits - not a fake MagenticAgentDeltaEvent class.
    Magentic uses AgentRunUpdateEvent with additional_properties containing magentic_event_type.
    """
-    from agent_framework._types import AgentResponseUpdate, Role
+    from agent_framework._types import AgentResponseUpdate
    from agent_framework._workflows._events import AgentRunUpdateEvent

    # Create the REAL event format that Magentic emits
    update = AgentResponseUpdate(
        contents=[Content.from_text(text="Hello from agent")],
-        role=Role.ASSISTANT,
+        role="assistant",
        author_name="Writer",
        additional_properties={
            "magentic_event_type": "agent_delta",
@@ -481,13 +480,13 @@ async def test_magentic_orchestrator_message_event(mapper: MessageMapper, test_r
    Magentic emits orchestrator planning/instruction messages using AgentRunUpdateEvent
    with additional_properties containing magentic_event_type='orchestrator_message'.
    """
-    from agent_framework._types import AgentResponseUpdate, Role
+    from agent_framework._types import AgentResponseUpdate
    from agent_framework._workflows._events import AgentRunUpdateEvent

    # Create orchestrator message event (REAL format from Magentic)
    update = AgentResponseUpdate(
        contents=[Content.from_text(text="Planning: First, the writer will create content...")],
-        role=Role.ASSISTANT,
+        role="assistant",
        author_name="Orchestrator",
        additional_properties={
            "magentic_event_type": "orchestrator_message",
@@ -517,21 +516,21 @@ async def test_magentic_events_use_same_event_class_as_other_workflows(
    additional_properties. Any mapper code checking for 'MagenticAgentDeltaEvent'
    class names is dead code.
    """
-    from agent_framework._types import AgentResponseUpdate, Role
+    from agent_framework._types import AgentResponseUpdate
    from agent_framework._workflows._events import AgentRunUpdateEvent

    # Create events the way different workflows do it
    # 1. Regular workflow (no additional_properties)
    regular_update = AgentResponseUpdate(
        contents=[Content.from_text(text="Regular workflow response")],
-        role=Role.ASSISTANT,
+        role="assistant",
    )
    regular_event = AgentRunUpdateEvent(executor_id="regular_executor", data=regular_update)

    # 2. Magentic workflow (with additional_properties)
    magentic_update = AgentResponseUpdate(
        contents=[Content.from_text(text="Magentic workflow response")],
-        role=Role.ASSISTANT,
+        role="assistant",
        additional_properties={"magentic_event_type": "agent_delta"},
    )
    magentic_event = AgentRunUpdateEvent(executor_id="magentic_executor", data=magentic_update)
@@ -598,13 +597,13 @@ async def test_workflow_output_event(mapper: MessageMapper, test_request: AgentF

 async def test_workflow_output_event_with_list_data(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
    """Test WorkflowOutputEvent with list data (common for sequential/concurrent workflows)."""
-    from agent_framework import ChatMessage, Role
+    from agent_framework import ChatMessage
    from agent_framework._workflows._events import WorkflowOutputEvent

    # Sequential/Concurrent workflows often output list[ChatMessage]
    messages = [
-        ChatMessage(role=Role.USER, contents=[Content.from_text(text="Hello")]),
-        ChatMessage(role=Role.ASSISTANT, contents=[Content.from_text(text="World")]),
+        ChatMessage("user", [Content.from_text(text="Hello")]),
+        ChatMessage("assistant", [Content.from_text(text="World")]),
    ]
    event = WorkflowOutputEvent(data=messages, executor_id="complete")
    events = await mapper.convert_event(event, test_request)
@@ -49,7 +49,7 @@ class TestMultimodalWorkflowInput:

    def test_convert_openai_input_to_chat_message_with_image(self):
        """Test that OpenAI format with image is converted to ChatMessage with DataContent."""
-        from agent_framework import ChatMessage, Role
+        from agent_framework import ChatMessage

        discovery = MagicMock(spec=EntityDiscovery)
        mapper = MagicMock(spec=MessageMapper)
@@ -72,7 +72,7 @@ class TestMultimodalWorkflowInput:

        # Verify result is ChatMessage
        assert isinstance(result, ChatMessage), f"Expected ChatMessage, got {type(result)}"
-        assert result.role == Role.USER
+        assert result.role == "user"

        # Verify contents
        assert len(result.contents) == 2, f"Expected 2 contents, got {len(result.contents)}"