Python: Add Sequential orchestration builder support. Samples. Tests. (#703)

* Add support for the Sequential Builder. Add samples. Add tests

* AgentExecutor: always compute full convo during response

* Upgrade azure-ai-agents ToolOutput to FunctionToolOutput

* Explicit notes around allows types for custom agent executors

python/samples/getting_started/workflow/README.md

@@ -83,6 +83,8 @@ Once comfortable with these, explore the rest of the samples below.
 | Concurrent Orchestration (Custom Agent Executors) | [orchestration/concurrent_custom_agent_executors.py](./orchestration/concurrent_custom_agent_executors.py) | Child executors own ChatAgents; concurrent fan-out/fan-in via ConcurrentBuilder |
 | Magentic Workflow (Multi-Agent) | [orchestration/magentic.py](./orchestration/magentic.py) | Orchestrate multiple agents with Magentic manager and streaming |
 | Magentic + Human Plan Review | [orchestration/magentic_human_plan_update.py](./orchestration/magentic_human_plan_update.py) | Human reviews/updates the plan before execution |
+| Sequential Orchestration (Agents) | [orchestration/sequential_agents.py](./orchestration/sequential_agents.py) | Chain agents sequentially with shared conversation context |
+| Sequential Orchestration (Custom Executor) | [orchestration/sequential_custom_executors.py](./orchestration/sequential_custom_executors.py) | Mix agents with a summarizer that appends a compact summary |
 
 ### parallelism
 | Sample | File | Concepts |
@@ -110,6 +112,13 @@ Once comfortable with these, explore the rest of the samples below.
 Notes
 - Agent-based samples use provider SDKs (Azure/OpenAI, etc.). Ensure credentials are configured, or adapt agents accordingly.
 
+Sequential orchestration uses a few small adapter nodes for plumbing:
+- "input-conversation" normalizes input to `list[ChatMessage]`
+- "to-conversation:<participant>" converts agent responses into the shared conversation
+- "complete" publishes the final `WorkflowCompletedEvent`
+These may appear in event streams (ExecutorInvoke/Completed). They’re analogous to
+concurrent’s dispatcher and aggregator and can be ignored if you only care about agent activity.
+
 ### Environment Variables
 
 - **AzureChatClient**: Set Azure OpenAI environment variables as documented [here](https://github.com/microsoft/agent-framework/blob/main/python/samples/getting_started/chat_client/README.md#environment-variables).  

python/samples/getting_started/workflow/orchestration/sequential_agents.py

@@ -0,0 +1,80 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Any
+
+from agent_framework import ChatMessage, Role
+from agent_framework.azure import AzureChatClient
+from agent_framework.workflow import SequentialBuilder, WorkflowCompletedEvent
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Sequential workflow (agent-focused API) with shared conversation context
+
+Build a high-level sequential workflow using SequentialBuilder and two domain agents.
+The shared conversation (list[ChatMessage]) flows through each participant. Each agent
+appends its assistant message to the context. The final WorkflowCompletedEvent includes
+the final conversation list.
+
+Note on internal adapters:
+- Sequential orchestration includes small adapter nodes for input normalization
+  ("input-conversation"), agent-response conversion ("to-conversation:<participant>"),
+  and completion ("complete"). These may appear as ExecutorInvoke/Completed events in
+  the stream—similar to how concurrent orchestration includes a dispatcher/aggregator.
+  You can safely ignore them when focusing on agent progress.
+
+Prerequisites:
+- Azure OpenAI access configured for AzureChatClient (use az login + env vars)
+"""
+
+
+async def main() -> None:
+    # 1) Create agents
+    chat_client = AzureChatClient(credential=AzureCliCredential())
+
+    writer = chat_client.create_agent(
+        instructions=("You are a concise copywriter. Provide a single, punchy marketing sentence based on the prompt."),
+        name="writer",
+    )
+
+    reviewer = chat_client.create_agent(
+        instructions=("You are a thoughtful reviewer. Give brief feedback on the previous assistant message."),
+        name="reviewer",
+    )
+
+    # 2) Build sequential workflow: writer -> reviewer
+    workflow = SequentialBuilder().participants([writer, reviewer]).build()
+
+    # 3) Run and print final conversation
+    completion: WorkflowCompletedEvent | None = None
+    async for event in workflow.run_stream("Write a tagline for a budget-friendly eBike."):
+        if isinstance(event, WorkflowCompletedEvent):
+            completion = event
+
+    if completion:
+        print("===== Final Conversation =====")
+        messages: list[ChatMessage] | Any = completion.data
+        for i, msg in enumerate(messages, start=1):
+            name = msg.author_name or ("assistant" if msg.role == Role.ASSISTANT else "user")
+            print(f"{'-' * 60}\n{i:02d} [{name}]\n{msg.text}")
+
+    """
+    Sample Output:
+
+    ===== Final Conversation =====
+    ------------------------------------------------------------
+    01 [user]
+    Write a tagline for a budget-friendly eBike.
+    ------------------------------------------------------------
+    02 [writer]
+    Ride farther, spend less—your affordable eBike adventure starts here.
+    ------------------------------------------------------------
+    03 [reviewer]
+    This tagline clearly communicates affordability and the benefit of extended travel, making it
+    appealing to budget-conscious consumers. It has a friendly and motivating tone, though it could
+    be slightly shorter for more punch. Overall, a strong and effective suggestion!
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflow/orchestration/sequential_custom_executors.py

@@ -0,0 +1,91 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Any
+
+from agent_framework import ChatMessage, Role
+from agent_framework.azure import AzureChatClient
+from agent_framework.workflow import Executor, SequentialBuilder, WorkflowCompletedEvent, WorkflowContext, handler
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Sequential workflow mixing agents and a custom summarizer executor
+
+This demonstrates how SequentialBuilder chains participants with a shared
+conversation context (list[ChatMessage]). An agent produces content; a custom
+executor appends a compact summary to the conversation. The final WorkflowCompletedEvent
+contains the complete conversation.
+
+Custom executor contract:
+- Provide at least one @handler accepting list[ChatMessage] and a WorkflowContext[list[ChatMessage]]
+- Emit the updated conversation via ctx.send_message([...])
+
+Note on internal adapters:
+- You may see adapter nodes in the event stream such as "input-conversation",
+  "to-conversation:<participant>", and "complete". These provide consistent typing,
+  conversion of agent responses into the shared conversation, and a single point
+  for completion—similar to concurrent's dispatcher/aggregator.
+
+Prerequisites:
+- Azure OpenAI access configured for AzureChatClient (use az login + env vars)
+"""
+
+
+class Summarizer(Executor):
+    """Simple summarizer: consumes full conversation and appends an assistant summary."""
+
+    @handler
+    async def summarize(self, conversation: list[ChatMessage], ctx: WorkflowContext[list[ChatMessage]]) -> None:
+        users = sum(1 for m in conversation if m.role == Role.USER)
+        assistants = sum(1 for m in conversation if m.role == Role.ASSISTANT)
+        summary = ChatMessage(role=Role.ASSISTANT, text=f"Summary -> users:{users} assistants:{assistants}")
+        await ctx.send_message(list(conversation) + [summary])
+
+
+async def main() -> None:
+    # 1) Create a content agent
+    chat_client = AzureChatClient(credential=AzureCliCredential())
+    content = chat_client.create_agent(
+        instructions="Produce a concise paragraph answering the user's request.",
+        name="content",
+    )
+
+    # 2) Build sequential workflow: content -> summarizer
+    summarizer = Summarizer(id="summarizer")
+    workflow = SequentialBuilder().participants([content, summarizer]).build()
+
+    # 3) Run and print final conversation
+    completion: WorkflowCompletedEvent | None = None
+    async for event in workflow.run_stream("Explain the benefits of budget eBikes for commuters."):
+        if isinstance(event, WorkflowCompletedEvent):
+            completion = event
+
+    if completion:
+        print("===== Final Conversation =====")
+        messages: list[ChatMessage] | Any = completion.data
+        for i, msg in enumerate(messages, start=1):
+            name = msg.author_name or ("assistant" if msg.role == Role.ASSISTANT else "user")
+            print(f"{'-' * 60}\n{i:02d} [{name}]\n{msg.text}")
+
+    """
+    Sample Output:
+
+    ------------------------------------------------------------
+    01 [user]
+    Explain the benefits of budget eBikes for commuters.
+    ------------------------------------------------------------
+    02 [content]
+    Budget eBikes offer commuters an affordable, eco-friendly alternative to cars and public transport.
+    Their electric assistance reduces physical strain and allows riders to cover longer distances quickly,
+    minimizing travel time and fatigue. Budget models are low-cost to maintain and operate, making them accessible
+    for a wider range of people. Additionally, eBikes help reduce traffic congestion and carbon emissions,
+    supporting greener urban environments. Overall, budget eBikes provide cost-effective, efficient, and
+    sustainable transportation for daily commuting needs.
+    ------------------------------------------------------------
+    03 [assistant]
+    Summary -> users:1 assistants:1
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())