Merge pull request #782 from MicrosoftDocs/main

Merge main to live

Author: moonbox3

.openpublishing.redirection.json

@@ -824,6 +824,11 @@
             "source_path": "semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md",
             "redirect_url": "/semantic-kernel/support/archive/agent-chat-example",
             "redirect_document_id": false
+        },
+        {
+            "source_path": "agent-framework/tutorials/workflows/visualization.md",
+            "redirect_url": "/agent-framework/user-guide/workflows/visualization",
+            "redirect_document_id": true
         }
     ]
 }

agent-framework/tutorials/workflows/TOC.yml

@@ -9,6 +9,4 @@
 - name: Handle requests and responses in workflows
   href: requests-and-responses.md
 - name: Checkpointing and resuming workflows
-  href: checkpointing-and-resuming.md
-- name: Visualizing workflows
-  href: visualization.md
+  href: checkpointing-and-resuming.md

agent-framework/tutorials/workflows/agents-in-workflows.md

@@ -27,6 +27,12 @@ You'll create a workflow that:
 - Streams real-time updates as agents process requests
 - Demonstrates proper resource cleanup for Azure Foundry agents
 
+### Concepts Covered
+
+- [Agents in Workflows](../../user-guide/workflows/using-agents.md)
+- [Direct Edges](../../user-guide/workflows/core-concepts/edges.md#direct-edges)
+- [Workflow Builder](../../user-guide/workflows/core-concepts/workflows.md)
+
 ## Prerequisites
 
 - [.NET 8.0 SDK or later](https://dotnet.microsoft.com/download)
@@ -68,18 +74,7 @@ public static class Program
         var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());
 ```
 
-## Step 3: Create Specialized Azure Foundry Agents
-
-Create three translation agents using the helper method:
-
-```csharp
-        // Create agents
-        AIAgent frenchAgent = await GetTranslationAgentAsync("French", persistentAgentsClient, model);
-        AIAgent spanishAgent = await GetTranslationAgentAsync("Spanish", persistentAgentsClient, model);
-        AIAgent englishAgent = await GetTranslationAgentAsync("English", persistentAgentsClient, model);
-```
-
-## Step 4: Create Agent Factory Method
+## Step 3: Create Agent Factory Method
 
 Implement a helper method to create Azure Foundry agents with specific instructions:
 
@@ -106,6 +101,17 @@ Implement a helper method to create Azure Foundry agents with specific instructi
 }
 ```
 
+## Step 4: Create Specialized Azure Foundry Agents
+
+Create three translation agents using the helper method:
+
+```csharp
+        // Create agents
+        AIAgent frenchAgent = await GetTranslationAgentAsync("French", persistentAgentsClient, model);
+        AIAgent spanishAgent = await GetTranslationAgentAsync("Spanish", persistentAgentsClient, model);
+        AIAgent englishAgent = await GetTranslationAgentAsync("English", persistentAgentsClient, model);
+```
+
 ## Step 5: Build the Workflow
 
 Connect the agents in a sequential workflow using the WorkflowBuilder:
@@ -187,6 +193,12 @@ You'll create a workflow that:
 - Streams real-time updates as agents process requests
 - Demonstrates proper async context management for Azure AI clients
 
+### Concepts Covered
+
+- [Agents in Workflows](../../user-guide/workflows/using-agents.md)
+- [Direct Edges](../../user-guide/workflows/core-concepts/edges.md#direct-edges)
+- [Workflow Builder](../../user-guide/workflows/core-concepts/workflows.md)
+
 ## Prerequisites
 
 - Python 3.10 or later

agent-framework/tutorials/workflows/checkpointing-and-resuming.md

@@ -13,6 +13,10 @@ ms.service: agent-framework
 
 Checkpointing allows workflows to save their state at specific points and resume execution later, even after process restarts. This is crucial for long-running workflows, error recovery, and human-in-the-loop scenarios.
 
+### Concepts Covered
+
+- [Checkpoints](../../user-guide/workflows/checkpoints.md)
+
 ::: zone pivot="programming-language-csharp"
 
 ## Prerequisites
@@ -67,14 +71,14 @@ await using Checkpointed<StreamingRun> checkpointedRun = await InProcessExecutio
 Executors can persist local state that survives checkpoints using the `Executor<T>` base class:
 
 ```csharp
-internal sealed class GuessNumberExecutor : Executor<NumberSignal>
+internal sealed class GuessNumberExecutor : Executor<NumberSignal>("Guess")
 {
     private const string StateKey = "GuessNumberExecutor.State";
 
     public int LowerBound { get; private set; }
     public int UpperBound { get; private set; }
 
-    public GuessNumberExecutor() : base("GuessNumber")
+    public GuessNumberExecutor() : this()
     {
     }
 
@@ -446,37 +450,45 @@ Executors can persist local state that survives checkpoints:
 ```python
 from agent_framework import Executor, WorkflowContext, handler
 
-class UpperCaseExecutor(Executor):
-    @handler
-    async def to_upper_case(self, text: str, ctx: WorkflowContext[str]) -> None:
-        result = text.upper()
-
-        # Persist executor-local state for checkpoints
-        prev = await ctx.get_executor_state() or {}
-        count = int(prev.get("count", 0)) + 1
-        await ctx.set_executor_state({
-            "count": count,
-            "last_input": text,
-            "last_output": result,
-        })
-
-        # Send result to next executor
-        await ctx.send_message(result)
-```
-
-### Shared State
+class WorkerExecutor(Executor):
+    """Processes numbers to compute their factor pairs and manages executor state for checkpointing."""
 
-Use shared state for data that multiple executors need to access:
+    def __init__(self, id: str) -> None:
+        super().__init__(id=id)
+        self._composite_number_pairs: dict[int, list[tuple[int, int]]] = {}
 
-```python
-class ProcessorExecutor(Executor):
     @handler
-    async def process(self, text: str, ctx: WorkflowContext[str]) -> None:
-        # Write to shared state for cross-executor visibility
-        await ctx.set_shared_state("original_input", text)
-        await ctx.set_shared_state("processed_output", text.upper())
-
-        await ctx.send_message(text.upper())
+    async def compute(
+        self,
+        task: ComputeTask,
+        ctx: WorkflowContext[ComputeTask, dict[int, list[tuple[int, int]]]],
+    ) -> None:
+        """Process the next number in the task, computing its factor pairs."""
+        next_number = task.remaining_numbers.pop(0)
+
+        print(f"WorkerExecutor: Computing factor pairs for {next_number}")
+        pairs: list[tuple[int, int]] = []
+        for i in range(1, next_number):
+            if next_number % i == 0:
+                pairs.append((i, next_number // i))
+        self._composite_number_pairs[next_number] = pairs
+
+        if not task.remaining_numbers:
+            # All numbers processed - output the results
+            await ctx.yield_output(self._composite_number_pairs)
+        else:
+            # More numbers to process - continue with remaining task
+            await ctx.send_message(task)
+
+    @override
+    async def on_checkpoint_save(self) -> dict[str, Any]:
+        """Save the executor's internal state for checkpointing."""
+        return {"composite_number_pairs": self._composite_number_pairs}
+
+    @override
+    async def on_checkpoint_restore(self, state: dict[str, Any]) -> None:
+        """Restore the executor's internal state from a checkpoint."""
+        self._composite_number_pairs = state.get("composite_number_pairs", {})
 ```
 
 ## Working with Checkpoints
@@ -496,24 +508,6 @@ workflow_checkpoints = await checkpoint_storage.list_checkpoints(workflow_id="my
 sorted_checkpoints = sorted(all_checkpoints, key=lambda cp: cp.timestamp)
 ```
 
-### Checkpoint Information
-
-Access checkpoint metadata and state:
-
-```python
-from agent_framework import get_checkpoint_summary
-
-for checkpoint in checkpoints:
-    # Get human-readable summary
-    summary = get_checkpoint_summary(checkpoint)
-
-    print(f"Checkpoint: {summary.checkpoint_id}")
-    print(f"Iteration: {summary.iteration_count}")
-    print(f"Status: {summary.status}")
-    print(f"Messages: {len(checkpoint.messages)}")
-    print(f"Shared State: {checkpoint.shared_state}")
-```
-
 ## Resuming from Checkpoints
 
 ### Streaming Resume
@@ -682,8 +676,3 @@ if __name__ == "__main__":
 For the complete working implementation, see the [Checkpoint with Resume sample](https://github.com/microsoft/agent-framework/blob/main/python/samples/getting_started/workflows/checkpoint/checkpoint_with_resume.py).
 
 ::: zone-end
-
-## Next Steps
-
-> [!div class="nextstepaction"]
-> [Learn about Workflow Visualization](visualization.md)

agent-framework/tutorials/workflows/requests-and-responses.md

@@ -13,6 +13,10 @@ ms.service: agent-framework
 
 This tutorial demonstrates how to handle requests and responses in workflows using Agent Framework Workflows. You'll learn how to create interactive workflows that can pause execution to request input from external sources (like humans or other systems) and then resume once a response is provided.
 
+## Concepts Covered
+
+- [Requests and Responses](../../user-guide/workflows/requests-and-responses.md)
+
 ::: zone pivot="programming-language-csharp"
 
 In .NET, human-in-the-loop workflows use `RequestPort` and external request handling to pause execution and gather user input. This pattern enables interactive workflows where the system can request information from external sources during execution.
@@ -68,12 +72,12 @@ Create executors that process user input and provide feedback:
 /// <summary>
 /// Executor that judges the guess and provides feedback.
 /// </summary>
-internal sealed class JudgeExecutor : Executor<int>, IMessageHandler<int>
+internal sealed class JudgeExecutor : Executor<int>("Judge")
 {
     private readonly int _targetNumber;
     private int _tries;
 
-    public JudgeExecutor(int targetNumber) : base("Judge")
+    public JudgeExecutor(int targetNumber) : this()
     {
         _targetNumber = targetNumber;
     }

agent-framework/tutorials/workflows/simple-concurrent-workflow.md

@@ -24,6 +24,14 @@ You'll create a workflow that:
 - Collects and combines responses from both agents into a single output
 - Demonstrates concurrent execution with AI agents using fan-out/fan-in patterns
 
+### Concepts Covered
+
+- [Executors](../../user-guide/workflows/core-concepts/executors.md)
+- [Fan-out Edges](../../user-guide/workflows/core-concepts/edges.md#fan-out-edges)
+- [Fan-in Edges](../../user-guide/workflows/core-concepts/edges.md#fan-in-edges)
+- [Workflow Builder](../../user-guide/workflows/core-concepts/workflows.md)
+- [Events](../../user-guide/workflows/core-concepts/events.md)
+
 ## Prerequisites
 
 - [.NET 8.0 SDK or later](https://dotnet.microsoft.com/download)
@@ -101,8 +109,7 @@ The `ConcurrentStartExecutor` implementation:
 /// <summary>
 /// Executor that starts the concurrent processing by sending messages to the agents.
 /// </summary>
-internal sealed class ConcurrentStartExecutor() :
-    Executor<string>("ConcurrentStartExecutor")
+internal sealed class ConcurrentStartExecutor() : Executor<string>("ConcurrentStartExecutor")
 {
     /// <summary>
     /// Starts the concurrent processing by sending messages to the agents.
@@ -139,7 +146,7 @@ The `ConcurrentAggregationExecutor` implementation:
 /// Executor that aggregates the results from the concurrent agents.
 /// </summary>
 internal sealed class ConcurrentAggregationExecutor() :
-    Executor<ChatMessage>("ConcurrentAggregationExecutor")
+    Executor<List<ChatMessage>>("ConcurrentAggregationExecutor")
 {
     private readonly List<ChatMessage> _messages = [];
 
@@ -151,9 +158,9 @@ internal sealed class ConcurrentAggregationExecutor() :
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.
     /// The default is <see cref="CancellationToken.None"/>.</param>
     /// <returns>A task representing the asynchronous operation</returns>
-    public override async ValueTask HandleAsync(ChatMessage message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    public override async ValueTask HandleAsync(List<ChatMessage> message, IWorkflowContext context, CancellationToken cancellationToken = default)
     {
-        this._messages.Add(message);
+        this._messages.AddRange(message);
 
         if (this._messages.Count == 2)
         {
@@ -231,6 +238,14 @@ You'll create a workflow that:
 - Aggregates the different result types (float and int) into a final output
 - Demonstrates how the framework handles different result types from concurrent executors
 
+### Concepts Covered
+
+- [Executors](../../user-guide/workflows/core-concepts/executors.md)
+- [Fan-out Edges](../../user-guide/workflows/core-concepts/edges.md#fan-out-edges)
+- [Fan-in Edges](../../user-guide/workflows/core-concepts/edges.md#fan-in-edges)
+- [Workflow Builder](../../user-guide/workflows/core-concepts/workflows.md)
+- [Events](../../user-guide/workflows/core-concepts/events.md)
+
 ## Prerequisites
 
 - Python 3.10 or later