Merge pull request #792 from MicrosoftDocs/main

Merge main to live

Author: moonbox3

agent-framework/integrations/ag-ui/getting-started.md

@@ -387,13 +387,13 @@ The AG-UI server hosts your AI agent and exposes it via HTTP endpoints using Fas
 Install the necessary packages for the server:
 
 ```bash
-pip install agent-framework-ag-ui
+pip install agent-framework-ag-ui --pre
 ```
 
 Or using uv:
 
 ```bash
-uv pip install agent-framework-ag-ui
+uv pip install agent-framework-ag-ui --prerelease=allow
 ```
 
 This will automatically install `agent-framework-core`, `fastapi`, and `uvicorn` as dependencies.
@@ -425,7 +425,7 @@ if not deployment_name:
 chat_client = AzureOpenAIChatClient(
     credential=AzureCliCredential(),
     endpoint=endpoint,
-    deployment_name=deployment_name,    
+    deployment_name=deployment_name,
 )
 
 # Create the AI agent
@@ -488,7 +488,7 @@ The AG-UI package is already installed, which includes the `AGUIChatClient`:
 
 ```bash
 # Already installed with agent-framework-ag-ui
-pip install agent-framework-ag-ui
+pip install agent-framework-ag-ui --pre
 ```
 
 ### Client Code
@@ -513,7 +513,7 @@ async def main():
 
     # Create AG-UI chat client
     chat_client = AGUIChatClient(server_url=server_url)
-    
+
     # Create agent with the chat client
     agent = ChatAgent(
         name="ClientAgent",

agent-framework/integrations/ag-ui/index.md

@@ -48,7 +48,7 @@ The Agent Framework AG-UI integration supports all 7 AG-UI protocol features:
 
 ## Build agent UIs with CopilotKit
 
-[CopilotKit](https://copilotkit.ai/) provides rich UI components for building agent user interfaces based on the standard AG-UI protocol. CopilotKit supports streaming chat interfaces, frontend & backend tool calling, human-in-the-loop interactions, generative UI, shared state, and much more. You can see a examples of the various agent UI scenarios that CopilotKit supports in the [AG-UI Dojo](https://dojo.ag-ui.com/microsoft-agent-framework-dotnet) sample application. 
+[CopilotKit](https://copilotkit.ai/) provides rich UI components for building agent user interfaces based on the standard AG-UI protocol. CopilotKit supports streaming chat interfaces, frontend & backend tool calling, human-in-the-loop interactions, generative UI, shared state, and much more. You can see a examples of the various agent UI scenarios that CopilotKit supports in the [AG-UI Dojo](https://dojo.ag-ui.com/microsoft-agent-framework-dotnet) sample application.
 
 CopilotKit helps you focus on your agent’s capabilities while delivering a polished user experience without reinventing the wheel.
 To learn more about getting started with Microsoft Agent Framework and CopilotKit, see the [Microsoft Agent Framework integration for CopilotKit](https://docs.copilotkit.ai/microsoft-agent-framework) documentation.
@@ -233,7 +233,7 @@ Understanding how Agent Framework concepts map to AG-UI helps you build effectiv
 Install the AG-UI integration package:
 
 ```bash
-pip install agent-framework-ag-ui
+pip install agent-framework-ag-ui --pre
 ```
 
 This installs both the core agent framework and AG-UI integration components.

agent-framework/integrations/ag-ui/state-management.md

@@ -488,7 +488,7 @@ agent = ChatAgent(
     chat_client=AzureOpenAIChatClient(
         credential=AzureCliCredential(),
         endpoint=endpoint,
-        deployment_name=deployment_name,    
+        deployment_name=deployment_name,
     ),
     tools=[update_recipe],
 )
@@ -614,7 +614,7 @@ async def main():
 
     # Create AG-UI chat client
     chat_client = AGUIChatClient(server_url=server_url)
-    
+
     # Wrap with ChatAgent for convenient API
     agent = ChatAgent(
         name="ClientAgent",
@@ -624,7 +624,7 @@ async def main():
 
     # Get a thread for conversation continuity
     thread = agent.get_new_thread()
-    
+
     # Track state locally
     state: dict[str, Any] = {}
 
@@ -647,7 +647,7 @@ async def main():
                 # Handle text content
                 if update.text:
                     print(update.text, end="", flush=True)
-                
+
                 # Handle state updates
                 for content in update.contents:
                     # STATE_SNAPSHOT events come as DataContent with application/json
@@ -656,7 +656,7 @@ async def main():
                         state_data = json.loads(content.data.decode() if isinstance(content.data, bytes) else content.data)
                         state = state_data
                         print("\n[State Snapshot Received]")
-                    
+
                     # STATE_DELTA events are handled similarly
                     # Apply JSON Patch deltas to maintain state
                     if hasattr(content, 'delta') and content.delta:
@@ -672,7 +672,7 @@ async def main():
 
 
 if __name__ == "__main__":
-    # Install dependencies: pip install agent-framework-ag-ui jsonpatch
+    # Install dependencies: pip install agent-framework-ag-ui jsonpatch --pre
     asyncio.run(main())
 ```
 
@@ -913,7 +913,7 @@ Always write the complete state, not just deltas:
 def update_recipe(recipe: Recipe) -> str:
     """
     You MUST write the complete recipe with ALL fields.
-    When modifying a recipe, include ALL existing ingredients and 
+    When modifying a recipe, include ALL existing ingredients and
     instructions plus your changes. NEVER delete existing data.
     """
     return "Recipe updated."

agent-framework/migration-guide/from-autogen/index.md

@@ -1,9 +1,9 @@
 ---
 title: AutoGen to Microsoft Agent Framework Migration Guide
 description: A comprehensive guide for migrating from AutoGen to the Microsoft Agent Framework Python SDK.
-author: ekzhu
+author: moonbox3
 ms.topic: reference
-ms.author: ekzhu
+ms.author: evmattso
 ms.date: 09/29/2025
 ms.service: agent-framework
 ---
@@ -1195,85 +1195,134 @@ result = await team.run("Complex research and analysis task")
 **Agent Framework Implementation:**
 
 ```python
+from typing import cast
 from agent_framework import (
-    MagenticBuilder, MagenticCallbackMode, WorkflowOutputEvent,
-    MagenticCallbackEvent, MagenticOrchestratorMessageEvent, MagenticAgentDeltaEvent
+    MAGENTIC_EVENT_TYPE_AGENT_DELTA,
+    MAGENTIC_EVENT_TYPE_ORCHESTRATOR,
+    AgentRunUpdateEvent,
+    ChatAgent,
+    ChatMessage,
+    MagenticBuilder,
+    WorkflowOutputEvent,
 )
+from agent_framework.openai import OpenAIChatClient
 
-# Assume we have researcher, coder, and coordinator_client from previous examples
-async def on_event(event: MagenticCallbackEvent) -> None:
-    if isinstance(event, MagenticOrchestratorMessageEvent):
-        print(f"[ORCHESTRATOR]: {event.message.text}")
-    elif isinstance(event, MagenticAgentDeltaEvent):
-        print(f"[{event.agent_id}]: {event.text}", end="")
-
-workflow = (MagenticBuilder()
-           .participants(researcher=researcher, coder=coder)
-           .on_event(on_event, mode=MagenticCallbackMode.STREAMING)
-           .with_standard_manager(
-               chat_client=coordinator_client,
-               max_round_count=20,
-               max_stall_count=3,
-               max_reset_count=2
-           )
-           .build())
+# Create a manager agent for orchestration
+manager_agent = ChatAgent(
+    name="MagenticManager",
+    description="Orchestrator that coordinates the workflow",
+    instructions="You coordinate a team to complete complex tasks efficiently.",
+    chat_client=OpenAIChatClient(),
+)
+
+workflow = (
+    MagenticBuilder()
+    .participants(researcher=researcher, coder=coder)
+    .with_standard_manager(
+        agent=manager_agent,
+        max_round_count=20,
+        max_stall_count=3,
+        max_reset_count=2,
+    )
+    .build()
+)
 
 # Example usage (would be in async context)
 async def magentic_example():
+    output: str | None = None
     async for event in workflow.run_stream("Complex research task"):
-        if isinstance(event, WorkflowOutputEvent):
-            final_result = event.data
+        if isinstance(event, AgentRunUpdateEvent):
+            props = event.data.additional_properties if event.data else None
+            event_type = props.get("magentic_event_type") if props else None
+
+            if event_type == MAGENTIC_EVENT_TYPE_ORCHESTRATOR:
+                text = event.data.text if event.data else ""
+                print(f"[ORCHESTRATOR]: {text}")
+            elif event_type == MAGENTIC_EVENT_TYPE_AGENT_DELTA:
+                agent_id = props.get("agent_id", event.executor_id) if props else event.executor_id
+                if event.data and event.data.text:
+                    print(f"[{agent_id}]: {event.data.text}", end="")
+
+        elif isinstance(event, WorkflowOutputEvent):
+            output_messages = cast(list[ChatMessage], event.data)
+            if output_messages:
+                output = output_messages[-1].text
 ```
 
 **Agent Framework Customization Options:**
 
 The Magentic workflow provides extensive customization options:
 
-- **Manager configuration**: Custom orchestrator models and prompts
+- **Manager configuration**: Use a ChatAgent with custom instructions and model settings
 - **Round limits**: `max_round_count`, `max_stall_count`, `max_reset_count`
-- **Event callbacks**: Real-time streaming with granular event filtering
+- **Event streaming**: Use `AgentRunUpdateEvent` with `magentic_event_type` metadata
 - **Agent specialization**: Custom instructions and tools per agent
-- **Callback modes**: `STREAMING` for real-time updates or `BATCH` for final results
-- **Human-in-the-loop planning**: Custom planner functions for interactive workflows
+- **Human-in-the-loop**: Plan review, tool approval, and stall intervention
 
 ```python
 # Advanced customization example with human-in-the-loop
+from typing import cast
+from agent_framework import (
+    MAGENTIC_EVENT_TYPE_AGENT_DELTA,
+    MAGENTIC_EVENT_TYPE_ORCHESTRATOR,
+    AgentRunUpdateEvent,
+    ChatAgent,
+    MagenticBuilder,
+    MagenticHumanInterventionDecision,
+    MagenticHumanInterventionKind,
+    MagenticHumanInterventionReply,
+    MagenticHumanInterventionRequest,
+    RequestInfoEvent,
+    WorkflowOutputEvent,
+)
 from agent_framework.openai import OpenAIChatClient
-from agent_framework import MagenticBuilder, MagenticCallbackMode, MagenticPlannerContext
-
-# Assume we have researcher_agent, coder_agent, analyst_agent, detailed_event_handler
-# and get_human_input function defined elsewhere
-
-async def custom_planner(context: MagenticPlannerContext) -> str:
-    """Custom planner with human input for critical decisions."""
-    if context.round_count > 5:
-        # Request human input for complex decisions
-        return await get_human_input(f"Next action for: {context.current_state}")
-    return "Continue with automated planning"
-
-workflow = (MagenticBuilder()
-           .participants(
-               researcher=researcher_agent,
-               coder=coder_agent,
-               analyst=analyst_agent
-           )
-           .with_standard_manager(
-               chat_client=OpenAIChatClient(model_id="gpt-5"),
-               max_round_count=15,      # Limit total rounds
-               max_stall_count=2,       # Prevent infinite loops
-               max_reset_count=1,       # Allow one reset on failure
-               orchestrator_prompt="Custom orchestration instructions..."
-           )
-           .with_planner(custom_planner)  # Human-in-the-loop planning
-           .on_event(detailed_event_handler, mode=MagenticCallbackMode.STREAMING)
-           .build())
+
+# Create manager agent with custom configuration
+manager_agent = ChatAgent(
+    name="MagenticManager",
+    description="Orchestrator for complex tasks",
+    instructions="Custom orchestration instructions...",
+    chat_client=OpenAIChatClient(model_id="gpt-4o"),
+)
+
+workflow = (
+    MagenticBuilder()
+    .participants(
+        researcher=researcher_agent,
+        coder=coder_agent,
+        analyst=analyst_agent,
+    )
+    .with_standard_manager(
+        agent=manager_agent,
+        max_round_count=15,      # Limit total rounds
+        max_stall_count=2,       # Trigger stall handling
+        max_reset_count=1,       # Allow one reset on failure
+    )
+    .with_plan_review()           # Enable human plan review
+    .with_human_input_on_stall()  # Enable human intervention on stalls
+    .build()
+)
+
+# Handle human intervention requests during execution
+async for event in workflow.run_stream("Complex task"):
+    if isinstance(event, RequestInfoEvent) and event.request_type is MagenticHumanInterventionRequest:
+        req = cast(MagenticHumanInterventionRequest, event.data)
+        if req.kind == MagenticHumanInterventionKind.PLAN_REVIEW:
+            # Review and approve the plan
+            reply = MagenticHumanInterventionReply(
+                decision=MagenticHumanInterventionDecision.APPROVE
+            )
+            async for ev in workflow.send_responses_streaming({event.request_id: reply}):
+                pass  # Handle continuation
 ```
 
 For detailed Magentic examples, see:
 
 - [Basic Magentic Workflow](https://github.com/microsoft/agent-framework/blob/main/python/samples/getting_started/workflows/orchestration/magentic.py) - Standard orchestrated multi-agent workflow
 - [Magentic with Checkpointing](https://github.com/microsoft/agent-framework/blob/main/python/samples/getting_started/workflows/orchestration/magentic_checkpoint.py) - Persistent orchestrated workflows
-- [Magentic Human Plan Update](https://github.com/microsoft/agent-framework/blob/main/python/samples/getting_started/workflows/orchestration/magentic_human_plan_update.py) - Human-in-the-loop planning
+- [Magentic Human Plan Update](https://github.com/microsoft/agent-framework/blob/main/python/samples/getting_started/workflows/orchestration/magentic_human_plan_update.py) - Human-in-the-loop plan review
+- [Magentic Agent Clarification](https://github.com/microsoft/agent-framework/blob/main/python/samples/getting_started/workflows/orchestration/magentic_agent_clarification.py) - Tool approval for agent clarification
+- [Magentic Human Replan](https://github.com/microsoft/agent-framework/blob/main/python/samples/getting_started/workflows/orchestration/magentic_human_replan.py) - Human intervention on stalls
 
 #### Future Patterns
 

agent-framework/migration-guide/from-semantic-kernel/index.md

@@ -321,7 +321,7 @@ from semantic_kernel.agents import ChatCompletionAgent
 ### Agent Framework
 
 Agent Framework package is installed as `agent-framework` and imported as `agent_framework`.
-Agent Framework is built up differently, it has a core package `agent-framework-core` that contains the core functionality, and then there are multiple packages that rely on that core package, such as `agent-framework-azure-ai`, `agent-framework-mem0`, `agent-framework-copilotstudio`, etc. When you run `pip install agent-framework` it will install the core package and *all* packages, so that you can get started with all the features quickly. When you are ready to reduce the number of packages because you know what you need, you can install only the packages you need, so for instance if you only plan to use Azure AI Foundry and Mem0 you can install only those two packages: `pip install agent-framework-azure-ai agent-framework-mem0`, `agent-framework-core` is a dependency to those two, so will automatically be installed.
+Agent Framework is built up differently, it has a core package `agent-framework-core` that contains the core functionality, and then there are multiple packages that rely on that core package, such as `agent-framework-azure-ai`, `agent-framework-mem0`, `agent-framework-copilotstudio`, etc. When you run `pip install agent-framework --pre` it will install the core package and *all* packages, so that you can get started with all the features quickly. When you are ready to reduce the number of packages because you know what you need, you can install only the packages you need, so for instance if you only plan to use Azure AI Foundry and Mem0 you can install only those two packages: `pip install agent-framework-azure-ai agent-framework-mem0 --pre`, `agent-framework-core` is a dependency to those two, so will automatically be installed.
 
 Even though the packages are split up, the imports are all from `agent_framework`, or it's modules. So for instance to import the client for Azure AI Foundry you would do:
 

agent-framework/overview/agent-framework-overview.md

@@ -1,9 +1,9 @@
 ---
 title: Introduction to Microsoft Agent Framework
 description: Learn about Microsoft Agent Framework
-author: ekzhu
+author: markwallace-microsoft
 ms.topic: reference
-ms.author: ekzhu
+ms.author: markwallace
 ms.date: 10/01/2025
 ms.service: agent-framework
 ---
@@ -57,7 +57,7 @@ and the same is expected for Agent Framework. Microsoft Agent Framework welcomes
 Python:
 
 ```bash
-pip install agent-framework
+pip install agent-framework --pre
 ```
 
 .NET:

agent-framework/support/index.md

@@ -2,7 +2,7 @@
 title: Support for Agent Framework
 description: Support for Agent Framework
 author: TaoChenOSU
-ms.topic: conceptual
+ms.topic: article
 ms.author: taochen
 ms.date: 10/30/2025
 ms.service: agent-framework
@@ -13,7 +13,7 @@ ms.service: agent-framework
 
 | Your preference | What's available |
 |---|---|
-| Read the docs | [This learning site](/agent-framework/overview) is the home of the latest information for developers |
+| Read the docs | [This learning site](/agent-framework/) is the home of the latest information for developers |
 | Visit the repo | Our open-source [GitHub repository](https://github.com/microsoft/agent-framework) is available for perusal and suggestions |
 | Connect with the Agent Framework Team | Visit our [GitHub Discussions](https://github.com/microsoft/agent-framework/discussions) to get supported quickly with our [CoC](https://github.com/microsoft/agent-framework/blob/main/CODE_OF_CONDUCT.md) actively enforced |
-|  Office Hours | We will be hosting regular office hours; the calendar invites and cadence are located here: [Community.MD](https://github.com/microsoft/agent-framework/blob/main/COMMUNITY.md) |
+|  Office Hours | We will be hosting regular office hours; the calendar invites and cadence are located here: [Community.MD](https://github.com/microsoft/agent-framework/blob/main/COMMUNITY.md) |

agent-framework/tutorials/agents/enable-observability.md

@@ -143,7 +143,7 @@ For prerequisites, see the [Create and run a simple agent](./run-agent.md) step
 To use Agent Framework with Azure OpenAI, you need to install the following packages. Agent Framework automatically includes all necessary OpenTelemetry dependencies:
 
 ```bash
-pip install agent-framework
+pip install agent-framework --pre
 ```
 
 The following OpenTelemetry packages are included by default:

agent-framework/tutorials/agents/run-agent.md

@@ -186,7 +186,7 @@ Before you begin, ensure you have the following prerequisites:
 To use Microsoft Agent Framework with Azure OpenAI, you need to install the following Python packages:
 
 ```bash
-pip install agent-framework
+pip install agent-framework --pre
 ```
 
 ## Create the agent