Python: [BREAKING] Python: Intro group chat and refactor orchestrations. Fix as_agent(). Standardize orchestration start msg types.

python/packages/core/agent_framework/_workflows/__init__.py

@@ -52,29 +52,27 @@
     handler,
 )
 from ._function_executor import FunctionExecutor, executor
+from ._group_chat import (
+    DEFAULT_MANAGER_INSTRUCTIONS,
+    GroupChatBuilder,
+    GroupChatDirective,
+    GroupChatStateSnapshot,
+)
 from ._handoff import HandoffBuilder, HandoffUserInputRequest
 from ._magentic import (
     MagenticAgentDeltaEvent,
-    MagenticAgentExecutor,
     MagenticAgentMessageEvent,
     MagenticBuilder,
-    MagenticCallbackEvent,
-    MagenticCallbackMode,
     MagenticContext,
     MagenticFinalResultEvent,
     MagenticManagerBase,
-    MagenticOrchestratorExecutor,
     MagenticOrchestratorMessageEvent,
     MagenticPlanReviewDecision,
     MagenticPlanReviewReply,
     MagenticPlanReviewRequest,
-    MagenticProgressLedger,
-    MagenticProgressLedgerItem,
-    MagenticRequestMessage,
-    MagenticResponseMessage,
-    MagenticStartMessage,
     StandardMagenticManager,
 )
+from ._orchestration_state import OrchestrationState
 from ._request_info_executor import (
     PendingRequestDetails,
     RequestInfoExecutor,
@@ -105,6 +103,7 @@
 from ._workflow_executor import WorkflowExecutor
 
 __all__ = [
+    "DEFAULT_MANAGER_INSTRUCTIONS",
     "DEFAULT_MAX_ITERATIONS",
     "AgentExecutor",
     "AgentExecutorRequest",
@@ -128,30 +127,25 @@
     "FileCheckpointStorage",
     "FunctionExecutor",
     "GraphConnectivityError",
+    "GroupChatBuilder",
+    "GroupChatDirective",
+    "GroupChatStateSnapshot",
     "HandoffBuilder",
     "HandoffUserInputRequest",
     "InMemoryCheckpointStorage",
     "InProcRunnerContext",
     "MagenticAgentDeltaEvent",
-    "MagenticAgentExecutor",
     "MagenticAgentMessageEvent",
     "MagenticBuilder",
-    "MagenticCallbackEvent",
-    "MagenticCallbackMode",
     "MagenticContext",
     "MagenticFinalResultEvent",
     "MagenticManagerBase",
-    "MagenticOrchestratorExecutor",
     "MagenticOrchestratorMessageEvent",
     "MagenticPlanReviewDecision",
     "MagenticPlanReviewReply",
     "MagenticPlanReviewRequest",
-    "MagenticProgressLedger",
-    "MagenticProgressLedgerItem",
-    "MagenticRequestMessage",
-    "MagenticResponseMessage",
-    "MagenticStartMessage",
     "Message",
+    "OrchestrationState",
     "PendingRequestDetails",
     "RequestInfoEvent",
     "RequestInfoExecutor",

python/packages/core/agent_framework/_workflows/__init__.pyi

@@ -50,29 +50,27 @@ from ._executor import (
     handler,
 )
 from ._function_executor import FunctionExecutor, executor
+from ._group_chat import (
+    DEFAULT_MANAGER_INSTRUCTIONS,
+    GroupChatBuilder,
+    GroupChatDirective,
+    GroupChatStateSnapshot,
+)
 from ._handoff import HandoffBuilder, HandoffUserInputRequest
 from ._magentic import (
     MagenticAgentDeltaEvent,
-    MagenticAgentExecutor,
     MagenticAgentMessageEvent,
     MagenticBuilder,
-    MagenticCallbackEvent,
-    MagenticCallbackMode,
     MagenticContext,
     MagenticFinalResultEvent,
     MagenticManagerBase,
-    MagenticOrchestratorExecutor,
     MagenticOrchestratorMessageEvent,
     MagenticPlanReviewDecision,
     MagenticPlanReviewReply,
     MagenticPlanReviewRequest,
-    MagenticProgressLedger,
-    MagenticProgressLedgerItem,
-    MagenticRequestMessage,
-    MagenticResponseMessage,
-    MagenticStartMessage,
     StandardMagenticManager,
 )
+from ._orchestration_state import OrchestrationState
 from ._request_info_executor import (
     PendingRequestDetails,
     RequestInfoExecutor,
@@ -103,6 +101,7 @@ from ._workflow_context import WorkflowContext
 from ._workflow_executor import WorkflowExecutor
 
 __all__ = [
+    "DEFAULT_MANAGER_INSTRUCTIONS",
     "DEFAULT_MAX_ITERATIONS",
     "AgentExecutor",
     "AgentExecutorRequest",
@@ -126,30 +125,25 @@ __all__ = [
     "FileCheckpointStorage",
     "FunctionExecutor",
     "GraphConnectivityError",
+    "GroupChatBuilder",
+    "GroupChatDirective",
+    "GroupChatStateSnapshot",
     "HandoffBuilder",
     "HandoffUserInputRequest",
     "InMemoryCheckpointStorage",
     "InProcRunnerContext",
     "MagenticAgentDeltaEvent",
-    "MagenticAgentExecutor",
     "MagenticAgentMessageEvent",
     "MagenticBuilder",
-    "MagenticCallbackEvent",
-    "MagenticCallbackMode",
     "MagenticContext",
     "MagenticFinalResultEvent",
     "MagenticManagerBase",
-    "MagenticOrchestratorExecutor",
     "MagenticOrchestratorMessageEvent",
     "MagenticPlanReviewDecision",
     "MagenticPlanReviewReply",
     "MagenticPlanReviewRequest",
-    "MagenticProgressLedger",
-    "MagenticProgressLedgerItem",
-    "MagenticRequestMessage",
-    "MagenticResponseMessage",
-    "MagenticStartMessage",
     "Message",
+    "OrchestrationState",
     "PendingRequestDetails",
     "RequestInfoEvent",
     "RequestInfoExecutor",

python/packages/core/agent_framework/_workflows/_agent.py

@@ -3,7 +3,7 @@
 import json
 import logging
 import uuid
-from collections.abc import AsyncIterable, Sequence
+from collections.abc import AsyncIterable
 from dataclasses import dataclass
 from datetime import datetime
 from typing import TYPE_CHECKING, Any, ClassVar, TypedDict, cast
@@ -19,7 +19,6 @@
     FunctionCallContent,
     FunctionResultContent,
     Role,
-    TextContent,
     UsageDetails,
 )
 
@@ -29,6 +28,7 @@
     RequestInfoEvent,
     WorkflowEvent,
 )
+from ._message_utils import normalize_messages_input
 
 if TYPE_CHECKING:
     from ._workflow import Workflow
@@ -131,7 +131,7 @@ async def run(
         """
         # Collect all streaming updates
         response_updates: list[AgentRunResponseUpdate] = []
-        input_messages = self._normalize_messages(messages)
+        input_messages = normalize_messages_input(messages)
         thread = thread or self.get_new_thread()
         response_id = str(uuid.uuid4())
 
@@ -165,7 +165,7 @@ async def run_stream(
         Yields:
             AgentRunResponseUpdate objects representing the workflow execution progress.
         """
-        input_messages = self._normalize_messages(messages)
+        input_messages = normalize_messages_input(messages)
         thread = thread or self.get_new_thread()
         response_updates: list[AgentRunResponseUpdate] = []
         response_id = str(uuid.uuid4())
@@ -225,28 +225,6 @@ async def _run_stream_impl(
             if update:
                 yield update
 
-    def _normalize_messages(
-        self,
-        messages: str | ChatMessage | Sequence[str] | Sequence[ChatMessage] | None = None,
-    ) -> list[ChatMessage]:
-        """Normalize input messages to a list of ChatMessage objects."""
-        if messages is None:
-            return []
-
-        if isinstance(messages, str):
-            return [ChatMessage(role=Role.USER, contents=[TextContent(text=messages)])]
-
-        if isinstance(messages, ChatMessage):
-            return [messages]
-
-        normalized: list[ChatMessage] = []
-        for msg in messages:
-            if isinstance(msg, str):
-                normalized.append(ChatMessage(role=Role.USER, contents=[TextContent(text=msg)]))
-            elif isinstance(msg, ChatMessage):
-                normalized.append(msg)
-        return normalized
-
     def _convert_workflow_event_to_agent_update(
         self,
         response_id: str,