Python: [BREAKING] Moved to a single get_response and run API (#3379)

* WIP * big update to new ResponseStream model * fixed tests and typing * fixed tests and typing * fixed tools typevar import * fix * mypy fix * mypy fixes and some cleanup * fix missing quoted names * and client * fix imports agui * fix anthropic override * fix agui * fix ag ui * fix import * fix anthropic types * fix mypy * refactoring * updated typing * fix 3.11 * fixes * redid layering of chat clients and agents * redid layering of chat clients and agents * Fix lint, type, and test issues after rebase - Add @overload decorators to AgentProtocol.run() for type compatibility - Add missing docstring params (middleware, function_invocation_configuration) - Fix TODO format (TD002) by adding author tags - Fix broken observability tests from upstream: - Replace non-existent use_instrumentation with direct instantiation - Replace non-existent use_agent_instrumentation with AgentTelemetryLayer mixin - Fix get_streaming_response to use get_response(stream=True) - Add AgentInitializationError import - Update streaming exception tests to match actual behavior * Fix AgentExecutionException import error in test_agents.py - Replace non-existent AgentExecutionException with AgentRunException * Fix test import and asyncio deprecation issues - Add 'tests' to pythonpath in ag-ui pyproject.toml for utils_test_ag_ui import - Replace deprecated asyncio.get_event_loop().run_until_complete with asyncio.run * Fix azure-ai test failures - Update _prepare_options patching to use correct class path - Fix test_to_azure_ai_agent_tools_web_search_missing_connection to clear env vars * Convert ag-ui utils_test_ag_ui.py to conftest.py - Move test utilities to conftest.py for proper pytest discovery - Update all test imports to use conftest instead of utils_test_ag_ui - Remove old utils_test_ag_ui.py file - Revert pythonpath change in pyproject.toml * fix: use relative imports for ag-ui test utilities * fix agui * Rename Bare*Client to Raw*Client and BaseChatClient - Renamed BareChatClient to BaseChatClient (abstract base class) - Renamed BareOpenAIChatClient to RawOpenAIChatClient - Renamed BareOpenAIResponsesClient to RawOpenAIResponsesClient - Renamed BareAzureAIClient to RawAzureAIClient - Added warning docstrings to Raw* classes about layer ordering - Updated README in samples/getting_started/agents/custom with layer docs - Added test for span ordering with function calling * Fix layer ordering: FunctionInvocationLayer before ChatTelemetryLayer This ensures each inner LLM call gets its own telemetry span, resulting in the correct span sequence: chat -> execute_tool -> chat Updated all production clients and test mocks to use correct ordering: - ChatMiddlewareLayer (first) - FunctionInvocationLayer (second) - ChatTelemetryLayer (third) - BaseChatClient/Raw...Client (fourth) * Remove run_stream usage * Fix conversation_id propagation * Python: Add BaseAgent implementation for Claude Agent SDK (#3509) * Added ClaudeAgent implementation * Updated streaming logic * Small updates * Small update * Fixes * Small fix * Naming improvements * Updated imports * Addressed comments * Updated package versions * Update Claude agent connector layering * fix test and plugin * Store function middleware in invocation layer * Fix telemetry streaming and ag-ui tests * Remove legacy ag-ui tests folder * updates * Remove terminate flag from FunctionInvocationContext, use MiddlewareTermination instead - Remove terminate attribute from FunctionInvocationContext - Add result attribute to MiddlewareTermination to carry function results - FunctionMiddlewarePipeline.execute() now lets MiddlewareTermination propagate - _auto_invoke_function captures context.result in exception before re-raising - _try_execute_function_calls catches MiddlewareTermination and sets should_terminate - Fix handoff middleware to append to chat_client.function_middleware directly - Update tests to use raise MiddlewareTermination instead of context.terminate - Add middleware flow documentation in samples/concepts/tools/README.md - Fix ag-ui to use FunctionMiddlewarePipeline instead of removed create_function_middleware_pipeline * fix: remove references to removed terminate flag in purview tests, add type ignore * fix: move _test_utils.py from package to test folder * fix: call get_final_response() to trigger context provider notification in streaming test * fix: correct broken links in tools README * docs: clarify default middleware behavior in summary table * fix: ensure inner stream result hooks are called when using map()/from_awaitable() * Fix mypy type errors * Address PR review comments on observability.py - Remove TODO comment about unconsumed streams, add explanatory note instead - Remove redundant _close_span cleanup hook (already called in _finalize_stream) - Clarify behavior: cleanup hooks run after stream iteration, if stream is not consumed the span remains open until garbage collected * Remove gen_ai.client.operation.duration from span attributes Duration is a metrics-only attribute per OpenTelemetry semantic conventions. It should be recorded to the histogram but not set as a span attribute. * Remove duration from _get_response_attributes, pass directly to _capture_response Duration is a metrics-only attribute. It's now passed directly to _capture_response instead of being included in the attributes dict that gets set on the span. * Remove redundant _close_span cleanup hook in AgentTelemetryLayer _finalize_stream already calls _close_span() in its finally block, so adding it as a separate cleanup hook is redundant. * Use weakref.finalize to close span when stream is garbage collected If a user creates a streaming response but never consumes it, the cleanup hooks won't run. Now we register a weak reference finalizer that will close the span when the stream object is garbage collected, ensuring spans don't leak in this scenario. * Fix _get_finalizers_from_stream to use _result_hooks attribute Renamed function to _get_result_hooks_from_stream and fixed it to look for the _result_hooks attribute which is the correct name in ResponseStream class. * Add missing asyncio import in test_request_info_mixin.py * Fix leftover merge conflict marker in image_generation sample * Update integration tests * Fix integration tests: increase max_iterations from 1 to 2 Tests with tool_choice options require at least 2 iterations: 1. First iteration to get function call and execute the tool 2. Second iteration to get the final text response With max_iterations=1, streaming tests would return early with only the function call/result but no final text content. * Fix duplicate function call error in conversation-based APIs When using conversation_id (for Responses/Assistants APIs), the server already has the function call message from the previous response. We should only send the new function result message, not all messages including the function call which would cause a duplicate ID error. Fix: When conversation_id is set, only send the last message (the tool result) instead of all response.messages. * Add regression test for conversation_id propagation between tool iterations Port test from PR #3664 with updates for new streaming API pattern. Tests that conversation_id is properly updated in options dict during function invocation loop iterations. * Fix tool_choice=required to return after tool execution When tool_choice is 'required', the user's intent is to force exactly one tool call. After the tool executes, return immediately with the function call and result - don't continue to call the model again. This fixes integration tests that were failing with empty text responses because with tool_choice=required, the model would keep returning function calls instead of text. Also adds regression tests for: - conversation_id propagation between tool iterations (from PR #3664) - tool_choice=required returns after tool execution * Document tool_choice behavior in tools README - Add table explaining tool_choice values (auto, none, required) - Explain why tool_choice=required returns immediately after tool execution - Add code example showing the difference between required and auto - Update flow diagram to show the early return path for tool_choice=required * Fix tool_choice=None behavior - don't default to 'auto' Remove the hardcoded default of 'auto' for tool_choice in ChatAgent init. When tool_choice is not specified (None), it will now not be sent to the API, allowing the API's default behavior to be used. Users who want tool_choice='auto' can still explicitly set it either in default_options or at runtime. Fixes #3585 * Fix tool_choice=none should not remove tools In OpenAI Assistants client, tools were not being sent when tool_choice='none'. This was incorrect - tool_choice='none' means the model won't call tools, but tools should still be available in the request (they may be used later in the conversation). Fixes #3585 * Add test for tool_choice=none preserving tools Adds a regression test to ensure that when tool_choice='none' is set but tools are provided, the tools are still sent to the API. This verifies the fix for #3585. * Fix tool_choice=none should not remove tools in all clients Apply the same fix to OpenAI Responses client and Azure AI client: - OpenAI Responses: Remove else block that popped tool_choice/parallel_tool_calls - Azure AI: Remove tool_choice != 'none' check when adding tools When tool_choice='none', the model won't call tools, but tools should still be sent to the API so they're available for future turns. Also update README to clarify tool_choice=required supports multiple tools. Fixes #3585 * Keep tool_choice even when tools is None Move tool_choice processing outside of the 'if tools' block in OpenAI Responses client so tool_choice is sent to the API even when no tools are provided. * Update test to match new parallel_tool_calls behavior Changed test_prepare_options_removes_parallel_tool_calls_when_no_tools to test_prepare_options_preserves_parallel_tool_calls_when_no_tools to reflect that parallel_tool_calls is now preserved even when no tools are present, consistent with the tool_choice behavior. * Fix ChatMessage API and Role enum usage after rebase - Update ChatMessage instantiation to use keyword args (role=, text=, contents=) - Fix Role enum comparisons to use .value for string comparison - Add created_at to AgentResponse in error handling - Fix AgentResponse.from_updates -> from_agent_run_response_updates - Fix DurableAgentStateMessage.from_chat_message to convert Role enum to string - Add Role import where needed * Fix additional ChatMessage API and method name changes - Fix ChatMessage usage in workflow files (use text= instead of contents= for strings) - Fix AgentResponse.from_updates -> from_agent_run_response_updates in workflow files - Fix test files for ChatMessage and Role enum usage * Fix remaining ChatMessage API usage in test files * Fix more ChatMessage and Role API changes in source and test files - Fix ChatMessage in _magentic.py replan method - Fix Role enum comparison in test assertions - Fix remaining test files with old ChatMessage syntax * Fix ChatMessage and Role API changes across packages - Add Role import where missing - Fix ChatMessage signature: positional args to keyword args (role=, text=, contents=) - Fix Role enum comparisons: .role.value instead of .role string - Fix FinishReason enum usage in ag-ui event converters - Rename AgentResponse.from_updates to from_agent_run_response_updates in ag-ui Fixes API compatibility after Types API Review improvements merge * Fix ChatMessage and Role API changes in github_copilot tests * Fix ChatMessage and Role API changes in redis and github_copilot packages - Fix redis provider: Role enum comparison using .value - Fix redis tests: ChatMessage signature and Role comparisons - Fix github_copilot tests: ChatMessage signature and Role comparisons - Update docstring examples in redis chat message store * Fix ChatMessage and Role API changes in devui package - Fix executor: ChatMessage signature change - Fix conversations: Role enum to string conversion in two places - Fix tests: ChatMessage signatures and Role comparisons * Fix ChatMessage and Role API changes in a2a and lab packages - Fix a2a tests: Role comparisons and ChatMessage signatures - Fix lab tau2 source: Role enum comparison in flip_messages, log_messages, sliding_window - Fix lab tau2 tests: ChatMessage signatures and Role comparisons * Remove duplicate test files from ag-ui/tests (tests are in ag_ui_tests) * Fix ChatMessage and Role API changes across packages After rebasing on upstream/main which merged PR #3647 (Types API Review improvements), fix all packages to use the new API: - ChatMessage: Use keyword args (role=, text=, contents=) instead of positional args - Role: Compare using .value attribute since it's now an enum Packages fixed: - ag-ui: Fixed Role value extraction bugs in _message_adapters.py - anthropic: Fixed ChatMessage and Role comparisons in tests - azure-ai: Fixed Role comparison in _client.py - azure-ai-search: Fixed ChatMessage and Role in source/tests - bedrock: Fixed ChatMessage signatures in tests - chatkit: Fixed ChatMessage and Role in source/tests - copilotstudio: Fixed ChatMessage and Role in tests - declarative: Fixed ChatMessage in _executors_agents.py - mem0: Fixed ChatMessage and Role in source/tests - purview: Fixed ChatMessage in source/tests * Fix mypy errors for ChatMessage and Role API changes - durabletask: Use str() fallback in role value extraction - core: Fix ChatMessage in _orchestrator_helpers.py to use keyword args - core: Add type ignore for _conversation_state.py contents deserialization - ag-ui: Fix type ignore comments (call-overload instead of arg-type) - azure-ai-search: Fix get_role_value type hint to accept Any - lab: Move get_role_value to module level with Any type hint * Improve CI test timeout configuration - Increase job timeout from 10 to 15 minutes - Reduce per-test timeout to 60s (was 900s/300s) - Add --timeout_method thread for better timeout handling - Add --timeout-verbose to see which tests are slow - Reduce retries from 3 to 2 and delay from 10s to 5s This ensures individual test timeouts are shorter than the job timeout, providing better visibility when tests hang. With 60s timeout and 2 retries, worst case per test is ~180s. * Fix ChatMessage API usage in docstrings and source - Fix ChatMessage positional args in docstrings: _serialization.py, _threads.py, _middleware.py - Fix ChatMessage in tau2 runner.py - Fix role comparison in _orchestrator_helpers.py to use .value - Fix role comparison in _group_chat.py docstring example - Fix role assertions in test_durable_entities.py to use .value * Revert tool_choice/parallel_tool_calls changes - must be removed when no tools OpenAI API requires tool_choice and parallel_tool_calls to only be present when tools are specified. Restored the logic that removes these options when there are no tools. - Restored check in _chat_client.py to remove tool_choice and parallel_tool_calls when no tools present - Restored same logic in _responses_client.py - Reverted test to expect the correct behavior * fixed issue in tests * fix: resolve merge conflict markers in ag-ui tests * fix: restructure ag-ui tests and fix Role/FinishReason to use string types * fix: streaming function invocation and middleware termination - Refactor streaming function invocation to use get_final_response() on inner streams - Fix MiddlewareTermination to accept result parameter for passing results - Fix _AutoHandoffMiddleware to use MiddlewareTermination instead of context.terminate - Fix AgentMiddlewareLayer.run() to properly forward function/chat middleware - Remove duplicate middleware registration in AgentMiddlewareLayer.__init__ - Fix exception handling in _auto_invoke_function to properly capture termination - Fix mypy errors in core package - Update tests to use stream=True parameter for unified run API * fix all tests command * Refactor integration tests to use pytest fixtures - Merge testutils.py into conftest.py for azurefunctions integration tests - Merge dt_testutils.py into conftest.py for durabletask integration tests - Convert all integration tests to use fixtures instead of direct imports (fixes ModuleNotFoundError with --import-mode=importlib) - Add sample_helper fixture for azurefunctions tests - Add agent_client_factory and orchestration_helper fixtures for durabletask - Integration tests now skip with descriptive messages when services unavailable - Restructure devui tests into tests/devui/ with proper conftest.py - Add test organization guidelines to CODING_STANDARD.md - Remove __init__.py from test directories per pytest best practices * Fix pytest_collection_modifyitems to only skip integration tests The hook was skipping all tests in the test session, not just integration tests. Now it only skips items in the integration_tests directory. * Fix mem0 tests failing on Python 3.13 Use patch.object on the imported module instead of @patch with string path to ensure the mock takes effect regardless of import timing. * fix mem0 * another attempt for mem0 * fix for mem0 * fix mem0 * Increase worker initialization wait time in durabletask tests Increase from 2 to 8 seconds to allow time for: - Python startup and module imports - Azure OpenAI client creation - Agent registration with DTS worker - Worker connection to DTS This helps prevent test failures in CI where the first tests may run before the worker is fully ready to process requests. * Fix streaming test to use ResponseStream with finalizer The _consume_stream method now expects a ResponseStream that can provide a final AgentResponse via get_final_response(). Update the test to use ResponseStream with AgentResponse.from_updates as the finalizer. * Fix MockToolCallingAgent to use new ResponseStream API and update samples * small updates to run_stream to run * fix sub workflow * temp fix for az func test --------- Co-authored-by: Dmytro Struk <13853051+dmytrostruk@users.noreply.github.com>
2026-06-16 21:04:09 +08:00 · 2026-02-05 21:09:58 +01:00
parent d1205896a1
commit 3dc59c83b5
372 changed files with 11583 additions and 9465 deletions
@@ -52,8 +52,9 @@ async def main():
    last_author: str | None = None

    # Run the workflow with the user's initial message and stream events as they occur.
-    async for event in workflow.run_stream(
-        ChatMessage("user", ["Create a slogan for a new electric SUV that is affordable and fun to drive."])
+    async for event in workflow.run(
+        ChatMessage("user", ["Create a slogan for a new electric SUV that is affordable and fun to drive."]),
+        stream=True,
    ):
        # The outputs of the workflow are whatever the agents produce. So the events are expected to
        # contain `AgentResponseUpdate` from the agents in the workflow.
@@ -84,7 +84,7 @@ async def main():
    )

    first_update = True
-    async for event in workflow.run_stream("hello world"):
+    async for event in workflow.run("hello world", stream=True):
        # The outputs of the workflow are whatever the agents produce. So the events are expected to
        # contain `AgentResponseUpdate` from the agents in the workflow.
        if isinstance(event, WorkflowOutputEvent) and isinstance(event.data, AgentResponseUpdate):
@@ -38,13 +38,15 @@ async def main() -> None:
        )

        # Build the workflow by adding agents directly as edges.
-        # Agents adapt to workflow mode: run_stream() for incremental updates, run() for complete responses.
+        # Agents adapt to workflow mode: run(stream=True) for complete responses, run() for incremental updates.
        workflow = WorkflowBuilder().set_start_executor(writer_agent).add_edge(writer_agent, reviewer_agent).build()

        # Track the last author to format streaming output.
        last_author: str | None = None

-        events = workflow.run_stream("Create a slogan for a new electric SUV that is affordable and fun to drive.")
+        events = workflow.run(
+            "Create a slogan for a new electric SUV that is affordable and fun to drive.", stream=True
+        )
        async for event in events:
            # The outputs of the workflow are whatever the agents produce. So the events are expected to
            # contain `AgentResponseUpdate` from the agents in the workflow.
@@ -118,8 +118,8 @@ async def main() -> None:
        .build()
    )

-    events = workflow.run_stream(
-        "Create quick workspace wellness tips for a remote analyst working across two monitors."
+    events = workflow.run(
+        "Create quick workspace wellness tips for a remote analyst working across two monitors.", stream=True
    )

    # Track the last author to format streaming output.
@@ -39,13 +39,13 @@ async def main():

    # Build the workflow using the fluent builder.
    # Set the start node and connect an edge from writer to reviewer.
-    # Agents adapt to workflow mode: run_stream() for incremental updates, run() for complete responses.
+    # Agents adapt to workflow mode: run(stream=True) for incremental updates, run() for complete responses.
    workflow = WorkflowBuilder().set_start_executor(writer_agent).add_edge(writer_agent, reviewer_agent).build()

    # Track the last author to format streaming output.
    last_author: str | None = None

-    events = workflow.run_stream("Create a slogan for a new electric SUV that is affordable and fun to drive.")
+    events = workflow.run("Create a slogan for a new electric SUV that is affordable and fun to drive.", stream=True)
    async for event in events:
        # The outputs of the workflow are whatever the agents produce. So the events are expected to
        # contain `AgentResponseUpdate` from the agents in the workflow.
@@ -0,0 +1,325 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import json
+from dataclasses import dataclass, field
+from typing import Annotated
+
+from agent_framework import (
+    AgentExecutorRequest,
+    AgentExecutorResponse,
+    AgentResponse,
+    AgentRunUpdateEvent,
+    ChatAgent,
+    ChatMessage,
+    Executor,
+    FunctionCallContent,
+    FunctionResultContent,
+    RequestInfoEvent,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowOutputEvent,
+    handler,
+    response_handler,
+    tool,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+from pydantic import Field
+from typing_extensions import Never
+
+"""
+Sample: Tool-enabled agents with human feedback
+
+Pipeline layout:
+writer_agent (uses Azure OpenAI tools) -> Coordinator -> writer_agent
+-> Coordinator -> final_editor_agent -> Coordinator -> output
+
+The writer agent calls tools to gather product facts before drafting copy. A custom executor
+packages the draft and emits a RequestInfoEvent so a human can comment, then replays the human
+guidance back into the conversation before the final editor agent produces the polished output.
+
+Demonstrates:
+- Attaching Python function tools to an agent inside a workflow.
+- Capturing the writer's output for human review.
+- Streaming AgentRunUpdateEvent updates alongside human-in-the-loop pauses.
+
+Prerequisites:
+- Azure OpenAI configured for AzureOpenAIChatClient with required environment variables.
+- Authentication via azure-identity. Run `az login` before executing.
+"""
+
+
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
+@tool(approval_mode="never_require")
+def fetch_product_brief(
+    product_name: Annotated[str, Field(description="Product name to look up.")],
+) -> str:
+    """Return a marketing brief for a product."""
+    briefs = {
+        "lumenx desk lamp": (
+            "Product: LumenX Desk Lamp\n"
+            "- Three-point adjustable arm with 270° rotation.\n"
+            "- Custom warm-to-neutral LED spectrum (2700K-4000K).\n"
+            "- USB-C charging pad integrated in the base.\n"
+            "- Designed for home offices and late-night study sessions."
+        )
+    }
+    return briefs.get(product_name.lower(), f"No stored brief for '{product_name}'.")
+
+
+@tool(approval_mode="never_require")
+def get_brand_voice_profile(
+    voice_name: Annotated[str, Field(description="Brand or campaign voice to emulate.")],
+) -> str:
+    """Return guidance for the requested brand voice."""
+    voices = {
+        "lumenx launch": (
+            "Voice guidelines:\n"
+            "- Friendly and modern with concise sentences.\n"
+            "- Highlight practical benefits before aesthetics.\n"
+            "- End with an invitation to imagine the product in daily use."
+        )
+    }
+    return voices.get(voice_name.lower(), f"No stored voice profile for '{voice_name}'.")
+
+
+@dataclass
+class DraftFeedbackRequest:
+    """Payload sent for human review."""
+
+    prompt: str = ""
+    draft_text: str = ""
+    conversation: list[ChatMessage] = field(default_factory=list)  # type: ignore[reportUnknownVariableType]
+
+
+class Coordinator(Executor):
+    """Bridge between the writer agent, human feedback, and final editor."""
+
+    def __init__(self, id: str, writer_id: str, final_editor_id: str) -> None:
+        super().__init__(id)
+        self.writer_id = writer_id
+        self.final_editor_id = final_editor_id
+
+    @handler
+    async def on_writer_response(
+        self,
+        draft: AgentExecutorResponse,
+        ctx: WorkflowContext[Never, AgentResponse],
+    ) -> None:
+        """Handle responses from the other two agents in the workflow."""
+        if draft.executor_id == self.final_editor_id:
+            # Final editor response; yield output directly.
+            await ctx.yield_output(draft.agent_response)
+            return
+
+        # Writer agent response; request human feedback.
+        # Preserve the full conversation so the final editor
+        # can see tool traces and the initial prompt.
+        conversation: list[ChatMessage]
+        if draft.full_conversation is not None:
+            conversation = list(draft.full_conversation)
+        else:
+            conversation = list(draft.agent_response.messages)
+        draft_text = draft.agent_response.text.strip()
+        if not draft_text:
+            draft_text = "No draft text was produced."
+
+        prompt = (
+            "Review the draft from the writer and provide a short directional note "
+            "(tone tweaks, must-have detail, target audience, etc.). "
+            "Keep it under 30 words."
+        )
+        await ctx.request_info(
+            request_data=DraftFeedbackRequest(prompt=prompt, draft_text=draft_text, conversation=conversation),
+            response_type=str,
+        )
+
+    @response_handler
+    async def on_human_feedback(
+        self,
+        original_request: DraftFeedbackRequest,
+        feedback: str,
+        ctx: WorkflowContext[AgentExecutorRequest],
+    ) -> None:
+        note = feedback.strip()
+        if note.lower() == "approve":
+            # Human approved the draft as-is; forward it unchanged.
+            await ctx.send_message(
+                AgentExecutorRequest(
+                    messages=original_request.conversation
+                    + [ChatMessage("user", text="The draft is approved as-is.")],
+                    should_respond=True,
+                ),
+                target_id=self.final_editor_id,
+            )
+            return
+
+        # Human provided feedback; prompt the writer to revise.
+        conversation: list[ChatMessage] = list(original_request.conversation)
+        instruction = (
+            "A human reviewer shared the following guidance:\n"
+            f"{note or 'No specific guidance provided.'}\n\n"
+            "Rewrite the draft from the previous assistant message into a polished final version. "
+            "Keep the response under 120 words and reflect any requested tone adjustments."
+        )
+        conversation.append(ChatMessage("user", text=instruction))
+        await ctx.send_message(
+            AgentExecutorRequest(messages=conversation, should_respond=True), target_id=self.writer_id
+        )
+
+
+def create_writer_agent() -> ChatAgent:
+    """Creates a writer agent with tools."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        name="writer_agent",
+        instructions=(
+            "You are a marketing writer. Call the available tools before drafting copy so you are precise. "
+            "Always call both tools once before drafting. Summarize tool outputs as bullet points, then "
+            "produce a 3-sentence draft."
+        ),
+        tools=[fetch_product_brief, get_brand_voice_profile],
+        tool_choice="required",
+    )
+
+
+def create_final_editor_agent() -> ChatAgent:
+    """Creates a final editor agent."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        name="final_editor_agent",
+        instructions=(
+            "You are an editor who polishes marketing copy after human approval. "
+            "Correct any legal or factual issues. Return the final version even if no changes are made. "
+        ),
+    )
+
+
+def display_agent_run_update(event: AgentRunUpdateEvent, last_executor: str | None) -> None:
+    """Display an AgentRunUpdateEvent in a readable format."""
+    printed_tool_calls: set[str] = set()
+    printed_tool_results: set[str] = set()
+    executor_id = event.executor_id
+    update = event.data
+    # Extract and print any new tool calls or results from the update.
+    function_calls = [c for c in update.contents if isinstance(c, FunctionCallContent)]  # type: ignore[union-attr]
+    function_results = [c for c in update.contents if isinstance(c, FunctionResultContent)]  # type: ignore[union-attr]
+    if executor_id != last_executor:
+        if last_executor is not None:
+            print()
+        print(f"{executor_id}:", end=" ", flush=True)
+        last_executor = executor_id
+    # Print any new tool calls before the text update.
+    for call in function_calls:
+        if call.call_id in printed_tool_calls:
+            continue
+        printed_tool_calls.add(call.call_id)
+        args = call.arguments
+        args_preview = json.dumps(args, ensure_ascii=False) if isinstance(args, dict) else (args or "").strip()
+        print(
+            f"\n{executor_id} [tool-call] {call.name}({args_preview})",
+            flush=True,
+        )
+        print(f"{executor_id}:", end=" ", flush=True)
+    # Print any new tool results before the text update.
+    for result in function_results:
+        if result.call_id in printed_tool_results:
+            continue
+        printed_tool_results.add(result.call_id)
+        result_text = result.result
+        if not isinstance(result_text, str):
+            result_text = json.dumps(result_text, ensure_ascii=False)
+        print(
+            f"\n{executor_id} [tool-result] {result.call_id}: {result_text}",
+            flush=True,
+        )
+        print(f"{executor_id}:", end=" ", flush=True)
+    # Finally, print the text update.
+    print(update, end="", flush=True)
+
+
+async def main() -> None:
+    """Run the workflow and bridge human feedback between two agents."""
+
+    # Build the workflow.
+    workflow = (
+        WorkflowBuilder()
+        .register_agent(create_writer_agent, name="writer_agent")
+        .register_agent(create_final_editor_agent, name="final_editor_agent")
+        .register_executor(
+            lambda: Coordinator(
+                id="coordinator",
+                writer_id="writer_agent",
+                final_editor_id="final_editor_agent",
+            ),
+            name="coordinator",
+        )
+        .set_start_executor("writer_agent")
+        .add_edge("writer_agent", "coordinator")
+        .add_edge("coordinator", "writer_agent")
+        .add_edge("final_editor_agent", "coordinator")
+        .add_edge("coordinator", "final_editor_agent")
+        .build()
+    )
+
+    # Switch to turn on agent run update display.
+    # By default this is off to reduce clutter during human input.
+    display_agent_run_update_switch = False
+
+    print(
+        "Interactive mode. When prompted, provide a short feedback note for the editor.",
+        flush=True,
+    )
+
+    pending_responses: dict[str, str] | None = None
+    completed = False
+    initial_run = True
+
+    while not completed:
+        last_executor: str | None = None
+        if initial_run:
+            stream = workflow.run(
+                "Create a short launch blurb for the LumenX desk lamp. Emphasize adjustability and warm lighting.",
+                stream=True,
+            )
+            initial_run = False
+        elif pending_responses is not None:
+            stream = workflow.send_responses_streaming(pending_responses)
+            pending_responses = None
+        else:
+            break
+
+        requests: list[tuple[str, DraftFeedbackRequest]] = []
+
+        async for event in stream:
+            if isinstance(event, AgentRunUpdateEvent) and display_agent_run_update_switch:
+                display_agent_run_update(event, last_executor)
+            if isinstance(event, RequestInfoEvent) and isinstance(event.data, DraftFeedbackRequest):
+                # Stash the request so we can prompt the human after the stream completes.
+                requests.append((event.request_id, event.data))
+                last_executor = None
+            elif isinstance(event, WorkflowOutputEvent):
+                last_executor = None
+                response = event.data
+                print("\n===== Final output =====")
+                final_text = getattr(response, "text", str(response))
+                print(final_text.strip())
+                completed = True
+
+        if requests and not completed:
+            responses: dict[str, str] = {}
+            for request_id, request in requests:
+                print("\n----- Writer draft -----")
+                print(request.draft_text.strip())
+                print("\nProvide guidance for the editor (or 'approve' to accept the draft).")
+                answer = input("Human feedback: ").strip()  # noqa: ASYNC250
+                if answer.lower() == "exit":
+                    print("Exiting...")
+                    return
+                responses[request_id] = answer
+            pending_responses = responses
+
+    print("Workflow complete.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -85,7 +85,7 @@ async def main() -> None:
        workflow_agent = workflow.as_agent(name="MagenticWorkflowAgent")

        last_response_id: str | None = None
-        async for update in workflow_agent.run_stream(task):
+        async for update in workflow_agent.run(task, stream=True):
            # Fallback for any other events with text
            if last_response_id != update.response_id:
                if last_response_id is not None:
@@ -4,8 +4,9 @@ import asyncio
 import json
 from typing import Annotated, Any

-from agent_framework import SequentialBuilder, tool
+from agent_framework import tool
 from agent_framework.openai import OpenAIChatClient
+from agent_framework.orchestrations import SequentialBuilder
 from pydantic import Field

 """
@@ -17,7 +18,7 @@ through a workflow exposed via .as_agent() to @tool functions using the **kwargs
 Key Concepts:
 - Build a workflow using SequentialBuilder (or any builder pattern)
 - Expose the workflow as a reusable agent via workflow.as_agent()
- Pass custom context as kwargs when invoking workflow_agent.run() or run_stream()
+- Pass custom context as kwargs when invoking workflow_agent.run()
 - kwargs are stored in State and propagated to all agent invocations
 - @tool functions receive kwargs via **kwargs parameter

@@ -121,12 +122,12 @@ async def main() -> None:
    print("-" * 70)

    # Run workflow agent with kwargs - these will flow through to tools
-    # Note: kwargs are passed to workflow_agent.run_stream() just like workflow.run_stream()
+    # Note: kwargs are passed to workflow.run()
    print("\n===== Streaming Response =====")
-    async for update in workflow_agent.run_stream(
+    async for update in workflow_agent.run(
        "Please get my user data and then call the users API endpoint.",
-        custom_data=custom_data,
-        user_token=user_token,
+        additional_function_arguments={"custom_data": custom_data, "user_token": user_token},
+        stream=True,
    ):
        if update.text:
            print(update.text, end="", flush=True)
@@ -251,10 +251,10 @@ async def run_interactive_session(
        else:
            if initial_message:
                print(f"\nStarting workflow with brief: {initial_message}\n")
-                event_stream = workflow.run_stream(message=initial_message)
+                event_stream = workflow.run(message=initial_message, stream=True)
            elif checkpoint_id:
                print("\nStarting workflow from checkpoint...\n")
-                event_stream = workflow.run_stream(checkpoint_id=checkpoint_id)
+                event_stream = workflow.run(checkpoint_id=checkpoint_id, stream=True)
            else:
                raise ValueError("Either initial_message or checkpoint_id must be provided")

@@ -119,9 +119,9 @@ async def main():
        # Start from checkpoint or fresh execution
        print(f"\n** Workflow {workflow.id} started **")
        event_stream = (
-            workflow.run_stream(message=10)
+            workflow.run(message=10, stream=True)
            if latest_checkpoint is None
-            else workflow.run_stream(checkpoint_id=latest_checkpoint.checkpoint_id)
+            else workflow.run(checkpoint_id=latest_checkpoint.checkpoint_id, stream=True)
        )

        output: str | None = None
@@ -39,7 +39,7 @@ Scenario:
 6. Workflow continues from the saved state.

 Pattern:
- Step 1: workflow.run_stream(checkpoint_id=...) to restore checkpoint and pending requests.
+- Step 1: workflow.run(checkpoint_id=..., stream=True) to restore checkpoint and pending requests.
 - Step 2: workflow.send_responses_streaming(responses) to supply human replies and approvals.
 - Two-step approach is required because send_responses_streaming does not accept checkpoint_id.

@@ -190,10 +190,10 @@ async def run_until_user_input_needed(

    if initial_message:
        print(f"\nStarting workflow with: {initial_message}\n")
-        event_stream = workflow.run_stream(message=initial_message)  # type: ignore[attr-defined]
+        event_stream = workflow.run(message=initial_message, stream=True)  # type: ignore[attr-defined]
    elif checkpoint_id:
        print(f"\nResuming workflow from checkpoint: {checkpoint_id}\n")
-        event_stream = workflow.run_stream(checkpoint_id=checkpoint_id)  # type: ignore[attr-defined]
+        event_stream = workflow.run(checkpoint_id=checkpoint_id, stream=True)  # type: ignore[attr-defined]
    else:
        raise ValueError("Must provide either initial_message or checkpoint_id")

@@ -257,7 +257,7 @@ async def resume_with_responses(
    # Step 1: Restore the checkpoint to load pending requests into memory
    # The checkpoint restoration re-emits pending RequestInfoEvents
    restored_requests: list[RequestInfoEvent] = []
-    async for event in workflow.run_stream(checkpoint_id=latest_checkpoint.checkpoint_id):  # type: ignore[attr-defined]
+    async for event in workflow.run(checkpoint_id=latest_checkpoint.checkpoint_id, stream=True):  # type: ignore[attr-defined]
        if isinstance(event, RequestInfoEvent):
            restored_requests.append(event)
            if isinstance(event.data, HandoffAgentUserRequest):
@@ -334,7 +334,7 @@ async def main() -> None:
    print("\n=== Stage 1: run until sub-workflow requests human review ===")

    request_id: str | None = None
-    async for event in workflow.run_stream("Contoso Gadget Launch"):
+    async for event in workflow.run("Contoso Gadget Launch", stream=True):
        if isinstance(event, RequestInfoEvent) and request_id is None:
            request_id = event.request_id
            print(f"Captured review request id: {request_id}")
@@ -365,7 +365,7 @@ async def main() -> None:
    workflow2 = build_parent_workflow(storage)

    request_info_event: RequestInfoEvent | None = None
-    async for event in workflow2.run_stream(checkpoint_id=resume_checkpoint.checkpoint_id):
+    async for event in workflow2.run(checkpoint_id=resume_checkpoint.checkpoint_id, stream=True):
        if isinstance(event, RequestInfoEvent):
            request_info_event = event

@@ -5,11 +5,11 @@ Sample: Workflow as Agent with Checkpointing

 Purpose:
 This sample demonstrates how to use checkpointing with a workflow wrapped as an agent.
-It shows how to enable checkpoint storage when calling agent.run() or agent.run_stream(),
+It shows how to enable checkpoint storage when calling agent.run(),
 allowing workflow execution state to be persisted and potentially resumed.

 What you learn:
- How to pass checkpoint_storage to WorkflowAgent.run() and run_stream()
+- How to pass checkpoint_storage to WorkflowAgent.run()
 - How checkpoints are created during workflow-as-agent execution
 - How to combine thread conversation history with workflow checkpointing
 - How to resume a workflow-as-agent from a checkpoint
@@ -147,7 +147,7 @@ async def streaming_with_checkpoints() -> None:
    print("[assistant]: ", end="", flush=True)

    # Stream with checkpointing
-    async for update in agent.run_stream(query, checkpoint_storage=checkpoint_storage):
+    async for update in agent.run(query, checkpoint_storage=checkpoint_storage, stream=True):
        if update.text:
            print(update.text, end="", flush=True)

@@ -18,10 +18,10 @@ Sample: Sub-Workflow kwargs Propagation

 This sample demonstrates how custom context (kwargs) flows from a parent workflow
 through to agents in sub-workflows. When you pass kwargs to the parent workflow's
-run_stream() or run(), they automatically propagate to nested sub-workflows.
+run(), they automatically propagate to nested sub-workflows.

 Key Concepts:
- kwargs passed to parent workflow.run_stream() propagate to sub-workflows
+- kwargs passed to parent workflow.run() propagate to sub-workflows
 - Sub-workflow agents receive the same kwargs as the parent workflow
 - Works with nested WorkflowExecutor compositions at any depth
 - Useful for passing authentication tokens, configuration, or request context
@@ -123,8 +123,9 @@ async def main() -> None:

    # Run the OUTER workflow with kwargs
    # These kwargs will automatically propagate to the inner sub-workflow
-    async for event in outer_workflow.run_stream(
+    async for event in outer_workflow.run(
        "Please fetch my profile data and then call the users service.",
+        stream=True,
        user_token=user_token,
        service_config=service_config,
    ):
@@ -302,7 +302,7 @@ async def main() -> None:
    # Execute the workflow
    for email in test_emails:
        print(f"\n🚀 Processing email to '{email.recipient}'")
-        async for event in workflow.run_stream(email):
+        async for event in workflow.run(email, stream=True):
            if isinstance(event, WorkflowOutputEvent):
                print(f"🎉 Final result for '{email.recipient}': {'Delivered' if event.data else 'Blocked'}")

@@ -276,7 +276,7 @@ async def main() -> None:
        email = "Hello team, here are the updates for this week..."

    # Print outputs and database events from streaming
-    async for event in workflow.run_stream(email):
+    async for event in workflow.run(email, stream=True):
        if isinstance(event, DatabaseEvent):
            print(f"{event}")
        elif isinstance(event, WorkflowOutputEvent):
@@ -16,7 +16,7 @@ from typing_extensions import Never
 Sample: Sequential workflow with streaming.

 Two custom executors run in sequence. The first converts text to uppercase,
-the second reverses the text and completes the workflow. The run_stream loop prints events as they occur.
+the second reverses the text and completes the workflow. The streaming run loop prints events as they occur.

 Purpose:
 Show how to define explicit Executor classes with @handler methods, wire them in order with
@@ -75,7 +75,7 @@ async def main() -> None:
    # Step 2: Stream events for a single input.
    # The stream will include executor invoke and completion events, plus workflow outputs.
    outputs: list[str] = []
-    async for event in workflow.run_stream("hello world"):
+    async for event in workflow.run("hello world", stream=True):
        print(f"Event: {event}")
        if isinstance(event, WorkflowOutputEvent):
            outputs.append(cast(str, event.data))
@@ -9,7 +9,7 @@ from typing_extensions import Never
 Sample: Foundational sequential workflow with streaming using function-style executors.

 Two lightweight steps run in order. The first converts text to uppercase.
-The second reverses the text and yields the workflow output. Events are printed as they arrive from run_stream.
+The second reverses the text and yields the workflow output. Events are printed as they arrive from a streaming run.

 Purpose:
 Show how to declare executors with the @executor decorator, connect them with WorkflowBuilder,
@@ -64,7 +64,7 @@ async def main():
    )

    # Step 2: Run the workflow and stream events in real time.
-    async for event in workflow.run_stream("hello world"):
+    async for event in workflow.run("hello world", stream=True):
        # You will see executor invoke and completion events as the workflow progresses.
        print(f"Event: {event}")
        if isinstance(event, WorkflowOutputEvent):
@@ -142,7 +142,7 @@ async def main():

    # Step 2: Run the workflow and print the events.
    iterations = 0
-    async for event in workflow.run_stream(NumberSignal.INIT):
+    async for event in workflow.run(NumberSignal.INIT, stream=True):
        if isinstance(event, ExecutorCompletedEvent) and event.executor_id == "guess_number":
            iterations += 1
        print(f"Event: {event}")
@@ -13,7 +13,7 @@ to demonstrate mid-execution cancellation using asyncio tasks.

 Purpose:
 Show how to cancel a running workflow by wrapping it in an asyncio.Task. This pattern
-works with both workflow.run() and workflow.run_stream(). Useful for implementing
+works with both workflow.run() stream=True and stream=False. Useful for implementing
 timeouts, graceful shutdown, or A2A executors that need cancellation support.

 Prerequisites:
@@ -256,7 +256,7 @@ async def main() -> None:
            pending_request_id = None
        else:
            # Start workflow
-            stream = workflow.run_stream(user_input)
+            stream = workflow.run(user_input, stream=True)

        async for event in stream:
            if isinstance(event, WorkflowOutputEvent):
@@ -192,7 +192,7 @@ async def main() -> None:
    # Example input
    task = "What is the weather like in Seattle and how does it compare to the average for this time of year?"

-    async for event in workflow.run_stream(task):
+    async for event in workflow.run(task, stream=True):
        if isinstance(event, WorkflowOutputEvent):
            print(f"{event.data}", end="", flush=True)

@@ -68,7 +68,7 @@ Session Complete
 1. Create an Azure OpenAI chat client
 2. Create an agent with instructions and function tools
 3. Register the agent with the workflow factory
-4. Load the workflow YAML and run it with `run_stream()`
+4. Load the workflow YAML and run it with `run()` and `stream=True`

 ```python
 # Create the agent with tools
@@ -85,6 +85,6 @@ factory.register_agent("MenuAgent", menu_agent)

 # Load and run the workflow
 workflow = factory.create_workflow_from_yaml_path(workflow_path)
-async for event in workflow.run_stream(inputs={"userInput": "What is the soup of the day?"}):
+async for event in workflow.run(inputs={"userInput": "What is the soup of the day?"}, stream=True):
    ...
 ```
@@ -92,7 +92,7 @@ async def main():
            response = ExternalInputResponse(user_input=user_input)
            stream = workflow.send_responses_streaming({pending_request_id: response})
        else:
-            stream = workflow.run_stream({"userInput": user_input})
+            stream = workflow.run({"userInput": user_input}, stream=True)

        pending_request_id = None
        first_response = True
@@ -21,11 +21,11 @@ from agent_framework_declarative._workflows._handlers import TextOutputEvent


 async def run_with_streaming(workflow: Workflow) -> None:
-    """Demonstrate streaming workflow execution with run_stream()."""
-    print("\n=== Streaming Execution (run_stream) ===")
+    """Demonstrate streaming workflow execution."""
+    print("\n=== Streaming Execution ===")
    print("-" * 40)

-    async for event in workflow.run_stream({}):
+    async for event in workflow.run({}, stream=True):
        # WorkflowOutputEvent wraps the actual output data
        if isinstance(event, WorkflowOutputEvent):
            data = event.data
@@ -84,7 +84,7 @@ async def main() -> None:
    # Pass a simple string input - like .NET
    product = "An eco-friendly stainless steel water bottle that keeps drinks cold for 24 hours."

-    async for event in workflow.run_stream(product):
+    async for event in workflow.run(product, stream=True):
        if isinstance(event, WorkflowOutputEvent):
            print(f"{event.data}", end="", flush=True)

@@ -43,7 +43,7 @@ When reviewing student work:
 2. Gently point out errors without giving away the answer
 3. Ask guiding questions to help them discover mistakes
 4. Provide hints that lead toward understanding
-5. When the student demonstrates clear understanding, respond with "CONGRATULATIONS" 
+5. When the student demonstrates clear understanding, respond with "CONGRATULATIONS"
   followed by a summary of what they learned

 Focus on building understanding, not just getting the right answer."""
@@ -81,7 +81,7 @@ async def main() -> None:
    print("Student-Teacher Math Coaching Session")
    print("=" * 50)

-    async for event in workflow.run_stream("How would you compute the value of PI?"):
+    async for event in workflow.run("How would you compute the value of PI?", stream=True):
        if isinstance(event, WorkflowOutputEvent):
            print(f"{event.data}", flush=True, end="")

@@ -204,8 +204,9 @@ async def main() -> None:

    # Initiate the first run of the workflow.
    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
-    stream = workflow.run_stream(
-        "Create a short launch blurb for the LumenX desk lamp. Emphasize adjustability and warm lighting."
+    stream = workflow.run(
+        "Create a short launch blurb for the LumenX desk lamp. Emphasize adjustability and warm lighting.",
+        stream=True,
    )

    pending_responses = await process_event_stream(stream)
@@ -188,7 +188,7 @@ async def main() -> None:

    # Initiate the first run of the workflow.
    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
-    stream = workflow.run_stream("Analyze the impact of large language models on software development.")
+    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:
@@ -151,9 +151,10 @@ async def main() -> None:

    # Initiate the first run of the workflow.
    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
-    stream = workflow.run_stream(
+    stream = workflow.run(
        "Discuss how our team should approach adopting AI tools for productivity. "
-        "Consider benefits, risks, and implementation strategies."
+        "Consider benefits, risks, and implementation strategies.",
+        stream=True,
    )

    pending_responses = await process_event_stream(stream)
@@ -36,7 +36,7 @@ Show how to integrate a human step in the middle of an LLM workflow by using
 Demonstrate:
 - Alternating turns between an AgentExecutor and a human, driven by events.
 - Using Pydantic response_format to enforce structured JSON output from the agent instead of regex parsing.
- Driving the loop in application code with run_stream and responses parameter.
+- Driving the loop in application code with run and responses parameter.

 Prerequisites:
 - Azure OpenAI configured for AzureOpenAIChatClient with required environment variables.
@@ -206,7 +206,7 @@ async def main() -> None:

    # Initiate the first run of the workflow.
    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
-    stream = workflow.run_stream("start")
+    stream = workflow.run("start", stream=True)

    pending_responses = await process_event_stream(stream)
    while pending_responses is not None:
@@ -126,7 +126,7 @@ async def main() -> None:

    # Initiate the first run of the workflow.
    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
-    stream = workflow.run_stream("Write a brief introduction to artificial intelligence.")
+    stream = workflow.run("Write a brief introduction to artificial intelligence.", stream=True)

    pending_responses = await process_event_stream(stream)
    while pending_responses is not None:
@@ -91,7 +91,7 @@ async def main() -> None:

    print("Running workflow with executor I/O observation...\n")

-    async for event in workflow.run_stream("hello world"):
+    async for event in workflow.run("hello world", stream=True):
        if isinstance(event, ExecutorInvokedEvent):
            # The input message received by the executor is in event.data
            print(f"[INVOKED] {event.executor_id}")
@@ -0,0 +1,145 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import json
+from typing import cast
+
+from agent_framework import (
+    AgentRunUpdateEvent,
+    ChatAgent,
+    ChatMessage,
+    MagenticBuilder,
+    MagenticPlanReviewRequest,
+    RequestInfoEvent,
+    WorkflowOutputEvent,
+)
+from agent_framework.openai import OpenAIChatClient
+
+"""
+Sample: Magentic Orchestration with Human Plan Review
+
+This sample demonstrates how humans can review and provide feedback on plans
+generated by the Magentic workflow orchestrator. When plan review is enabled,
+the workflow requests human approval or revision before executing each plan.
+
+Key concepts:
+- with_plan_review(): Enables human review of generated plans
+- MagenticPlanReviewRequest: The event type for plan review requests
+- Human can choose to: approve the plan or provide revision feedback
+
+Plan review options:
+- approve(): Accept the proposed plan and continue execution
+- revise(feedback): Provide textual feedback to modify the plan
+
+Prerequisites:
+- OpenAI credentials configured for `OpenAIChatClient`.
+"""
+
+
+async def main() -> None:
+    researcher_agent = ChatAgent(
+        name="ResearcherAgent",
+        description="Specialist in research and information gathering",
+        instructions="You are a Researcher. You find information and gather facts.",
+        chat_client=OpenAIChatClient(model_id="gpt-4o"),
+    )
+
+    analyst_agent = ChatAgent(
+        name="AnalystAgent",
+        description="Data analyst who processes and summarizes research findings",
+        instructions="You are an Analyst. You analyze findings and create summaries.",
+        chat_client=OpenAIChatClient(model_id="gpt-4o"),
+    )
+
+    manager_agent = ChatAgent(
+        name="MagenticManager",
+        description="Orchestrator that coordinates the workflow",
+        instructions="You coordinate a team to complete tasks efficiently.",
+        chat_client=OpenAIChatClient(model_id="gpt-4o"),
+    )
+
+    print("\nBuilding Magentic Workflow with Human Plan Review...")
+
+    workflow = (
+        MagenticBuilder()
+        .participants([researcher_agent, analyst_agent])
+        .with_manager(
+            agent=manager_agent,
+            max_round_count=10,
+            max_stall_count=1,
+            max_reset_count=2,
+        )
+        .with_plan_review()  # Request human input for plan review
+        .build()
+    )
+
+    task = "Research sustainable aviation fuel technology and summarize the findings."
+
+    print(f"\nTask: {task}")
+    print("\nStarting workflow execution...")
+    print("=" * 60)
+
+    pending_request: RequestInfoEvent | None = None
+    pending_responses: dict[str, object] | None = None
+    output_event: WorkflowOutputEvent | None = None
+
+    while not output_event:
+        if pending_responses is not None:
+            stream = workflow.send_responses_streaming(pending_responses)
+        else:
+            stream = workflow.run(task, stream=True)
+
+        last_message_id: str | None = None
+        async for event in stream:
+            if isinstance(event, AgentRunUpdateEvent):
+                message_id = event.data.message_id
+                if message_id != last_message_id:
+                    if last_message_id is not None:
+                        print("\n")
+                    print(f"- {event.executor_id}:", end=" ", flush=True)
+                    last_message_id = message_id
+                print(event.data, end="", flush=True)
+
+            elif isinstance(event, RequestInfoEvent) and event.request_type is MagenticPlanReviewRequest:
+                pending_request = event
+
+            elif isinstance(event, WorkflowOutputEvent):
+                output_event = event
+
+        pending_responses = None
+
+        # Handle plan review request if any
+        if pending_request is not None:
+            event_data = cast(MagenticPlanReviewRequest, pending_request.data)
+
+            print("\n\n[Magentic Plan Review Request]")
+            if event_data.current_progress is not None:
+                print("Current Progress Ledger:")
+                print(json.dumps(event_data.current_progress.to_dict(), indent=2))
+                print()
+            print(f"Proposed Plan:\n{event_data.plan.text}\n")
+            print("Please provide your feedback (press Enter to approve):")
+
+            reply = await asyncio.get_event_loop().run_in_executor(None, input, "> ")
+            if reply.strip() == "":
+                print("Plan approved.\n")
+                pending_responses = {pending_request.request_id: event_data.approve()}
+            else:
+                print("Plan revised by human.\n")
+                pending_responses = {pending_request.request_id: event_data.revise(reply)}
+            pending_request = None
+
+    print("\n" + "=" * 60)
+    print("WORKFLOW COMPLETED")
+    print("=" * 60)
+    print("Final Output:")
+    # The output of the Magentic workflow is a list of ChatMessages with only one final message
+    # generated by the orchestrator.
+    output_messages = cast(list[ChatMessage], output_event.data)
+    if output_messages:
+        output = output_messages[-1].text
+        print(output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -86,7 +86,7 @@ async def main() -> None:

    # 2) Run the workflow
    output: list[int | float] | None = None
-    async for event in workflow.run_stream([random.randint(1, 100) for _ in range(10)]):
+    async for event in workflow.run([random.randint(1, 100) for _ in range(10)], stream=True):
        if isinstance(event, WorkflowOutputEvent):
            output = event.data

@@ -11,6 +11,7 @@ from agent_framework import (  # Core chat primitives to build LLM requests
    Executor,  # Base class for custom Python executors
    ExecutorCompletedEvent,
    ExecutorInvokedEvent,
+    Role,  # Enum of chat roles (user, assistant, system)
    WorkflowBuilder,  # Fluent builder for wiring the workflow graph
    WorkflowContext,  # Per run context and event bus
    WorkflowOutputEvent,  # Event emitted when workflow yields output
@@ -44,7 +45,7 @@ class DispatchToExperts(Executor):
    @handler
    async def dispatch(self, prompt: str, ctx: WorkflowContext[AgentExecutorRequest]) -> None:
        # Wrap the incoming prompt as a user message for each expert and request a response.
-        initial_message = ChatMessage("user", text=prompt)
+        initial_message = ChatMessage(Role.USER, text=prompt)
        await ctx.send_message(AgentExecutorRequest(messages=[initial_message], should_respond=True))


@@ -139,7 +140,9 @@ async def main() -> None:
    )

    # 3) Run with a single prompt and print progress plus the final consolidated output
-    async for event in workflow.run_stream("We are launching a new budget-friendly electric bike for urban commuters."):
+    async for event in workflow.run(
+        "We are launching a new budget-friendly electric bike for urban commuters.", stream=True
+    ):
        if isinstance(event, ExecutorInvokedEvent):
            # Show when executors are invoked and completed for lightweight observability.
            print(f"{event.executor_id} invoked")
@@ -330,7 +330,7 @@ async def main():
        raw_text = await f.read()

    # Step 4: Run the workflow with the raw text as input.
-    async for event in workflow.run_stream(raw_text):
+    async for event in workflow.run(raw_text, stream=True):
        print(f"Event: {event}")
        if isinstance(event, WorkflowOutputEvent):
            print(f"Final Output: {event.data}")
@@ -4,8 +4,9 @@ import asyncio
 import json
 from typing import Annotated, Any

-from agent_framework import ChatMessage, SequentialBuilder, WorkflowOutputEvent, tool
+from agent_framework import ChatMessage, WorkflowOutputEvent, tool
 from agent_framework.openai import OpenAIChatClient
+from agent_framework.orchestrations import SequentialBuilder
 from pydantic import Field

 """
@@ -15,7 +16,7 @@ This sample demonstrates how to flow custom context (skill data, user tokens, et
 through any workflow pattern to @tool functions using the **kwargs pattern.

 Key Concepts:
- Pass custom context as kwargs when invoking workflow.run_stream() or workflow.run()
+- Pass custom context as kwargs when invoking workflow.run()
 - kwargs are stored in State and passed to all agent invocations
 - @tool functions receive kwargs via **kwargs parameter
 - Works with Sequential, Concurrent, GroupChat, Handoff, and Magentic patterns
@@ -112,10 +113,10 @@ async def main() -> None:
    print("-" * 70)

    # Run workflow with kwargs - these will flow through to tools
-    async for event in workflow.run_stream(
+    async for event in workflow.run(
        "Please get my user data and then call the users API endpoint.",
-        custom_data=custom_data,
-        user_token=user_token,
+        additional_function_arguments={"custom_data": custom_data, "user_token": user_token},
+        stream=True,
    ):
        if isinstance(event, WorkflowOutputEvent):
            output_data = event.data
@@ -158,9 +158,10 @@ async def main() -> None:

    # Initiate the first run of the workflow.
    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
-    stream = workflow.run_stream(
+    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."
+        "your best judgment based on market sentiment. No need to confirm trades with me.",
+        stream=True,
    )

    pending_responses = await process_event_stream(stream)
@@ -169,7 +169,9 @@ async def main() -> None:

    # Initiate the first run of the workflow.
    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
-    stream = workflow.run_stream("We need to deploy version 2.4.0 to production. Please coordinate the deployment.")
+    stream = workflow.run(
+        "We need to deploy version 2.4.0 to production. Please coordinate the deployment.", stream=True
+    )

    pending_responses = await process_event_stream(stream)
    while pending_responses is not None:
@@ -119,7 +119,9 @@ async def main() -> None:

    # Initiate the first run of the workflow.
    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
-    stream = workflow.run_stream("Check the schema and then update all orders with status 'pending' to 'processing'")
+    stream = workflow.run(
+        "Check the schema and then update all orders with status 'pending' to 'processing'", stream=True
+    )

    pending_responses = await process_event_stream(stream)
    while pending_responses is not None: