Python: (samples): adopt AzureOpenAIResponsesClient, reorganize orchestration examples, and fix workflow/orchestration bugs (#3873)

* adopt AzureOpenAIResponsesClient, reorganize orchestration examples, and fix workflow/orchestration bugs

* Updates

* add comment

python/samples/getting_started/orchestrations/concurrent/concurrent_agents.py

@@ -0,0 +1,136 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from typing import Any
+
+from agent_framework import Message
+from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework.orchestrations import ConcurrentBuilder
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Concurrent fan-out/fan-in (agent-only API) with default aggregator
+
+Build a high-level concurrent workflow using ConcurrentBuilder and three domain agents.
+The default dispatcher fans out the same user prompt to all agents in parallel.
+The default aggregator fans in their results and yields output containing
+a list[Message] representing the concatenated conversations from all agents.
+
+Demonstrates:
+- Minimal wiring with ConcurrentBuilder(participants=[...]).build()
+- Fan-out to multiple agents, fan-in aggregation of final ChatMessages
+- Workflow completion when idle with no pending work
+
+Prerequisites:
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure OpenAI access configured for AzureOpenAIResponsesClient (use az login + env vars)
+- Familiarity with Workflow events (WorkflowEvent)
+"""
+
+
+async def main() -> None:
+    # 1) Create three domain agents using AzureOpenAIResponsesClient
+    client = AzureOpenAIResponsesClient(
+        project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    )
+
+    researcher = client.as_agent(
+        instructions=(
+            "You're an expert market and product researcher. Given a prompt, provide concise, factual insights,"
+            " opportunities, and risks."
+        ),
+        name="researcher",
+    )
+
+    marketer = client.as_agent(
+        instructions=(
+            "You're a creative marketing strategist. Craft compelling value propositions and target messaging"
+            " aligned to the prompt."
+        ),
+        name="marketer",
+    )
+
+    legal = client.as_agent(
+        instructions=(
+            "You're a cautious legal/compliance reviewer. Highlight constraints, disclaimers, and policy concerns"
+            " based on the prompt."
+        ),
+        name="legal",
+    )
+
+    # 2) Build a concurrent workflow
+    # Participants are either Agents (type of SupportsAgentRun) or Executors
+    workflow = ConcurrentBuilder(participants=[researcher, marketer, legal]).build()
+
+    # 3) Run with a single prompt and pretty-print the final combined messages
+    events = await workflow.run("We are launching a new budget-friendly electric bike for urban commuters.")
+    outputs = events.get_outputs()
+
+    if outputs:
+        print("===== Final Aggregated Conversation (messages) =====")
+        for output in outputs:
+            messages: list[Message] | Any = output
+            for i, msg in enumerate(messages, start=1):
+                name = msg.author_name if msg.author_name else "user"
+                print(f"{'-' * 60}\n\n{i:02d} [{name}]:\n{msg.text}")
+
+    """
+    Sample Output:
+
+    ===== Final Aggregated Conversation (messages) =====
+    ------------------------------------------------------------
+
+    01 [user]:
+    We are launching a new budget-friendly electric bike for urban commuters.
+    ------------------------------------------------------------
+
+    02 [researcher]:
+    **Insights:**
+
+    - **Target Demographic:** Urban commuters seeking affordable, eco-friendly transport;
+        likely to include students, young professionals, and price-sensitive urban residents.
+    - **Market Trends:** E-bike sales are growing globally, with increasing urbanization,
+        higher fuel costs, and sustainability concerns driving adoption.
+    - **Competitive Landscape:** Key competitors include brands like Rad Power Bikes, Aventon,
+        Lectric, and domestic budget-focused manufacturers in North America, Europe, and Asia.
+    - **Feature Expectations:** Customers expect reliability, ease-of-use, theft protection,
+        lightweight design, sufficient battery range for daily city commutes (typically 25-40 miles),
+        and low-maintenance components.
+
+    **Opportunities:**
+
+    - **First-time Buyers:** Capture newcomers to e-biking by emphasizing affordability, ease of
+        operation, and cost savings vs. public transit/car ownership.
+    ...
+    ------------------------------------------------------------
+
+    03 [marketer]:
+    **Value Proposition:**
+    "Empowering your city commute: Our new electric bike combines affordability, reliability, and
+        sustainable design—helping you conquer urban journeys without breaking the bank."
+
+    **Target Messaging:**
+
+    *For Young Professionals:*
+    ...
+    ------------------------------------------------------------
+
+    04 [legal]:
+    **Constraints, Disclaimers, & Policy Concerns for Launching a Budget-Friendly Electric Bike for Urban Commuters:**
+
+    **1. Regulatory Compliance**
+    - Verify that the electric bike meets all applicable federal, state, and local regulations
+        regarding e-bike classification, speed limits, power output, and safety features.
+    - Ensure necessary certifications (e.g., UL certification for batteries, CE markings if sold internationally) are obtained.
+
+    **2. Product Safety**
+    - Include consumer safety warnings regarding use, battery handling, charging protocols, and age restrictions.
+    ...
+    """  # noqa: E501
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/orchestrations/concurrent/concurrent_builder_tool_approval.py

@@ -0,0 +1,207 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from collections.abc import AsyncIterable
+from typing import Annotated
+
+from agent_framework import (
+    Content,
+    Message,
+    WorkflowEvent,
+    tool,
+)
+from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework.orchestrations import ConcurrentBuilder
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Concurrent Workflow with Tool Approval Requests
+
+This sample demonstrates how to use ConcurrentBuilder with tools that require human
+approval before execution. Multiple agents run in parallel, and any tool requiring
+approval will pause the workflow until the human responds.
+
+This sample works as follows:
+1. A ConcurrentBuilder workflow is created with two agents running in parallel.
+2. Both agents have the same tools, including one requiring approval (execute_trade).
+3. Both agents receive the same task and work concurrently on their respective stocks.
+4. When either agent tries to execute a trade, it triggers an approval request.
+5. The sample simulates human approval and the workflow completes.
+6. Results from both agents are aggregated and output.
+
+Purpose:
+Show how tool call approvals work in parallel execution scenarios where multiple
+agents may independently trigger approval requests.
+
+Demonstrate:
+- Handling multiple approval requests from different agents in concurrent workflows.
+- Handling  during concurrent agent execution.
+- Understanding that approval pauses only the agent that triggered it, not all agents.
+
+Prerequisites:
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- OpenAI or Azure OpenAI configured with the required environment variables.
+- Basic familiarity with ConcurrentBuilder and streaming workflow events.
+"""
+
+
+# 1. Define market data tools (no approval required)
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
+# See:
+# samples/getting_started/tools/function_tool_with_approval.py
+# samples/getting_started/tools/function_tool_with_approval_and_threads.py.
+@tool(approval_mode="never_require")
+def get_stock_price(symbol: Annotated[str, "The stock ticker symbol"]) -> str:
+    """Get the current stock price for a given symbol."""
+    # Mock data for demonstration
+    prices = {"AAPL": 175.50, "GOOGL": 140.25, "MSFT": 378.90, "AMZN": 178.75}
+    price = prices.get(symbol.upper(), 100.00)
+    return f"{symbol.upper()}: ${price:.2f}"
+
+
+@tool(approval_mode="never_require")
+def get_market_sentiment(symbol: Annotated[str, "The stock ticker symbol"]) -> str:
+    """Get market sentiment analysis for a stock."""
+    # Mock sentiment data
+    mock_data = {
+        "AAPL": "Market sentiment for AAPL: Bullish (68% positive mentions in last 24h)",
+        "GOOGL": "Market sentiment for GOOGL: Neutral (50% positive mentions in last 24h)",
+        "MSFT": "Market sentiment for MSFT: Bullish (72% positive mentions in last 24h)",
+        "AMZN": "Market sentiment for AMZN: Bearish (40% positive mentions in last 24h)",
+    }
+    return mock_data.get(symbol.upper(), f"Market sentiment for {symbol.upper()}: Unknown")
+
+
+# 2. Define trading tools (approval required)
+@tool(approval_mode="always_require")
+def execute_trade(
+    symbol: Annotated[str, "The stock ticker symbol"],
+    action: Annotated[str, "Either 'buy' or 'sell'"],
+    quantity: Annotated[int, "Number of shares to trade"],
+) -> str:
+    """Execute a stock trade. Requires human approval due to financial impact."""
+    return f"Trade executed: {action.upper()} {quantity} shares of {symbol.upper()}"
+
+
+@tool(approval_mode="never_require")
+def get_portfolio_balance() -> str:
+    """Get current portfolio balance and available funds."""
+    return "Portfolio: $50,000 invested, $10,000 cash available. Holdings: AAPL, GOOGL, MSFT."
+
+
+def _print_output(event: WorkflowEvent) -> None:
+    if not event.data:
+        raise ValueError("WorkflowEvent has no data")
+
+    if not isinstance(event.data, list) and not all(isinstance(msg, Message) for msg in event.data):
+        raise ValueError("WorkflowEvent data is not a list of Message")
+
+    messages: list[Message] = event.data  # type: ignore
+
+    print("\n" + "-" * 60)
+    print("Workflow completed. Aggregated results from both agents:")
+    for msg in messages:
+        if msg.text:
+            print(f"- {msg.author_name or msg.role}: {msg.text}")
+
+
+async def process_event_stream(stream: AsyncIterable[WorkflowEvent]) -> dict[str, Content] | None:
+    """Process events from the workflow stream to capture human feedback requests."""
+    requests: dict[str, Content] = {}
+    async for event in stream:
+        if event.type == "request_info" and isinstance(event.data, Content):
+            # We are only expecting tool approval requests in this sample
+            requests[event.request_id] = event.data
+        elif event.type == "output":
+            _print_output(event)
+
+    responses: dict[str, Content] = {}
+    if requests:
+        for request_id, request in requests.items():
+            if request.type == "function_approval_request":
+                print(f"\nSimulating human approval for: {request.function_call.name}")  # type: ignore
+                # Create approval response
+                responses[request_id] = request.to_function_approval_response(approved=True)
+
+    return responses if responses else None
+
+
+async def main() -> None:
+    # 3. Create two agents focused on different stocks but with the same tool sets
+    client = AzureOpenAIResponsesClient(
+        project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    )
+
+    microsoft_agent = client.as_agent(
+        name="MicrosoftAgent",
+        instructions=(
+            "You are a personal trading assistant focused on Microsoft (MSFT). "
+            "You manage my portfolio and take actions based on market data."
+        ),
+        tools=[get_stock_price, get_market_sentiment, get_portfolio_balance, execute_trade],
+    )
+
+    google_agent = client.as_agent(
+        name="GoogleAgent",
+        instructions=(
+            "You are a personal trading assistant focused on Google (GOOGL). "
+            "You manage my trades and portfolio based on market conditions."
+        ),
+        tools=[get_stock_price, get_market_sentiment, get_portfolio_balance, execute_trade],
+    )
+
+    # 4. Build a concurrent workflow with both agents
+    # ConcurrentBuilder requires at least 2 participants for fan-out
+    workflow = ConcurrentBuilder(participants=[microsoft_agent, google_agent]).build()
+
+    # 5. Start the workflow - both agents will process the same task in parallel
+    print("Starting concurrent workflow with tool approval...")
+    print("-" * 60)
+
+    # Initiate the first run of the workflow.
+    # Runs are not isolated; state is preserved across multiple calls to run.
+    stream = workflow.run(
+        "Manage my portfolio. Use a max of 5000 dollars to adjust my position using "
+        "your best judgment based on market sentiment. No need to confirm trades with me.",
+        stream=True,
+    )
+
+    pending_responses = await process_event_stream(stream)
+    while pending_responses is not None:
+        # Run the workflow until there is no more human feedback to provide,
+        # in which case this workflow completes.
+        stream = workflow.run(stream=True, responses=pending_responses)
+        pending_responses = await process_event_stream(stream)
+
+    """
+    Sample Output:
+    Starting concurrent workflow with tool approval...
+    ------------------------------------------------------------
+
+    Approval requested for tool: execute_trade
+    Arguments: {"symbol":"MSFT","action":"buy","quantity":13}
+
+    Approval requested for tool: execute_trade
+    Arguments: {"symbol":"GOOGL","action":"buy","quantity":35}
+
+    Simulating human approval for: execute_trade
+
+    Simulating human approval for: execute_trade
+
+    ------------------------------------------------------------
+    Workflow completed. Aggregated results from both agents:
+    - user: Manage my portfolio. Use a max of 5000 dollars to adjust my position using your best judgment based on
+            market sentiment. No need to confirm trades with me.
+    - MicrosoftAgent: I have successfully executed the trade, purchasing 13 shares of Microsoft (MSFT). This action
+                      was based on the positive market sentiment and available funds within the specified limit.
+                      Your portfolio has been adjusted accordingly.
+    - GoogleAgent: I have successfully executed the trade, purchasing 35 shares of GOOGL. If you need further
+                   assistance or any adjustments, feel free to ask!
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/orchestrations/concurrent/concurrent_custom_agent_executors.py

@@ -0,0 +1,180 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from typing import Any
+
+from agent_framework import (
+    Agent,
+    AgentExecutorRequest,
+    AgentExecutorResponse,
+    Executor,
+    Message,
+    WorkflowContext,
+    handler,
+)
+from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework.orchestrations import ConcurrentBuilder
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Concurrent Orchestration with Custom Agent Executors
+
+This sample shows a concurrent fan-out/fan-in pattern using child Executor classes
+that each own their Agent. The executors accept AgentExecutorRequest inputs
+and emit AgentExecutorResponse outputs, which allows reuse of the high-level
+ConcurrentBuilder API and the default aggregator.
+
+Demonstrates:
+- Executors that create their Agent in __init__ (via AzureOpenAIResponsesClient)
+- A @handler that converts AgentExecutorRequest -> AgentExecutorResponse
+- ConcurrentBuilder(participants=[...]) to build fan-out/fan-in
+- Default aggregator returning list[Message] (one user + one assistant per agent)
+- Workflow completion when all participants become idle
+
+Prerequisites:
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure OpenAI configured for AzureOpenAIResponsesClient (az login + required env vars)
+"""
+
+
+class ResearcherExec(Executor):
+    agent: Agent
+
+    def __init__(self, client: AzureOpenAIResponsesClient, id: str = "researcher"):
+        self.agent = client.as_agent(
+            instructions=(
+                "You're an expert market and product researcher. Given a prompt, provide concise, factual insights,"
+                " opportunities, and risks."
+            ),
+            name=id,
+        )
+        super().__init__(id=id)
+
+    @handler
+    async def run(self, request: AgentExecutorRequest, ctx: WorkflowContext[AgentExecutorResponse]) -> None:
+        response = await self.agent.run(request.messages)
+        full_conversation = list(request.messages) + list(response.messages)
+        await ctx.send_message(AgentExecutorResponse(self.id, response, full_conversation=full_conversation))
+
+
+class MarketerExec(Executor):
+    agent: Agent
+
+    def __init__(self, client: AzureOpenAIResponsesClient, id: str = "marketer"):
+        self.agent = client.as_agent(
+            instructions=(
+                "You're a creative marketing strategist. Craft compelling value propositions and target messaging"
+                " aligned to the prompt."
+            ),
+            name=id,
+        )
+        super().__init__(id=id)
+
+    @handler
+    async def run(self, request: AgentExecutorRequest, ctx: WorkflowContext[AgentExecutorResponse]) -> None:
+        response = await self.agent.run(request.messages)
+        full_conversation = list(request.messages) + list(response.messages)
+        await ctx.send_message(AgentExecutorResponse(self.id, response, full_conversation=full_conversation))
+
+
+class LegalExec(Executor):
+    agent: Agent
+
+    def __init__(self, client: AzureOpenAIResponsesClient, id: str = "legal"):
+        self.agent = client.as_agent(
+            instructions=(
+                "You're a cautious legal/compliance reviewer. Highlight constraints, disclaimers, and policy concerns"
+                " based on the prompt."
+            ),
+            name=id,
+        )
+        super().__init__(id=id)
+
+    @handler
+    async def run(self, request: AgentExecutorRequest, ctx: WorkflowContext[AgentExecutorResponse]) -> None:
+        response = await self.agent.run(request.messages)
+        full_conversation = list(request.messages) + list(response.messages)
+        await ctx.send_message(AgentExecutorResponse(self.id, response, full_conversation=full_conversation))
+
+
+async def main() -> None:
+    client = AzureOpenAIResponsesClient(
+        project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    )
+
+    researcher = ResearcherExec(client)
+    marketer = MarketerExec(client)
+    legal = LegalExec(client)
+
+    workflow = ConcurrentBuilder(participants=[researcher, marketer, legal]).build()
+
+    events = await workflow.run("We are launching a new budget-friendly electric bike for urban commuters.")
+    outputs = events.get_outputs()
+
+    if outputs:
+        print("===== Final Aggregated Conversation (messages) =====")
+        messages: list[Message] | Any = outputs[0]  # Get the first (and typically only) output
+        for i, msg in enumerate(messages, start=1):
+            name = msg.author_name if msg.author_name else "user"
+            print(f"{'-' * 60}\n\n{i:02d} [{name}]:\n{msg.text}")
+
+    """
+    Sample Output:
+
+    ===== Final Aggregated Conversation (messages) =====
+    ------------------------------------------------------------
+
+    01 [user]:
+    We are launching a new budget-friendly electric bike for urban commuters.
+    ------------------------------------------------------------
+
+    02 [researcher]:
+    **Insights:**
+
+    - **Target Demographic:** Urban commuters seeking affordable, eco-friendly transport;
+        likely to include students, young professionals, and price-sensitive urban residents.
+    - **Market Trends:** E-bike sales are growing globally, with increasing urbanization,
+        higher fuel costs, and sustainability concerns driving adoption.
+    - **Competitive Landscape:** Key competitors include brands like Rad Power Bikes, Aventon,
+        Lectric, and domestic budget-focused manufacturers in North America, Europe, and Asia.
+    - **Feature Expectations:** Customers expect reliability, ease-of-use, theft protection,
+        lightweight design, sufficient battery range for daily city commutes (typically 25-40 miles),
+        and low-maintenance components.
+
+    **Opportunities:**
+
+    - **First-time Buyers:** Capture newcomers to e-biking by emphasizing affordability, ease of
+        operation, and cost savings vs. public transit/car ownership.
+    ...
+    ------------------------------------------------------------
+
+    03 [marketer]:
+    **Value Proposition:**
+    "Empowering your city commute: Our new electric bike combines affordability, reliability, and
+        sustainable design—helping you conquer urban journeys without breaking the bank."
+
+    **Target Messaging:**
+
+    *For Young Professionals:*
+    ...
+    ------------------------------------------------------------
+
+    04 [legal]:
+    **Constraints, Disclaimers, & Policy Concerns for Launching a Budget-Friendly Electric Bike for Urban Commuters:**
+
+    **1. Regulatory Compliance**
+    - Verify that the electric bike meets all applicable federal, state, and local regulations
+        regarding e-bike classification, speed limits, power output, and safety features.
+    - Ensure necessary certifications (e.g., UL certification for batteries, CE markings if sold internationally) are obtained.
+
+    **2. Product Safety**
+    - Include consumer safety warnings regarding use, battery handling, charging protocols, and age restrictions.
+    ...
+    """  # noqa: E501
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/orchestrations/concurrent/concurrent_custom_aggregator.py

@@ -0,0 +1,128 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from typing import Any
+
+from agent_framework import Message
+from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework.orchestrations import ConcurrentBuilder
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Concurrent Orchestration with Custom Aggregator
+
+Build a concurrent workflow with ConcurrentBuilder that fans out one prompt to
+multiple domain agents and fans in their responses. Override the default
+aggregator with a custom async callback that uses AzureOpenAIResponsesClient.get_response()
+to synthesize a concise, consolidated summary from the experts' outputs.
+The workflow completes when all participants become idle.
+
+Demonstrates:
+- ConcurrentBuilder(participants=[...]).with_aggregator(callback)
+- Fan-out to agents and fan-in at an aggregator
+- Aggregation implemented via an LLM call (client.get_response)
+- Workflow output yielded with the synthesized summary string
+
+Prerequisites:
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure OpenAI configured for AzureOpenAIResponsesClient (az login + required env vars)
+"""
+
+
+async def main() -> None:
+    client = AzureOpenAIResponsesClient(
+        project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    )
+
+    researcher = client.as_agent(
+        instructions=(
+            "You're an expert market and product researcher. Given a prompt, provide concise, factual insights,"
+            " opportunities, and risks."
+        ),
+        name="researcher",
+    )
+    marketer = client.as_agent(
+        instructions=(
+            "You're a creative marketing strategist. Craft compelling value propositions and target messaging"
+            " aligned to the prompt."
+        ),
+        name="marketer",
+    )
+    legal = client.as_agent(
+        instructions=(
+            "You're a cautious legal/compliance reviewer. Highlight constraints, disclaimers, and policy concerns"
+            " based on the prompt."
+        ),
+        name="legal",
+    )
+
+    # Define a custom aggregator callback that uses the chat client to summarize
+    async def summarize_results(results: list[Any]) -> str:
+        # Extract one final assistant message per agent
+        expert_sections: list[str] = []
+        for r in results:
+            try:
+                messages = getattr(r.agent_response, "messages", [])
+                final_text = messages[-1].text if messages and hasattr(messages[-1], "text") else "(no content)"
+                expert_sections.append(f"{getattr(r, 'executor_id', 'expert')}:\n{final_text}")
+            except Exception as e:
+                expert_sections.append(f"{getattr(r, 'executor_id', 'expert')}: (error: {type(e).__name__}: {e})")
+
+        # Ask the model to synthesize a concise summary of the experts' outputs
+        system_msg = Message(
+            "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 = Message("user", text="\n\n".join(expert_sections))
+
+        response = await client.get_response([system_msg, user_msg])
+        # Return the model's final assistant text as the completion result
+        return response.messages[-1].text if response.messages else ""
+
+    # Build with a custom aggregator callback function
+    # - participants([...]) accepts SupportsAgentRun (agents) or Executor instances.
+    #   Each participant becomes a parallel branch (fan-out) from an internal dispatcher.
+    # - with_aggregator(...) overrides the default aggregator:
+    #   • Default aggregator -> returns list[Message] (one user + one assistant per agent)
+    #   • Custom callback    -> return value becomes workflow output (string here)
+    #   The callback can be sync or async; it receives list[AgentExecutorResponse].
+    workflow = ConcurrentBuilder(participants=[researcher, marketer, legal]).with_aggregator(summarize_results).build()
+
+    events = await workflow.run("We are launching a new budget-friendly electric bike for urban commuters.")
+    outputs = events.get_outputs()
+
+    if outputs:
+        print("===== Final Consolidated Output =====")
+        print(outputs[0])  # Get the first (and typically only) output
+
+    """
+    Sample Output:
+
+    ===== Final Consolidated Output =====
+    Urban e-bike demand is rising rapidly due to eco-awareness, urban congestion, and high fuel costs,
+    with market growth projected at a ~10% CAGR through 2030. Key customer concerns are affordability,
+    easy maintenance, convenient charging, compact design, and theft protection. Differentiation opportunities
+    include integrating smart features (GPS, app connectivity), offering subscription or leasing options, and
+    developing portable, space-saving designs. Partnering with local governments and bike shops can boost visibility.
+
+    Risks include price wars eroding margins, regulatory hurdles, battery quality concerns, and heightened expectations
+    for after-sales support. Accurate, substantiated product claims and transparent marketing (with range disclaimers)
+    are essential. All e-bikes must comply with local and federal regulations on speed, wattage, safety certification,
+    and labeling. Clear warranty, safety instructions (especially regarding batteries), and inclusive, accessible
+    marketing are required. For connected features, data privacy policies and user consents are mandatory.
+
+    Effective messaging should target young professionals, students, eco-conscious commuters, and first-time buyers,
+    emphasizing affordability, convenience, and sustainability. Slogan suggestion: “Charge Ahead—City Commutes Made
+    Affordable.” Legal review in each target market, compliance vetting, and robust customer support policies are
+    critical before launch.
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/orchestrations/concurrent/concurrent_request_info.py

@@ -0,0 +1,203 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Sample: Request Info with ConcurrentBuilder
+
+This sample demonstrates using the `.with_request_info()` method to pause a
+ConcurrentBuilder workflow for specific agents, allowing human review and
+modification of individual agent outputs before aggregation.
+
+Purpose:
+Show how to use the request info API that pauses for selected concurrent agents,
+allowing review and steering of their results.
+
+Demonstrate:
+- Configuring request info with `.with_request_info()` for specific agents
+- Reviewing output from individual agents during concurrent execution
+- Injecting human guidance for specific agents before aggregation
+
+Prerequisites:
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure OpenAI configured for AzureOpenAIResponsesClient with required environment variables
+- Authentication via azure-identity (run az login before executing)
+"""
+
+import asyncio
+import os
+from collections.abc import AsyncIterable
+from typing import Any
+
+from agent_framework import (
+    AgentExecutorResponse,
+    Message,
+    WorkflowEvent,
+)
+from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework.orchestrations import AgentRequestInfoResponse, ConcurrentBuilder
+from azure.identity import AzureCliCredential
+
+# Store chat client at module level for aggregator access
+_chat_client: AzureOpenAIResponsesClient | None = None
+
+
+async def aggregate_with_synthesis(results: list[AgentExecutorResponse]) -> Any:
+    """Custom aggregator that synthesizes concurrent agent outputs using an LLM.
+
+    This aggregator extracts the outputs from each parallel agent and uses the
+    chat client to create a unified summary, incorporating any human feedback
+    that was injected into the conversation.
+
+    Args:
+        results: List of responses from all concurrent agents
+
+    Returns:
+        The synthesized summary text
+    """
+    if not _chat_client:
+        return "Error: Chat client not initialized"
+
+    # Extract each agent's final output
+    expert_sections: list[str] = []
+    human_guidance = ""
+
+    for r in results:
+        try:
+            messages = getattr(r.agent_response, "messages", [])
+            final_text = messages[-1].text if messages and hasattr(messages[-1], "text") else "(no content)"
+            expert_sections.append(f"{getattr(r, 'executor_id', 'analyst')}:\n{final_text}")
+
+            # Check for human feedback in the conversation (will be last user message if present)
+            if r.full_conversation:
+                for msg in reversed(r.full_conversation):
+                    if msg.role == "user" and msg.text and "perspectives" not in msg.text.lower():
+                        human_guidance = msg.text
+                        break
+        except Exception:
+            expert_sections.append(f"{getattr(r, 'executor_id', 'analyst')}: (error extracting output)")
+
+    # Build prompt with human guidance if provided
+    guidance_text = f"\n\nHuman guidance: {human_guidance}" if human_guidance else ""
+
+    system_msg = Message(
+        "system",
+        text=(
+            "You are a synthesis expert. Consolidate the following analyst perspectives "
+            "into one cohesive, balanced summary (3-4 sentences). If human guidance is provided, "
+            "prioritize aspects as directed."
+        ),
+    )
+    user_msg = Message("user", text="\n\n".join(expert_sections) + guidance_text)
+
+    response = await _chat_client.get_response([system_msg, user_msg])
+    return response.messages[-1].text if response.messages else ""
+
+
+async def process_event_stream(stream: AsyncIterable[WorkflowEvent]) -> dict[str, AgentRequestInfoResponse] | None:
+    """Process events from the workflow stream to capture human feedback requests."""
+
+    requests: dict[str, AgentExecutorResponse] = {}
+    async for event in stream:
+        if event.type == "request_info" and isinstance(event.data, AgentExecutorResponse):
+            requests[event.request_id] = event.data
+
+        if event.type == "output":
+            # The output of the workflow comes from the aggregator and it's a single string
+            print("\n" + "=" * 60)
+            print("ANALYSIS COMPLETE")
+            print("=" * 60)
+            print("Final synthesized analysis:")
+            print(event.data)
+
+    # Process any requests for human feedback
+    responses: dict[str, AgentRequestInfoResponse] = {}
+    if requests:
+        for request_id, request in requests.items():
+            print("\n" + "-" * 40)
+            print("INPUT REQUESTED")
+            print(
+                f"Agent {request.executor_id} just responded with: '{request.agent_response.text}'. "
+                "Please provide your feedback."
+            )
+            print("-" * 40)
+            if request.full_conversation:
+                print("Conversation context:")
+                recent = (
+                    request.full_conversation[-2:] if len(request.full_conversation) > 2 else request.full_conversation
+                )
+                for msg in recent:
+                    name = msg.author_name or msg.role
+                    text = (msg.text or "")[:150]
+                    print(f"  [{name}]: {text}...")
+                print("-" * 40)
+
+            # Get human input to steer this agent's contribution
+            user_input = input("Your guidance for the analysts (or 'skip' to approve): ")  # noqa: ASYNC250
+            if user_input.lower() == "skip":
+                user_input = AgentRequestInfoResponse.approve()
+            else:
+                user_input = AgentRequestInfoResponse.from_strings([user_input])
+
+            responses[request_id] = user_input
+
+    return responses if responses else None
+
+
+async def main() -> None:
+    global _chat_client
+    _chat_client = AzureOpenAIResponsesClient(
+        project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    )
+
+    # Create agents that analyze from different perspectives
+    technical_analyst = _chat_client.as_agent(
+        name="technical_analyst",
+        instructions=(
+            "You are a technical analyst. When given a topic, provide a technical "
+            "perspective focusing on implementation details, performance, and architecture. "
+            "Keep your analysis to 2-3 sentences."
+        ),
+    )
+
+    business_analyst = _chat_client.as_agent(
+        name="business_analyst",
+        instructions=(
+            "You are a business analyst. When given a topic, provide a business "
+            "perspective focusing on ROI, market impact, and strategic value. "
+            "Keep your analysis to 2-3 sentences."
+        ),
+    )
+
+    user_experience_analyst = _chat_client.as_agent(
+        name="ux_analyst",
+        instructions=(
+            "You are a UX analyst. When given a topic, provide a user experience "
+            "perspective focusing on usability, accessibility, and user satisfaction. "
+            "Keep your analysis to 2-3 sentences."
+        ),
+    )
+
+    # Build workflow with request info enabled and custom aggregator
+    workflow = (
+        ConcurrentBuilder(participants=[technical_analyst, business_analyst, user_experience_analyst])
+        .with_aggregator(aggregate_with_synthesis)
+        # Only enable request info for the technical analyst agent
+        .with_request_info(agents=["technical_analyst"])
+        .build()
+    )
+
+    # Initiate the first run of the workflow.
+    # Runs are not isolated; state is preserved across multiple calls to run.
+    stream = workflow.run("Analyze the impact of large language models on software development.", stream=True)
+
+    pending_responses = await process_event_stream(stream)
+    while pending_responses is not None:
+        # Run the workflow until there is no more human feedback to provide,
+        # in which case this workflow completes.
+        stream = workflow.run(stream=True, responses=pending_responses)
+        pending_responses = await process_event_stream(stream)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/orchestrations/concurrent/concurrent_workflow_as_agent.py

@@ -0,0 +1,89 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework.orchestrations import ConcurrentBuilder
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Build a concurrent workflow orchestration and wrap it as an agent.
+
+This script wires up a fan-out/fan-in workflow using `ConcurrentBuilder`, and then
+invokes the entire orchestration through the `workflow.as_agent(...)` interface so
+downstream coordinators can reuse the orchestration as a single agent.
+
+Demonstrates:
+- Fan-out to multiple agents, fan-in aggregation of final ChatMessages.
+- Reusing the orchestrated workflow as an agent entry point with `workflow.as_agent(...)`.
+- Workflow completion when idle with no pending work
+
+Prerequisites:
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure OpenAI access configured for AzureOpenAIResponsesClient (use az login + env vars)
+- Familiarity with Workflow events (WorkflowEvent with type "output")
+"""
+
+
+def clear_and_redraw(buffers: dict[str, str], agent_order: list[str]) -> None:
+    """Clear terminal and redraw all agent outputs grouped together."""
+    # ANSI escape: clear screen and move cursor to top-left
+    print("\033[2J\033[H", end="")
+    print("===== Concurrent Agent Streaming (Live) =====\n")
+    for name in agent_order:
+        print(f"--- {name} ---")
+        print(buffers.get(name, ""))
+        print()
+    print("", end="", flush=True)
+
+
+async def main() -> None:
+    # 1) Create three domain agents using AzureOpenAIResponsesClient
+    client = AzureOpenAIResponsesClient(
+        project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    )
+
+    researcher = client.as_agent(
+        instructions=(
+            "You're an expert market and product researcher. Given a prompt, provide concise, factual insights,"
+            " opportunities, and risks."
+        ),
+        name="researcher",
+    )
+
+    marketer = client.as_agent(
+        instructions=(
+            "You're a creative marketing strategist. Craft compelling value propositions and target messaging"
+            " aligned to the prompt."
+        ),
+        name="marketer",
+    )
+
+    legal = client.as_agent(
+        instructions=(
+            "You're a cautious legal/compliance reviewer. Highlight constraints, disclaimers, and policy concerns"
+            " based on the prompt."
+        ),
+        name="legal",
+    )
+
+    # 2) Build a concurrent workflow
+    workflow = ConcurrentBuilder(participants=[researcher, marketer, legal]).build()
+
+    # 3) Expose the concurrent workflow as an agent for easy reuse
+    agent = workflow.as_agent(name="ConcurrentWorkflowAgent")
+    prompt = "We are launching a new budget-friendly electric bike for urban commuters."
+
+    agent_response = await agent.run(prompt)
+    print("===== Final Aggregated Response =====\n")
+    for message in agent_response.messages:
+        # The agent_response contains messages from all participants concatenated
+        # into a single message.
+        print(f"{message.author_name}: {message.text}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())