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
@@ -12,7 +12,6 @@ from agent_framework import (
    Executor,
    WorkflowContext,
    handler,
-    tool,
 )
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
@@ -3,7 +3,7 @@
 import asyncio
 from typing import Any

-from agent_framework import ChatMessage, ConcurrentBuilder, Role
+from agent_framework import ChatMessage, ConcurrentBuilder
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential

@@ -66,13 +66,13 @@ async def main() -> None:

        # Ask the model to synthesize a concise summary of the experts' outputs
        system_msg = ChatMessage(
-            Role.SYSTEM,
+            "system",
            text=(
                "You are a helpful assistant that consolidates multiple domain expert outputs "
                "into one cohesive, concise summary with clear takeaways. Keep it under 200 words."
            ),
        )
-        user_msg = ChatMessage(Role.USER, text="\n\n".join(expert_sections))
+        user_msg = ChatMessage("user", text="\n\n".join(expert_sections))

        response = await chat_client.get_response([system_msg, user_msg])
        # Return the model's final assistant text as the completion result
@@ -8,11 +8,9 @@ from agent_framework import (
    ChatMessage,
    ConcurrentBuilder,
    Executor,
-    Role,
    Workflow,
    WorkflowContext,
    handler,
-    tool,
 )
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
@@ -98,13 +96,13 @@ class SummarizationExecutor(Executor):

        # Ask the model to synthesize a concise summary of the experts' outputs
        system_msg = ChatMessage(
-            Role.SYSTEM,
+            "system",
            text=(
                "You are a helpful assistant that consolidates multiple domain expert outputs "
                "into one cohesive, concise summary with clear takeaways. Keep it under 200 words."
            ),
        )
-        user_msg = ChatMessage(Role.USER, text="\n\n".join(expert_sections))
+        user_msg = ChatMessage("user", text="\n\n".join(expert_sections))

        response = await self.chat_client.get_response([system_msg, user_msg])

@@ -7,9 +7,7 @@ from agent_framework import (
    ChatAgent,
    ChatMessage,
    GroupChatBuilder,
-    Role,
    WorkflowOutputEvent,
-    tool,
 )
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
@@ -73,7 +71,7 @@ async def main() -> None:
        .participants([researcher, writer])
        # Set a hard termination condition: stop after 4 assistant messages
        # The agent orchestrator will intelligently decide when to end before this limit but just in case
-        .with_termination_condition(lambda messages: sum(1 for msg in messages if msg.role == Role.ASSISTANT) >= 4)
+        .with_termination_condition(lambda messages: sum(1 for msg in messages if msg.role == "assistant") >= 4)
        .build()
    )

@@ -9,9 +9,7 @@ from agent_framework import (
    ChatAgent,
    ChatMessage,
    GroupChatBuilder,
-    Role,
    WorkflowOutputEvent,
-    tool,
 )
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
@@ -214,7 +212,7 @@ Share your perspective authentically. Feel free to:
        GroupChatBuilder()
        .with_orchestrator(agent=moderator)
        .participants([farmer, developer, teacher, activist, spiritual_leader, artist, immigrant, doctor])
-        .with_termination_condition(lambda messages: sum(1 for msg in messages if msg.role == Role.ASSISTANT) >= 10)
+        .with_termination_condition(lambda messages: sum(1 for msg in messages if msg.role == "assistant") >= 10)
        .build()
    )

@@ -9,7 +9,6 @@ from agent_framework import (
    GroupChatBuilder,
    GroupChatState,
    WorkflowOutputEvent,
-    tool,
 )
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
@@ -14,7 +14,6 @@ from agent_framework import (
    WorkflowEvent,
    WorkflowOutputEvent,
    resolve_agent_id,
-    tool,
 )
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
@@ -95,7 +94,7 @@ def _display_event(event: WorkflowEvent) -> None:
        conversation = cast(list[ChatMessage], event.data)
        print("\n=== Final Conversation (Autonomous with Iteration) ===")
        for message in conversation:
-            speaker = message.author_name or message.role.value
+            speaker = message.author_name or message.role
            text_preview = message.text[:200] + "..." if len(message.text) > 200 else message.text
            print(f"- {speaker}: {text_preview}")
        print(f"\nTotal messages: {len(conversation)}")
@@ -131,7 +130,7 @@ async def main() -> None:
        )
        .with_termination_condition(
            # Terminate after coordinator provides 5 assistant responses
-            lambda conv: sum(1 for msg in conv if msg.author_name == "coordinator" and msg.role.value == "assistant")
+            lambda conv: sum(1 for msg in conv if msg.author_name == "coordinator" and msg.role == "assistant")
            >= 5
        )
        .build()
@@ -131,7 +131,7 @@ def _handle_events(events: list[WorkflowEvent]) -> list[RequestInfoEvent]:
                if not message.text:
                    # Skip messages without text (e.g., tool calls)
                    continue
-                speaker = message.author_name or message.role.value
+                speaker = message.author_name or message.role
                print(f"- {speaker}: {message.text}")

        # HandoffSentEvent: Indicates a handoff has been initiated
@@ -151,7 +151,7 @@ def _handle_events(events: list[WorkflowEvent]) -> list[RequestInfoEvent]:
            if isinstance(conversation, list):
                print("\n=== Final Conversation Snapshot ===")
                for message in conversation:
-                    speaker = message.author_name or message.role.value
+                    speaker = message.author_name or message.role
                    print(f"- {speaker}: {message.text or [content.type for content in message.contents]}")
                print("===================================")

@@ -183,7 +183,7 @@ def _print_handoff_agent_user_request(response: AgentResponse) -> None:
        if not message.text:
            # Skip messages without text (e.g., tool calls)
            continue
-        speaker = message.author_name or message.role.value
+        speaker = message.author_name or message.role
        print(f"- {speaker}: {message.text}")


@@ -126,7 +126,7 @@ def _handle_events(events: list[WorkflowEvent]) -> list[RequestInfoEvent]:
                if not message.text:
                    # Skip messages without text (e.g., tool calls)
                    continue
-                speaker = message.author_name or message.role.value
+                speaker = message.author_name or message.role
                print(f"- {speaker}: {message.text}")

        # HandoffSentEvent: Indicates a handoff has been initiated
@@ -146,7 +146,7 @@ def _handle_events(events: list[WorkflowEvent]) -> list[RequestInfoEvent]:
            if isinstance(conversation, list):
                print("\n=== Final Conversation Snapshot ===")
                for message in conversation:
-                    speaker = message.author_name or message.role.value
+                    speaker = message.author_name or message.role
                    print(f"- {speaker}: {message.text or [content.type for content in message.contents]}")
                print("===================================")

@@ -178,7 +178,7 @@ def _print_handoff_agent_user_request(response: AgentResponse) -> None:
        if not message.text:
            # Skip messages without text (e.g., tool calls)
            continue
-        speaker = message.author_name or message.role.value
+        speaker = message.author_name or message.role
        print(f"- {speaker}: {message.text}")


@@ -41,7 +41,6 @@ from agent_framework import (
    WorkflowEvent,
    WorkflowRunState,
    WorkflowStatusEvent,
-    tool,
 )
 from azure.identity.aio import AzureCliCredential

@@ -157,7 +156,7 @@ async def main() -> None:
                HandoffBuilder()
                .participants([triage, code_specialist])
                .with_start_agent(triage)
-                .with_termination_condition(lambda conv: sum(1 for msg in conv if msg.role.value == "user") >= 2)
+                .with_termination_condition(lambda conv: sum(1 for msg in conv if msg.role == "user") >= 2)
                .build()
            )

@@ -15,7 +15,6 @@ from agent_framework import (
    MagenticOrchestratorEvent,
    MagenticProgressLedger,
    WorkflowOutputEvent,
-    tool,
 )
 from agent_framework.openai import OpenAIChatClient, OpenAIResponsesClient

@@ -16,7 +16,6 @@ from agent_framework import (
    WorkflowOutputEvent,
    WorkflowRunState,
    WorkflowStatusEvent,
-    tool,
 )
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity._credentials import AzureCliCredential
@@ -12,7 +12,6 @@ from agent_framework import (
    MagenticPlanReviewRequest,
    RequestInfoEvent,
    WorkflowOutputEvent,
-    tool,
 )
 from agent_framework.openai import OpenAIChatClient

@@ -3,7 +3,7 @@
 import asyncio
 from typing import cast

-from agent_framework import ChatMessage, Role, SequentialBuilder, WorkflowOutputEvent
+from agent_framework import ChatMessage, SequentialBuilder, WorkflowOutputEvent
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential

@@ -53,7 +53,7 @@ async def main() -> None:
    if outputs:
        print("===== Final Conversation =====")
        for i, msg in enumerate(outputs[-1], start=1):
-            name = msg.author_name or ("assistant" if msg.role == Role.ASSISTANT else "user")
+            name = msg.author_name or ("assistant" if msg.role == "assistant" else "user")
            print(f"{'-' * 60}\n{i:02d} [{name}]\n{msg.text}")

    """
@@ -7,11 +7,9 @@ from agent_framework import (
    AgentExecutorResponse,
    ChatMessage,
    Executor,
-    Role,
    SequentialBuilder,
    WorkflowContext,
    handler,
-    tool,
 )
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
@@ -48,12 +46,12 @@ class Summarizer(Executor):
        the output must be `list[ChatMessage]`.
        """
        if not agent_response.full_conversation:
-            await ctx.send_message([ChatMessage(role=Role.ASSISTANT, text="No conversation to summarize.")])
+            await ctx.send_message([ChatMessage("assistant", ["No conversation to summarize."])])
            return

-        users = sum(1 for m in agent_response.full_conversation if m.role == Role.USER)
-        assistants = sum(1 for m in agent_response.full_conversation if m.role == Role.ASSISTANT)
-        summary = ChatMessage(role=Role.ASSISTANT, text=f"Summary -> users:{users} assistants:{assistants}")
+        users = sum(1 for m in agent_response.full_conversation if m.role == "user")
+        assistants = sum(1 for m in agent_response.full_conversation if m.role == "assistant")
+        summary = ChatMessage("assistant", [f"Summary -> users:{users} assistants:{assistants}"])
        final_conversation = list(agent_response.full_conversation) + [summary]
        await ctx.send_message(final_conversation)

@@ -78,7 +76,7 @@ async def main() -> None:
        print("===== Final Conversation =====")
        messages: list[ChatMessage] | Any = outputs[0]
        for i, msg in enumerate(messages, start=1):
-            name = msg.author_name or ("assistant" if msg.role == Role.ASSISTANT else "user")
+            name = msg.author_name or ("assistant" if msg.role == "assistant" else "user")
            print(f"{'-' * 60}\n{i:02d} [{name}]\n{msg.text}")

    """
@@ -6,12 +6,10 @@ from agent_framework import (
    ChatAgent,
    ChatMessage,
    Executor,
-    Role,
    SequentialBuilder,
    Workflow,
    WorkflowContext,
    handler,
-    tool,
 )
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
@@ -64,7 +62,7 @@ async def run_workflow(workflow: Workflow, query: str) -> None:
    if outputs:
        messages: list[ChatMessage] = outputs[0]
        for message in messages:
-            name = message.author_name or ("assistant" if message.role == Role.ASSISTANT else "user")
+            name = message.author_name or ("assistant" if message.role == "assistant" else "user")
            print(f"{name}: {message.text}")
    else:
        raise RuntimeError("No outputs received from the workflow.")