Merge branch 'main' into dmkorolev/threads

dotnet/Directory.Packages.props

@@ -15,7 +15,7 @@
     <PackageVersion Include="Aspire.Hosting.AppHost" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="Aspire.Hosting.Azure.CognitiveServices" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="Aspire.Microsoft.Azure.Cosmos" Version="$(AspireAppHostSdkVersion)" />
-    <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0-beta.435" />
+    <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0-beta.440" />
     <!-- Azure.* -->
     <PackageVersion Include="Azure.AI.Projects" Version="1.2.0-beta.3" />
     <PackageVersion Include="Azure.AI.Projects.OpenAI" Version="1.0.0-beta.3" />
@@ -81,6 +81,10 @@
     <PackageVersion Include="Microsoft.SemanticKernel.Plugins.OpenApi" Version="1.67.0" />
     <!-- Agent SDKs -->
     <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.2.41" />
+    <!-- M365 Agents SDK -->
+    <PackageVersion Include="AdaptiveCards" Version="3.1.0" />
+    <PackageVersion Include="Microsoft.Agents.Authentication.Msal" Version="1.2.41" />
+    <PackageVersion Include="Microsoft.Agents.Hosting.AspNetCore" Version="1.2.41" />
     <!-- A2A -->
     <PackageVersion Include="A2A" Version="0.3.3-preview" />
     <PackageVersion Include="A2A.AspNetCore" Version="0.3.3-preview" />

dotnet/agent-framework-dotnet.slnx

@@ -103,11 +103,11 @@
     <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step03_CustomRAGDataSource/AgentWithRAG_Step03_CustomRAGDataSource.csproj" />
   </Folder>
   <Folder Name="/Samples/GettingStarted/FoundryAgents/">
+    <File Path="samples/GettingStarted/FoundryAgents/README.md" />
     <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step01.1_Basics/FoundryAgents_Step01.1_Basics.csproj" />
     <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step01.2_Running/FoundryAgents_Step01.2_Running.csproj" />
     <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step02_MultiturnConversation/FoundryAgents_Step02_MultiturnConversation.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step03.1_UsingFunctionTools/FoundryAgents_Step03.1_UsingFunctionTools.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step03.2_UsingFunctionTools_FromOpenAPI/FoundryAgents_Step03.2_UsingFunctionTools_FromOpenAPI.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step03_UsingFunctionTools/FoundryAgents_Step03_UsingFunctionTools.csproj" />
     <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step04_UsingFunctionToolsWithApprovals/FoundryAgents_Step04_UsingFunctionToolsWithApprovals.csproj" />
     <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step05_StructuredOutput/FoundryAgents_Step05_StructuredOutput.csproj" />
     <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step06_PersistedConversations/FoundryAgents_Step06_PersistedConversations.csproj" />
@@ -191,7 +191,7 @@
     <Project Path="samples/GettingStarted/Workflows/Observability/WorkflowAsAnAgent/WorkflowAsAnAgentObservability.csproj" />
   </Folder>
   <Folder Name="/Samples/GettingStarted/Workflows/Visualization/">
-    <Project Path="samples/GettingStarted/Workflows/Visualization/Visualization.csproj" Id="99bf0bc6-2440-428e-b3e7-d880e4b7a5fd" />
+    <Project Path="samples/GettingStarted/Workflows/Visualization/Visualization.csproj" />
   </Folder>
   <Folder Name="/Samples/GettingStarted/Workflows/_Foundational/">
     <Project Path="samples/GettingStarted/Workflows/_Foundational/01_ExecutorsAndEdges/01_ExecutorsAndEdges.csproj" />
@@ -208,6 +208,9 @@
     <Project Path="samples/HostedAgents/AgentWithHostedMCP/AgentWithHostedMCP.csproj" />
     <Project Path="samples/HostedAgents/AgentWithTextSearchRag/AgentWithTextSearchRag.csproj" />
   </Folder>
+  <Folder Name="/Samples/M365Agent/">
+    <Project Path="samples/M365Agent/M365Agent.csproj" />
+  </Folder>
   <Folder Name="/Solution Items/">
     <File Path=".editorconfig" />
     <File Path=".gitignore" />
@@ -371,6 +374,7 @@
     <Project Path="tests/Microsoft.Agents.AI.AGUI.UnitTests/Microsoft.Agents.AI.AGUI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.AzureAI.UnitTests/Microsoft.Agents.AI.AzureAI.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.DevUI.UnitTests/Microsoft.Agents.AI.DevUI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DurableTask.UnitTests/Microsoft.Agents.AI.DurableTask.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/Microsoft.Agents.AI.Hosting.A2A.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests.csproj" />

dotnet/samples/AgentWebChat/AgentWebChat.AgentHost/ActorFrameworkWebApplicationExtensions.cs

@@ -2,7 +2,7 @@
 
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json.Serialization;
-using Microsoft.Agents.AI.Hosting;
+using Microsoft.Agents.AI;
 
 namespace AgentWebChat.AgentHost;
 
@@ -10,24 +10,24 @@ internal static class ActorFrameworkWebApplicationExtensions
 {
     public static void MapAgentDiscovery(this IEndpointRouteBuilder endpoints, [StringSyntax("Route")] string path)
     {
-        var routeGroup = endpoints.MapGroup(path);
-        routeGroup.MapGet("/", async (
-            AgentCatalog agentCatalog,
-            CancellationToken cancellationToken) =>
-            {
-                var results = new List<AgentDiscoveryCard>();
-                await foreach (var result in agentCatalog.GetAgentsAsync(cancellationToken).ConfigureAwait(false))
-                {
-                    results.Add(new AgentDiscoveryCard
-                    {
-                        Name = result.Name!,
-                        Description = result.Description,
-                    });
-                }
+        var registeredAIAgents = endpoints.ServiceProvider.GetKeyedServices<AIAgent>(KeyedService.AnyKey);
 
-                return Results.Ok(results);
-            })
-            .WithName("GetAgents");
+        var routeGroup = endpoints.MapGroup(path);
+        routeGroup.MapGet("/", async (CancellationToken cancellationToken) =>
+        {
+            var results = new List<AgentDiscoveryCard>();
+            foreach (var result in registeredAIAgents)
+            {
+                results.Add(new AgentDiscoveryCard
+                {
+                    Name = result.Name!,
+                    Description = result.Description,
+                });
+            }
+
+            return Results.Ok(results);
+        })
+        .WithName("GetAgents");
     }
 
     internal sealed class AgentDiscoveryCard

dotnet/samples/AgentWebChat/AgentWebChat.AgentHost/AgentWebChat.AgentHost.csproj

@@ -8,6 +8,7 @@
   </PropertyGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.DevUI\Microsoft.Agents.AI.DevUI.csproj" />
     <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
     <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Abstractions\Microsoft.Agents.AI.Abstractions.csproj" />
     <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Hosting\Microsoft.Agents.AI.Hosting.csproj" />

dotnet/samples/AgentWebChat/AgentWebChat.AgentHost/Program.cs

@@ -5,6 +5,7 @@ using AgentWebChat.AgentHost;
 using AgentWebChat.AgentHost.Custom;
 using AgentWebChat.AgentHost.Utilities;
 using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.DevUI;
 using Microsoft.Agents.AI.Hosting;
 using Microsoft.Agents.AI.Workflows;
 using Microsoft.Extensions.AI;
@@ -21,6 +22,13 @@ builder.Services.AddProblemDetails();
 // Configure the chat model and our agent.
 builder.AddKeyedChatClient("chat-model");
 
+// Add DevUI services
+builder.AddDevUI();
+
+// Add OpenAI services
+builder.AddOpenAIChatCompletions();
+builder.AddOpenAIResponses();
+
 var pirateAgentBuilder = builder.AddAIAgent(
     "pirate",
     instructions: "You are a pirate. Speak like a pirate",
@@ -95,8 +103,48 @@ var scienceConcurrentWorkflow = builder.AddWorkflow("science-concurrent-workflow
     return AgentWorkflowBuilder.BuildConcurrent(workflowName: key, agents: agents);
 }).AddAsAIAgent();
 
-builder.AddOpenAIChatCompletions();
-builder.AddOpenAIResponses();
+builder.AddWorkflow("nonAgentWorkflow", (sp, key) =>
+{
+    List<IHostedAgentBuilder> usedAgents = [pirateAgentBuilder, chemistryAgent];
+    var agents = usedAgents.Select(ab => sp.GetRequiredKeyedService<AIAgent>(ab.Name));
+    return AgentWorkflowBuilder.BuildSequential(workflowName: key, agents: agents);
+});
+
+builder.Services.AddKeyedSingleton("NonAgentAndNonmatchingDINameWorkflow", (sp, key) =>
+{
+    List<IHostedAgentBuilder> usedAgents = [pirateAgentBuilder, chemistryAgent];
+    var agents = usedAgents.Select(ab => sp.GetRequiredKeyedService<AIAgent>(ab.Name));
+    return AgentWorkflowBuilder.BuildSequential(workflowName: "random-name", agents: agents);
+});
+
+builder.Services.AddSingleton<AIAgent>(sp =>
+{
+    var chatClient = sp.GetRequiredKeyedService<IChatClient>("chat-model");
+    return new ChatClientAgent(chatClient, name: "default-agent", instructions: "you are a default agent.");
+});
+
+builder.Services.AddKeyedSingleton<AIAgent>("my-di-nonmatching-agent", (sp, name) =>
+{
+    var chatClient = sp.GetRequiredKeyedService<IChatClient>("chat-model");
+    return new ChatClientAgent(
+        chatClient,
+        name: "some-random-name", // demonstrating registration can be different for DI and actual agent
+        instructions: "you are a dependency inject agent. Tell me all about dependency injection.");
+});
+
+builder.Services.AddKeyedSingleton<AIAgent>("my-di-matchingname-agent", (sp, name) =>
+{
+    if (name is not string nameStr)
+    {
+        throw new NotSupportedException("Name should be passed as a key");
+    }
+
+    var chatClient = sp.GetRequiredKeyedService<IChatClient>("chat-model");
+    return new ChatClientAgent(
+        chatClient,
+        name: nameStr, // demonstrating registration with the same name
+        instructions: "you are a dependency inject agent. Tell me all about dependency injection.");
+});
 
 var app = builder.Build();
 
@@ -118,7 +166,10 @@ app.MapA2A(knightsKnavesAgentBuilder, path: "/a2a/knights-and-knaves", agentCard
     // Url = "http://localhost:5390/a2a/knights-and-knaves"
 });
 
+app.MapDevUI();
+
 app.MapOpenAIResponses();
+app.MapOpenAIConversations();
 
 app.MapOpenAIChatCompletions(pirateAgentBuilder);
 app.MapOpenAIChatCompletions(knightsKnavesAgentBuilder);

dotnet/samples/AgentWebChat/AgentWebChat.AppHost/Program.cs

@@ -9,7 +9,9 @@ var azOpenAiResourceGroup = builder.AddParameterFromConfiguration("AzureOpenAIRe
 var chatModel = builder.AddAIModel("chat-model").AsAzureOpenAI("gpt-4o", o => o.AsExisting(azOpenAiResource, azOpenAiResourceGroup));
 
 var agentHost = builder.AddProject<Projects.AgentWebChat_AgentHost>("agenthost")
-        .WithReference(chatModel);
+    .WithHttpEndpoint(name: "devui")
+    .WithUrlForEndpoint("devui", (url) => new() { Url = "/devui", DisplayText = "Dev UI" })
+    .WithReference(chatModel);
 
 builder.AddProject<Projects.AgentWebChat_Web>("webfrontend")
     .WithExternalHttpEndpoints()

dotnet/samples/AzureFunctions/01_SingleAgent/README.md

@@ -47,7 +47,7 @@ curl -X POST http://localhost:7071/api/agents/Joker/run \
 To continue a conversation, include the `thread_id` in the query string or JSON body:
 
 ```bash
-curl -X POST "http://localhost:7071/api/agents/Joker/run?thread_id=@dafx-joker@your-thread-id" \
+curl -X POST "http://localhost:7071/api/agents/Joker/run?thread_id=your-thread-id" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{"message": "Tell me another one."}'
@@ -64,7 +64,7 @@ The expected `application/json` output will look something like:
 ```json
 {
   "status": 200,
-  "thread_id": "@dafx-joker@your-thread-id",
+  "thread_id": "ee6e47a0-f24b-40b1-ade8-16fcebb9eb40",
   "response": {
     "Messages": [
       {

dotnet/samples/AzureFunctions/06_LongRunningTools/README.md

@@ -52,7 +52,7 @@ The response will be a text string that looks something like the following, indi
 ```http
 HTTP/1.1 200 OK
 Content-Type: text/plain
-x-ms-thread-id: @publisher@351ec855-7f4d-4527-a60d-498301ced36d
+x-ms-thread-id: 351ec855-7f4d-4527-a60d-498301ced36d
 
 ```
 

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step01.1_Basics/Program.cs

@@ -11,14 +11,15 @@ using Microsoft.Extensions.AI;
 string endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
 string deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
-const string JokerInstructions = "You are good at telling jokes.";
+const string JokerInstructionsV1 = "You are good at telling jokes.";
+const string JokerInstructionsV2 = "You are extremely hilarious at telling jokes.";
 const string JokerName = "JokerAgent";
 
 // Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
 AIProjectClient aiProjectClient = new(new Uri(endpoint), new AzureCliCredential());
 
 // Define the agent you want to create. (Prompt Agent in this case)
-AgentVersionCreationOptions options = new(new PromptAgentDefinition(model: deploymentName) { Instructions = JokerInstructions });
+AgentVersionCreationOptions options = new(new PromptAgentDefinition(model: deploymentName) { Instructions = JokerInstructionsV1 });
 
 // Azure.AI.Agents SDK creates and manages agent by name and versions.
 // You can create a server side agent version with the Azure.AI.Agents SDK client below.
@@ -32,8 +33,8 @@ AgentVersion agentVersion = aiProjectClient.Agents.CreateAgentVersion(agentName:
 // You can retrieve an AIAgent for an already created server side agent version.
 AIAgent jokerAgentV1 = aiProjectClient.GetAIAgent(agentVersion);
 
-// You can also create another AIAgent version (V2) by providing the same name with a different definition.
-AIAgent jokerAgentV2 = aiProjectClient.CreateAIAgent(name: JokerName, model: deploymentName, instructions: JokerInstructions + "V2");
+// You can also create another AIAgent version (V2) by providing the same name with a different definition/instruction.
+AIAgent jokerAgentV2 = aiProjectClient.CreateAIAgent(name: JokerName, model: deploymentName, instructions: JokerInstructionsV2);
 
 // You can also get the AIAgent latest version by just providing its name.
 AIAgent jokerAgentLatest = aiProjectClient.GetAIAgent(name: JokerName);
@@ -43,11 +44,7 @@ AgentVersion latestVersion = jokerAgentLatest.GetService<AgentVersion>()!;
 Console.WriteLine($"Latest agent version id: {latestVersion.Id}");
 
 // Once you have the AIAgent, you can invoke it like any other AIAgent.
-AgentThread thread = jokerAgentLatest.GetNewThread();
-Console.WriteLine(await jokerAgentLatest.RunAsync("Tell me a joke about a pirate.", thread));
-
-// This will use the same thread to continue the conversation.
-Console.WriteLine(await jokerAgentLatest.RunAsync("Now tell me a joke about a cat and a dog using last joke as the anchor.", thread));
+Console.WriteLine(await jokerAgentLatest.RunAsync("Tell me a joke about a pirate."));
 
 // Cleanup by agent name removes both agent versions created (jokerAgentV1 + jokerAgentV2).
 await aiProjectClient.Agents.DeleteAgentAsync(jokerAgentV1.Name);

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step01.2_Running/Program.cs

@@ -26,13 +26,8 @@ AgentVersion agentVersion = aiProjectClient.Agents.CreateAgentVersion(agentName:
 // You can retrieve an AIAgent for a already created server side agent version.
 AIAgent jokerAgent = aiProjectClient.GetAIAgent(agentVersion);
 
-// Invoke the agent and output the text result.
-AgentThread thread = jokerAgent.GetNewThread();
-Console.WriteLine(await jokerAgent.RunAsync("Tell me a joke about a pirate.", thread));
-
 // Invoke the agent with streaming support.
-thread = jokerAgent.GetNewThread();
-await foreach (AgentRunResponseUpdate update in jokerAgent.RunStreamingAsync("Tell me a joke about a pirate.", thread))
+await foreach (AgentRunResponseUpdate update in jokerAgent.RunStreamingAsync("Tell me a joke about a pirate."))
 {
     Console.WriteLine(update);
 }

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step03.2_UsingFunctionTools_FromOpenAPI/FoundryAgents_Step03.2_UsingFunctionTools_FromOpenAPI.csproj

@@ -1,27 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <OutputType>Exe</OutputType>
-    <TargetFramework>net9.0</TargetFramework>
-
-    <Nullable>enable</Nullable>
-    <ImplicitUsings>enable</ImplicitUsings>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <PackageReference Include="Azure.AI.Projects" />
-    <PackageReference Include="Azure.Identity" />
-    <PackageReference Include="Microsoft.SemanticKernel.Plugins.OpenApi" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <None Update="OpenAPISpec.json">
-      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
-    </None>
-  </ItemGroup>
-
-</Project>

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step03.2_UsingFunctionTools_FromOpenAPI/OpenAPISpec.json

@@ -1,354 +0,0 @@
-{
-    "openapi": "3.0.1",
-    "info": {
-        "title": "Github Versions API",
-        "version": "1.0.0"
-    },
-    "servers": [
-        {
-            "url": "https://api.github.com"
-        }
-    ],
-    "components": {
-        "schemas": {
-            "basic-error": {
-                "title": "Basic Error",
-                "description": "Basic Error",
-                "type": "object",
-                "properties": {
-                    "message": {
-                        "type": "string"
-                    },
-                    "documentation_url": {
-                        "type": "string"
-                    },
-                    "url": {
-                        "type": "string"
-                    },
-                    "status": {
-                        "type": "string"
-                    }
-                }
-            },
-            "label": {
-                "title": "Label",
-                "description": "Color-coded labels help you categorize and filter your issues (just like labels in Gmail).",
-                "type": "object",
-                "properties": {
-                    "id": {
-                        "description": "Unique identifier for the label.",
-                        "type": "integer",
-                        "format": "int64",
-                        "example": 208045946
-                    },
-                    "node_id": {
-                        "type": "string",
-                        "example": "MDU6TGFiZWwyMDgwNDU5NDY="
-                    },
-                    "url": {
-                        "description": "URL for the label",
-                        "example": "https://api.github.com/repositories/42/labels/bug",
-                        "type": "string",
-                        "format": "uri"
-                    },
-                    "name": {
-                        "description": "The name of the label.",
-                        "example": "bug",
-                        "type": "string"
-                    },
-                    "description": {
-                        "description": "Optional description of the label, such as its purpose.",
-                        "type": "string",
-                        "example": "Something isn't working",
-                        "nullable": true
-                    },
-                    "color": {
-                        "description": "6-character hex code, without the leading #, identifying the color",
-                        "example": "FFFFFF",
-                        "type": "string"
-                    },
-                    "default": {
-                        "description": "Whether this label comes by default in a new repository.",
-                        "type": "boolean",
-                        "example": true
-                    }
-                },
-                "required": [
-                    "id",
-                    "node_id",
-                    "url",
-                    "name",
-                    "description",
-                    "color",
-                    "default"
-                ]
-            },
-            "tag": {
-                "title": "Tag",
-                "description": "Tag",
-                "type": "object",
-                "properties": {
-                    "name": {
-                        "type": "string",
-                        "example": "v0.1"
-                    },
-                    "commit": {
-                        "type": "object",
-                        "properties": {
-                            "sha": {
-                                "type": "string"
-                            },
-                            "url": {
-                                "type": "string",
-                                "format": "uri"
-                            }
-                        },
-                        "required": [
-                            "sha",
-                            "url"
-                        ]
-                    },
-                    "zipball_url": {
-                        "type": "string",
-                        "format": "uri",
-                        "example": "https://github.com/octocat/Hello-World/zipball/v0.1"
-                    },
-                    "tarball_url": {
-                        "type": "string",
-                        "format": "uri",
-                        "example": "https://github.com/octocat/Hello-World/tarball/v0.1"
-                    },
-                    "node_id": {
-                        "type": "string"
-                    }
-                },
-                "required": [
-                    "name",
-                    "node_id",
-                    "commit",
-                    "zipball_url",
-                    "tarball_url"
-                ]
-            }
-        },
-        "examples": {
-            "label-items": {
-                "value": [
-                    {
-                        "id": 208045946,
-                        "node_id": "MDU6TGFiZWwyMDgwNDU5NDY=",
-                        "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
-                        "name": "bug",
-                        "description": "Something isn't working",
-                        "color": "f29513",
-                        "default": true
-                    },
-                    {
-                        "id": 208045947,
-                        "node_id": "MDU6TGFiZWwyMDgwNDU5NDc=",
-                        "url": "https://api.github.com/repos/octocat/Hello-World/labels/enhancement",
-                        "name": "enhancement",
-                        "description": "New feature or request",
-                        "color": "a2eeef",
-                        "default": false
-                    }
-                ]
-            },
-            "tag-items": {
-                "value": [
-                    {
-                        "name": "v0.1",
-                        "commit": {
-                            "sha": "c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc",
-                            "url": "https://api.github.com/repos/octocat/Hello-World/commits/c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc"
-                        },
-                        "zipball_url": "https://github.com/octocat/Hello-World/zipball/v0.1",
-                        "tarball_url": "https://github.com/octocat/Hello-World/tarball/v0.1",
-                        "node_id": "MDQ6VXNlcjE="
-                    }
-                ]
-            }
-        },
-        "parameters": {
-            "owner": {
-                "name": "owner",
-                "description": "The account owner of the repository. The name is not case sensitive.",
-                "in": "path",
-                "required": true,
-                "schema": {
-                    "type": "string"
-                }
-            },
-            "repo": {
-                "name": "repo",
-                "description": "The name of the repository without the `.git` extension. The name is not case sensitive.",
-                "in": "path",
-                "required": true,
-                "schema": {
-                    "type": "string"
-                }
-            },
-            "per-page": {
-                "name": "per_page",
-                "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"",
-                "in": "query",
-                "schema": {
-                    "type": "integer",
-                    "default": 30
-                }
-            },
-            "page": {
-                "name": "page",
-                "description": "The page number of the results to fetch. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"",
-                "in": "query",
-                "schema": {
-                    "type": "integer",
-                    "default": 1
-                }
-            }
-        },
-        "responses": {
-            "not_found": {
-                "description": "Resource not found",
-                "content": {
-                    "application/json": {
-                        "schema": {
-                            "$ref": "#/components/schemas/basic-error"
-                        }
-                    }
-                }
-            }
-        },
-        "headers": {
-            "link": {
-                "example": "<https://api.github.com/resource?page=2>; rel=\"next\", <https://api.github.com/resource?page=5>; rel=\"last\"",
-                "schema": {
-                    "type": "string"
-                }
-            }
-        }
-    },
-    "paths": {
-        "/repos/{owner}/{repo}/tags": {
-            "get": {
-                "summary": "List repository tags",
-                "description": "",
-                "tags": [
-                    "repos"
-                ],
-                "operationId": "repos/list-tags",
-                "externalDocs": {
-                    "description": "API method documentation",
-                    "url": "https://docs.github.com/rest/repos/repos#list-repository-tags"
-                },
-                "parameters": [
-                    {
-                        "$ref": "#/components/parameters/owner"
-                    },
-                    {
-                        "$ref": "#/components/parameters/repo"
-                    },
-                    {
-                        "$ref": "#/components/parameters/per-page"
-                    },
-                    {
-                        "$ref": "#/components/parameters/page"
-                    }
-                ],
-                "responses": {
-                    "200": {
-                        "description": "Response",
-                        "content": {
-                            "application/json": {
-                                "schema": {
-                                    "type": "array",
-                                    "items": {
-                                        "$ref": "#/components/schemas/tag"
-                                    }
-                                },
-                                "examples": {
-                                    "default": {
-                                        "$ref": "#/components/examples/tag-items"
-                                    }
-                                }
-                            }
-                        },
-                        "headers": {
-                            "Link": {
-                                "$ref": "#/components/headers/link"
-                            }
-                        }
-                    }
-                },
-                "x-github": {
-                    "githubCloudOnly": false,
-                    "enabledForGitHubApps": true,
-                    "category": "repos",
-                    "subcategory": "repos"
-                }
-            }
-        },
-        "/repos/{owner}/{repo}/labels": {
-            "get": {
-                "summary": "List labels for a repository",
-                "description": "Lists all labels for a repository.",
-                "tags": [
-                    "issues"
-                ],
-                "operationId": "issues/list-labels-for-repo",
-                "externalDocs": {
-                    "description": "API method documentation",
-                    "url": "https://docs.github.com/rest/issues/labels#list-labels-for-a-repository"
-                },
-                "parameters": [
-                    {
-                        "$ref": "#/components/parameters/owner"
-                    },
-                    {
-                        "$ref": "#/components/parameters/repo"
-                    },
-                    {
-                        "$ref": "#/components/parameters/per-page"
-                    },
-                    {
-                        "$ref": "#/components/parameters/page"
-                    }
-                ],
-                "responses": {
-                    "200": {
-                        "description": "Response",
-                        "content": {
-                            "application/json": {
-                                "schema": {
-                                    "type": "array",
-                                    "items": {
-                                        "$ref": "#/components/schemas/label"
-                                    }
-                                },
-                                "examples": {
-                                    "default": {
-                                        "$ref": "#/components/examples/label-items"
-                                    }
-                                }
-                            }
-                        },
-                        "headers": {
-                            "Link": {
-                                "$ref": "#/components/headers/link"
-                            }
-                        }
-                    },
-                    "404": {
-                        "$ref": "#/components/responses/not_found"
-                    }
-                },
-                "x-github": {
-                    "githubCloudOnly": false,
-                    "enabledForGitHubApps": true,
-                    "category": "issues",
-                    "subcategory": "labels"
-                }
-            }
-        }
-    }
-}

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step03.2_UsingFunctionTools_FromOpenAPI/Program.cs

@@ -1,38 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample demonstrates how to use an agent with function tools provided via an OpenAPI spec.
-// It uses functionality from Semantic Kernel to parse the OpenAPI spec and create function tools to use with the Agent Framework Agent.
-
-using Azure.AI.Projects;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using Microsoft.SemanticKernel;
-using Microsoft.SemanticKernel.Plugins.OpenApi;
-
-string endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
-string deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-
-// Load the OpenAPI Spec from a file.
-KernelPlugin plugin = await OpenApiKernelPluginFactory.CreateFromOpenApiAsync("github", "OpenAPISpec.json");
-
-// Convert the Semantic Kernel plugin to Agent Framework function tools.
-// This requires a dummy Kernel instance, since KernelFunctions cannot execute without one.
-Kernel kernel = new();
-List<AITool> tools = plugin.Select(x => x.WithKernel(kernel)).Cast<AITool>().ToList();
-
-const string AssistantInstructions = "You are a helpful assistant that can query GitHub repositories.";
-const string AssistantName = "GitHubAssistant";
-
-// Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
-AIProjectClient aiProjectClient = new(new Uri(endpoint), new AzureCliCredential());
-
-// Create AIAgent directly
-AIAgent agent = await aiProjectClient.CreateAIAgentAsync(name: AssistantName, model: deploymentName, instructions: AssistantInstructions, tools: tools);
-
-// Run the agent with the OpenAPI function tools.
-AgentThread thread = agent.GetNewThread();
-Console.WriteLine(await agent.RunAsync("Please list the names, colors and descriptions of all the labels available in the microsoft/agent-framework repository on github.", thread));
-
-// Cleanup by agent name removes the agent version created.
-await aiProjectClient.Agents.DeleteAgentAsync(agent.Name);

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step03.2_UsingFunctionTools_FromOpenAPI/README.md

@@ -1,49 +0,0 @@
-# Using Function Tools from OpenAPI Specifications
-
-This sample demonstrates how to create function tools from an OpenAPI specification and use them with AI agents.
-
-## What this sample demonstrates
-
-- Loading OpenAPI specifications from files
-- Converting OpenAPI specifications to Semantic Kernel plugins
-- Converting Semantic Kernel plugins to AI function tools
-- Using OpenAPI-based function tools with AI agents
-- Managing agent lifecycle (creation and deletion)
-
-## Prerequisites
-
-Before you begin, ensure you have the following prerequisites:
-
-- .NET 8.0 SDK or later
-- Azure Foundry service endpoint and deployment configured
-- Azure CLI installed and authenticated (for Azure credential authentication)
-
-**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
-
-Set the following environment variables:
-
-```powershell
-$env:AZURE_FOUNDRY_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Azure Foundry resource endpoint
-$env:AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
-```
-
-## Run the sample
-
-Navigate to the FoundryAgents sample directory and run:
-
-```powershell
-cd dotnet/samples/GettingStarted/FoundryAgents
-dotnet run --project .\FoundryAgents_Step03.2_UsingFunctionTools_FromOpenAPI
-```
-
-## Expected behavior
-
-The sample will:
-
-1. Load the OpenAPI specification from OpenAPISpec.json (GitHub API)
-2. Convert the OpenAPI spec to Semantic Kernel plugins
-3. Create an agent named "GitHubAssistant" with the OpenAPI-based function tools
-4. Run the agent with a prompt to query GitHub repositories
-5. The agent will invoke the appropriate OpenAPI function tools to retrieve data
-6. Clean up resources by deleting the agent
-

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step03_UsingFunctionTools/Program.cs

@@ -26,18 +26,26 @@ AIProjectClient aiProjectClient = new(new Uri(endpoint), new AzureCliCredential(
 AITool tool = AIFunctionFactory.Create(GetWeather);
 
 // Create AIAgent directly
-AIAgent agent = await aiProjectClient.CreateAIAgentAsync(name: AssistantName, model: deploymentName, instructions: AssistantInstructions, tools: [tool]);
+var newAgent = await aiProjectClient.CreateAIAgentAsync(name: AssistantName, model: deploymentName, instructions: AssistantInstructions, tools: [tool]);
+
+// Getting an already existing agent by name with tools.
+/* 
+ * IMPORTANT: Since agents that are stored in the server only know the definition of the function tools (JSON Schema),
+ * you need to provided all invocable function tools when retrieving the agent so it can invoke them automatically.
+ * If no invocable tools are provided, the function calling needs to handled manually.
+ */
+var existingAgent = await aiProjectClient.GetAIAgentAsync(name: AssistantName, tools: [tool]);
 
 // Non-streaming agent interaction with function tools.
-AgentThread thread = agent.GetNewThread();
-Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?", thread));
+AgentThread thread = existingAgent.GetNewThread();
+Console.WriteLine(await existingAgent.RunAsync("What is the weather like in Amsterdam?", thread));
 
 // Streaming agent interaction with function tools.
-thread = agent.GetNewThread();
-await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync("What is the weather like in Amsterdam?", thread))
+thread = existingAgent.GetNewThread();
+await foreach (AgentRunResponseUpdate update in existingAgent.RunStreamingAsync("What is the weather like in Amsterdam?", thread))
 {
     Console.WriteLine(update);
 }
 
 // Cleanup by agent name removes the agent version created.
-await aiProjectClient.Agents.DeleteAgentAsync(agent.Name);
+await aiProjectClient.Agents.DeleteAgentAsync(existingAgent.Name);

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step04_UsingFunctionToolsWithApprovals/Program.cs

@@ -25,7 +25,7 @@ const string AssistantName = "WeatherAssistant";
 // Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
 AIProjectClient aiProjectClient = new(new Uri(endpoint), new AzureCliCredential());
 
-ApprovalRequiredAIFunction approvalTool = new(AIFunctionFactory.Create(GetWeather));
+ApprovalRequiredAIFunction approvalTool = new(AIFunctionFactory.Create(GetWeather, name: nameof(GetWeather)));
 
 // Create AIAgent directly
 AIAgent agent = await aiProjectClient.CreateAIAgentAsync(name: AssistantName, model: deploymentName, instructions: AssistantInstructions, tools: [approvalTool]);

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step10_UsingImages/FoundryAgents_Step10_UsingImages.csproj

@@ -16,5 +16,11 @@
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
   </ItemGroup>
+
+  <ItemGroup>
+    <None Update="Assets\walkway.jpg">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
   
 </Project>

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step10_UsingImages/Program.cs

@@ -8,7 +8,7 @@ using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
 string endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
-string deploymentName = System.Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o";
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o";
 
 const string VisionInstructions = "You are a helpful agent that can analyze images";
 const string VisionName = "VisionAgent";
@@ -21,7 +21,7 @@ AIAgent agent = aiProjectClient.CreateAIAgent(name: VisionName, model: deploymen
 
 ChatMessage message = new(ChatRole.User, [
     new TextContent("What do you see in this image?"),
-    new UriContent("https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg", "image/jpeg")
+    new DataContent(File.ReadAllBytes("assets/walkway.jpg"), "image/jpeg")
 ]);
 
 AgentThread thread = agent.GetNewThread();

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step14_CodeInterpreter/Program.cs

@@ -55,7 +55,7 @@ AgentRunResponse response = await agentOption1.RunAsync("I need to solve the equ
 // AgentRunResponse response = await agentOption2.RunAsync("I need to solve the equation sin(x) + x^2 = 42");
 
 // Get the CodeInterpreterToolCallContent
-CodeInterpreterToolCallContent? toolCallContent = response.Messages.SelectMany(m => m.Contents).OfType<CodeInterpreterToolCallContent>().SingleOrDefault();
+CodeInterpreterToolCallContent? toolCallContent = response.Messages.SelectMany(m => m.Contents).OfType<CodeInterpreterToolCallContent>().FirstOrDefault();
 if (toolCallContent?.Inputs is not null)
 {
     DataContent? codeInput = toolCallContent.Inputs.OfType<DataContent>().FirstOrDefault();

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step15_ComputerUse/Program.cs

@@ -15,8 +15,8 @@ internal sealed class Program
 {
     private static async Task Main(string[] args)
     {
-        string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-        string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "computer-use-preview";
+        string endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
+        string deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "computer-use-preview";
 
         // Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
         AIProjectClient aiProjectClient = new(new Uri(endpoint), new AzureCliCredential());

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step15_ComputerUse/README.md

@@ -24,8 +24,8 @@ Before you begin, ensure you have the following prerequisites:
 Set the following environment variables:
 
 ```powershell
-$env:AZURE_OPENAI_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Azure Foundry resource endpoint
-$env:AZURE_OPENAI_DEPLOYMENT_NAME="computer-use-preview"  # Optional, defaults to computer-use-preview
+$env:AZURE_FOUNDRY_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Azure Foundry resource endpoint
+$env:AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME="computer-use-preview"  # Optional, defaults to computer-use-preview
 ```
 
 ## Run the sample

dotnet/samples/GettingStarted/FoundryAgents/README.md

@@ -0,0 +1,82 @@
+# Getting started with Foundry Agents
+
+The getting started with Foundry Agents samples demonstrate the fundamental concepts and functionalities
+of Azure Foundry Agents and can be used with Azure Foundry as the AI provider.
+
+These samples showcase how to work with agents managed through Azure Foundry, including agent creation,
+versioning, multi-turn conversations, and advanced features like code interpretation and computer use.
+
+## Getting started with Foundry Agents prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 8.0 SDK or later
+- Azure Foundry service endpoint and project configured
+- Azure CLI installed and authenticated (for Azure credential authentication)
+
+**Note**: These samples use Azure Foundry Agents. For more information, see [Azure AI Foundry documentation](https://learn.microsoft.com/en-us/azure/ai-foundry/).
+
+**Note**: These samples use Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
+
+## Samples
+
+|Sample|Description|
+|---|---|
+|[Basics](./FoundryAgents_Step01.1_Basics/)|This sample demonstrates how to create and manage AI agents with versioning|
+|[Running a simple agent](./FoundryAgents_Step01.2_Running/)|This sample demonstrates how to create and run a basic Foundry agent|
+|[Multi-turn conversation](./FoundryAgents_Step02_MultiturnConversation/)|This sample demonstrates how to implement a multi-turn conversation with a Foundry agent|
+|[Using function tools](./FoundryAgents_Step03_UsingFunctionTools/)|This sample demonstrates how to use function tools with a Foundry agent|
+|[Using function tools with approvals](./FoundryAgents_Step04_UsingFunctionToolsWithApprovals/)|This sample demonstrates how to use function tools where approvals require human in the loop approvals before execution|
+|[Structured output](./FoundryAgents_Step05_StructuredOutput/)|This sample demonstrates how to use structured output with a Foundry agent|
+|[Persisted conversations](./FoundryAgents_Step06_PersistedConversations/)|This sample demonstrates how to persist conversations and reload them later|
+|[Observability](./FoundryAgents_Step07_Observability/)|This sample demonstrates how to add telemetry to a Foundry agent|
+|[Dependency injection](./FoundryAgents_Step08_DependencyInjection/)|This sample demonstrates how to add and resolve a Foundry agent with a dependency injection container|
+|[Using MCP client as tools](./FoundryAgents_Step09_UsingMcpClientAsTools/)|This sample demonstrates how to use MCP clients as tools with a Foundry agent|
+|[Using images](./FoundryAgents_Step10_UsingImages/)|This sample demonstrates how to use image multi-modality with a Foundry agent|
+|[Exposing as a function tool](./FoundryAgents_Step11_AsFunctionTool/)|This sample demonstrates how to expose a Foundry agent as a function tool|
+|[Using middleware](./FoundryAgents_Step12_Middleware/)|This sample demonstrates how to use middleware with a Foundry agent|
+|[Using plugins](./FoundryAgents_Step13_Plugins/)|This sample demonstrates how to use plugins with a Foundry agent|
+|[Code interpreter](./FoundryAgents_Step14_CodeInterpreter/)|This sample demonstrates how to use the code interpreter tool with a Foundry agent|
+|[Computer use](./FoundryAgents_Step15_ComputerUse/)|This sample demonstrates how to use computer use capabilities with a Foundry agent|
+
+## Running the samples from the console
+
+To run the samples, navigate to the desired sample directory, e.g.
+
+```powershell
+cd FoundryAgents_Step01.2_Running
+```
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_FOUNDRY_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Azure Foundry resource endpoint
+$env:AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
+```
+
+If the variables are not set, you will be prompted for the values when running the samples.
+
+Execute the following command to build the sample:
+
+```powershell
+dotnet build
+```
+
+Execute the following command to run the sample:
+
+```powershell
+dotnet run --no-build
+```
+
+Or just build and run in one step:
+
+```powershell
+dotnet run
+```
+
+## Running the samples from Visual Studio
+
+Open the solution in Visual Studio and set the desired sample project as the startup project. Then, run the project using the built-in debugger or by pressing `F5`.
+
+You will be prompted for any required environment variables if they are not already set.
+

dotnet/samples/GettingStarted/README.md

@@ -8,6 +8,7 @@ of the agent framework.
 |Sample|Description|
 |---|---|
 |[Agents](./Agents/README.md)|Step by step instructions for getting started with agents|
+|[Foundry Agents](./FoundryAgents/README.md)|Getting started with Azure Foundry Agents|
 |[Agent Providers](./AgentProviders/README.md)|Getting started with creating agents using various providers|
 |[Agents With Retrieval Augmented Generation (RAG)](./AgentWithRAG/README.md)|Adding Retrieval Augmented Generation (RAG) capabilities to your agents.|
 |[Agents With Memory](./AgentWithMemory/README.md)|Adding Memory capabilities to your agents.|

dotnet/samples/M365Agent/AFAgentApplication.cs

@@ -0,0 +1,188 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using AdaptiveCards;
+using M365Agent.Agents;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.Builder;
+using Microsoft.Agents.Builder.App;
+using Microsoft.Agents.Builder.State;
+using Microsoft.Agents.Core.Models;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace M365Agent;
+
+/// <summary>
+/// An adapter class that exposes a Microsoft Agent Framework <see cref="AIAgent"/> as a M365 Agent SDK <see cref="AgentApplication"/>.
+/// </summary>
+internal sealed class AFAgentApplication : AgentApplication
+{
+    private readonly AIAgent _agent;
+    private readonly string? _welcomeMessage;
+
+    public AFAgentApplication(AIAgent agent, AgentApplicationOptions options, [FromKeyedServices("AFAgentApplicationWelcomeMessage")] string? welcomeMessage = null) : base(options)
+    {
+        this._agent = agent;
+        this._welcomeMessage = welcomeMessage;
+
+        this.OnConversationUpdate(ConversationUpdateEvents.MembersAdded, this.WelcomeMessageAsync);
+        this.OnActivity(ActivityTypes.Message, this.MessageActivityAsync, rank: RouteRank.Last);
+    }
+
+    /// <summary>
+    /// The main agent invocation method, where each user message triggers a call to the underlying <see cref="AIAgent"/>.
+    /// </summary>
+    private async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
+    {
+        // Start a Streaming Process 
+        await turnContext.StreamingResponse.QueueInformativeUpdateAsync("Working on a response for you", cancellationToken);
+
+        // Get the conversation history from turn state.
+        JsonElement threadElementStart = turnState.GetValue<JsonElement>("conversation.chatHistory");
+
+        // Deserialize the conversation history into an AgentThread, or create a new one if none exists.
+        AgentThread agentThread = threadElementStart.ValueKind is not JsonValueKind.Undefined and not JsonValueKind.Null
+            ? this._agent.DeserializeThread(threadElementStart, JsonUtilities.DefaultOptions)
+            : this._agent.GetNewThread();
+
+        ChatMessage chatMessage = HandleUserInput(turnContext);
+
+        // Invoke the WeatherForecastAgent to process the message
+        AgentRunResponse agentRunResponse = await this._agent.RunAsync(chatMessage, agentThread, cancellationToken: cancellationToken);
+
+        // Check for any user input requests in the response
+        // and turn them into adaptive cards in the streaming response.
+        List<Attachment>? attachments = null;
+        HandleUserInputRequests(agentRunResponse, ref attachments);
+
+        // Check for Adaptive Card content in the response messages
+        // and return them appropriately in the response.
+        var adaptiveCards = agentRunResponse.Messages.SelectMany(x => x.Contents).OfType<AdaptiveCardAIContent>().ToList();
+        if (adaptiveCards.Count > 0)
+        {
+            attachments ??= [];
+            attachments.Add(new Attachment()
+            {
+                ContentType = "application/vnd.microsoft.card.adaptive",
+                Content = adaptiveCards.First().AdaptiveCardJson,
+            });
+        }
+        else
+        {
+            turnContext.StreamingResponse.QueueTextChunk(agentRunResponse.Text);
+        }
+
+        // If created any adaptive cards, add them to the final message.
+        if (attachments is not null)
+        {
+            turnContext.StreamingResponse.FinalMessage = MessageFactory.Attachment(attachments);
+        }
+
+        // Serialize and save the updated conversation history back to turn state.
+        JsonElement threadElementEnd = agentThread.Serialize(JsonUtilities.DefaultOptions);
+        turnState.SetValue("conversation.chatHistory", threadElementEnd);
+
+        // End the streaming response
+        await turnContext.StreamingResponse.EndStreamAsync(cancellationToken);
+    }
+
+    /// <summary>
+    /// A method to show a welcome message when a new user joins the conversation.
+    /// </summary>
+    private async Task WelcomeMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(this._welcomeMessage))
+        {
+            return;
+        }
+
+        foreach (ChannelAccount member in turnContext.Activity.MembersAdded)
+        {
+            if (member.Id != turnContext.Activity.Recipient.Id)
+            {
+                await turnContext.SendActivityAsync(MessageFactory.Text(this._welcomeMessage), cancellationToken);
+            }
+        }
+    }
+
+    /// <summary>
+    /// When a user responds to a function approval request by clicking on a card, this method converts the response
+    /// into the appropriate approval or rejection <see cref="ChatMessage"/>.
+    /// </summary>
+    /// <param name="turnContext">The <see cref="ITurnContext"/> for the current turn.</param>
+    /// <returns>The <see cref="ChatMessage"/> to pass to the <see cref="AIAgent"/>.</returns>
+    private static ChatMessage HandleUserInput(ITurnContext turnContext)
+    {
+        // Check if this contains the function approval Adaptive Card response.
+        if (turnContext.Activity.Value is JsonElement valueElement
+            && valueElement.GetProperty("type").GetString() == "functionApproval"
+            && valueElement.GetProperty("approved") is JsonElement approvedJsonElement
+            && approvedJsonElement.ValueKind is JsonValueKind.True or JsonValueKind.False
+            && valueElement.GetProperty("requestJson") is JsonElement requestJsonElement
+            && requestJsonElement.ValueKind == JsonValueKind.String)
+        {
+            var requestContent = JsonSerializer.Deserialize<FunctionApprovalRequestContent>(requestJsonElement.GetString()!, JsonUtilities.DefaultOptions);
+
+            return new ChatMessage(ChatRole.User, [requestContent!.CreateResponse(approvedJsonElement.ValueKind == JsonValueKind.True)]);
+        }
+
+        return new ChatMessage(ChatRole.User, turnContext.Activity.Text);
+    }
+
+    /// <summary>
+    /// When the agent returns any user input requests, this method converts them into adaptive cards that
+    /// asks the user to approve or deny the requests.
+    /// </summary>
+    /// <param name="response">The <see cref="AgentRunResponse"/> that may contain the user input requests.</param>
+    /// <param name="attachments">The list of <see cref="Attachment"/> to which the adaptive cards will be added.</param>
+    private static void HandleUserInputRequests(AgentRunResponse response, ref List<Attachment>? attachments)
+    {
+        var userInputRequests = response.UserInputRequests.ToList();
+        if (userInputRequests.Count > 0)
+        {
+            foreach (var functionApprovalRequest in userInputRequests.OfType<FunctionApprovalRequestContent>())
+            {
+                var functionApprovalRequestJson = JsonSerializer.Serialize(functionApprovalRequest, JsonUtilities.DefaultOptions);
+
+                var card = new AdaptiveCard("1.5");
+                card.Body.Add(new AdaptiveTextBlock
+                {
+                    Text = "Function Call Approval Required",
+                    Size = AdaptiveTextSize.Large,
+                    Weight = AdaptiveTextWeight.Bolder,
+                    HorizontalAlignment = AdaptiveHorizontalAlignment.Center
+                });
+                card.Body.Add(new AdaptiveTextBlock
+                {
+                    Text = $"Function: {functionApprovalRequest.FunctionCall.Name}"
+                });
+                card.Body.Add(new AdaptiveActionSet()
+                {
+                    Actions =
+                    [
+                        new AdaptiveSubmitAction
+                        {
+                            Id = "Approve",
+                            Title = "Approve",
+                            Data = new { type = "functionApproval", approved = true, requestJson = functionApprovalRequestJson }
+                        },
+                        new AdaptiveSubmitAction
+                        {
+                            Id = "Deny",
+                            Title = "Deny",
+                            Data = new { type = "functionApproval", approved = false, requestJson = functionApprovalRequestJson }
+                        }
+                    ]
+                });
+
+                attachments ??= [];
+                attachments.Add(new Attachment()
+                {
+                    ContentType = "application/vnd.microsoft.card.adaptive",
+                    Content = card.ToJson(),
+                });
+            }
+        }
+    }
+}

dotnet/samples/M365Agent/Agents/AdaptiveCardAIContent.cs

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+using AdaptiveCards;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace M365Agent.Agents;
+
+/// <summary>
+/// An <see cref="AIContent"/> type allows an <see cref="AIAgent"/> to return adaptive cards as part of its response messages.
+/// </summary>
+internal sealed class AdaptiveCardAIContent : AIContent
+{
+    public AdaptiveCardAIContent(AdaptiveCard adaptiveCard)
+    {
+        this.AdaptiveCard = adaptiveCard ?? throw new ArgumentNullException(nameof(adaptiveCard));
+    }
+
+#pragma warning disable CS8618 // Non-nullable field must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring as nullable.
+    [JsonConstructor]
+    public AdaptiveCardAIContent(string adaptiveCardJson)
+    {
+        this.AdaptiveCardJson = adaptiveCardJson;
+    }
+#pragma warning restore CS8618 // Non-nullable field must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring as nullable.
+
+    [JsonIgnore]
+    public AdaptiveCard AdaptiveCard { get; private set; }
+
+    public string AdaptiveCardJson
+    {
+        get => this.AdaptiveCard.ToJson();
+        set => this.AdaptiveCard = AdaptiveCard.FromJson(value).Card;
+    }
+}

dotnet/samples/M365Agent/Agents/WeatherForecastAgent.cs

@@ -0,0 +1,115 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Text.Json;
+using AdaptiveCards;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace M365Agent.Agents;
+
+/// <summary>
+/// A weather forecasting agent. This agent wraps a <see cref="ChatClientAgent"/> and adds custom logic
+/// to generate adaptive cards for weather forecasts and add these to the agent's response.
+/// </summary>
+public class WeatherForecastAgent : DelegatingAIAgent
+{
+    private const string AgentName = "WeatherForecastAgent";
+    private const string AgentInstructions = """
+        You are a friendly assistant that helps people find a weather forecast for a given location.
+        You may ask follow up questions until you have enough information to answer the customers question.
+        When answering with a weather forecast, fill out the weatherCard property with an adaptive card containing the weather information and
+        add some emojis to indicate the type of weather.
+        When answering with just text, fill out the context property with a friendly response.
+        """;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="WeatherForecastAgent"/> class.
+    /// </summary>
+    /// <param name="chatClient">An instance of <see cref="IChatClient"/> for interacting with an LLM.</param>
+    public WeatherForecastAgent(IChatClient chatClient)
+        : base(new ChatClientAgent(
+            chatClient: chatClient,
+            new ChatClientAgentOptions()
+            {
+                Name = AgentName,
+                Instructions = AgentInstructions,
+                ChatOptions = new ChatOptions()
+                {
+                    Tools = [new ApprovalRequiredAIFunction(AIFunctionFactory.Create(GetWeather))],
+                    // We want the agent to return structured output in a known format
+                    // so that we can easily create adaptive cards from the response.
+                    ResponseFormat = ChatResponseFormat.ForJsonSchema(
+                        schema: AIJsonUtilities.CreateJsonSchema(typeof(WeatherForecastAgentResponse)),
+                        schemaName: "WeatherForecastAgentResponse",
+                        schemaDescription: "Response to a query about the weather in a specified location"),
+                }
+            }))
+    {
+    }
+
+    public override async Task<AgentRunResponse> RunAsync(IEnumerable<ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
+    {
+        var response = await base.RunAsync(messages, thread, options, cancellationToken);
+
+        // If the agent returned a valid structured output response
+        // we might be able to enhance the response with an adaptive card.
+        if (response.TryDeserialize<WeatherForecastAgentResponse>(JsonSerializerOptions.Web, out var structuredOutput))
+        {
+            var textContentMessage = response.Messages.FirstOrDefault(x => x.Contents.OfType<TextContent>().Any());
+            if (textContentMessage is not null)
+            {
+                // If the response contains weather information, create an adaptive card.
+                if (structuredOutput.ContentType == WeatherForecastAgentResponseContentType.WeatherForecastAgentResponse)
+                {
+                    var card = CreateWeatherCard(structuredOutput.Location, structuredOutput.MeteorologicalCondition, structuredOutput.TemperatureInCelsius);
+                    textContentMessage.Contents.Add(new AdaptiveCardAIContent(card));
+                }
+
+                // If the response is just text, replace the structured output with the text response.
+                if (structuredOutput.ContentType == WeatherForecastAgentResponseContentType.OtherAgentResponse)
+                {
+                    var textContent = textContentMessage.Contents.OfType<TextContent>().First();
+                    textContent.Text = structuredOutput.OtherResponse;
+                }
+            }
+        }
+
+        return response;
+    }
+
+    /// <summary>
+    /// A mock weather tool, to get weather information for a given location.
+    /// </summary>
+    [Description("Get the weather for a given location.")]
+    private static string GetWeather([Description("The location to get the weather for.")] string location)
+        => $"The weather in {location} is cloudy with a high of 15°C.";
+
+    /// <summary>
+    /// Create an adaptive card to display weather information.
+    /// </summary>
+    private static AdaptiveCard CreateWeatherCard(string? location, string? condition, string? temperature)
+    {
+        var card = new AdaptiveCard("1.5");
+        card.Body.Add(new AdaptiveTextBlock
+        {
+            Text = "🌤️ Weather Forecast 🌤️",
+            Size = AdaptiveTextSize.Large,
+            Weight = AdaptiveTextWeight.Bolder,
+            HorizontalAlignment = AdaptiveHorizontalAlignment.Center
+        });
+        card.Body.Add(new AdaptiveTextBlock
+        {
+            Text = "Location: " + location,
+        });
+        card.Body.Add(new AdaptiveTextBlock
+        {
+            Text = "Condition: " + condition,
+        });
+        card.Body.Add(new AdaptiveTextBlock
+        {
+            Text = "Temperature: " + temperature,
+        });
+        return card;
+    }
+}

dotnet/samples/M365Agent/Agents/WeatherForecastAgentResponse.cs

@@ -0,0 +1,47 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Text.Json.Serialization;
+
+namespace M365Agent.Agents;
+
+/// <summary>
+/// The structured output type for the <see cref="WeatherForecastAgent"/>.
+/// </summary>
+internal sealed class WeatherForecastAgentResponse
+{
+    /// <summary>
+    /// A value indicating whether the response contains a weather forecast or some other type of response.
+    /// </summary>
+    [JsonPropertyName("contentType")]
+    [JsonConverter(typeof(JsonStringEnumConverter))]
+    public WeatherForecastAgentResponseContentType ContentType { get; set; }
+
+    /// <summary>
+    /// If the agent could not provide a weather forecast this should contain a textual response.
+    /// </summary>
+    [Description("If the answer is other agent response, contains the textual agent response.")]
+    [JsonPropertyName("otherResponse")]
+    public string? OtherResponse { get; set; }
+
+    /// <summary>
+    /// The location for which the weather forecast is given.
+    /// </summary>
+    [Description("If the answer is a weather forecast, contains the location for which the forecast is given.")]
+    [JsonPropertyName("location")]
+    public string? Location { get; set; }
+
+    /// <summary>
+    /// The temperature in Celsius for the given location.
+    /// </summary>
+    [Description("If the answer is a weather forecast, contains the temperature in Celsius.")]
+    [JsonPropertyName("temperatureInCelsius")]
+    public string? TemperatureInCelsius { get; set; }
+
+    /// <summary>
+    /// The meteorological condition for the given location.
+    /// </summary>
+    [Description("If the answer is a weather forecast, contains the meteorological condition (e.g., Sunny, Rainy).")]
+    [JsonPropertyName("meteorologicalCondition")]
+    public string? MeteorologicalCondition { get; set; }
+}

dotnet/samples/M365Agent/Agents/WeatherForecastAgentResponseContentType.cs

@@ -0,0 +1,17 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace M365Agent.Agents;
+
+/// <summary>
+/// The type of content contained in a <see cref="WeatherForecastAgentResponse"/>.
+/// </summary>
+internal enum WeatherForecastAgentResponseContentType
+{
+    [JsonPropertyName("otherAgentResponse")]
+    OtherAgentResponse,
+
+    [JsonPropertyName("weatherForecastAgentResponse")]
+    WeatherForecastAgentResponse
+}

dotnet/samples/M365Agent/Auth/AspNetExtensions.cs

@@ -0,0 +1,206 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Concurrent;
+using System.Globalization;
+using System.IdentityModel.Tokens.Jwt;
+using System.Text;
+using Microsoft.Agents.Authentication;
+using Microsoft.Agents.Core;
+using Microsoft.AspNetCore.Authentication.JwtBearer;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.IdentityModel.Protocols;
+using Microsoft.IdentityModel.Protocols.OpenIdConnect;
+using Microsoft.IdentityModel.Tokens;
+using Microsoft.IdentityModel.Validators;
+
+namespace M365Agent;
+
+internal static class AspNetExtensions
+{
+    private static readonly CompositeFormat s_cachedValidTokenIssuerUrlTemplateV1Format = CompositeFormat.Parse(AuthenticationConstants.ValidTokenIssuerUrlTemplateV1);
+    private static readonly CompositeFormat s_cachedValidTokenIssuerUrlTemplateV2Format = CompositeFormat.Parse(AuthenticationConstants.ValidTokenIssuerUrlTemplateV2);
+
+    private static readonly ConcurrentDictionary<string, ConfigurationManager<OpenIdConnectConfiguration>> s_openIdMetadataCache = new();
+
+    /// <summary>
+    /// Adds AspNet token validation typical for ABS/SMBA and agent-to-agent using settings in configuration.
+    /// </summary>
+    /// <param name="services">The service collection to resolve dependencies.</param>
+    /// <param name="configuration">Used to read configuration settings.</param>
+    /// <param name="tokenValidationSectionName">Name of the config section to read.</param>
+    /// <remarks>
+    /// <para>This extension reads <see cref="TokenValidationOptions"/> settings from configuration.  If configuration is missing JWT token
+    /// is not enabled.</para>
+    /// <p>The minimum, but typical, configuration is:</p>
+    /// <code>
+    /// "TokenValidation": {
+    ///    "Enabled": boolean,
+    ///    "Audiences": [
+    ///      "{{ClientId}}" // this is the Client ID used for the Azure Bot
+    ///    ],
+    ///    "TenantId": "{{TenantId}}"
+    /// }
+    /// </code>
+    /// <para>The full options are:</para>
+    /// <code>
+    /// "TokenValidation": {
+    ///   "Enabled": boolean,
+    ///   "Audiences": [
+    ///     "{required:agent-appid}"
+    ///   ],
+    ///   "TenantId": "{recommended:tenant-id}",
+    ///   "ValidIssuers": [
+    ///     "{default:Public-AzureBotService}"
+    ///   ],
+    ///   "IsGov": {optional:false},
+    ///   "AzureBotServiceOpenIdMetadataUrl": optional,
+    ///   "OpenIdMetadataUrl": optional,
+    ///   "AzureBotServiceTokenHandling": "{optional:true}"
+    ///   "OpenIdMetadataRefresh": "optional-12:00:00"
+    /// }
+    /// </code>
+    /// </remarks>
+    public static void AddAgentAspNetAuthentication(this IServiceCollection services, IConfiguration configuration, string tokenValidationSectionName = "TokenValidation")
+    {
+        IConfigurationSection tokenValidationSection = configuration.GetSection(tokenValidationSectionName);
+
+        if (!tokenValidationSection.Exists() || !tokenValidationSection.GetValue("Enabled", true))
+        {
+            // Noop if TokenValidation section missing or disabled.
+            System.Diagnostics.Trace.WriteLine("AddAgentAspNetAuthentication: Auth disabled");
+            return;
+        }
+
+        services.AddAgentAspNetAuthentication(tokenValidationSection.Get<TokenValidationOptions>()!);
+    }
+
+    /// <summary>
+    /// Adds AspNet token validation typical for ABS/SMBA and agent-to-agent.
+    /// </summary>
+    public static void AddAgentAspNetAuthentication(this IServiceCollection services, TokenValidationOptions validationOptions)
+    {
+        AssertionHelpers.ThrowIfNull(validationOptions, nameof(validationOptions));
+
+        // Must have at least one Audience.
+        if (validationOptions.Audiences == null || validationOptions.Audiences.Count == 0)
+        {
+            throw new ArgumentException($"{nameof(TokenValidationOptions)}:Audiences requires at least one ClientId");
+        }
+
+        // Audience values must be GUID's
+        foreach (var audience in validationOptions.Audiences)
+        {
+            if (!Guid.TryParse(audience, out _))
+            {
+                throw new ArgumentException($"{nameof(TokenValidationOptions)}:Audiences values must be a GUID");
+            }
+        }
+
+        // If ValidIssuers is empty, default for ABS Public Cloud
+        if (validationOptions.ValidIssuers == null || validationOptions.ValidIssuers.Count == 0)
+        {
+            validationOptions.ValidIssuers =
+            [
+                "https://api.botframework.com",
+                "https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/",
+                "https://login.microsoftonline.com/d6d49420-f39b-4df7-a1dc-d59a935871db/v2.0",
+                "https://sts.windows.net/f8cdef31-a31e-4b4a-93e4-5f571e91255a/",
+                "https://login.microsoftonline.com/f8cdef31-a31e-4b4a-93e4-5f571e91255a/v2.0",
+                "https://sts.windows.net/69e9b82d-4842-4902-8d1e-abc5b98a55e8/",
+                "https://login.microsoftonline.com/69e9b82d-4842-4902-8d1e-abc5b98a55e8/v2.0",
+            ];
+
+            if (!string.IsNullOrEmpty(validationOptions.TenantId) && Guid.TryParse(validationOptions.TenantId, out _))
+            {
+                validationOptions.ValidIssuers.Add(string.Format(CultureInfo.InvariantCulture, s_cachedValidTokenIssuerUrlTemplateV1Format, validationOptions.TenantId));
+                validationOptions.ValidIssuers.Add(string.Format(CultureInfo.InvariantCulture, s_cachedValidTokenIssuerUrlTemplateV2Format, validationOptions.TenantId));
+            }
+        }
+
+        // If the `AzureBotServiceOpenIdMetadataUrl` setting is not specified, use the default based on `IsGov`.  This is what is used to authenticate ABS tokens.
+        if (string.IsNullOrEmpty(validationOptions.AzureBotServiceOpenIdMetadataUrl))
+        {
+            validationOptions.AzureBotServiceOpenIdMetadataUrl = validationOptions.IsGov ? AuthenticationConstants.GovAzureBotServiceOpenIdMetadataUrl : AuthenticationConstants.PublicAzureBotServiceOpenIdMetadataUrl;
+        }
+
+        // If the `OpenIdMetadataUrl` setting is not specified, use the default based on `IsGov`.  This is what is used to authenticate Entra ID tokens.
+        if (string.IsNullOrEmpty(validationOptions.OpenIdMetadataUrl))
+        {
+            validationOptions.OpenIdMetadataUrl = validationOptions.IsGov ? AuthenticationConstants.GovOpenIdMetadataUrl : AuthenticationConstants.PublicOpenIdMetadataUrl;
+        }
+
+        var openIdMetadataRefresh = validationOptions.OpenIdMetadataRefresh ?? BaseConfigurationManager.DefaultAutomaticRefreshInterval;
+
+        _ = services.AddAuthentication(options =>
+        {
+            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
+            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
+        })
+        .AddJwtBearer(options =>
+        {
+            options.SaveToken = true;
+            options.TokenValidationParameters = new TokenValidationParameters
+            {
+                ValidateIssuer = true,
+                ValidateAudience = true,
+                ValidateLifetime = true,
+                ClockSkew = TimeSpan.FromMinutes(5),
+                ValidIssuers = validationOptions.ValidIssuers,
+                ValidAudiences = validationOptions.Audiences,
+                ValidateIssuerSigningKey = true,
+                RequireSignedTokens = true,
+            };
+
+            // Using Microsoft.IdentityModel.Validators
+            options.TokenValidationParameters.EnableAadSigningKeyIssuerValidation();
+
+            options.Events = new JwtBearerEvents
+            {
+                // Create a ConfigurationManager based on the requestor.  This is to handle ABS non-Entra tokens.
+                OnMessageReceived = async context =>
+                {
+                    string authorizationHeader = context.Request.Headers.Authorization.ToString();
+
+                    if (string.IsNullOrWhiteSpace(authorizationHeader))
+                    {
+                        // Default to AadTokenValidation handling
+                        context.Options.TokenValidationParameters.ConfigurationManager ??= options.ConfigurationManager as BaseConfigurationManager;
+                        await Task.CompletedTask.ConfigureAwait(false);
+                        return;
+                    }
+
+                    string[] parts = authorizationHeader.Split(' ')!;
+                    if (parts.Length != 2 || parts[0] != "Bearer")
+                    {
+                        // Default to AadTokenValidation handling
+                        context.Options.TokenValidationParameters.ConfigurationManager ??= options.ConfigurationManager as BaseConfigurationManager;
+                        await Task.CompletedTask.ConfigureAwait(false);
+                        return;
+                    }
+
+                    JwtSecurityToken token = new(parts[1]);
+                    string issuer = token.Claims.FirstOrDefault(claim => claim.Type == AuthenticationConstants.IssuerClaim)?.Value!;
+
+                    string openIdMetadataUrl = (validationOptions.AzureBotServiceTokenHandling && AuthenticationConstants.BotFrameworkTokenIssuer.Equals(issuer, StringComparison.Ordinal))
+                        ? validationOptions.AzureBotServiceOpenIdMetadataUrl
+                        : validationOptions.OpenIdMetadataUrl;
+
+                    context.Options.TokenValidationParameters.ConfigurationManager = s_openIdMetadataCache.GetOrAdd(openIdMetadataUrl, key =>
+                    {
+                        return new ConfigurationManager<OpenIdConnectConfiguration>(openIdMetadataUrl, new OpenIdConnectConfigurationRetriever(), new HttpClient())
+                        {
+                            AutomaticRefreshInterval = openIdMetadataRefresh
+                        };
+                    });
+
+                    await Task.CompletedTask.ConfigureAwait(false);
+                },
+
+                OnTokenValidated = context => Task.CompletedTask,
+                OnForbidden = context => Task.CompletedTask,
+                OnAuthenticationFailed = context => Task.CompletedTask
+            };
+        });
+    }
+}

dotnet/samples/M365Agent/Auth/TokenValidationOptions.cs

@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.Authentication;
+
+namespace M365Agent;
+
+internal sealed class TokenValidationOptions
+{
+    /// <summary>
+    /// The list of audiences to validate against.
+    /// </summary>
+    public IList<string>? Audiences { get; set; }
+
+    /// <summary>
+    /// TenantId of the Azure Bot. Optional but recommended.
+    /// </summary>
+    public string? TenantId { get; set; }
+
+    /// <summary>
+    /// Additional valid issuers. Optional, in which case the Public Azure Bot Service issuers are used.
+    /// </summary>
+    public IList<string>? ValidIssuers { get; set; }
+
+    /// <summary>
+    /// Can be omitted, in which case public Azure Bot Service and Azure Cloud metadata urls are used.
+    /// </summary>
+    public bool IsGov { get; set; }
+
+    /// <summary>
+    /// Azure Bot Service OpenIdMetadataUrl. Optional, in which case default value depends on IsGov.
+    /// </summary>
+    /// <see cref="AuthenticationConstants.PublicAzureBotServiceOpenIdMetadataUrl"/>
+    /// <see cref="AuthenticationConstants.GovAzureBotServiceOpenIdMetadataUrl"/>
+    public string? AzureBotServiceOpenIdMetadataUrl { get; set; }
+
+    /// <summary>
+    /// Entra OpenIdMetadataUrl. Optional, in which case default value depends on IsGov.
+    /// </summary>
+    /// <see cref="AuthenticationConstants.PublicOpenIdMetadataUrl"/>
+    /// <see cref="AuthenticationConstants.GovOpenIdMetadataUrl"/>
+    public string? OpenIdMetadataUrl { get; set; }
+
+    /// <summary>
+    /// Determines if Azure Bot Service tokens are handled. Defaults to true and should always be true until Azure Bot Service sends Entra ID token.
+    /// </summary>
+    public bool AzureBotServiceTokenHandling { get; set; } = true;
+
+    /// <summary>
+    /// OpenIdMetadata refresh interval.  Defaults to 12 hours.
+    /// </summary>
+    public TimeSpan? OpenIdMetadataRefresh { get; set; }
+}

dotnet/samples/M365Agent/JsonUtilities.cs

@@ -0,0 +1,73 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Encodings.Web;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using System.Text.Json.Serialization.Metadata;
+using M365Agent.Agents;
+using Microsoft.Extensions.AI;
+
+namespace M365Agent;
+
+/// <summary>Provides a collection of utility methods for working with JSON data in the context of the application.</summary>
+internal static partial class JsonUtilities
+{
+    /// <summary>
+    /// Gets the <see cref="JsonSerializerOptions"/> singleton used as the default in JSON serialization operations.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// For Native AOT or applications disabling <see cref="JsonSerializer.IsReflectionEnabledByDefault"/>, this instance
+    /// includes source generated contracts for all common exchange types contained in this library.
+    /// </para>
+    /// <para>
+    /// It additionally turns on the following settings:
+    /// <list type="number">
+    /// <item>Enables <see cref="JsonSerializerDefaults.Web"/> defaults.</item>
+    /// <item>Enables <see cref="JsonIgnoreCondition.WhenWritingNull"/> as the default ignore condition for properties.</item>
+    /// <item>Enables <see cref="JsonNumberHandling.AllowReadingFromString"/> as the default number handling for number types.</item>
+    /// </list>
+    /// </para>
+    /// </remarks>
+    public static JsonSerializerOptions DefaultOptions { get; } = CreateDefaultOptions();
+
+    /// <summary>
+    /// Creates default options to use for agents-related serialization.
+    /// </summary>
+    /// <returns>The configured options.</returns>
+    [UnconditionalSuppressMessage("ReflectionAnalysis", "IL3050:RequiresDynamicCode", Justification = "Converter is guarded by IsReflectionEnabledByDefault check.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2026:Members annotated with 'RequiresUnreferencedCodeAttribute' require dynamic access", Justification = "Converter is guarded by IsReflectionEnabledByDefault check.")]
+    private static JsonSerializerOptions CreateDefaultOptions()
+    {
+        // Copy the configuration from the source generated context.
+        JsonSerializerOptions options = new(JsonContext.Default.Options)
+        {
+            // Chain in the resolvers from both AgentAbstractionsJsonUtilities and our source generated context.
+            // We want AgentAbstractionsJsonUtilities first to ensure any M.E.AI types are handled via its resolver.
+            TypeInfoResolver = JsonTypeInfoResolver.Combine(AIJsonUtilities.DefaultOptions.TypeInfoResolver, JsonContext.Default),
+            Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping, // same as in AgentAbstractionsJsonUtilities and AIJsonUtilities
+        };
+        options.AddAIContentType<AdaptiveCardAIContent>(typeDiscriminatorId: "adaptiveCard");
+
+        if (JsonSerializer.IsReflectionEnabledByDefault)
+        {
+            options.Converters.Add(new JsonStringEnumConverter());
+        }
+
+        options.MakeReadOnly();
+        return options;
+    }
+
+    // Keep in sync with CreateDefaultOptions above.
+    [JsonSourceGenerationOptions(JsonSerializerDefaults.Web,
+        UseStringEnumConverter = true,
+        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+        NumberHandling = JsonNumberHandling.AllowReadingFromString)]
+
+    // M365Agent specific types
+    [JsonSerializable(typeof(AdaptiveCardAIContent))]
+
+    [ExcludeFromCodeCoverage]
+    internal sealed partial class JsonContext : JsonSerializerContext;
+}

dotnet/samples/M365Agent/M365Agent.csproj

@@ -0,0 +1,30 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <UserSecretsId>b842df34-390f-490d-9dc0-73909363ad16</UserSecretsId>
+    <NoWarn>$(NoWarn);CA1812</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Content Include="appsettings.json.template" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="AdaptiveCards" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Microsoft.Agents.Authentication.Msal" />
+    <PackageReference Include="Microsoft.Agents.Hosting.AspNetCore" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+    <PackageReference Include="System.Text.Json" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/M365Agent/Program.cs

@@ -0,0 +1,104 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Sample that shows how to create an Agent Framework agent that is hosted using the M365 Agent SDK.
+// The agent can then be consumed from various M365 channels.
+// See the README.md for more information.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using M365Agent;
+using M365Agent.Agents;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.Builder;
+using Microsoft.Agents.Hosting.AspNetCore;
+using Microsoft.Agents.Storage;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using OpenAI;
+
+WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
+
+if (builder.Environment.IsDevelopment())
+{
+    builder.Configuration.AddUserSecrets<Program>();
+}
+
+builder.Services.AddHttpClient();
+
+// Register the inference service of your choice. AzureOpenAI and OpenAI are demonstrated...
+IChatClient chatClient;
+if (builder.Configuration.GetSection("AIServices").GetValue<bool>("UseAzureOpenAI"))
+{
+    var deploymentName = builder.Configuration.GetSection("AIServices:AzureOpenAI").GetValue<string>("DeploymentName")!;
+    var endpoint = builder.Configuration.GetSection("AIServices:AzureOpenAI").GetValue<string>("Endpoint")!;
+
+    chatClient = new AzureOpenAIClient(
+        new Uri(endpoint),
+        new AzureCliCredential())
+         .GetChatClient(deploymentName)
+         .AsIChatClient();
+}
+else
+{
+    var modelId = builder.Configuration.GetSection("AIServices:OpenAI").GetValue<string>("ModelId")!;
+    var apiKey = builder.Configuration.GetSection("AIServices:OpenAI").GetValue<string>("ApiKey")!;
+
+    chatClient = new OpenAIClient(
+        apiKey)
+        .GetChatClient(modelId)
+        .AsIChatClient();
+}
+builder.Services.AddSingleton(chatClient);
+
+// Add AgentApplicationOptions from appsettings section "AgentApplication".
+builder.AddAgentApplicationOptions();
+
+// Add the WeatherForecastAgent plus a welcome message.
+// These will be consumed by the AFAgentApplication and exposed as an Agent SDK AgentApplication.
+builder.Services.AddSingleton<AIAgent, WeatherForecastAgent>();
+builder.Services.AddKeyedSingleton("AFAgentApplicationWelcomeMessage", "Hello and Welcome! I'm here to help with all your weather forecast needs!");
+
+// Add the AgentApplication, which contains the logic for responding to
+// user messages via the Agent SDK.
+builder.AddAgent<AFAgentApplication>();
+
+// Register IStorage.  For development, MemoryStorage is suitable.
+// For production Agents, persisted storage should be used so
+// that state survives Agent restarts, and operates correctly
+// in a cluster of Agent instances.
+builder.Services.AddSingleton<IStorage, MemoryStorage>();
+
+// Configure the HTTP request pipeline.
+
+// Add AspNet token validation for Azure Bot Service and Entra.  Authentication is
+// configured in the appsettings.json "TokenValidation" section.
+builder.Services.AddControllers();
+builder.Services.AddAgentAspNetAuthentication(builder.Configuration);
+
+WebApplication app = builder.Build();
+
+// Enable AspNet authentication and authorization
+app.UseAuthentication();
+app.UseAuthorization();
+
+app.MapGet("/", () => "Microsoft Agents SDK Sample");
+
+// This receives incoming messages and routes them to the registered AgentApplication.
+var incomingRoute = app.MapPost("/api/messages", async (HttpRequest request, HttpResponse response, IAgentHttpAdapter adapter, IAgent agent, CancellationToken cancellationToken) => await adapter.ProcessAsync(request, response, agent, cancellationToken));
+
+if (!app.Environment.IsDevelopment())
+{
+    incomingRoute.RequireAuthorization();
+}
+else
+{
+    // Hardcoded for brevity and ease of testing. 
+    // In production, this should be set in configuration.
+    app.Urls.Add("http://localhost:3978");
+}
+
+app.Run();

dotnet/samples/M365Agent/Properties/launchSettings.json

@@ -0,0 +1,12 @@
+{
+  "profiles": {
+    "M365Agent": {
+      "commandName": "Project",
+      "launchBrowser": true,
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      },
+      "applicationUrl": "https://localhost:49692;http://localhost:49693"
+    }
+  }
+}

dotnet/samples/M365Agent/README.md

@@ -0,0 +1,119 @@
+# Microsoft Agent Framework agents with the M365 Agents SDK Weather Agent sample
+
+This is a sample of a simple Weather Forecast Agent that is hosted on an Asp.Net core web service and is exposed via the M365 Agent SDK. This Agent is configured to accept a request asking for information about a weather forecast and respond to the caller with an Adaptive Card. This agent will handle multiple "turns" to get the required information from the user.
+
+This Agent Sample is intended to introduce you the basics of integrating Agent Framework with the Microsoft 365 Agents SDK in order to use Agent Framework agents in various M365 services and applications. It can also be used as the base for a custom Agent that you choose to develop.
+
+***Note:*** This sample requires JSON structured output from the model which works best from newer versions of the model such as gpt-4o-mini.
+
+## Prerequisites
+
+- [.NET 8.0 SDK or later](https://dotnet.microsoft.com/download)
+- [devtunnel](https://learn.microsoft.com/azure/developer/dev-tunnels/get-started?tabs=windows)
+- [Microsoft 365 Agents Toolkit](https://github.com/OfficeDev/microsoft-365-agents-toolkit)
+
+- You will need an Azure OpenAI or OpenAI resource using `gpt-4o-mini`
+ 
+- Configure OpenAI in appsettings
+
+  ```json
+  "AIServices": {
+    "AzureOpenAI": {
+      "DeploymentName": "", // This is the Deployment (as opposed to model) Name of the Azure OpenAI model
+      "Endpoint": "", // This is the Endpoint of the Azure OpenAI resource
+      "ApiKey": "" // This is the API Key of the Azure OpenAI resource. Optional, uses AzureCliCredential if not provided
+    },
+    "OpenAI": {
+      "ModelId": "", // This is the Model ID of the OpenAI model
+      "ApiKey": "" // This is your API Key for the OpenAI service
+    },
+    "UseAzureOpenAI": false // This is a flag to determine whether to use the Azure OpenAI or the OpenAI service
+  }
+  ```
+
+## QuickStart using Agent Toolkit
+1. If you haven't done so already, install the Agents Playground
+ 
+   ```
+   winget install agentsplayground
+   ```
+1. Start the sample application.
+1. Start Agents Playground.  At a command prompt: `agentsplayground`
+   - The tool will open a web browser showing the Microsoft 365 Agents Playground, ready to send messages to your agent. 
+1. Interact with the Agent via the browser
+
+## QuickStart using WebChat or Teams
+
+- Overview of running and testing an Agent
+  - Provision an Azure Bot in your Azure Subscription
+  - Configure your Agent settings to use to desired authentication type
+  - Running an instance of the Agent app (either locally or deployed to Azure)
+  - Test in a client
+
+1. Create an Azure Bot with one of these authentication types
+   - [SingleTenant, Client Secret](https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/azure-bot-create-single-secret)
+   - [SingleTenant, Federated Credentials](https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/azure-bot-create-federated-credentials) 
+   - [User Assigned Managed Identity](https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/azure-bot-create-managed-identity)
+    
+   > Be sure to follow the **Next Steps** at the end of these docs to configure your agent settings.
+
+   > **IMPORTANT:** If you want to run your agent locally via devtunnels, the only support auth type is ClientSecret and Certificates
+
+1. Running the Agent
+   1. Running the Agent locally
+      - Requires a tunneling tool to allow for local development and debugging should you wish to do local development whilst connected to a external client such as Microsoft Teams.
+      - **For ClientSecret or Certificate authentication types only.**  Federated Credentials and Managed Identity will not work via a tunnel to a local agent and must be deployed to an App Service or container.
+      
+      1. Run `devtunnel`. Please follow [Create and host a dev tunnel](https://learn.microsoft.com/azure/developer/dev-tunnels/get-started?tabs=windows) and host the tunnel with anonymous user access command as shown below:
+
+         ```bash
+         devtunnel host -p 3978 --allow-anonymous
+         ```
+
+      1. On the Azure Bot, select **Settings**, then **Configuration**, and update the **Messaging endpoint** to `{tunnel-url}/api/messages`
+
+      1. Start the Agent in Visual Studio
+
+   1. Deploy Agent code to Azure
+      1. VS Publish works well for this.  But any tools used to deploy a web application will also work.
+      1. On the Azure Bot, select **Settings**, then **Configuration**, and update the **Messaging endpoint** to `https://{{appServiceDomain}}/api/messages`
+
+## Testing this agent with WebChat
+
+   1. Select **Test in WebChat** under **Settings** on the Azure Bot in the Azure Portal
+
+## Testing this Agent in Teams or M365
+
+1. Update the manifest.json
+   - Edit the `manifest.json` contained in the `/appManifest` folder
+     - Replace with your AppId (that was created above) *everywhere* you see the place holder string `<<AAD_APP_CLIENT_ID>>`
+     - Replace `<<BOT_DOMAIN>>` with your Agent url.  For example, the tunnel host name.
+   - Zip up the contents of the `/appManifest` folder to create a `manifest.zip`
+     - `manifest.json`
+     - `outline.png`
+     - `color.png`
+
+1. Your Azure Bot should have the **Microsoft Teams** channel added under **Channels**.
+
+1. Navigate to the Microsoft Admin Portal (MAC). Under **Settings** and **Integrated Apps,** select **Upload Custom App**.
+
+1. Select the `manifest.zip` created in the previous step. 
+
+1. After a short period of time, the agent shows up in Microsoft Teams and Microsoft 365 Copilot.
+
+## Enabling JWT token validation
+1. By default, the AspNet token validation is disabled in order to support local debugging.
+1. Enable by updating appsettings
+   ```json
+   "TokenValidation": {
+     "Enabled": true,
+     "Audiences": [
+       "{{ClientId}}" // this is the Client ID used for the Azure Bot
+     ],
+     "TenantId": "{{TenantId}}"
+   },
+   ```
+
+## Further reading
+
+To learn more about using the M365 Agent SDK, see [Microsoft 365 Agents SDK](https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/).

dotnet/samples/M365Agent/appManifest/manifest.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.22/MicrosoftTeams.schema.json",
+  "manifestVersion": "1.22",
+  "version": "1.0.0",
+  "id": "<<AAD_APP_CLIENT_ID>>",
+  "developer": {
+    "name": "Microsoft, Inc.",
+    "websiteUrl": "https://example.azurewebsites.net",
+    "privacyUrl": "https://example.azurewebsites.net/privacy",
+    "termsOfUseUrl": "https://example.azurewebsites.net/termsofuse"
+  },
+  "icons": {
+    "color": "color.png",
+    "outline": "outline.png"
+  },
+  "name": {
+    "short": "AF Sample Agent",
+    "full": "M365 AgentSDK and Microsoft Agent Framework Sample"
+  },
+  "description": {
+    "short": "Sample demonstrating M365 AgentSDK, Teams, and Microsoft Agent Framework",
+    "full": "Sample demonstrating M365 AgentSDK, Teams, and Microsoft Agent Framework"
+  },
+  "accentColor": "#FFFFFF",
+  "copilotAgents": {
+    "customEngineAgents": [
+      {
+        "id": "<<AAD_APP_CLIENT_ID>>",
+        "type": "bot"
+      }
+    ]
+  },
+  "bots": [
+    {
+      "botId": "<<AAD_APP_CLIENT_ID>>",
+      "scopes": [
+        "personal"
+      ],
+      "supportsFiles": false,
+      "isNotificationOnly": false
+    }
+  ],
+  "permissions": [
+    "identity",
+    "messageTeamMembers"
+  ],
+  "validDomains": [
+    "<<BOT_DOMAIN>>"
+  ]
+}

dotnet/samples/M365Agent/appsettings.json.template

@@ -0,0 +1,54 @@
+{
+  "TokenValidation": {
+    "Enabled": false,
+    "Audiences": [
+      "{{ClientId}}" // this is the Client ID used for the Azure Bot
+    ],
+    "TenantId": "{{TenantId}}"
+  },
+
+  "AgentApplication": {
+    "StartTypingTimer": true,
+    "RemoveRecipientMention": false,
+    "NormalizeMentions": false
+  },
+
+  "Connections": {
+    "ServiceConnection": {
+      "Settings": {
+        // this is the AuthType for the connection, valid values can be found in Microsoft.Agents.Authentication.Msal.Model.AuthTypes.  The default is ClientSecret.
+        "AuthType": "" 
+
+        // Other properties dependent on the authorization type the Azure Bot uses.
+      }
+    }
+  },
+  "ConnectionsMap": [
+    {
+      "ServiceUrl": "*",
+      "Connection": "ServiceConnection"
+    }
+  ],
+
+  // This is the configuration for the AI services, use environment variables or user secrets to store sensitive information.
+  // Do not store sensitive information in this file
+  "AIServices": {
+    "AzureOpenAI": {
+      "DeploymentName": "", // This is the Deployment (as opposed to model) Name of the Azure OpenAI model
+      "Endpoint": "", // This is the Endpoint of the Azure OpenAI resource
+      "ApiKey": "" // This is the API Key of the Azure OpenAI resource. Optional, uses AzureCliCredential if not provided
+    },
+    "OpenAI": {
+      "ModelId": "", // This is the Model ID of the OpenAI model
+      "ApiKey": "" // This is your API Key for the OpenAI service
+    },
+    "UseAzureOpenAI": false // This is a flag to determine whether to use the Azure OpenAI or the OpenAI service
+  },
+
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

dotnet/src/Microsoft.Agents.AI.DevUI/EntitiesApiExtensions.cs

@@ -1,10 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using System.Runtime.CompilerServices;
 using System.Text.Json;
-
 using Microsoft.Agents.AI.DevUI.Entities;
-using Microsoft.Agents.AI.Hosting;
 using Microsoft.Agents.AI.Workflows;
 using Microsoft.Extensions.AI;
 
@@ -27,21 +24,26 @@ internal static class EntitiesApiExtensions
     /// <item><description>GET /v1/entities/{entityId}/info - Get detailed information about a specific entity</description></item>
     /// </list>
     /// The endpoints are compatible with the Python DevUI frontend and automatically discover entities
-    /// from the registered <see cref="AgentCatalog"/> and <see cref="WorkflowCatalog"/> services.
+    /// from the registered <see cref="AIAgent">agents</see> and <see cref="Workflow">workflows</see> in the dependency injection container.
     /// </remarks>
     public static IEndpointConventionBuilder MapEntities(this IEndpointRouteBuilder endpoints)
     {
+        var registeredAIAgents = GetRegisteredEntities<AIAgent>(endpoints.ServiceProvider);
+        var registeredWorkflows = GetRegisteredEntities<Workflow>(endpoints.ServiceProvider);
+
         var group = endpoints.MapGroup("/v1/entities")
             .WithTags("Entities");
 
         // List all entities
-        group.MapGet("", ListEntitiesAsync)
+        group.MapGet("", (CancellationToken cancellationToken)
+                => ListEntitiesAsync(registeredAIAgents, registeredWorkflows, cancellationToken))
             .WithName("ListEntities")
             .WithSummary("List all registered entities (agents and workflows)")
             .Produces<DiscoveryResponse>(StatusCodes.Status200OK, contentType: "application/json");
 
         // Get detailed entity information
-        group.MapGet("{entityId}/info", GetEntityInfoAsync)
+        group.MapGet("{entityId}/info", (string entityId, string? type, CancellationToken cancellationToken)
+                => GetEntityInfoAsync(entityId, type, registeredAIAgents, registeredWorkflows, cancellationToken))
             .WithName("GetEntityInfo")
             .WithSummary("Get detailed information about a specific entity")
             .Produces<EntityInfo>(StatusCodes.Status200OK, contentType: "application/json")
@@ -51,8 +53,8 @@ internal static class EntitiesApiExtensions
     }
 
     private static async Task<IResult> ListEntitiesAsync(
-        AgentCatalog? agentCatalog,
-        WorkflowCatalog? workflowCatalog,
+        IEnumerable<AIAgent> agents,
+        IEnumerable<Workflow> workflows,
         CancellationToken cancellationToken)
     {
         try
@@ -60,13 +62,13 @@ internal static class EntitiesApiExtensions
             var entities = new Dictionary<string, EntityInfo>();
 
             // Discover agents
-            await foreach (var agentInfo in DiscoverAgentsAsync(agentCatalog, entityIdFilter: null, cancellationToken).ConfigureAwait(false))
+            foreach (var agentInfo in DiscoverAgents(agents, entityIdFilter: null))
             {
                 entities[agentInfo.Id] = agentInfo;
             }
 
             // Discover workflows
-            await foreach (var workflowInfo in DiscoverWorkflowsAsync(workflowCatalog, entityIdFilter: null, cancellationToken).ConfigureAwait(false))
+            foreach (var workflowInfo in DiscoverWorkflows(workflows, entityIdFilter: null))
             {
                 entities[workflowInfo.Id] = workflowInfo;
             }
@@ -85,15 +87,15 @@ internal static class EntitiesApiExtensions
     private static async Task<IResult> GetEntityInfoAsync(
         string entityId,
         string? type,
-        AgentCatalog? agentCatalog,
-        WorkflowCatalog? workflowCatalog,
+        IEnumerable<AIAgent> agents,
+        IEnumerable<Workflow> workflows,
         CancellationToken cancellationToken)
     {
         try
         {
             if (type is null || string.Equals(type, "workflow", StringComparison.OrdinalIgnoreCase))
             {
-                await foreach (var workflowInfo in DiscoverWorkflowsAsync(workflowCatalog, entityId, cancellationToken).ConfigureAwait(false))
+                foreach (var workflowInfo in DiscoverWorkflows(workflows, entityId))
                 {
                     return Results.Json(workflowInfo, EntitiesJsonContext.Default.EntityInfo);
                 }
@@ -101,7 +103,7 @@ internal static class EntitiesApiExtensions
 
             if (type is null || string.Equals(type, "agent", StringComparison.OrdinalIgnoreCase))
             {
-                await foreach (var agentInfo in DiscoverAgentsAsync(agentCatalog, entityId, cancellationToken).ConfigureAwait(false))
+                foreach (var agentInfo in DiscoverAgents(agents, entityId))
                 {
                     return Results.Json(agentInfo, EntitiesJsonContext.Default.EntityInfo);
                 }
@@ -118,17 +120,9 @@ internal static class EntitiesApiExtensions
         }
     }
 
-    private static async IAsyncEnumerable<EntityInfo> DiscoverAgentsAsync(
-        AgentCatalog? agentCatalog,
-        string? entityIdFilter,
-        [EnumeratorCancellation] CancellationToken cancellationToken)
+    private static IEnumerable<EntityInfo> DiscoverAgents(IEnumerable<AIAgent> agents, string? entityIdFilter)
     {
-        if (agentCatalog is null)
-        {
-            yield break;
-        }
-
-        await foreach (var agent in agentCatalog.GetAgentsAsync(cancellationToken).ConfigureAwait(false))
+        foreach (var agent in agents)
         {
             // If filtering by entity ID, skip non-matching agents
             if (entityIdFilter is not null &&
@@ -148,17 +142,9 @@ internal static class EntitiesApiExtensions
         }
     }
 
-    private static async IAsyncEnumerable<EntityInfo> DiscoverWorkflowsAsync(
-        WorkflowCatalog? workflowCatalog,
-        string? entityIdFilter,
-        [EnumeratorCancellation] CancellationToken cancellationToken)
+    private static IEnumerable<EntityInfo> DiscoverWorkflows(IEnumerable<Workflow> workflows, string? entityIdFilter)
     {
-        if (workflowCatalog is null)
-        {
-            yield break;
-        }
-
-        await foreach (var workflow in workflowCatalog.GetWorkflowsAsync(cancellationToken).ConfigureAwait(false))
+        foreach (var workflow in workflows)
         {
             var workflowId = workflow.Name ?? workflow.StartExecutorId;
 
@@ -304,4 +290,14 @@ internal static class EntitiesApiExtensions
             StartExecutorId = workflow.StartExecutorId
         };
     }
+
+    private static IEnumerable<T> GetRegisteredEntities<T>(IServiceProvider serviceProvider)
+    {
+        var keyedEntities = serviceProvider.GetKeyedServices<T>(KeyedService.AnyKey);
+        var defaultEntities = serviceProvider.GetServices<T>() ?? [];
+
+        return keyedEntities
+            .Concat(defaultEntities)
+            .Where(entity => entity is not null);
+    }
 }

dotnet/src/Microsoft.Agents.AI.DevUI/HostApplicationBuilderExtensions.cs

@@ -0,0 +1,23 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Extensions.Hosting;
+
+/// <summary>
+/// Extension methods for <see cref="IHostApplicationBuilder"/> to configure DevUI.
+/// </summary>
+public static class MicrosoftAgentAIDevUIHostApplicationBuilderExtensions
+{
+    /// <summary>
+    /// Adds DevUI services to the host application builder.
+    /// </summary>
+    /// <param name="builder">The <see cref="IHostApplicationBuilder"/> to configure.</param>
+    /// <returns>The <see cref="IHostApplicationBuilder"/> for method chaining.</returns>
+    public static IHostApplicationBuilder AddDevUI(this IHostApplicationBuilder builder)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+
+        builder.Services.AddDevUI();
+
+        return builder;
+    }
+}

dotnet/src/Microsoft.Agents.AI.DevUI/Microsoft.Agents.AI.DevUI.csproj

@@ -1,7 +1,8 @@
 <Project Sdk="Microsoft.NET.Sdk.Web">
 
   <PropertyGroup>
-    <TargetFrameworks>net9.0</TargetFrameworks>
+    <TargetFrameworks>$(ProjectsCoreTargetFrameworks)</TargetFrameworks>
+    <TargetFrameworks Condition="'$(Configuration)' == 'Debug'">$(ProjectsDebugCoreTargetFrameworks)</TargetFrameworks>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
     <RootNamespace>Microsoft.Agents.AI.DevUI</RootNamespace>
@@ -12,6 +13,10 @@
     <NoWarn>$(NoWarn);CS1591;CA1852;CA1050;RCS1037;RCS1036;RCS1124;RCS1021;RCS1146;RCS1211;CA2007;CA1308;IL2026;IL3050;CA1812</NoWarn>
   </PropertyGroup>
 
+  <PropertyGroup>
+    <InjectSharedThrow>true</InjectSharedThrow>
+  </PropertyGroup>
+
   <!-- Import nuget packaging properties -->
   <Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />
 
@@ -33,4 +38,7 @@
     <Description>Provides Microsoft Agent Framework support for developer UI.</Description>
   </PropertyGroup>
 
+  <ItemGroup>
+    <InternalsVisibleTo Include="Microsoft.Agents.AI.DevUI.UnitTests"/>
+  </ItemGroup>
 </Project>

dotnet/src/Microsoft.Agents.AI.DevUI/README.md

@@ -24,9 +24,15 @@ var builder = WebApplication.CreateBuilder(args);
 // Register your agents
 builder.AddAIAgent("assistant", "You are a helpful assistant.");
 
+// Register DevUI services
+if (builder.Environment.IsDevelopment())
+{
+    builder.AddDevUI();
+}
+
 // Register services for OpenAI responses and conversations (also required for DevUI)
-builder.Services.AddOpenAIResponses();
-builder.Services.AddOpenAIConversations();
+builder.AddOpenAIResponses();
+builder.AddOpenAIConversations();
 
 var app = builder.Build();
 

dotnet/src/Microsoft.Agents.AI.DevUI/ServiceCollectionsExtensions.cs

@@ -0,0 +1,61 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.DependencyInjection;
+
+/// <summary>
+/// Extension methods for <see cref="IServiceCollection"/> to configure DevUI.
+/// </summary>
+public static class MicrosoftAgentAIDevUIServiceCollectionsExtensions
+{
+    /// <summary>
+    /// Adds services required for DevUI integration.
+    /// </summary>
+    /// <param name="services">The <see cref="IServiceCollection"/> to configure.</param>
+    /// <returns>The <see cref="IServiceCollection"/> for method chaining.</returns>
+    public static IServiceCollection AddDevUI(this IServiceCollection services)
+    {
+        ArgumentNullException.ThrowIfNull(services);
+
+        // a factory that tries to construct an AIAgent from Workflow,
+        // even if workflow was not explicitly registered as an AIAgent.
+
+#pragma warning disable IDE0001 // Simplify Names
+        services.AddKeyedSingleton<AIAgent>(KeyedService.AnyKey, (sp, key) =>
+        {
+            var keyAsStr = key as string;
+            Throw.IfNullOrEmpty(keyAsStr);
+
+            var workflow = sp.GetKeyedService<Workflow>(keyAsStr);
+            if (workflow is not null)
+            {
+                return workflow.AsAgent(name: workflow.Name);
+            }
+
+            // another thing we can do is resolve a non-keyed workflow.
+            // however, we can't rely on anything than key to be equal to the workflow.Name.
+            // so we try: if we fail, we return null.
+            workflow = sp.GetService<Workflow>();
+            if (workflow is not null && workflow.Name?.Equals(keyAsStr, StringComparison.Ordinal) == true)
+            {
+                return workflow.AsAgent(name: workflow.Name);
+            }
+
+            // and it's possible to lookup at the default-registered AIAgent
+            // with the condition of same name as the key.
+            var agent = sp.GetService<AIAgent>();
+            if (agent is not null && agent.Name?.Equals(keyAsStr, StringComparison.Ordinal) == true)
+            {
+                return agent;
+            }
+
+            return null!;
+        });
+#pragma warning restore IDE0001 // Simplify Names
+
+        return services;
+    }
+}

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/BuiltInFunctions.cs

@@ -83,12 +83,13 @@ internal static class BuiltInFunctions
 
         string? threadIdValue = threadIdFromBody ?? threadIdFromQuery;
 
-        // If no session ID is provided, use a new one based on the function name and invocation ID.
-        // This may be better than a random one because it can be correlated with the function invocation.
-        // Specifying a session ID is how the caller correlates multiple calls to the same agent session.
+        // The thread_id is treated as a session key (not a full session ID).
+        // If no session key is provided, use the function invocation ID as the session key
+        // to help correlate the session with the function invocation.
+        string agentName = GetAgentName(context);
         AgentSessionId sessionId = string.IsNullOrEmpty(threadIdValue)
-            ? new AgentSessionId(GetAgentName(context), context.InvocationId)
-            : AgentSessionId.Parse(threadIdValue);
+            ? new AgentSessionId(agentName, context.InvocationId)
+            : new AgentSessionId(agentName, threadIdValue);
 
         if (string.IsNullOrWhiteSpace(message))
         {
@@ -110,7 +111,7 @@ internal static class BuiltInFunctions
             }
         }
 
-        AIAgent agentProxy = client.AsDurableAgentProxy(context, GetAgentName(context));
+        AIAgent agentProxy = client.AsDurableAgentProxy(context, agentName);
 
         DurableAgentRunOptions options = new() { IsFireAndForget = !waitForResponse };
 
@@ -126,7 +127,7 @@ internal static class BuiltInFunctions
                 req,
                 context,
                 HttpStatusCode.OK,
-                sessionId.ToString(),
+                sessionId.Key,
                 agentResponse);
         }
 
@@ -140,7 +141,7 @@ internal static class BuiltInFunctions
         return await CreateAcceptedResponseAsync(
             req,
             context,
-            sessionId.ToString());
+            sessionId.Key);
     }
 
     public static async Task<string?> RunMcpToolAsync(

dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/HostedAgentResponseExecutor.cs

@@ -63,7 +63,11 @@ internal sealed class HostedAgentResponseExecutor : IResponseExecutor
             return ValueTask.FromResult<ResponseError?>(new ResponseError
             {
                 Code = "agent_not_found",
-                Message = $"Agent '{agentName}' not found. Ensure the agent is registered with AddAIAgent()."
+                Message = $"""
+                    Agent '{agentName}' not found.
+                    Ensure the agent is registered with '{agentName}' name in the dependency injection container.
+                    We recommend using 'builder.AddAIAgent()' for simplicity.
+                """
             });
         }
 

dotnet/src/Microsoft.Agents.AI.Hosting/AgentCatalog.cs

@@ -1,38 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System.Collections.Generic;
-using System.Threading;
-
-namespace Microsoft.Agents.AI.Hosting;
-
-/// <summary>
-/// Provides a catalog of registered AI agents within the hosting environment.
-/// </summary>
-/// <remarks>
-/// The agent catalog allows enumeration of all registered agents in the dependency injection container.
-/// This is useful for scenarios where you need to discover and interact with multiple agents programmatically.
-/// </remarks>
-public abstract class AgentCatalog
-{
-    /// <summary>
-    /// Initializes a new instance of the <see cref="AgentCatalog"/> class.
-    /// </summary>
-    protected AgentCatalog()
-    {
-    }
-
-    /// <summary>
-    /// Asynchronously retrieves all registered AI agents from the catalog.
-    /// </summary>
-    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
-    /// <returns>
-    /// An asynchronous enumerable of <see cref="AIAgent"/> instances representing all registered agents.
-    /// The enumeration will only include agents that are successfully resolved from the service provider.
-    /// </returns>
-    /// <remarks>
-    /// This method enumerates through all registered agent names and attempts to resolve each agent
-    /// from the dependency injection container. Only successfully resolved agents are yielded.
-    /// The enumeration is lazy and agents are resolved on-demand during iteration.
-    /// </remarks>
-    public abstract IAsyncEnumerable<AIAgent> GetAgentsAsync(CancellationToken cancellationToken = default);
-}

dotnet/src/Microsoft.Agents.AI.Hosting/AgentHostingServiceCollectionExtensions.cs

@@ -2,7 +2,6 @@
 
 using System;
 using System.Collections.Generic;
-using System.Linq;
 using Microsoft.Agents.AI.Hosting.Local;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.DependencyInjection;
@@ -126,31 +125,9 @@ public static class AgentHostingServiceCollectionExtensions
             return agent;
         });
 
-        // Register the agent by name for discovery.
-        var agentHostBuilder = GetAgentRegistry(services);
-        agentHostBuilder.AgentNames.Add(name);
-
         return new HostedAgentBuilder(name, services);
     }
 
-    private static LocalAgentRegistry GetAgentRegistry(IServiceCollection services)
-    {
-        var descriptor = services.FirstOrDefault(s => !s.IsKeyedService && s.ServiceType.Equals(typeof(LocalAgentRegistry)));
-        if (descriptor?.ImplementationInstance is not LocalAgentRegistry instance)
-        {
-            instance = new LocalAgentRegistry();
-            ConfigureHostBuilder(services, instance);
-        }
-
-        return instance;
-    }
-
-    private static void ConfigureHostBuilder(IServiceCollection services, LocalAgentRegistry agentHostBuilderContext)
-    {
-        services.Add(ServiceDescriptor.Singleton(agentHostBuilderContext));
-        services.AddSingleton<AgentCatalog, LocalAgentCatalog>();
-    }
-
     private static IList<AITool> GetRegisteredToolsForAgent(IServiceProvider serviceProvider, string agentName)
     {
         var registry = serviceProvider.GetService<LocalAgentToolRegistry>();

dotnet/src/Microsoft.Agents.AI.Hosting/HostApplicationBuilderWorkflowExtensions.cs

@@ -1,8 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System;
-using System.Linq;
-using Microsoft.Agents.AI.Hosting.Local;
 using Microsoft.Agents.AI.Workflows;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
@@ -47,28 +45,6 @@ public static class HostApplicationBuilderWorkflowExtensions
             return workflow;
         });
 
-        // Register the workflow by name for discovery.
-        var workflowRegistry = GetWorkflowRegistry(builder);
-        workflowRegistry.WorkflowNames.Add(name);
-
         return new HostedWorkflowBuilder(name, builder);
     }
-
-    private static LocalWorkflowRegistry GetWorkflowRegistry(IHostApplicationBuilder builder)
-    {
-        var descriptor = builder.Services.FirstOrDefault(s => !s.IsKeyedService && s.ServiceType.Equals(typeof(LocalWorkflowRegistry)));
-        if (descriptor?.ImplementationInstance is not LocalWorkflowRegistry instance)
-        {
-            instance = new LocalWorkflowRegistry();
-            ConfigureHostBuilder(builder, instance);
-        }
-
-        return instance;
-    }
-
-    private static void ConfigureHostBuilder(IHostApplicationBuilder builder, LocalWorkflowRegistry agentHostBuilderContext)
-    {
-        builder.Services.Add(ServiceDescriptor.Singleton(agentHostBuilderContext));
-        builder.Services.AddSingleton<WorkflowCatalog, LocalWorkflowCatalog>();
-    }
 }

dotnet/src/Microsoft.Agents.AI.Hosting/Local/LocalAgentCatalog.cs

@@ -1,37 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System;
-using System.Collections.Generic;
-using System.Runtime.CompilerServices;
-using System.Threading;
-using System.Threading.Tasks;
-using Microsoft.Extensions.DependencyInjection;
-
-namespace Microsoft.Agents.AI.Hosting.Local;
-
-// Implementation of an AgentCatalog which enumerates agents registered in the local service provider.
-internal sealed class LocalAgentCatalog : AgentCatalog
-{
-    public readonly HashSet<string> _registeredAgents;
-    private readonly IServiceProvider _serviceProvider;
-
-    public LocalAgentCatalog(LocalAgentRegistry agentHostBuilder, IServiceProvider serviceProvider)
-    {
-        this._registeredAgents = [.. agentHostBuilder.AgentNames];
-        this._serviceProvider = serviceProvider;
-    }
-
-    public override async IAsyncEnumerable<AIAgent> GetAgentsAsync([EnumeratorCancellation] CancellationToken cancellationToken = default)
-    {
-        await Task.CompletedTask.ConfigureAwait(false);
-
-        foreach (var name in this._registeredAgents)
-        {
-            var agent = this._serviceProvider.GetKeyedService<AIAgent>(name);
-            if (agent is not null)
-            {
-                yield return agent;
-            }
-        }
-    }
-}

dotnet/src/Microsoft.Agents.AI.Hosting/Local/LocalAgentRegistry.cs

@@ -1,10 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System.Collections.Generic;
-
-namespace Microsoft.Agents.AI.Hosting.Local;
-
-internal sealed class LocalAgentRegistry
-{
-    public HashSet<string> AgentNames { get; } = [];
-}

dotnet/src/Microsoft.Agents.AI.Hosting/Local/LocalWorkflowCatalog.cs

@@ -1,37 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System;
-using System.Collections.Generic;
-using System.Runtime.CompilerServices;
-using System.Threading;
-using System.Threading.Tasks;
-using Microsoft.Agents.AI.Workflows;
-using Microsoft.Extensions.DependencyInjection;
-
-namespace Microsoft.Agents.AI.Hosting.Local;
-
-internal sealed class LocalWorkflowCatalog : WorkflowCatalog
-{
-    public readonly HashSet<string> _registeredWorkflows;
-    private readonly IServiceProvider _serviceProvider;
-
-    public LocalWorkflowCatalog(LocalWorkflowRegistry workflowRegistry, IServiceProvider serviceProvider)
-    {
-        this._registeredWorkflows = [.. workflowRegistry.WorkflowNames];
-        this._serviceProvider = serviceProvider;
-    }
-
-    public override async IAsyncEnumerable<Workflow> GetWorkflowsAsync([EnumeratorCancellation] CancellationToken cancellationToken = default)
-    {
-        await Task.CompletedTask.ConfigureAwait(false);
-
-        foreach (var name in this._registeredWorkflows)
-        {
-            var workflow = this._serviceProvider.GetKeyedService<Workflow>(name);
-            if (workflow is not null)
-            {
-                yield return workflow;
-            }
-        }
-    }
-}

dotnet/src/Microsoft.Agents.AI.Hosting/Local/LocalWorkflowRegistry.cs

@@ -1,10 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System.Collections.Generic;
-
-namespace Microsoft.Agents.AI.Hosting.Local;
-
-internal sealed class LocalWorkflowRegistry
-{
-    public HashSet<string> WorkflowNames { get; } = [];
-}

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentThread.cs

@@ -75,8 +75,8 @@ public class ChatClientAgentThread : AgentThread
     /// <remarks>
     /// <para>
     /// Note that either <see cref="ConversationId"/> or <see cref="MessageStore "/> may be set, but not both.
-    /// If <see cref="MessageStore "/> is not null, and <see cref="ConversationId"/> is set, <see cref="MessageStore "/>
-    /// will be reverted to null, and vice versa.
+    /// If <see cref="MessageStore "/> is not null, setting <see cref="ConversationId"/> will throw an
+    /// <see cref="InvalidOperationException "/> exception.
     /// </para>
     /// <para>
     /// This property may be null in the following cases:
@@ -91,6 +91,7 @@ public class ChatClientAgentThread : AgentThread
     /// to fork the thread with each iteration.
     /// </para>
     /// </remarks>
+    /// <exception cref="InvalidOperationException">Attempted to set a conversation ID but a <see cref="MessageStore"/> is already set.</exception>
     public string? ConversationId
     {
         get => this._conversationId;

dotnet/tests/Microsoft.Agents.AI.DevUI.UnitTests/DevUIExtensionsTests.cs

@@ -0,0 +1,222 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+using Moq;
+
+namespace Microsoft.Agents.AI.DevUI.UnitTests;
+
+/// <summary>
+/// Unit tests for DevUI service collection extensions.
+/// Tests verify that workflows and agents can be resolved even when registered non-conventionally.
+/// </summary>
+public class DevUIExtensionsTests
+{
+    /// <summary>
+    /// Verifies that AddDevUI throws ArgumentNullException when services collection is null.
+    /// </summary>
+    [Fact]
+    public void AddDevUI_NullServices_ThrowsArgumentNullException()
+    {
+        IServiceCollection services = null!;
+        Assert.Throws<ArgumentNullException>(() => services.AddDevUI());
+    }
+
+    /// <summary>
+    /// Verifies that GetRequiredKeyedService throws for non-existent keys.
+    /// </summary>
+    [Fact]
+    public void AddDevUI_GetRequiredKeyedServiceNonExistent_ThrowsInvalidOperationException()
+    {
+        // Arrange
+        var services = new ServiceCollection();
+        services.AddDevUI();
+        var serviceProvider = services.BuildServiceProvider();
+
+        // Act & Assert
+        Assert.Throws<InvalidOperationException>(() => serviceProvider.GetRequiredKeyedService<AIAgent>("non-existent"));
+    }
+
+    /// <summary>
+    /// Verifies that an agent with null name can be resolved by its workflow.
+    /// </summary>
+    [Fact]
+    public void AddDevUI_WorkflowWithName_CanBeResolved_AsAIAgent()
+    {
+        // Arrange
+        var services = new ServiceCollection();
+        var mockChatClient = new Mock<IChatClient>();
+        var agent1 = new ChatClientAgent(mockChatClient.Object, "Test 1", name: null);
+        var agent2 = new ChatClientAgent(mockChatClient.Object, "Test 2", name: null);
+        var workflow = AgentWorkflowBuilder.BuildSequential(agent1, agent2);
+
+        services.AddKeyedSingleton("workflow", workflow);
+        services.AddDevUI();
+
+        var serviceProvider = services.BuildServiceProvider();
+
+        // Act
+        var resolvedWorkflowAsAgent = serviceProvider.GetKeyedService<AIAgent>("workflow");
+
+        // Assert
+        Assert.NotNull(resolvedWorkflowAsAgent);
+        Assert.Null(resolvedWorkflowAsAgent.Name);
+    }
+
+    /// <summary>
+    /// Verifies that an agent with null name can be resolved by its workflow.
+    /// </summary>
+    [Fact]
+    public void AddDevUI_MultipleWorkflowsWithName_CanBeResolved_AsAIAgent()
+    {
+        var services = new ServiceCollection();
+        var mockChatClient = new Mock<IChatClient>();
+        var agent1 = new ChatClientAgent(mockChatClient.Object, "Test 1", name: null);
+        var agent2 = new ChatClientAgent(mockChatClient.Object, "Test 2", name: null);
+        var workflow1 = AgentWorkflowBuilder.BuildSequential(agent1, agent2);
+        var workflow2 = AgentWorkflowBuilder.BuildSequential(agent1, agent2);
+
+        services.AddKeyedSingleton("workflow1", workflow1);
+        services.AddKeyedSingleton("workflow2", workflow2);
+        services.AddDevUI();
+
+        var serviceProvider = services.BuildServiceProvider();
+
+        var resolvedWorkflow1AsAgent = serviceProvider.GetKeyedService<AIAgent>("workflow1");
+        Assert.NotNull(resolvedWorkflow1AsAgent);
+        Assert.Null(resolvedWorkflow1AsAgent.Name);
+
+        var resolvedWorkflow2AsAgent = serviceProvider.GetKeyedService<AIAgent>("workflow2");
+        Assert.NotNull(resolvedWorkflow2AsAgent);
+        Assert.Null(resolvedWorkflow2AsAgent.Name);
+
+        Assert.False(resolvedWorkflow1AsAgent == resolvedWorkflow2AsAgent);
+    }
+
+    /// <summary>
+    /// Verifies that an agent with null name can be resolved by its workflow.
+    /// </summary>
+    [Fact]
+    public void AddDevUI_NonKeyedWorkflow_CanBeResolved_AsAIAgent()
+    {
+        var services = new ServiceCollection();
+        var mockChatClient = new Mock<IChatClient>();
+        var agent1 = new ChatClientAgent(mockChatClient.Object, "Test 1", name: null);
+        var agent2 = new ChatClientAgent(mockChatClient.Object, "Test 2", name: null);
+        var workflow = AgentWorkflowBuilder.BuildSequential(agent1, agent2);
+
+        services.AddKeyedSingleton("workflow", workflow);
+        services.AddDevUI();
+
+        var serviceProvider = services.BuildServiceProvider();
+
+        var resolvedWorkflowAsAgent = serviceProvider.GetKeyedService<AIAgent>("workflow");
+        Assert.NotNull(resolvedWorkflowAsAgent);
+        Assert.Null(resolvedWorkflowAsAgent.Name);
+    }
+
+    /// <summary>
+    /// Verifies that an agent with null name can be resolved by its workflow.
+    /// </summary>
+    [Fact]
+    public void AddDevUI_NonKeyedWorkflow_PlusKeyedWorkflow_CanBeResolved_AsAIAgent()
+    {
+        var services = new ServiceCollection();
+        var mockChatClient = new Mock<IChatClient>();
+        var agent1 = new ChatClientAgent(mockChatClient.Object, "Test 1", name: null);
+        var agent2 = new ChatClientAgent(mockChatClient.Object, "Test 2", name: null);
+        var workflow = AgentWorkflowBuilder.BuildSequential("standardname", agent1, agent2);
+        var keyedWorkflow = AgentWorkflowBuilder.BuildSequential("keyedname", agent1, agent2);
+
+        services.AddSingleton(workflow);
+        services.AddKeyedSingleton("keyed", keyedWorkflow);
+        services.AddDevUI();
+
+        var serviceProvider = services.BuildServiceProvider();
+
+        // resolve a workflow with the same name as workflow's name (which is registered without a key)
+        var standardAgent = serviceProvider.GetKeyedService<AIAgent>("standardname");
+        Assert.NotNull(standardAgent);
+        Assert.Equal("standardname", standardAgent.Name);
+
+        var keyedAgent = serviceProvider.GetKeyedService<AIAgent>("keyed");
+        Assert.NotNull(keyedAgent);
+        Assert.Equal("keyedname", keyedAgent.Name);
+
+        var nonExisting = serviceProvider.GetKeyedService<AIAgent>("random-non-existing!!!");
+        Assert.Null(nonExisting);
+    }
+
+    /// <summary>
+    /// Verifies that an agent registered with a different key than its name can be resolved by key.
+    /// </summary>
+    [Fact]
+    public void AddDevUI_AgentRegisteredWithDifferentKey_CanBeResolvedByKey()
+    {
+        // Arrange
+        var services = new ServiceCollection();
+        const string AgentName = "actual-agent-name";
+        const string RegistrationKey = "different-key";
+        var mockChatClient = new Mock<IChatClient>();
+        var agent = new ChatClientAgent(mockChatClient.Object, "Test", AgentName);
+
+        services.AddKeyedSingleton<AIAgent>(RegistrationKey, agent);
+        services.AddDevUI();
+
+        var serviceProvider = services.BuildServiceProvider();
+
+        // Act
+        var resolvedAgent = serviceProvider.GetKeyedService<AIAgent>(RegistrationKey);
+
+        // Assert
+        Assert.NotNull(resolvedAgent);
+        // The resolved agent should have the agent's name, not the registration key
+        Assert.Equal(AgentName, resolvedAgent.Name);
+    }
+
+    /// <summary>
+    /// Verifies that an agent registered with a different key than its name can be resolved by key.
+    /// </summary>
+    [Fact]
+    public void AddDevUI_Keyed_AndStandard_BothCanBeResolved()
+    {
+        // Arrange
+        var services = new ServiceCollection();
+        var mockChatClient = new Mock<IChatClient>();
+        var defaultAgent = new ChatClientAgent(mockChatClient.Object, "default", "default");
+        var keyedAgent = new ChatClientAgent(mockChatClient.Object, "keyed", "keyed");
+
+        services.AddSingleton<AIAgent>(defaultAgent);
+        services.AddKeyedSingleton<AIAgent>("keyed-registration", keyedAgent);
+        services.AddDevUI();
+
+        var serviceProvider = services.BuildServiceProvider();
+
+        var resolvedKeyedAgent = serviceProvider.GetKeyedService<AIAgent>("keyed-registration");
+        Assert.NotNull(resolvedKeyedAgent);
+        Assert.Equal("keyed", resolvedKeyedAgent.Name);
+
+        // resolving default agent based on its name, not on the registration-key
+        var resolvedDefaultAgent = serviceProvider.GetKeyedService<AIAgent>("default");
+        Assert.NotNull(resolvedDefaultAgent);
+        Assert.Equal("default", resolvedDefaultAgent.Name);
+    }
+
+    /// <summary>
+    /// Verifies that the DevUI fallback handler error message includes helpful information.
+    /// </summary>
+    [Fact]
+    public void AddDevUI_InvalidResolution_ErrorMessageIsInformative()
+    {
+        // Arrange
+        var services = new ServiceCollection();
+        services.AddDevUI();
+        var serviceProvider = services.BuildServiceProvider();
+        const string InvalidKey = "invalid-key-name";
+
+        // Act & Assert
+        var exception = Assert.Throws<InvalidOperationException>(() => serviceProvider.GetRequiredKeyedService<AIAgent>(InvalidKey));
+    }
+}

dotnet/tests/Microsoft.Agents.AI.DevUI.UnitTests/DevUIIntegrationTests.cs

@@ -0,0 +1,285 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Net.Http.Json;
+using System.Threading.Tasks;
+using Microsoft.Agents.AI.DevUI.Entities;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.TestHost;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+using Moq;
+
+namespace Microsoft.Agents.AI.DevUI.UnitTests;
+
+public class DevUIIntegrationTests
+{
+    private sealed class NoOpExecutor(string id) : Executor(id)
+    {
+        protected override RouteBuilder ConfigureRoutes(RouteBuilder routeBuilder) =>
+            routeBuilder.AddHandler<object>(
+                (msg, ctx) => ctx.SendMessageAsync(msg));
+    }
+
+    [Fact]
+    public async Task TestServerWithDevUI_ResolvesRequestToWorkflow_ByKeyAsync()
+    {
+        // Arrange
+        WebApplicationBuilder builder = WebApplication.CreateBuilder();
+        builder.WebHost.UseTestServer();
+
+        var mockChatClient = new Mock<IChatClient>();
+        var agent = new ChatClientAgent(mockChatClient.Object, "Test", "agent-name");
+
+        builder.Services.AddKeyedSingleton<AIAgent>("registration-key", agent);
+        builder.Services.AddDevUI();
+
+        using WebApplication app = builder.Build();
+        app.MapDevUI();
+
+        await app.StartAsync();
+
+        // Act
+        var resolvedAgent = app.Services.GetKeyedService<AIAgent>("registration-key");
+        var client = app.GetTestClient();
+        var response = await client.GetAsync(new Uri("/v1/entities", uriKind: UriKind.Relative));
+
+        var discoveryResponse = await response.Content.ReadFromJsonAsync<DiscoveryResponse>();
+        Assert.NotNull(discoveryResponse);
+        Assert.Single(discoveryResponse.Entities);
+        Assert.Equal("agent-name", discoveryResponse.Entities[0].Name);
+    }
+
+    [Fact]
+    public async Task TestServerWithDevUI_ResolvesMultipleAIAgents_ByKeyAsync()
+    {
+        // Arrange
+        WebApplicationBuilder builder = WebApplication.CreateBuilder();
+        builder.WebHost.UseTestServer();
+
+        var mockChatClient = new Mock<IChatClient>();
+        var agent1 = new ChatClientAgent(mockChatClient.Object, "Test", "agent-one");
+        var agent2 = new ChatClientAgent(mockChatClient.Object, "Test", "agent-two");
+        var agent3 = new ChatClientAgent(mockChatClient.Object, "Test", "agent-three");
+
+        builder.Services.AddKeyedSingleton<AIAgent>("key-1", agent1);
+        builder.Services.AddKeyedSingleton<AIAgent>("key-2", agent2);
+        builder.Services.AddKeyedSingleton<AIAgent>("key-3", agent3);
+        builder.Services.AddDevUI();
+
+        using WebApplication app = builder.Build();
+        app.MapDevUI();
+
+        await app.StartAsync();
+
+        // Act
+        var client = app.GetTestClient();
+        var response = await client.GetAsync(new Uri("/v1/entities", uriKind: UriKind.Relative));
+
+        var discoveryResponse = await response.Content.ReadFromJsonAsync<DiscoveryResponse>();
+
+        // Assert
+        Assert.NotNull(discoveryResponse);
+        Assert.Equal(3, discoveryResponse.Entities.Count);
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "agent-one" && e.Type == "agent");
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "agent-two" && e.Type == "agent");
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "agent-three" && e.Type == "agent");
+    }
+
+    [Fact]
+    public async Task TestServerWithDevUI_ResolvesAIAgents_WithKeyedAndDefaultRegistrationAsync()
+    {
+        // Arrange
+        WebApplicationBuilder builder = WebApplication.CreateBuilder();
+        builder.WebHost.UseTestServer();
+
+        var mockChatClient = new Mock<IChatClient>();
+        var agentKeyed1 = new ChatClientAgent(mockChatClient.Object, "Test", "keyed-agent-one");
+        var agentKeyed2 = new ChatClientAgent(mockChatClient.Object, "Test", "keyed-agent-two");
+        var agentDefault = new ChatClientAgent(mockChatClient.Object, "Test", "default-agent");
+
+        builder.Services.AddKeyedSingleton<AIAgent>("key-1", agentKeyed1);
+        builder.Services.AddKeyedSingleton<AIAgent>("key-2", agentKeyed2);
+        builder.Services.AddSingleton<AIAgent>(agentDefault);
+        builder.Services.AddDevUI();
+
+        using WebApplication app = builder.Build();
+        app.MapDevUI();
+
+        await app.StartAsync();
+
+        // Act
+        var client = app.GetTestClient();
+        var response = await client.GetAsync(new Uri("/v1/entities", uriKind: UriKind.Relative));
+
+        var discoveryResponse = await response.Content.ReadFromJsonAsync<DiscoveryResponse>();
+
+        // Assert
+        Assert.NotNull(discoveryResponse);
+        Assert.Equal(3, discoveryResponse.Entities.Count);
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "keyed-agent-one" && e.Type == "agent");
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "keyed-agent-two" && e.Type == "agent");
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "default-agent" && e.Type == "agent");
+    }
+
+    [Fact]
+    public async Task TestServerWithDevUI_ResolvesMultipleWorkflows_ByKeyAsync()
+    {
+        // Arrange
+        WebApplicationBuilder builder = WebApplication.CreateBuilder();
+        builder.WebHost.UseTestServer();
+
+        var workflow1 = new WorkflowBuilder("executor-1")
+            .WithName("workflow-one")
+            .WithDescription("First workflow")
+            .BindExecutor(new NoOpExecutor("executor-1"))
+            .Build();
+
+        var workflow2 = new WorkflowBuilder("executor-2")
+            .WithName("workflow-two")
+            .WithDescription("Second workflow")
+            .BindExecutor(new NoOpExecutor("executor-2"))
+            .Build();
+
+        var workflow3 = new WorkflowBuilder("executor-3")
+            .WithName("workflow-three")
+            .WithDescription("Third workflow")
+            .BindExecutor(new NoOpExecutor("executor-3"))
+            .Build();
+
+        builder.Services.AddKeyedSingleton("key-1", workflow1);
+        builder.Services.AddKeyedSingleton("key-2", workflow2);
+        builder.Services.AddKeyedSingleton("key-3", workflow3);
+        builder.Services.AddDevUI();
+
+        using WebApplication app = builder.Build();
+        app.MapDevUI();
+
+        await app.StartAsync();
+
+        // Act
+        var client = app.GetTestClient();
+        var response = await client.GetAsync(new Uri("/v1/entities", uriKind: UriKind.Relative));
+
+        var discoveryResponse = await response.Content.ReadFromJsonAsync<DiscoveryResponse>();
+
+        // Assert
+        Assert.NotNull(discoveryResponse);
+        Assert.Equal(3, discoveryResponse.Entities.Count);
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "workflow-one" && e.Type == "workflow");
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "workflow-two" && e.Type == "workflow");
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "workflow-three" && e.Type == "workflow");
+    }
+
+    [Fact]
+    public async Task TestServerWithDevUI_ResolvesWorkflows_WithKeyedAndDefaultRegistrationAsync()
+    {
+        // Arrange
+        WebApplicationBuilder builder = WebApplication.CreateBuilder();
+        builder.WebHost.UseTestServer();
+
+        var workflowKeyed1 = new WorkflowBuilder("executor-1")
+            .WithName("keyed-workflow-one")
+            .BindExecutor(new NoOpExecutor("executor-1"))
+            .Build();
+
+        var workflowKeyed2 = new WorkflowBuilder("executor-2")
+            .WithName("keyed-workflow-two")
+            .BindExecutor(new NoOpExecutor("executor-2"))
+            .Build();
+
+        var workflowDefault = new WorkflowBuilder("executor-default")
+            .WithName("default-workflow")
+            .BindExecutor(new NoOpExecutor("executor-default"))
+            .Build();
+
+        builder.Services.AddKeyedSingleton("key-1", workflowKeyed1);
+        builder.Services.AddKeyedSingleton("key-2", workflowKeyed2);
+        builder.Services.AddSingleton(workflowDefault);
+        builder.Services.AddDevUI();
+
+        using WebApplication app = builder.Build();
+        app.MapDevUI();
+
+        await app.StartAsync();
+
+        // Act
+        var client = app.GetTestClient();
+        var response = await client.GetAsync(new Uri("/v1/entities", uriKind: UriKind.Relative));
+
+        var discoveryResponse = await response.Content.ReadFromJsonAsync<DiscoveryResponse>();
+
+        // Assert
+        Assert.NotNull(discoveryResponse);
+        Assert.Equal(3, discoveryResponse.Entities.Count);
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "keyed-workflow-one" && e.Type == "workflow");
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "keyed-workflow-two" && e.Type == "workflow");
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "default-workflow" && e.Type == "workflow");
+    }
+
+    [Fact]
+    public async Task TestServerWithDevUI_ResolvesMixedAgentsAndWorkflows_AllRegistrationsAsync()
+    {
+        // Arrange
+        WebApplicationBuilder builder = WebApplication.CreateBuilder();
+        builder.WebHost.UseTestServer();
+
+        var mockChatClient = new Mock<IChatClient>();
+
+        // Create AIAgents
+        var agent1 = new ChatClientAgent(mockChatClient.Object, "Test", "mixed-agent-one");
+        var agent2 = new ChatClientAgent(mockChatClient.Object, "Test", "mixed-agent-two");
+        var agentDefault = new ChatClientAgent(mockChatClient.Object, "Test", "default-mixed-agent");
+
+        // Create Workflows
+        var workflow1 = new WorkflowBuilder("executor-1")
+            .WithName("mixed-workflow-one")
+            .BindExecutor(new NoOpExecutor("executor-1"))
+            .Build();
+
+        var workflow2 = new WorkflowBuilder("executor-2")
+            .WithName("mixed-workflow-two")
+            .BindExecutor(new NoOpExecutor("executor-2"))
+            .Build();
+
+        var workflowDefault = new WorkflowBuilder("executor-default")
+            .WithName("default-mixed-workflow")
+            .BindExecutor(new NoOpExecutor("executor-default"))
+            .Build();
+
+        // Register all
+        builder.Services.AddKeyedSingleton<AIAgent>("agent-key-1", agent1);
+        builder.Services.AddKeyedSingleton<AIAgent>("agent-key-2", agent2);
+        builder.Services.AddSingleton<AIAgent>(agentDefault);
+        builder.Services.AddKeyedSingleton("workflow-key-1", workflow1);
+        builder.Services.AddKeyedSingleton("workflow-key-2", workflow2);
+        builder.Services.AddSingleton(workflowDefault);
+        builder.Services.AddDevUI();
+
+        using WebApplication app = builder.Build();
+        app.MapDevUI();
+
+        await app.StartAsync();
+
+        // Act
+        var client = app.GetTestClient();
+        var response = await client.GetAsync(new Uri("/v1/entities", uriKind: UriKind.Relative));
+
+        var discoveryResponse = await response.Content.ReadFromJsonAsync<DiscoveryResponse>();
+
+        // Assert
+        Assert.NotNull(discoveryResponse);
+        Assert.Equal(6, discoveryResponse.Entities.Count);
+
+        // Verify agents
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "mixed-agent-one" && e.Type == "agent");
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "mixed-agent-two" && e.Type == "agent");
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "default-mixed-agent" && e.Type == "agent");
+
+        // Verify workflows
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "mixed-workflow-one" && e.Type == "workflow");
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "mixed-workflow-two" && e.Type == "workflow");
+        Assert.Contains(discoveryResponse.Entities, e => e.Name == "default-mixed-workflow" && e.Type == "workflow");
+    }
+}

dotnet/tests/Microsoft.Agents.AI.DevUI.UnitTests/Microsoft.Agents.AI.DevUI.UnitTests.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFrameworks>$(ProjectsCoreTargetFrameworks)</TargetFrameworks>
+    <TargetFrameworks Condition="'$(Configuration)' == 'Debug'">$(ProjectsDebugCoreTargetFrameworks)</TargetFrameworks>
+    <IsPackable>false</IsPackable>
+    <NoWarn>$(NoWarn);CA1812</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.AspNetCore.TestHost" VersionOverride="8.0.21" Condition="'$(TargetFramework)' == 'net8.0'" />
+    <PackageReference Include="Microsoft.AspNetCore.TestHost" Condition="'$(TargetFramework)' != 'net8.0'" />
+    <PackageReference Include="OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Microsoft.Agents.AI.DevUI\Microsoft.Agents.AI.DevUI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/tests/Microsoft.Agents.AI.DevUI.UnitTests/Properties/launchSettings.json

@@ -0,0 +1,12 @@
+{
+  "profiles": {
+    "Microsoft.Agents.AI.DevUI.UnitTests": {
+      "commandName": "Project",
+      "launchBrowser": true,
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      },
+      "applicationUrl": "https://localhost:63009;http://localhost:63010"
+    }
+  }
+}

dotnet/tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/Properties/launchSettings.json

@@ -0,0 +1,12 @@
+{
+  "profiles": {
+    "Microsoft.Agents.AI.Hosting.A2A.UnitTests": {
+      "commandName": "Project",
+      "launchBrowser": true,
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      },
+      "applicationUrl": "https://localhost:52186;http://localhost:52187"
+    }
+  }
+}

dotnet/tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests/SamplesValidation.cs

@@ -75,9 +75,9 @@ public sealed class SamplesValidation(ITestOutputHelper outputHelper) : IAsyncLi
             // The response headers should include the agent thread ID, which can be used to continue the conversation.
             string? threadId = response.Headers.GetValues("x-ms-thread-id")?.FirstOrDefault();
             Assert.NotNull(threadId);
+            Assert.NotEmpty(threadId);
 
             this._outputHelper.WriteLine($"Agent thread ID: {threadId}");
-            Assert.StartsWith("@dafx-joker@", threadId);
 
             // Wait for up to 30 seconds to see if the agent response is available in the logs
             await this.WaitForConditionAsync(
@@ -289,7 +289,7 @@ public sealed class SamplesValidation(ITestOutputHelper outputHelper) : IAsyncLi
             startResponse.Headers.TryGetValues("x-ms-thread-id", out IEnumerable<string>? agentIdValues);
             string? threadId = agentIdValues?.FirstOrDefault();
             Assert.NotNull(threadId);
-            Assert.StartsWith("@dafx-publisher@", threadId);
+            Assert.NotEmpty(threadId);
 
             // Wait for the orchestration to report that it's waiting for human approval
             await this.WaitForConditionAsync(

python/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0b251117] - 2025-11-17
+
+### Fixed
+
+- **agent-framework-ag-ui**: Fix ag-ui state handling issues ([#2289](https://github.com/microsoft/agent-framework/pull/2289))
+
 ## [1.0.0b251114] - 2025-11-14
 
 ### Added

python/packages/ag-ui/agent_framework_ag_ui/_events.py

@@ -86,6 +86,7 @@ class AgentFrameworkEventBridge:
         self.pending_tool_calls: list[dict[str, Any]] = []  # Track tool calls for assistant message
         self.tool_results: list[dict[str, Any]] = []  # Track tool results
         self.tool_calls_ended: set[str] = set()  # Track which tool calls have had ToolCallEndEvent emitted
+        self.accumulated_text_content: str = ""  # Track accumulated text for final MessagesSnapshotEvent
 
     async def from_agent_run_update(self, update: AgentRunResponseUpdate) -> list[BaseEvent]:
         """
@@ -99,18 +100,29 @@ class AgentFrameworkEventBridge:
         """
         events: list[BaseEvent] = []
 
-        for content in update.contents:
+        logger.info(f"Processing AgentRunUpdate with {len(update.contents)} content items")
+        for idx, content in enumerate(update.contents):
+            logger.info(f"  Content {idx}: type={type(content).__name__}")
             if isinstance(content, TextContent):
+                logger.info(
+                    f"  TextContent found: text_length={len(content.text)}, text_preview='{content.text[:100]}'"
+                )
+                logger.info(
+                    f"  Flags: skip_text_content={self.skip_text_content}, should_stop_after_confirm={self.should_stop_after_confirm}"
+                )
+
                 # Skip text content if using structured outputs (it's just the JSON)
                 if self.skip_text_content:
+                    logger.info("  SKIPPING TextContent: skip_text_content is True")
                     continue
 
                 # Skip text content if we're about to emit confirm_changes
                 # The summary should only appear after user confirms
                 if self.should_stop_after_confirm:
-                    logger.debug("Skipping text content - waiting for confirm_changes response")
+                    logger.info("  SKIPPING TextContent: waiting for confirm_changes response")
                     # Save the summary text to show after confirmation
                     self.suppressed_summary += content.text
+                    logger.info(f"  Suppressed summary now has {len(self.suppressed_summary)} chars")
                     continue
 
                 if not self.current_message_id:
@@ -119,14 +131,16 @@ class AgentFrameworkEventBridge:
                         message_id=self.current_message_id,
                         role="assistant",
                     )
-                    logger.debug(f"Emitting TextMessageStartEvent with message_id={self.current_message_id}")
+                    logger.info(f"  EMITTING TextMessageStartEvent with message_id={self.current_message_id}")
                     events.append(start_event)
 
                 event = TextMessageContentEvent(
                     message_id=self.current_message_id,
                     delta=content.text,
                 )
-                logger.debug(f"Emitting TextMessageContentEvent with delta: {content.text}")
+                # Accumulate text content for final MessagesSnapshotEvent
+                self.accumulated_text_content += content.text
+                logger.info(f"  EMITTING TextMessageContentEvent with delta: '{content.text}'")
                 events.append(event)
 
             elif isinstance(content, FunctionCallContent):
@@ -427,7 +441,24 @@ class AgentFrameworkEventBridge:
 
                 # Emit MessagesSnapshotEvent with the complete conversation including tool calls and results
                 # This is required for CopilotKit's useCopilotAction to detect tool result
-                if self.pending_tool_calls and self.tool_results:
+                # HOWEVER: Skip this for predictive tools when require_confirmation=False, because
+                # the agent will generate a follow-up text message and we'll emit a complete snapshot at the end.
+                # Emitting here would create an incomplete snapshot that gets replaced, causing UI flicker.
+                should_emit_snapshot = self.pending_tool_calls and self.tool_results
+
+                # Check if this is a predictive tool that will have a follow-up message
+                is_predictive_without_confirmation = False
+                if should_emit_snapshot and self.current_tool_call_name and self.predict_state_config:
+                    for state_key, config in self.predict_state_config.items():
+                        if config["tool"] == self.current_tool_call_name and not self.require_confirmation:
+                            is_predictive_without_confirmation = True
+                            logger.info(
+                                f"Skipping intermediate MessagesSnapshotEvent for predictive tool '{self.current_tool_call_name}' "
+                                "- will emit complete snapshot after follow-up message"
+                            )
+                            break
+
+                if should_emit_snapshot and not is_predictive_without_confirmation:
                     # Import message adapter
                     from ._message_adapters import agent_framework_messages_to_agui
 

python/packages/ag-ui/agent_framework_ag_ui/_message_adapters.py

@@ -283,8 +283,62 @@ def extract_text_from_contents(contents: list[Any]) -> str:
     return "".join(text_parts)
 
 
+def agui_messages_to_snapshot_format(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Normalize AG-UI messages for MessagesSnapshotEvent.
+
+    Converts AG-UI input format (with 'input_text' type) to snapshot format (with 'text' type).
+
+    Args:
+        messages: List of AG-UI messages in input format
+
+    Returns:
+        List of normalized messages suitable for MessagesSnapshotEvent
+    """
+    from ._utils import generate_event_id
+
+    result: list[dict[str, Any]] = []
+    for msg in messages:
+        normalized_msg = msg.copy()
+
+        # Ensure ID exists
+        if "id" not in normalized_msg:
+            normalized_msg["id"] = generate_event_id()
+
+        # Normalize content field
+        content = normalized_msg.get("content")
+        if isinstance(content, list):
+            # Convert content array format to simple string
+            text_parts = []
+            for item in content:
+                if isinstance(item, dict):
+                    # Convert 'input_text' to 'text' type
+                    if item.get("type") == "input_text":
+                        text_parts.append(item.get("text", ""))
+                    elif item.get("type") == "text":
+                        text_parts.append(item.get("text", ""))
+                    else:
+                        # Other types - just extract text field if present
+                        text_parts.append(item.get("text", ""))
+            normalized_msg["content"] = "".join(text_parts)
+        elif content is None:
+            normalized_msg["content"] = ""
+
+        # Normalize tool_call_id to toolCallId for tool messages
+        if normalized_msg.get("role") == "tool":
+            if "tool_call_id" in normalized_msg:
+                normalized_msg["toolCallId"] = normalized_msg["tool_call_id"]
+                del normalized_msg["tool_call_id"]
+            elif "toolCallId" not in normalized_msg:
+                normalized_msg["toolCallId"] = ""
+
+        result.append(normalized_msg)
+
+    return result
+
+
 __all__ = [
     "agui_messages_to_agent_framework",
     "agent_framework_messages_to_agui",
+    "agui_messages_to_snapshot_format",
     "extract_text_from_contents",
 ]

python/packages/ag-ui/agent_framework_ag_ui/_orchestrators.py

@@ -11,6 +11,7 @@ from typing import TYPE_CHECKING, Any
 
 from ag_ui.core import (
     BaseEvent,
+    MessagesSnapshotEvent,
     RunErrorEvent,
     TextMessageContentEvent,
     TextMessageEndEvent,
@@ -588,32 +589,37 @@ class DefaultOrchestrator(Orchestrator):
         # We should NOT add to thread.on_new_messages() as that would cause duplication.
         # Instead, we pass messages directly to the agent via messages_to_run.
 
-        # Inject current state as system message context if we have state
+        # Inject current state as system message context if we have state and this is a new user turn
         messages_to_run: list[Any] = []
 
+        # Check if the last message is from the user (new turn) vs assistant/tool (mid-execution)
+        is_new_user_turn = False
+        if provider_messages:
+            last_msg = provider_messages[-1]
+            is_new_user_turn = last_msg.role.value == "user"
+
+        # Check if conversation has tool calls (indicates mid-execution)
         conversation_has_tool_calls = False
-        logger.debug(f"Checking {len(provider_messages)} provider messages for tool calls")
-        for i, msg in enumerate(provider_messages):
-            logger.debug(
-                f"  Message {i}: role={msg.role.value}, contents={len(msg.contents) if hasattr(msg, 'contents') and msg.contents else 0}"
-            )
         for msg in provider_messages:
             if msg.role.value == "assistant" and hasattr(msg, "contents") and msg.contents:
                 if any(isinstance(content, FunctionCallContent) for content in msg.contents):
                     conversation_has_tool_calls = True
                     break
-        if current_state and context.config.state_schema and not conversation_has_tool_calls:
+
+        # Only inject state context on new user turns AND when conversation doesn't have tool calls
+        # (tool calls indicate we're mid-execution, so state context was already injected)
+        if current_state and context.config.state_schema and is_new_user_turn and not conversation_has_tool_calls:
             state_json = json.dumps(current_state, indent=2)
             state_context_msg = ChatMessage(
                 role="system",
                 contents=[
                     TextContent(
                         text=f"""Current state of the application:
-{state_json}
+        {state_json}
 
-When modifying state, you MUST include ALL existing data plus your changes.
-For example, if adding a new ingredient, include all existing ingredients PLUS the new one.
-Never replace existing data - always append or merge."""
+        When modifying state, you MUST include ALL existing data plus your changes.
+        For example, if adding one new item to a list, include ALL existing items PLUS the one new item.
+        Never replace existing data - always preserve and append or merge."""
                     )
                 ],
             )
@@ -714,12 +720,19 @@ Never replace existing data - always append or merge."""
 
         # Collect all updates to get the final structured output
         all_updates: list[Any] = []
+        update_count = 0
         async for update in context.agent.run_stream(messages_to_run, thread=thread, tools=tools_param):
+            update_count += 1
+            logger.info(f"[STREAM] Received update #{update_count} from agent")
             all_updates.append(update)
             events = await event_bridge.from_agent_run_update(update)
+            logger.info(f"[STREAM] Update #{update_count} produced {len(events)} events")
             for event in events:
+                logger.info(f"[STREAM] Yielding event: {type(event).__name__}")
                 yield event
 
+        logger.info(f"[STREAM] Agent stream completed. Total updates: {update_count}")
+
         # After agent completes, check if we should stop (waiting for user to confirm changes)
         if event_bridge.should_stop_after_confirm:
             logger.info("Stopping run after confirm_changes - waiting for user response")
@@ -793,9 +806,56 @@ Never replace existing data - always append or merge."""
                     yield TextMessageEndEvent(message_id=message_id)
                     logger.info(f"Emitted conversational message: {response_dict['message'][:100]}...")
 
+        logger.info(f"[FINALIZE] Checking for unclosed message. current_message_id={event_bridge.current_message_id}")
         if event_bridge.current_message_id:
+            logger.info(f"[FINALIZE] Emitting TextMessageEndEvent for message_id={event_bridge.current_message_id}")
             yield event_bridge.create_message_end_event(event_bridge.current_message_id)
 
+            # Emit MessagesSnapshotEvent to persist the final assistant text message
+            from ._message_adapters import agui_messages_to_snapshot_format
+
+            # Build the final assistant message with accumulated text content
+            assistant_text_message = {
+                "id": event_bridge.current_message_id,
+                "role": "assistant",
+                "content": event_bridge.accumulated_text_content,
+            }
+
+            # Convert input messages to snapshot format (normalize content structure)
+            # event_bridge.input_messages are already in AG-UI format, just need normalization
+            converted_input_messages = agui_messages_to_snapshot_format(event_bridge.input_messages)
+
+            # Build complete messages array
+            # Include: input messages + any pending tool calls/results + final text message
+            all_messages = converted_input_messages.copy()
+
+            # Add assistant message with tool calls if any
+            if event_bridge.pending_tool_calls:
+                tool_call_message = {
+                    "id": generate_event_id(),
+                    "role": "assistant",
+                    "tool_calls": event_bridge.pending_tool_calls.copy(),
+                }
+                all_messages.append(tool_call_message)
+
+            # Add tool results if any
+            all_messages.extend(event_bridge.tool_results.copy())
+
+            # Add final text message
+            all_messages.append(assistant_text_message)
+
+            messages_snapshot = MessagesSnapshotEvent(
+                messages=all_messages,  # type: ignore[arg-type]
+            )
+            logger.info(
+                f"[FINALIZE] Emitting MessagesSnapshotEvent with {len(all_messages)} messages "
+                f"(text content length: {len(event_bridge.accumulated_text_content)})"
+            )
+            yield messages_snapshot
+        else:
+            logger.info("[FINALIZE] No current_message_id - skipping TextMessageEndEvent")
+
+        logger.info("[FINALIZE] Emitting RUN_FINISHED event")
         yield event_bridge.create_run_finished_event()
         logger.info(f"Completed agent run for thread_id={context.thread_id}, run_id={context.run_id}")
 

python/packages/ag-ui/agent_framework_ag_ui_examples/agents/recipe_agent.py

@@ -130,4 +130,5 @@ def recipe_agent(chat_client: ChatClientProtocol) -> AgentFrameworkAgent:
             "recipe": {"tool": "update_recipe", "tool_argument": "recipe"},
         },
         confirmation_strategy=RecipeConfirmationStrategy(),
+        require_confirmation=False,
     )

python/packages/ag-ui/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-framework-ag-ui"
-version = "1.0.0b251114"
+version = "1.0.0b251117"
 description = "AG-UI protocol integration for Agent Framework"
 readme = "README.md"
 license-files = ["LICENSE"]

python/packages/core/agent_framework/_workflows/__init__.py

@@ -37,6 +37,8 @@ from ._events import (
     ExecutorFailedEvent,
     ExecutorInvokedEvent,
     RequestInfoEvent,
+    SuperStepCompletedEvent,
+    SuperStepStartedEvent,
     WorkflowErrorDetails,
     WorkflowEvent,
     WorkflowEventSource,
@@ -152,6 +154,8 @@ __all__ = [
     "StandardMagenticManager",
     "SubWorkflowRequestMessage",
     "SubWorkflowResponseMessage",
+    "SuperStepCompletedEvent",
+    "SuperStepStartedEvent",
     "SwitchCaseEdgeGroup",
     "SwitchCaseEdgeGroupCase",
     "SwitchCaseEdgeGroupDefault",

python/packages/core/agent_framework/_workflows/__init__.pyi

@@ -35,6 +35,8 @@ from ._events import (
     ExecutorFailedEvent,
     ExecutorInvokedEvent,
     RequestInfoEvent,
+    SuperStepCompletedEvent,
+    SuperStepStartedEvent,
     WorkflowErrorDetails,
     WorkflowEvent,
     WorkflowEventSource,
@@ -148,6 +150,8 @@ __all__ = [
     "StandardMagenticManager",
     "SubWorkflowRequestMessage",
     "SubWorkflowResponseMessage",
+    "SuperStepCompletedEvent",
+    "SuperStepStartedEvent",
     "SwitchCaseEdgeGroup",
     "SwitchCaseEdgeGroupCase",
     "SwitchCaseEdgeGroupDefault",

python/packages/core/agent_framework/_workflows/_agent_executor.py

@@ -1,6 +1,7 @@
 # Copyright (c) Microsoft. All rights reserved.
 
 import logging
+import sys
 from dataclasses import dataclass
 from typing import Any, cast
 
@@ -20,6 +21,11 @@ from ._message_utils import normalize_messages_input
 from ._request_info_mixin import response_handler
 from ._workflow_context import WorkflowContext
 
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
 logger = logging.getLogger(__name__)
 
 
@@ -179,7 +185,8 @@ class AgentExecutor(Executor):
             self._pending_responses_to_agent.clear()
             await self._run_agent_and_emit(ctx)
 
-    async def snapshot_state(self) -> dict[str, Any]:
+    @override
+    async def on_checkpoint_save(self) -> dict[str, Any]:
         """Capture current executor state for checkpointing.
 
         NOTE: if the thread storage is on the server side, the full thread state
@@ -196,9 +203,6 @@ class AgentExecutor(Executor):
             client_module = self._agent.chat_client.__class__.__module__
 
             if client_class_name == "AzureAIAgentClient" and "azure_ai" in client_module:
-                # TODO(TaoChenOSU): update this warning when we surface the hooks for
-                # custom executor checkpointing.
-                # https://github.com/microsoft/agent-framework/issues/1816
                 logger.warning(
                     "Checkpointing an AgentExecutor with AzureAIAgentClient that uses server-side threads. "
                     "Currently, checkpointing does not capture messages from server-side threads "
@@ -217,7 +221,8 @@ class AgentExecutor(Executor):
             "pending_responses_to_agent": encode_checkpoint_value(self._pending_responses_to_agent),
         }
 
-    async def restore_state(self, state: dict[str, Any]) -> None:
+    @override
+    async def on_checkpoint_restore(self, state: dict[str, Any]) -> None:
         """Restore executor state from checkpoint.
 
         Args:

python/packages/core/agent_framework/_workflows/_base_group_chat_orchestrator.py

@@ -4,6 +4,7 @@
 
 import inspect
 import logging
+import sys
 from abc import ABC, abstractmethod
 from collections.abc import Awaitable, Callable, Sequence
 from typing import Any
@@ -13,6 +14,12 @@ from ._executor import Executor
 from ._orchestrator_helpers import ParticipantRegistry
 from ._workflow_context import WorkflowContext
 
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
+
 logger = logging.getLogger(__name__)
 
 
@@ -210,11 +217,12 @@ class BaseGroupChatOrchestrator(Executor, ABC):
 
     # State persistence (shared across all patterns)
 
-    def snapshot_state(self) -> dict[str, Any]:
+    @override
+    async def on_checkpoint_save(self) -> dict[str, Any]:
         """Capture current orchestrator state for checkpointing.
 
         Default implementation uses OrchestrationState to serialize common state.
-        Subclasses should override _snapshot_pattern_metadata() to add pattern-specific data.
+        Subclasses can override this method or _snapshot_pattern_metadata() to add pattern-specific data.
 
         Returns:
             Serialized state dict
@@ -238,11 +246,12 @@ class BaseGroupChatOrchestrator(Executor, ABC):
         """
         return {}
 
-    def restore_state(self, state: dict[str, Any]) -> None:
+    @override
+    async def on_checkpoint_restore(self, state: dict[str, Any]) -> None:
         """Restore orchestrator state from checkpoint.
 
         Default implementation uses OrchestrationState to deserialize common state.
-        Subclasses should override _restore_pattern_metadata() to restore pattern-specific data.
+        Subclasses can override this method or _restore_pattern_metadata() to restore pattern-specific data.
 
         Args:
             state: Serialized state dict

python/packages/core/agent_framework/_workflows/_conversation_history.py

@@ -6,9 +6,7 @@ These utilities operate on standard `list[ChatMessage]` collections and simple
 dictionary snapshots so orchestrators can share logic without new mixins.
 """
 
-import json
-from collections.abc import Mapping, Sequence
-from typing import Any
+from collections.abc import Sequence
 
 from .._types import ChatMessage
 
@@ -26,25 +24,3 @@ def ensure_author(message: ChatMessage, fallback: str) -> ChatMessage:
     """Attach `fallback` author if message is missing `author_name`."""
     message.author_name = message.author_name or fallback
     return message
-
-
-def snapshot_state(conversation: Sequence[ChatMessage]) -> dict[str, Any]:
-    """Build an immutable snapshot for checkpoint storage."""
-    if hasattr(conversation, "to_dict"):
-        result = conversation.to_dict()  # type: ignore[attr-defined]
-        if isinstance(result, dict):
-            return result  # type: ignore[return-value]
-        if isinstance(result, Mapping):
-            return dict(result)  # type: ignore[arg-type]
-    serialisable: list[dict[str, Any]] = []
-    for message in conversation:
-        if hasattr(message, "to_dict") and callable(message.to_dict):  # type: ignore[attr-defined]
-            msg_dict = message.to_dict()  # type: ignore[attr-defined]
-            serialisable.append(dict(msg_dict) if isinstance(msg_dict, Mapping) else msg_dict)  # type: ignore[arg-type]
-        elif hasattr(message, "to_json") and callable(message.to_json):  # type: ignore[attr-defined]
-            json_payload = message.to_json()  # type: ignore[attr-defined]
-            parsed = json.loads(json_payload) if isinstance(json_payload, str) else json_payload
-            serialisable.append(dict(parsed) if isinstance(parsed, Mapping) else parsed)  # type: ignore[arg-type]
-        else:
-            serialisable.append(dict(getattr(message, "__dict__", {})))  # type: ignore[arg-type]
-    return {"messages": serialisable}

python/packages/core/agent_framework/_workflows/_events.py

@@ -294,6 +294,36 @@ class WorkflowOutputEvent(WorkflowEvent):
         return f"{self.__class__.__name__}(data={self.data}, source_executor_id={self.source_executor_id})"
 
 
+class SuperStepEvent(WorkflowEvent):
+    """Event triggered when a superstep starts or ends."""
+
+    def __init__(self, iteration: int, data: Any | None = None):
+        """Initialize the superstep event.
+
+        Args:
+            iteration: The number of the superstep (1-based index).
+            data: Optional data associated with the superstep event.
+        """
+        super().__init__(data)
+        self.iteration = iteration
+
+    def __repr__(self) -> str:
+        """Return a string representation of the superstep event."""
+        return f"{self.__class__.__name__}(iteration={self.iteration}, data={self.data})"
+
+
+class SuperStepStartedEvent(SuperStepEvent):
+    """Event triggered when a superstep starts."""
+
+    ...
+
+
+class SuperStepCompletedEvent(SuperStepEvent):
+    """Event triggered when a superstep ends."""
+
+    ...
+
+
 class ExecutorEvent(WorkflowEvent):
     """Base class for executor events."""
 
@@ -310,17 +340,13 @@ class ExecutorEvent(WorkflowEvent):
 class ExecutorInvokedEvent(ExecutorEvent):
     """Event triggered when an executor handler is invoked."""
 
-    def __repr__(self) -> str:
-        """Return a string representation of the executor handler invoke event."""
-        return f"{self.__class__.__name__}(executor_id={self.executor_id}, data={self.data})"
+    ...
 
 
 class ExecutorCompletedEvent(ExecutorEvent):
     """Event triggered when an executor handler is completed."""
 
-    def __repr__(self) -> str:
-        """Return a string representation of the executor handler complete event."""
-        return f"{self.__class__.__name__}(executor_id={self.executor_id}, data={self.data})"
+    ...
 
 
 class ExecutorFailedEvent(ExecutorEvent):

python/packages/core/agent_framework/_workflows/_executor.py

@@ -155,6 +155,11 @@ class Executor(RequestInfoMixin, DictConvertible):
     that parent workflows can intercept. See WorkflowExecutor documentation for details on
     workflow composition patterns and request/response handling.
 
+    ## State Management
+    Executors can contain states that persist across workflow runs and checkpoints. Override the
+    `on_checkpoint_save` and `on_checkpoint_restore` methods to implement custom state
+    serialization and restoration logic.
+
     ## Implementation Notes
     - Do not call `execute()` directly - it's invoked by the workflow engine
     - Do not override `execute()` - define handlers using decorators instead
@@ -460,6 +465,32 @@ class Executor(RequestInfoMixin, DictConvertible):
                 return self._handlers[message_type]
         raise RuntimeError(f"Executor {self.__class__.__name__} cannot handle message of type {type(message)}.")
 
+    async def on_checkpoint_save(self) -> dict[str, Any]:
+        """Hook called when the workflow is being saved to a checkpoint.
+
+        Override this method in subclasses to implement custom logic that should
+        return state to be saved in the checkpoint.
+
+        The returned state dictionary will be passed to `on_checkpoint_restore`
+        when the workflow is restored from the checkpoint. The dictionary should
+        only contain JSON-serializable data.
+
+        Returns:
+            A state dictionary to be saved during checkpointing.
+        """
+        return {}
+
+    async def on_checkpoint_restore(self, state: dict[str, Any]) -> None:
+        """Hook called when the workflow is restored from a checkpoint.
+
+        Override this method in subclasses to implement custom logic that should
+        run when the workflow is restored from a checkpoint.
+
+        Args:
+            state: The state dictionary that was saved during checkpointing.
+        """
+        ...
+
 
 # endregion: Executor
 

python/packages/core/agent_framework/_workflows/_function_executor.py

@@ -17,6 +17,7 @@ Design Pattern:
 
 import asyncio
 import inspect
+import typing
 from collections.abc import Awaitable, Callable
 from typing import Any, overload
 
@@ -218,15 +219,16 @@ def _validate_function_signature(func: Callable[..., Any]) -> tuple[type, Any, l
     if message_param.annotation == inspect.Parameter.empty:
         raise ValueError(f"Function instance {func.__name__} must have a type annotation for the message parameter")
 
-    message_type = message_param.annotation
+    type_hints = typing.get_type_hints(func)
+    message_type = type_hints.get(message_param.name, message_param.annotation)
 
     # Check if there's a context parameter
     if len(params) == 2:
         ctx_param = params[1]
+        ctx_annotation = type_hints.get(ctx_param.name, ctx_param.annotation)
         output_types, workflow_output_types = validate_workflow_context_annotation(
-            ctx_param.annotation, f"parameter '{ctx_param.name}'", "Function instance"
+            ctx_annotation, f"parameter '{ctx_param.name}'", "Function instance"
         )
-        ctx_annotation = ctx_param.annotation
     else:
         # No context parameter (only valid for function executors)
         output_types, workflow_output_types = [], []

python/packages/core/agent_framework/_workflows/_handoff.py

@@ -16,6 +16,7 @@ Key properties:
 
 import logging
 import re
+import sys
 from collections.abc import Awaitable, Callable, Mapping, Sequence
 from dataclasses import dataclass, field
 from typing import Any
@@ -50,6 +51,12 @@ from ._workflow import Workflow
 from ._workflow_builder import WorkflowBuilder
 from ._workflow_context import WorkflowContext
 
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
+
 logger = logging.getLogger(__name__)
 
 
@@ -307,15 +314,6 @@ class _HandoffCoordinator(BaseGroupChatOrchestrator):
         ctx: WorkflowContext[AgentExecutorRequest | list[ChatMessage], list[ChatMessage] | _ConversationForUserInput],
     ) -> None:
         """Process an agent's response and determine whether to route, request input, or terminate."""
-        # Hydrate coordinator state (and detect new run) using checkpointable executor state
-        state = await ctx.get_executor_state()
-        if not state:
-            self._clear_conversation()
-        elif not self._get_conversation():
-            restored = self._restore_conversation_from_state(state)
-            if restored:
-                self._conversation = list(restored)
-
         source = ctx.get_source_executor_id()
         is_starting_agent = source == self._starting_agent_id
 
@@ -343,7 +341,7 @@ class _HandoffCoordinator(BaseGroupChatOrchestrator):
             # Update current agent when handoff occurs
             self._current_agent_id = target
             logger.info(f"Handoff detected: {source} -> {target}. Routing control to specialist '{target}'.")
-            await self._persist_state(ctx)
+
             # Clean tool-related content before sending to next agent
             cleaned = clean_conversation_for_handoff(conversation)
             request = AgentExecutorRequest(messages=cleaned, should_respond=True)
@@ -360,7 +358,6 @@ class _HandoffCoordinator(BaseGroupChatOrchestrator):
             f"Agent '{source}' responded without handoff. "
             f"Requesting user input. Return-to-previous: {self._return_to_previous}"
         )
-        await self._persist_state(ctx)
 
         if await self._check_termination():
             # Clean the output conversation for display
@@ -388,7 +385,6 @@ class _HandoffCoordinator(BaseGroupChatOrchestrator):
         """Receive full conversation with new user input from gateway, update history, trim for agent."""
         # Update authoritative conversation
         self._conversation = list(message.full_conversation)
-        await self._persist_state(ctx)
 
         # Check termination before sending to agent
         if await self._check_termination():
@@ -473,11 +469,7 @@ class _HandoffCoordinator(BaseGroupChatOrchestrator):
             )
         return list(conversation)
 
-    async def _persist_state(self, ctx: WorkflowContext[Any, Any]) -> None:
-        """Store authoritative conversation snapshot without losing rich metadata."""
-        state_payload = self.snapshot_state()
-        await ctx.set_executor_state(state_payload)
-
+    @override
     def _snapshot_pattern_metadata(self) -> dict[str, Any]:
         """Serialize pattern-specific state.
 
@@ -492,6 +484,7 @@ class _HandoffCoordinator(BaseGroupChatOrchestrator):
             }
         return {}
 
+    @override
     def _restore_pattern_metadata(self, metadata: dict[str, Any]) -> None:
         """Restore pattern-specific state.
 
@@ -503,17 +496,6 @@ class _HandoffCoordinator(BaseGroupChatOrchestrator):
         if self._return_to_previous and "current_agent_id" in metadata:
             self._current_agent_id = metadata["current_agent_id"]
 
-    def _restore_conversation_from_state(self, state: Mapping[str, Any]) -> list[ChatMessage]:
-        """Rehydrate the coordinator's conversation history from checkpointed state.
-
-        DEPRECATED: Use restore_state() instead. Kept for backward compatibility.
-        """
-        from ._orchestration_state import OrchestrationState
-
-        orch_state_dict = {"conversation": state.get("full_conversation", state.get("conversation", []))}
-        temp_state = OrchestrationState.from_dict(orch_state_dict)
-        return list(temp_state.conversation)
-
     def _apply_response_metadata(self, conversation: list[ChatMessage], agent_response: AgentRunResponse) -> None:
         """Merge top-level response metadata into the latest assistant message."""
         if not agent_response.additional_properties:

python/packages/core/agent_framework/_workflows/_magentic.py

@@ -45,9 +45,15 @@ from ._workflow import Workflow, WorkflowRunResult
 from ._workflow_context import WorkflowContext
 
 if sys.version_info >= (3, 11):
-    from typing import Self  # pragma: no cover
+    from typing import Self
 else:
-    from typing_extensions import Self  # pragma: no cover
+    from typing_extensions import Self
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
 
 logger = logging.getLogger(__name__)
 
@@ -673,11 +679,11 @@ class MagenticManagerBase(ABC):
         """Prepare the final answer."""
         ...
 
-    def snapshot_state(self) -> dict[str, Any]:
+    def on_checkpoint_save(self) -> dict[str, Any]:
         """Serialize runtime state for checkpointing."""
         return {}
 
-    def restore_state(self, state: dict[str, Any]) -> None:
+    def on_checkpoint_restore(self, state: dict[str, Any]) -> None:
         """Restore runtime state from checkpoint data."""
         return
 
@@ -695,22 +701,6 @@ class StandardMagenticManager(MagenticManagerBase):
 
     task_ledger: _MagenticTaskLedger | None
 
-    def snapshot_state(self) -> dict[str, Any]:
-        state = super().snapshot_state()
-        if self.task_ledger is not None:
-            state = dict(state)
-            state["task_ledger"] = self.task_ledger.to_dict()
-        return state
-
-    def restore_state(self, state: dict[str, Any]) -> None:
-        super().restore_state(state)
-        ledger = state.get("task_ledger")
-        if ledger is not None:
-            try:
-                self.task_ledger = _MagenticTaskLedger.from_dict(ledger)
-            except Exception:  # pragma: no cover - defensive
-                logger.warning("Failed to restore manager task ledger from checkpoint state")
-
     def __init__(
         self,
         chat_client: ChatClientProtocol,
@@ -940,6 +930,22 @@ class StandardMagenticManager(MagenticManagerBase):
             author_name=response.author_name or MAGENTIC_MANAGER_NAME,
         )
 
+    @override
+    def on_checkpoint_save(self) -> dict[str, Any]:
+        state: dict[str, Any] = {}
+        if self.task_ledger is not None:
+            state["task_ledger"] = self.task_ledger.to_dict()
+        return state
+
+    @override
+    def on_checkpoint_restore(self, state: dict[str, Any]) -> None:
+        ledger = state.get("task_ledger")
+        if ledger is not None:
+            try:
+                self.task_ledger = _MagenticTaskLedger.from_dict(ledger)
+            except Exception:  # pragma: no cover - defensive
+                logger.warning("Failed to restore manager task ledger from checkpoint state")
+
 
 # endregion Magentic Manager
 
@@ -997,7 +1003,6 @@ class MagenticOrchestratorExecutor(BaseGroupChatOrchestrator):
         # Terminal state marker to stop further processing after completion/limits
         self._terminated = False
         # Tracks whether checkpoint state has been applied for this run
-        self._state_restored = False
 
     def _get_author_name(self) -> str:
         """Get the magentic manager name for orchestrator-generated messages."""
@@ -1036,7 +1041,8 @@ class MagenticOrchestratorExecutor(BaseGroupChatOrchestrator):
         )
         await ctx.add_event(event)
 
-    def snapshot_state(self) -> dict[str, Any]:
+    @override
+    async def on_checkpoint_save(self) -> dict[str, Any]:
         """Capture current orchestrator state for checkpointing.
 
         Uses OrchestrationState for structure but maintains Magentic's complex metadata
@@ -1055,14 +1061,16 @@ class MagenticOrchestratorExecutor(BaseGroupChatOrchestrator):
             state["magentic_context"] = self._context.to_dict()
         if self._task_ledger is not None:
             state["task_ledger"] = _message_to_payload(self._task_ledger)
-        manager_state: dict[str, Any] | None = None
-        with contextlib.suppress(Exception):
-            manager_state = self._manager.snapshot_state()
-        if manager_state:
-            state["manager_state"] = manager_state
+
+        try:
+            state["manager_state"] = self._manager.on_checkpoint_save()
+        except Exception as exc:
+            logger.warning("Failed to save manager state for checkpoint: %s\nSkipping...", exc)
+
         return state
 
-    def restore_state(self, state: dict[str, Any]) -> None:
+    @override
+    async def on_checkpoint_restore(self, state: dict[str, Any]) -> None:
         """Restore orchestrator state from checkpoint.
 
         Maintains backward compatibility with existing Magentic checkpoints
@@ -1112,7 +1120,7 @@ class MagenticOrchestratorExecutor(BaseGroupChatOrchestrator):
         manager_state = state.get("manager_state")
         if manager_state is not None:
             try:
-                self._manager.restore_state(manager_state)
+                self._manager.on_checkpoint_restore(manager_state)
             except Exception as exc:  # pragma: no cover
                 logger.warning("Failed to restore manager state: %s", exc)
 
@@ -1142,49 +1150,6 @@ class MagenticOrchestratorExecutor(BaseGroupChatOrchestrator):
         for name, description in expected.items():
             restored[name] = description
 
-    def _snapshot_pattern_metadata(self) -> dict[str, Any]:
-        """Serialize pattern-specific state.
-
-        Magentic uses custom snapshot_state() instead of base class hooks.
-        This method exists to satisfy the base class contract.
-
-        Returns:
-            Empty dict (Magentic manages its own state)
-        """
-        return {}
-
-    def _restore_pattern_metadata(self, metadata: dict[str, Any]) -> None:
-        """Restore pattern-specific state.
-
-        Magentic uses custom restore_state() instead of base class hooks.
-        This method exists to satisfy the base class contract.
-
-        Args:
-            metadata: Pattern-specific state dict (ignored)
-        """
-        pass
-
-    async def _ensure_state_restored(
-        self,
-        context: WorkflowContext[Any, Any],
-    ) -> None:
-        if self._state_restored and self._context is not None:
-            return
-        state = await context.get_executor_state()
-        if not state:
-            self._state_restored = True
-            return
-        if not isinstance(state, dict):
-            self._state_restored = True
-            return
-        try:
-            self.restore_state(state)
-        except Exception as exc:  # pragma: no cover
-            logger.warning("Magentic Orchestrator: Failed to apply checkpoint state: %s", exc, exc_info=True)
-            raise
-        else:
-            self._state_restored = True
-
     @handler
     async def handle_start_message(
         self,
@@ -1204,7 +1169,7 @@ class MagenticOrchestratorExecutor(BaseGroupChatOrchestrator):
         )
         if message.messages:
             self._context.chat_history.extend(message.messages)
-        self._state_restored = True
+
         # Non-streaming callback for the orchestrator receipt of the task
         await self._emit_orchestrator_message(context, message.task, ORCH_MSG_KIND_USER_TASK)
 
@@ -1269,7 +1234,7 @@ class MagenticOrchestratorExecutor(BaseGroupChatOrchestrator):
         """Handle responses from agents."""
         if getattr(self, "_terminated", False):
             return
-        await self._ensure_state_restored(context)
+
         if self._context is None:
             raise RuntimeError("Magentic Orchestrator: Received response but not initialized")
 
@@ -1301,7 +1266,7 @@ class MagenticOrchestratorExecutor(BaseGroupChatOrchestrator):
     ) -> None:
         if getattr(self, "_terminated", False):
             return
-        await self._ensure_state_restored(context)
+
         if self._context is None:
             return
 
@@ -1636,9 +1601,9 @@ class MagenticAgentExecutor(Executor):
         self._agent = agent
         self._agent_id = agent_id
         self._chat_history: list[ChatMessage] = []
-        self._state_restored = False
 
-    def snapshot_state(self) -> dict[str, Any]:
+    @override
+    async def on_checkpoint_save(self) -> dict[str, Any]:
         """Capture current executor state for checkpointing.
 
         Returns:
@@ -1650,7 +1615,8 @@ class MagenticAgentExecutor(Executor):
             "chat_history": encode_chat_messages(self._chat_history),
         }
 
-    def restore_state(self, state: dict[str, Any]) -> None:
+    @override
+    async def on_checkpoint_restore(self, state: dict[str, Any]) -> None:
         """Restore executor state from checkpoint.
 
         Args:
@@ -1668,24 +1634,6 @@ class MagenticAgentExecutor(Executor):
         else:
             self._chat_history = []
 
-    async def _ensure_state_restored(self, context: WorkflowContext[Any, Any]) -> None:
-        if self._state_restored and self._chat_history:
-            return
-        state = await context.get_executor_state()
-        if not state:
-            self._state_restored = True
-            return
-        if not isinstance(state, dict):
-            self._state_restored = True
-            return
-        try:
-            self.restore_state(state)
-        except Exception as exc:  # pragma: no cover
-            logger.warning("Agent %s: Failed to apply checkpoint state: %s", self._agent_id, exc, exc_info=True)
-            raise
-        else:
-            self._state_restored = True
-
     @handler
     async def handle_response_message(
         self, message: _MagenticResponseMessage, context: WorkflowContext[_MagenticResponseMessage]
@@ -1693,8 +1641,6 @@ class MagenticAgentExecutor(Executor):
         """Handle response message (task ledger broadcast)."""
         logger.debug("Agent %s: Received response message", self._agent_id)
 
-        await self._ensure_state_restored(context)
-
         # Check if this message is intended for this agent
         if message.target_agent is not None and message.target_agent != self._agent_id and not message.broadcast:
             # Message is targeted to a different agent, ignore it
@@ -1735,8 +1681,6 @@ class MagenticAgentExecutor(Executor):
 
         logger.info("Agent %s: Received request to respond", self._agent_id)
 
-        await self._ensure_state_restored(context)
-
         # Add persona adoption message with appropriate role
         persona_role = self._get_persona_adoption_role()
         persona_msg = ChatMessage(
@@ -1783,7 +1727,6 @@ class MagenticAgentExecutor(Executor):
         """Reset the internal chat history of the agent (internal operation)."""
         logger.debug("Agent %s: Resetting chat history", self._agent_id)
         self._chat_history.clear()
-        self._state_restored = True
 
     async def _emit_agent_delta_event(
         self,

python/packages/core/agent_framework/_workflows/_runner.py

@@ -11,7 +11,7 @@ from ._checkpoint_encoding import DATACLASS_MARKER, MODEL_MARKER, decode_checkpo
 from ._const import EXECUTOR_STATE_KEY
 from ._edge import EdgeGroup
 from ._edge_runner import EdgeRunner, create_edge_runner
-from ._events import WorkflowEvent
+from ._events import SuperStepCompletedEvent, SuperStepStartedEvent, WorkflowEvent
 from ._executor import Executor
 from ._runner_context import (
     Message,
@@ -92,6 +92,7 @@ class Runner:
 
             while self._iteration < self._max_iterations:
                 logger.info(f"Starting superstep {self._iteration + 1}")
+                yield SuperStepStartedEvent(iteration=self._iteration + 1)
 
                 # Run iteration concurrently with live event streaming: we poll
                 # for new events while the iteration coroutine progresses.
@@ -126,6 +127,9 @@ class Runner:
                 # Create checkpoint after each superstep iteration
                 await self._create_checkpoint_if_enabled(f"superstep_{self._iteration}")
 
+                yield SuperStepCompletedEvent(iteration=self._iteration)
+
+                # Check for convergence: no more messages to process
                 if not await self._ctx.has_messages():
                     break
 
@@ -183,8 +187,8 @@ class Runner:
             return None
 
         try:
-            # Auto-snapshot executor states
-            await self._auto_snapshot_executor_states()
+            # Snapshot executor states
+            await self._save_executor_states()
             checkpoint_category = "initial" if checkpoint_type == "after_initial_execution" else "superstep"
             metadata = {
                 "superstep": self._iteration,
@@ -203,41 +207,6 @@ class Runner:
             logger.warning(f"Failed to create {checkpoint_type} checkpoint: {e}")
             return None
 
-    async def _auto_snapshot_executor_states(self) -> None:
-        """Populate executor state by calling snapshot hooks on executors if available.
-
-        TODO(@taochen#1614): this method is potentially problematic if executors also call
-        set_executor_state on the context directly. We should clarify the intended usage
-        pattern for executor state management.
-
-        Convention:
-          - If an executor defines an async or sync method `snapshot_state(self) -> dict`, use it.
-          - Else if it has a plain attribute `state` that is a dict, use that.
-        Only JSON-serializable dicts should be provided by executors.
-        """
-        for exec_id, executor in self._executors.items():
-            state_dict: dict[str, Any] | None = None
-            snapshot = getattr(executor, "snapshot_state", None)
-            try:
-                if callable(snapshot):
-                    maybe = snapshot()
-                    if asyncio.iscoroutine(maybe):  # type: ignore[arg-type]
-                        maybe = await maybe  # type: ignore[assignment]
-                    if isinstance(maybe, dict):
-                        state_dict = maybe  # type: ignore[assignment]
-                else:
-                    state_attr = getattr(executor, "state", None)
-                    if isinstance(state_attr, dict):
-                        state_dict = state_attr  # type: ignore[assignment]
-            except Exception as ex:  # pragma: no cover
-                logger.debug(f"Executor {exec_id} snapshot_state failed: {ex}")
-
-            if state_dict is not None:
-                try:
-                    await self._set_executor_state(exec_id, state_dict)
-                except Exception as ex:  # pragma: no cover
-                    logger.debug(f"Failed to persist state for executor {exec_id}: {ex}")
-
     async def restore_from_checkpoint(
         self,
         checkpoint_id: str,
@@ -300,7 +269,65 @@ class Runner:
             logger.error(f"Failed to restore from checkpoint {checkpoint_id}: {e}")
             return False
 
+    async def _save_executor_states(self) -> None:
+        """Populate executor state by calling checkpoint hooks on executors.
+
+        Backward compatibility behavior:
+          - If an executor defines an async or sync method `snapshot_state(self) -> dict`, use it.
+          - Else if it has a plain attribute `state` that is a dict, use that.
+
+        Updated behavior:
+          - Executors should implement `on_checkpoint_save(self) -> dict` to provide state.
+
+        This method will try the backward compatibility behavior first; if that does not yield state,
+        it falls back to the updated behavior.
+
+        Only JSON-serializable dicts should be provided by executors.
+        """
+        for exec_id, executor in self._executors.items():
+            state_dict: dict[str, Any] | None = None
+            # Try backward compatibility behavior first
+            # TODO(@taochen): Remove backward compatibility
+            snapshot = getattr(executor, "snapshot_state", None)
+            try:
+                if callable(snapshot):
+                    maybe = snapshot()
+                    if asyncio.iscoroutine(maybe):  # type: ignore[arg-type]
+                        maybe = await maybe  # type: ignore[assignment]
+                    if isinstance(maybe, dict):
+                        state_dict = maybe  # type: ignore[assignment]
+                else:
+                    state_attr = getattr(executor, "state", None)
+                    if isinstance(state_attr, dict):
+                        state_dict = state_attr  # type: ignore[assignment]
+            except Exception as ex:  # pragma: no cover
+                logger.debug(f"Executor {exec_id} snapshot_state failed: {ex}")
+
+            if state_dict is None:
+                # Try the updated behavior only if backward compatibility did not yield state
+                try:
+                    state_dict = await executor.on_checkpoint_save()
+                except Exception as ex:  # pragma: no cover
+                    raise ValueError(f"Executor {exec_id} on_checkpoint_save failed: {ex}") from ex
+
+            try:
+                await self._set_executor_state(exec_id, state_dict)
+            except Exception as ex:  # pragma: no cover
+                logger.debug(f"Failed to persist state for executor {exec_id}: {ex}")
+
     async def _restore_executor_states(self) -> None:
+        """Restore executor state by calling restore hooks on executors.
+
+        Backward compatibility behavior:
+            - If an executor defines an async or sync method `restore_state(self, state: dict)`, use it.
+            - Else, skip restoration for that executor.
+
+        Updated behavior:
+            - Executors should implement `on_checkpoint_restore(self, state: dict)` to restore state.
+
+        This method will try the backward compatibility behavior first; if that does not restore state,
+        it falls back to the updated behavior.
+        """
         has_executor_states = await self._shared_state.has(EXECUTOR_STATE_KEY)
         if not has_executor_states:
             return
@@ -309,16 +336,18 @@ class Runner:
         if not isinstance(executor_states, dict):
             raise ValueError("Executor states in shared state is not a dictionary. Unable to restore.")
 
-        for executor_id, state in executor_states.items():
+        for executor_id, state in executor_states.items():  # pyright: ignore[reportUnknownVariableType]
             if not isinstance(executor_id, str):
                 raise ValueError("Executor ID in executor states is not a string. Unable to restore.")
-            if not isinstance(state, dict):
-                raise ValueError(f"Executor state for {executor_id} is not a dictionary. Unable to restore.")
+            if not isinstance(state, dict) or not all(isinstance(k, str) for k in state):  # pyright: ignore[reportUnknownVariableType]
+                raise ValueError(f"Executor state for {executor_id} is not a dict[str, Any]. Unable to restore.")
 
             executor = self._executors.get(executor_id)
             if not executor:
                 raise ValueError(f"Executor {executor_id} not found during state restoration.")
 
+            # Try backward compatibility behavior first
+            # TODO(@taochen): Remove backward compatibility
             restored = False
             restore_method = getattr(executor, "restore_state", None)
             try:
@@ -330,6 +359,14 @@ class Runner:
             except Exception as ex:  # pragma: no cover - defensive
                 raise ValueError(f"Executor {executor_id} restore_state failed: {ex}") from ex
 
+            if not restored:
+                # Try the updated behavior only if backward compatibility did not restore
+                try:
+                    await executor.on_checkpoint_restore(state)  # pyright: ignore[reportUnknownArgumentType]
+                    restored = True
+                except Exception as ex:  # pragma: no cover - defensive
+                    raise ValueError(f"Executor {executor_id} on_checkpoint_restore failed: {ex}") from ex
+
             if not restored:
                 logger.debug(f"Executor {executor_id} does not support state restoration; skipping.")
 

python/packages/core/agent_framework/_workflows/_workflow.py

@@ -109,9 +109,9 @@ class Workflow(DictConvertible):
     """A graph-based execution engine that orchestrates connected executors.
 
     ## Overview
-    A workflow executes a directed graph of executors connected via edge groups using a Pregel-like model,
-    running in supersteps until the graph becomes idle. Workflows are created using the
-    WorkflowBuilder class - do not instantiate this class directly.
+    A workflow executes a directed graph of executors connected via edge groups using a
+    Pregel-like model, running in supersteps until the graph becomes idle. Workflows
+    are created using the WorkflowBuilder class - do not instantiate this class directly.
 
     ## Execution Model
     Executors run in synchronized supersteps where each executor:
@@ -142,6 +142,10 @@ class Workflow(DictConvertible):
     - HIL continuation: Provide `responses` to continue after RequestInfoExecutor requests
     - Runtime checkpointing: Provide `checkpoint_storage` to enable/override checkpointing for this run
 
+    ## State Management
+    Workflow instances contain states and states are preserved across calls to `run` and `run_stream`.
+    To execute multiple independent runs, create separate Workflow instances via WorkflowBuilder.
+
     ## External Input Requests
     Executors within a workflow can request external input using `ctx.request_info()`:
     1. Executor calls `ctx.request_info()` to request input

python/packages/core/agent_framework/_workflows/_workflow_builder.py

@@ -39,7 +39,40 @@ logger = logging.getLogger(__name__)
 class WorkflowBuilder:
     """A builder class for constructing workflows.
 
-    This class provides methods to add edges and set the starting executor for the workflow.
+    This class provides a fluent API for defining workflow graphs by connecting executors
+    with edges and configuring execution parameters. Call :meth:`build` to create an
+    immutable :class:`Workflow` instance.
+
+    Example:
+        .. code-block:: python
+
+            from typing_extensions import Never
+            from agent_framework import Executor, WorkflowBuilder, WorkflowContext, handler
+
+
+            class UpperCaseExecutor(Executor):
+                @handler
+                async def process(self, text: str, ctx: WorkflowContext[str]) -> None:
+                    await ctx.send_message(text.upper())
+
+
+            class ReverseExecutor(Executor):
+                @handler
+                async def process(self, text: str, ctx: WorkflowContext[Never, str]) -> None:
+                    await ctx.yield_output(text[::-1])
+
+
+            # Build a workflow
+            workflow = (
+                WorkflowBuilder()
+                .add_edge(UpperCaseExecutor(id="upper"), ReverseExecutor(id="reverse"))
+                .set_start_executor("upper")
+                .build()
+            )
+
+            # Run the workflow
+            events = await workflow.run("hello")
+            print(events.get_outputs())  # ['OLLEH']
     """
 
     def __init__(
@@ -51,7 +84,7 @@ class WorkflowBuilder:
         """Initialize the WorkflowBuilder with an empty list of edges and no starting executor.
 
         Args:
-            max_iterations: Maximum number of iterations for workflow convergence.
+            max_iterations: Maximum number of iterations for workflow convergence. Default is 100.
             name: Optional human-readable name for the workflow.
             description: Optional description of what the workflow does.
         """
@@ -164,10 +197,22 @@ class WorkflowBuilder:
             id: A unique identifier for the executor. If None, the agent's name will be used if available.
 
         Returns:
-            The WorkflowBuilder instance (for method chaining).
+            Self: The WorkflowBuilder instance for method chaining.
 
         Raises:
             ValueError: If the provided id or agent name conflicts with an existing executor.
+
+        Example:
+            .. code-block:: python
+
+                from agent_framework import WorkflowBuilder
+                from agent_framework_anthropic import AnthropicAgent
+
+                # Create an agent
+                agent = AnthropicAgent(name="writer", model="claude-3-5-sonnet-20241022")
+
+                # Add the agent to a workflow
+                workflow = WorkflowBuilder().add_agent(agent, output_response=True).set_start_executor(agent).build()
         """
         executor = self._maybe_wrap_agent(
             agent, agent_thread=agent_thread, output_response=output_response, executor_id=id
@@ -184,12 +229,53 @@ class WorkflowBuilder:
         """Add a directed edge between two executors.
 
         The output types of the source and the input types of the target must be compatible.
+        Messages sent by the source executor will be routed to the target executor.
 
         Args:
             source: The source executor of the edge.
             target: The target executor of the edge.
             condition: An optional condition function that determines whether the edge
                        should be traversed based on the message type.
+
+        Returns:
+            Self: The WorkflowBuilder instance for method chaining.
+
+        Example:
+            .. code-block:: python
+
+                from typing_extensions import Never
+                from agent_framework import Executor, WorkflowBuilder, WorkflowContext, handler
+
+
+                class ProcessorA(Executor):
+                    @handler
+                    async def process(self, data: str, ctx: WorkflowContext[int]) -> None:
+                        await ctx.send_message(len(data))
+
+
+                class ProcessorB(Executor):
+                    @handler
+                    async def process(self, count: int, ctx: WorkflowContext[Never, str]) -> None:
+                        await ctx.yield_output(f"Processed {count} characters")
+
+
+                # Connect executors with an edge
+                workflow = (
+                    WorkflowBuilder().add_edge(ProcessorA(id="a"), ProcessorB(id="b")).set_start_executor("a").build()
+                )
+
+
+                # With a condition
+                def only_large_numbers(msg: int) -> bool:
+                    return msg > 100
+
+
+                workflow = (
+                    WorkflowBuilder()
+                    .add_edge(ProcessorA(id="a"), ProcessorB(id="b"), condition=only_large_numbers)
+                    .set_start_executor("a")
+                    .build()
+                )
         """
         # TODO(@taochen): Support executor factories for lazy initialization
         source_exec = self._maybe_wrap_agent(source)
@@ -204,13 +290,50 @@ class WorkflowBuilder:
         source: Executor | AgentProtocol,
         targets: Sequence[Executor | AgentProtocol],
     ) -> Self:
-        """Add multiple edges to the workflow where messages from the source will be sent to all target.
+        """Add multiple edges to the workflow where messages from the source will be sent to all targets.
 
         The output types of the source and the input types of the targets must be compatible.
+        Messages from the source will be broadcast to all target executors concurrently.
 
         Args:
             source: The source executor of the edges.
             targets: A list of target executors for the edges.
+
+        Returns:
+            Self: The WorkflowBuilder instance for method chaining.
+
+        Example:
+            .. code-block:: python
+
+                from agent_framework import Executor, WorkflowBuilder, WorkflowContext, handler
+
+
+                class DataSource(Executor):
+                    @handler
+                    async def generate(self, count: int, ctx: WorkflowContext[str]) -> None:
+                        for i in range(count):
+                            await ctx.send_message(f"data_{i}")
+
+
+                class ValidatorA(Executor):
+                    @handler
+                    async def validate(self, data: str, ctx: WorkflowContext) -> None:
+                        print(f"ValidatorA: {data}")
+
+
+                class ValidatorB(Executor):
+                    @handler
+                    async def validate(self, data: str, ctx: WorkflowContext) -> None:
+                        print(f"ValidatorB: {data}")
+
+
+                # Broadcast to multiple validators
+                workflow = (
+                    WorkflowBuilder()
+                    .add_fan_out_edges(DataSource(id="source"), [ValidatorA(id="val_a"), ValidatorB(id="val_b")])
+                    .set_start_executor("source")
+                    .build()
+                )
         """
         source_exec = self._maybe_wrap_agent(source)
         target_execs = [self._maybe_wrap_agent(t) for t in targets]
@@ -241,6 +364,53 @@ class WorkflowBuilder:
         Args:
             source: The source executor of the edges.
             cases: A list of case objects that determine the target executor for each message.
+
+        Returns:
+            Self: The WorkflowBuilder instance for method chaining.
+
+        Example:
+            .. code-block:: python
+
+                from agent_framework import Executor, WorkflowBuilder, WorkflowContext, handler, Case, Default
+                from dataclasses import dataclass
+
+
+                @dataclass
+                class Result:
+                    score: int
+
+
+                class Evaluator(Executor):
+                    @handler
+                    async def evaluate(self, text: str, ctx: WorkflowContext[Result]) -> None:
+                        await ctx.send_message(Result(score=len(text)))
+
+
+                class HighScoreHandler(Executor):
+                    @handler
+                    async def handle(self, result: Result, ctx: WorkflowContext) -> None:
+                        print(f"High score: {result.score}")
+
+
+                class LowScoreHandler(Executor):
+                    @handler
+                    async def handle(self, result: Result, ctx: WorkflowContext) -> None:
+                        print(f"Low score: {result.score}")
+
+
+                # Route based on score value
+                workflow = (
+                    WorkflowBuilder()
+                    .add_switch_case_edge_group(
+                        Evaluator(id="eval"),
+                        [
+                            Case(condition=lambda r: r.score > 10, target=HighScoreHandler(id="high")),
+                            Default(target=LowScoreHandler(id="low")),
+                        ],
+                    )
+                    .set_start_executor("eval")
+                    .build()
+                )
         """
         source_exec = self._maybe_wrap_agent(source)
         source_id = self._add_executor(source_exec)
@@ -270,13 +440,67 @@ class WorkflowBuilder:
         Messages from the source executor will be sent to multiple target executors based on
         the provided selection function.
 
-        The selection function should take a message and the name of the target executors,
-        and return a list of indices indicating which target executors should receive the message.
+        The selection function should take a message and a list of target executor IDs,
+        and return a list of executor IDs indicating which target executors should receive the message.
 
         Args:
             source: The source executor of the edges.
             targets: A list of target executors for the edges.
             selection_func: A function that selects target executors for messages.
+                Takes (message, list[executor_id]) and returns list[executor_id].
+
+        Returns:
+            Self: The WorkflowBuilder instance for method chaining.
+
+        Example:
+            .. code-block:: python
+
+                from agent_framework import Executor, WorkflowBuilder, WorkflowContext, handler
+                from dataclasses import dataclass
+
+
+                @dataclass
+                class Task:
+                    priority: str
+                    data: str
+
+
+                class TaskDispatcher(Executor):
+                    @handler
+                    async def dispatch(self, text: str, ctx: WorkflowContext[Task]) -> None:
+                        priority = "high" if len(text) > 10 else "low"
+                        await ctx.send_message(Task(priority=priority, data=text))
+
+
+                class WorkerA(Executor):
+                    @handler
+                    async def process(self, task: Task, ctx: WorkflowContext) -> None:
+                        print(f"WorkerA processing: {task.data}")
+
+
+                class WorkerB(Executor):
+                    @handler
+                    async def process(self, task: Task, ctx: WorkflowContext) -> None:
+                        print(f"WorkerB processing: {task.data}")
+
+
+                # Select workers based on task priority
+                def select_workers(task: Task, executor_ids: list[str]) -> list[str]:
+                    if task.priority == "high":
+                        return executor_ids  # Send to all workers
+                    return [executor_ids[0]]  # Send to first worker only
+
+
+                workflow = (
+                    WorkflowBuilder()
+                    .add_multi_selection_edge_group(
+                        TaskDispatcher(id="dispatcher"),
+                        [WorkerA(id="worker_a"), WorkerB(id="worker_b")],
+                        selection_func=select_workers,
+                    )
+                    .set_start_executor("dispatcher")
+                    .build()
+                )
         """
         source_exec = self._maybe_wrap_agent(source)
         target_execs = [self._maybe_wrap_agent(t) for t in targets]
@@ -298,31 +522,42 @@ class WorkflowBuilder:
 
         The target executor will receive a list of messages aggregated from all source executors.
         Thus the input types of the target executor must be compatible with a list of the output
-        types of the source executors. For example:
-
-            class Target(Executor):
-                @handler
-                def handle_messages(self, messages: list[Message]) -> None:
-                    # Process the aggregated messages from all sources
-
-            class Source(Executor):
-                @handler(output_type=[Message])
-                def handle_message(self, message: Message) -> None:
-                    # Send a message to the target executor
-                    self.send_message(message)
-
-            workflow = (
-                WorkflowBuilder()
-                .add_fan_in_edges(
-                    [Source(id="source1"), Source(id="source2")],
-                    Target(id="target")
-                )
-                .build()
-            )
+        types of the source executors.
 
         Args:
             sources: A list of source executors for the edges.
             target: The target executor for the edges.
+
+        Returns:
+            Self: The WorkflowBuilder instance for method chaining.
+
+        Example:
+            .. code-block:: python
+
+                from typing_extensions import Never
+                from agent_framework import Executor, WorkflowBuilder, WorkflowContext, handler
+
+
+                class Producer(Executor):
+                    @handler
+                    async def produce(self, seed: int, ctx: WorkflowContext[str]) -> None:
+                        await ctx.send_message(f"result_{seed}")
+
+
+                class Aggregator(Executor):
+                    @handler
+                    async def aggregate(self, results: list[str], ctx: WorkflowContext[Never, str]) -> None:
+                        combined = ", ".join(results)
+                        await ctx.yield_output(f"Combined: {combined}")
+
+
+                # Collect results from multiple producers
+                workflow = (
+                    WorkflowBuilder()
+                    .add_fan_in_edges([Producer(id="prod_1"), Producer(id="prod_2")], Aggregator(id="agg"))
+                    .set_start_executor("prod_1")
+                    .build()
+                )
         """
         source_execs = [self._maybe_wrap_agent(s) for s in sources]
         target_exec = self._maybe_wrap_agent(target)
@@ -342,6 +577,42 @@ class WorkflowBuilder:
 
         Args:
             executors: A list of executors to be added to the chain.
+
+        Returns:
+            Self: The WorkflowBuilder instance for method chaining.
+
+        Example:
+            .. code-block:: python
+
+                from typing_extensions import Never
+                from agent_framework import Executor, WorkflowBuilder, WorkflowContext, handler
+
+
+                class Step1(Executor):
+                    @handler
+                    async def process(self, text: str, ctx: WorkflowContext[str]) -> None:
+                        await ctx.send_message(text.upper())
+
+
+                class Step2(Executor):
+                    @handler
+                    async def process(self, text: str, ctx: WorkflowContext[str]) -> None:
+                        await ctx.send_message(text[::-1])
+
+
+                class Step3(Executor):
+                    @handler
+                    async def process(self, text: str, ctx: WorkflowContext[Never, str]) -> None:
+                        await ctx.yield_output(f"Final: {text}")
+
+
+                # Chain executors in sequence
+                workflow = (
+                    WorkflowBuilder()
+                    .add_chain([Step1(id="step1"), Step2(id="step2"), Step3(id="step3")])
+                    .set_start_executor("step1")
+                    .build()
+                )
         """
         # Wrap each candidate first to ensure stable IDs before adding edges
         wrapped: list[Executor] = [self._maybe_wrap_agent(e) for e in executors]
@@ -352,8 +623,46 @@ class WorkflowBuilder:
     def set_start_executor(self, executor: Executor | AgentProtocol | str) -> Self:
         """Set the starting executor for the workflow.
 
+        The start executor is the entry point for the workflow. When the workflow is executed,
+        the initial message will be sent to this executor.
+
         Args:
-            executor: The starting executor, which can be an Executor instance or its ID.
+            executor: The starting executor, which can be an Executor instance, AgentProtocol instance,
+                or the string ID of an executor previously added to the workflow.
+
+        Returns:
+            Self: The WorkflowBuilder instance for method chaining.
+
+        Example:
+            .. code-block:: python
+
+                from typing_extensions import Never
+                from agent_framework import Executor, WorkflowBuilder, WorkflowContext, handler
+
+
+                class EntryPoint(Executor):
+                    @handler
+                    async def process(self, text: str, ctx: WorkflowContext[str]) -> None:
+                        await ctx.send_message(text.upper())
+
+
+                class Processor(Executor):
+                    @handler
+                    async def process(self, text: str, ctx: WorkflowContext[Never, str]) -> None:
+                        await ctx.yield_output(text)
+
+
+                # Set by executor instance
+                entry = EntryPoint(id="entry")
+                workflow = WorkflowBuilder().add_edge(entry, Processor(id="proc")).set_start_executor(entry).build()
+
+                # Set by executor ID string
+                workflow = (
+                    WorkflowBuilder()
+                    .add_edge(EntryPoint(id="entry"), Processor(id="proc"))
+                    .set_start_executor("entry")
+                    .build()
+                )
         """
         if isinstance(executor, str):
             self._start_executor = executor
@@ -370,8 +679,43 @@ class WorkflowBuilder:
     def set_max_iterations(self, max_iterations: int) -> Self:
         """Set the maximum number of iterations for the workflow.
 
+        When a workflow contains cycles, this limit prevents infinite loops by capping
+        the total number of executor invocations. The default is 100 iterations.
+
         Args:
             max_iterations: The maximum number of iterations the workflow will run for convergence.
+
+        Returns:
+            Self: The WorkflowBuilder instance for method chaining.
+
+        Example:
+            .. code-block:: python
+
+                from agent_framework import Executor, WorkflowBuilder, WorkflowContext, handler
+
+
+                class StepA(Executor):
+                    @handler
+                    async def process(self, count: int, ctx: WorkflowContext[int]) -> None:
+                        if count < 10:
+                            await ctx.send_message(count + 1)
+
+
+                class StepB(Executor):
+                    @handler
+                    async def process(self, count: int, ctx: WorkflowContext[int]) -> None:
+                        await ctx.send_message(count)
+
+
+                # Set a custom iteration limit for workflow with cycles
+                workflow = (
+                    WorkflowBuilder()
+                    .set_max_iterations(500)
+                    .add_edge(StepA(id="step_a"), StepB(id="step_b"))
+                    .add_edge(StepB(id="step_b"), StepA(id="step_a"))  # Cycle
+                    .set_start_executor("step_a")
+                    .build()
+                )
         """
         self._max_iterations = max_iterations
         return self
@@ -381,8 +725,48 @@ class WorkflowBuilder:
     def with_checkpointing(self, checkpoint_storage: CheckpointStorage) -> Self:
         """Enable checkpointing with the specified storage.
 
+        Checkpointing allows workflows to save their state periodically, enabling
+        pause/resume functionality and recovery from failures. The checkpoint storage
+        implementation determines where checkpoints are persisted.
+
         Args:
-            checkpoint_storage: The checkpoint storage to use.
+            checkpoint_storage: The checkpoint storage implementation to use.
+
+        Returns:
+            Self: The WorkflowBuilder instance for method chaining.
+
+        Example:
+            .. code-block:: python
+
+                from typing_extensions import Never
+                from agent_framework import Executor, WorkflowBuilder, WorkflowContext, handler
+                from agent_framework import FileCheckpointStorage
+
+
+                class ProcessorA(Executor):
+                    @handler
+                    async def process(self, text: str, ctx: WorkflowContext[str]) -> None:
+                        await ctx.send_message(text.upper())
+
+
+                class ProcessorB(Executor):
+                    @handler
+                    async def process(self, text: str, ctx: WorkflowContext[Never, str]) -> None:
+                        await ctx.yield_output(text)
+
+
+                # Enable checkpointing with file-based storage
+                storage = FileCheckpointStorage("./checkpoints")
+                workflow = (
+                    WorkflowBuilder()
+                    .add_edge(ProcessorA(id="proc_a"), ProcessorB(id="proc_b"))
+                    .set_start_executor("proc_a")
+                    .with_checkpointing(storage)
+                    .build()
+                )
+
+                # Run with checkpoint saving
+                events = await workflow.run("input")
         """
         self._checkpoint_storage = checkpoint_storage
         return self
@@ -390,15 +774,43 @@ class WorkflowBuilder:
     def build(self) -> Workflow:
         """Build and return the constructed workflow.
 
-        This method performs validation before building the workflow.
+        This method performs validation before building the workflow to ensure:
+        - A starting executor has been set
+        - All edges connect valid executors
+        - The graph is properly connected
+        - Type compatibility between connected executors
 
         Returns:
-            A Workflow instance with the defined edges and starting executor.
+            Workflow: An immutable Workflow instance ready for execution.
 
         Raises:
             ValueError: If starting executor is not set.
             WorkflowValidationError: If workflow validation fails (includes EdgeDuplicationError,
                 TypeCompatibilityError, and GraphConnectivityError subclasses).
+
+        Example:
+            .. code-block:: python
+
+                from typing_extensions import Never
+                from agent_framework import Executor, WorkflowBuilder, WorkflowContext, handler
+
+
+                class MyExecutor(Executor):
+                    @handler
+                    async def process(self, text: str, ctx: WorkflowContext[Never, str]) -> None:
+                        await ctx.yield_output(text.upper())
+
+
+                # Build and execute a workflow
+                workflow = WorkflowBuilder().set_start_executor(MyExecutor(id="executor")).build()
+
+                # The workflow is now immutable and ready to run
+                events = await workflow.run("hello")
+                print(events.get_outputs())  # ['HELLO']
+
+                # Workflows can be reused multiple times
+                events2 = await workflow.run("world")
+                print(events2.get_outputs())  # ['WORLD']
         """
         # Create workflow build span that includes validation and workflow creation
         with create_workflow_span(OtelAttr.WORKFLOW_BUILD_SPAN) as span:

python/packages/core/agent_framework/_workflows/_workflow_context.py

@@ -8,7 +8,7 @@ from typing import TYPE_CHECKING, Any, Generic, Union, cast, get_args, get_origi
 
 from opentelemetry.propagate import inject
 from opentelemetry.trace import SpanKind
-from typing_extensions import Never, TypeVar
+from typing_extensions import Never, TypeVar, deprecated
 
 from ..observability import OtelAttr, create_workflow_span
 from ._const import EXECUTOR_STATE_KEY
@@ -410,6 +410,11 @@ class WorkflowContext(Generic[T_Out, T_W_Out]):
         """Get the shared state."""
         return self._shared_state
 
+    @deprecated(
+        "Override `on_checkpoint_save()` methods instead. "
+        "For cross-executor state sharing, use set_shared_state() instead. "
+        "This API will be removed after 12/01/2025."
+    )
     async def set_executor_state(self, state: dict[str, Any]) -> None:
         """Store executor state in shared state under a reserved key.
 
@@ -428,6 +433,11 @@ class WorkflowContext(Generic[T_Out, T_W_Out]):
         existing_states[self._executor_id] = state
         await self._shared_state.set(EXECUTOR_STATE_KEY, existing_states)
 
+    @deprecated(
+        "Override `on_checkpoint_restore()` methods instead. "
+        "For cross-executor state sharing, use get_shared_state() instead. "
+        "This API will be removed after 12/01/2025."
+    )
     async def get_executor_state(self) -> dict[str, Any] | None:
         """Retrieve previously persisted state for this executor, if any."""
         has_existing_states = await self._shared_state.has(EXECUTOR_STATE_KEY)

python/packages/core/agent_framework/_workflows/_workflow_executor.py

@@ -1,8 +1,8 @@
 # Copyright (c) Microsoft. All rights reserved.
 
 import asyncio
-import contextlib
 import logging
+import sys
 import uuid
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
@@ -26,6 +26,12 @@ from ._typing_utils import is_instance_of
 from ._workflow import WorkflowRunResult
 from ._workflow_context import WorkflowContext
 
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
+
 logger = logging.getLogger(__name__)
 
 
@@ -181,8 +187,7 @@ class WorkflowExecutor(Executor):
 
         # Includes all sub-workflow output types
         # Plus SubWorkflowRequestMessage if sub-workflow can make requests
-    output_types = workflow.output_types + [SubWorkflowRequestMessage]  # if applicable
-    ```
+        output_types = workflow.output_types + [SubWorkflowRequestMessage]  # if applicable
 
     ## Error Handling
     WorkflowExecutor propagates sub-workflow failures:
@@ -221,23 +226,10 @@ class WorkflowExecutor(Executor):
 
     ### Important Considerations
     **Shared Workflow Instance**: All concurrent executions use the same underlying workflow instance.
-    For proper isolation, ensure that:
-    - The wrapped workflow and its executors are stateless
-    - Executors use WorkflowContext state management instead of instance variables
-    - Any shared state is managed through WorkflowContext.get_shared_state/set_shared_state
+    For proper isolation, ensure that the wrapped workflow and its executors are stateless.
 
     .. code-block:: python
 
-        # Good: Stateless executor using context state
-        class StatelessExecutor(Executor):
-            @handler
-            async def process(self, data: str, ctx: WorkflowContext[str]) -> None:
-                # Use context state instead of instance variables
-                state = await ctx.get_executor_state() or {}
-                state["processed"] = data
-                await ctx.set_executor_state(state)
-
-
         # Avoid: Stateful executor with instance variables
         class StatefulExecutor(Executor):
             def __init__(self):
@@ -246,23 +238,23 @@ class WorkflowExecutor(Executor):
 
     ## Integration with Parent Workflows
     Parent workflows can intercept sub-workflow requests:
-    ```python
-    class ParentExecutor(Executor):
-        @handler
-        async def handle_subworkflow_request(
-            self,
-            request: SubWorkflowRequestMessage,
-            ctx: WorkflowContext[SubWorkflowResponseMessage],
-        ) -> None:
-            # Handle request locally or forward to external source
-            if self.can_handle_locally(request):
-                # Send response back to sub-workflow
-                response = request.create_response(data="local response data")
-                await ctx.send_message(response, target_id=request.source_executor_id)
-            else:
-                # Forward to external handler
-                await ctx.request_info(request.source_event, response_type=request.source_event.response_type)
-    ```
+
+    .. code-block:: python
+        class ParentExecutor(Executor):
+            @handler
+            async def handle_subworkflow_request(
+                self,
+                request: SubWorkflowRequestMessage,
+                ctx: WorkflowContext[SubWorkflowResponseMessage],
+            ) -> None:
+                # Handle request locally or forward to external source
+                if self.can_handle_locally(request):
+                    # Send response back to sub-workflow
+                    response = request.create_response(data="local response data")
+                    await ctx.send_message(response, target_id=request.source_executor_id)
+                else:
+                    # Forward to external handler
+                    await ctx.request_info(request.source_event, response_type=request.source_event.response_type)
 
     ## Implementation Notes
     - Sub-workflows run to completion before processing their results
@@ -296,7 +288,6 @@ class WorkflowExecutor(Executor):
         self._execution_contexts: dict[str, ExecutionContext] = {}  # execution_id -> ExecutionContext
         # Map request_id to execution_id for response routing
         self._request_to_execution: dict[str, str] = {}  # request_id -> execution_id
-        self._state_loaded: bool = False
 
     @property
     def input_types(self) -> list[type[Any]]:
@@ -362,8 +353,6 @@ class WorkflowExecutor(Executor):
             input_data: The input data to send to the sub-workflow.
             ctx: The workflow context from the parent.
         """
-        await self._ensure_state_loaded(ctx)
-
         # Create execution context for this sub-workflow run
         execution_id = str(uuid.uuid4())
         execution_context = ExecutionContext(
@@ -405,8 +394,6 @@ class WorkflowExecutor(Executor):
             response: The response to a previous request.
             ctx: The workflow context.
         """
-        await self._ensure_state_loaded(ctx)
-
         # Find the execution context for this request
         original_request = response.source_event
         execution_id = self._request_to_execution.get(original_request.request_id)
@@ -434,8 +421,6 @@ class WorkflowExecutor(Executor):
         # Accumulate the response in this execution's context
         execution_context.collected_responses[original_request.request_id] = response.data
 
-        await self._persist_execution_state(ctx)
-
         # Check if we have all expected responses for this execution
         if len(execution_context.collected_responses) < execution_context.expected_response_count:
             logger.debug(
@@ -459,25 +444,20 @@ class WorkflowExecutor(Executor):
             if not execution_context.pending_requests:
                 del self._execution_contexts[execution_id]
 
-    async def _ensure_state_loaded(self, ctx: WorkflowContext[Any]) -> None:
-        if self._state_loaded:
-            return
+    @override
+    async def on_checkpoint_save(self) -> dict[str, Any]:
+        """Get the current state of the WorkflowExecutor for checkpointing purposes."""
+        return {
+            "execution_contexts": {
+                execution_id: encode_checkpoint_value(execution_context)
+                for execution_id, execution_context in self._execution_contexts.items()
+            },
+            "request_to_execution": dict(self._request_to_execution),
+        }
 
-        state: dict[str, Any] | None = None
-        try:
-            state = await ctx.get_executor_state()
-        except Exception:
-            state = None
-
-        if isinstance(state, dict) and state:
-            with contextlib.suppress(Exception):
-                await self.restore_state(state)
-                self._state_loaded = True
-        else:
-            self._state_loaded = True
-
-    async def restore_state(self, state: dict[str, Any]) -> None:
-        """Restore pending request bookkeeping from a checkpoint snapshot."""
+    @override
+    async def on_checkpoint_restore(self, state: dict[str, Any]) -> None:
+        """Restore the WorkflowExecutor state from a checkpoint snapshot."""
         # Validate the state contains the right keys
         if "execution_contexts" not in state:
             raise KeyError("Missing 'execution_contexts' in WorkflowExecutor state.")
@@ -529,23 +509,6 @@ class WorkflowExecutor(Executor):
             for event in request_info_events
         ])
 
-        self._state_loaded = True
-
-    async def _persist_execution_state(self, ctx: WorkflowContext) -> None:
-        """Persist the state of the WorkflowExecutor for checkpointing purposes."""
-        state = {
-            "execution_contexts": {
-                execution_id: encode_checkpoint_value(execution_context)
-                for execution_id, execution_context in self._execution_contexts.items()
-            },
-            "request_to_execution": dict(self._request_to_execution),
-        }
-
-        try:
-            await ctx.set_executor_state(state)
-        except Exception as exc:  # pragma: no cover - transport specific
-            logger.warning(f"WorkflowExecutor {self.id} failed to persist state: {exc}")
-
     async def _process_workflow_result(
         self,
         result: WorkflowRunResult,
@@ -635,5 +598,3 @@ class WorkflowExecutor(Executor):
             )
         else:
             raise RuntimeError(f"Unexpected workflow run state: {workflow_run_state}")
-
-        await self._persist_execution_state(ctx)

python/packages/core/agent_framework/observability.py

@@ -1120,7 +1120,7 @@ def _trace_agent_run(
                     span=span,
                     provider_name=provider_name,
                     messages=messages,
-                    system_instructions=getattr(self, "instructions", None),
+                    system_instructions=getattr(getattr(self, "chat_options", None), "instructions", None),
                 )
             try:
                 response = await run_func(self, messages=messages, thread=thread, **kwargs)
@@ -1189,7 +1189,7 @@ def _trace_agent_run_stream(
                     span=span,
                     provider_name=provider_name,
                     messages=messages,
-                    system_instructions=getattr(self, "instructions", None),
+                    system_instructions=getattr(getattr(self, "chat_options", None), "instructions", None),
                 )
             try:
                 async for update in run_streaming_func(self, messages=messages, thread=thread, **kwargs):

python/packages/core/tests/workflow/test_agent_executor.py

@@ -158,8 +158,8 @@ async def test_agent_executor_checkpoint_stores_and_restores_state() -> None:
     assert thread_messages[1].text == "Initial response 1"
 
 
-async def test_agent_executor_snapshot_and_restore_state_directly() -> None:
-    """Test AgentExecutor's snapshot_state and restore_state methods directly."""
+async def test_agent_executor_save_and_restore_state_directly() -> None:
+    """Test AgentExecutor's on_checkpoint_save and on_checkpoint_restore methods directly."""
     # Create agent with thread containing messages
     agent = _CountingAgent(id="direct_test_agent", name="DirectTestAgent")
     thread = AgentThread(message_store=ChatMessageStore())
@@ -182,7 +182,7 @@ async def test_agent_executor_snapshot_and_restore_state_directly() -> None:
     executor._cache = list(cache_messages)  # type: ignore[reportPrivateUsage]
 
     # Snapshot the state
-    state = await executor.snapshot_state()  # type: ignore[reportUnknownMemberType]
+    state = await executor.on_checkpoint_save()
 
     # Verify snapshot contains both cache and thread
     assert "cache" in state
@@ -206,7 +206,7 @@ async def test_agent_executor_snapshot_and_restore_state_directly() -> None:
     assert len(initial_thread_msgs) == 0
 
     # Restore state
-    await new_executor.restore_state(state)  # type: ignore[reportUnknownMemberType]
+    await new_executor.on_checkpoint_restore(state)
 
     # Verify cache is restored
     restored_cache = new_executor._cache  # type: ignore[reportPrivateUsage]

python/packages/core/tests/workflow/test_function_executor_future.py

@@ -0,0 +1,39 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_framework import FunctionExecutor, WorkflowContext, executor
+
+
+class TestFunctionExecutorFutureAnnotations:
+    """Test suite for FunctionExecutor with from __future__ import annotations."""
+
+    def test_executor_decorator_future_annotations(self):
+        """Test @executor decorator works with stringified annotations."""
+
+        @executor(id="future_test")
+        async def process_future(value: int, ctx: WorkflowContext[int]) -> None:
+            await ctx.send_message(value * 2)
+
+        assert isinstance(process_future, FunctionExecutor)
+        assert process_future.id == "future_test"
+        assert int in process_future._handlers
+
+        # Check spec
+        spec = process_future._handler_specs[0]
+        assert spec["message_type"] is int
+        assert spec["output_types"] == [int]
+
+    def test_executor_decorator_future_annotations_complex(self):
+        """Test @executor decorator works with complex stringified annotations."""
+
+        @executor
+        async def process_complex(data: dict[str, Any], ctx: WorkflowContext[list[str]]) -> None:
+            await ctx.send_message(["done"])
+
+        assert isinstance(process_complex, FunctionExecutor)
+        spec = process_complex._handler_specs[0]
+        assert spec["message_type"] == dict[str, Any]
+        assert spec["output_types"] == [list[str]]

python/packages/core/tests/workflow/test_handoff.py

@@ -288,57 +288,6 @@ def test_build_fails_without_participants():
         HandoffBuilder().build()
 
 
-async def test_multiple_runs_dont_leak_conversation():
-    """Verify that running the same workflow multiple times doesn't leak conversation history."""
-    triage = _RecordingAgent(name="triage", handoff_to="specialist")
-    specialist = _RecordingAgent(name="specialist")
-
-    workflow = (
-        HandoffBuilder(participants=[triage, specialist])
-        .set_coordinator("triage")
-        .with_termination_condition(lambda conv: sum(1 for m in conv if m.role == Role.USER) >= 2)
-        .build()
-    )
-
-    # First run
-    events = await _drain(workflow.run_stream("First run message"))
-    requests = [ev for ev in events if isinstance(ev, RequestInfoEvent)]
-    assert requests
-    events = await _drain(workflow.send_responses_streaming({requests[-1].request_id: "Second message"}))
-    outputs = [ev for ev in events if isinstance(ev, WorkflowOutputEvent)]
-    assert outputs, "First run should emit output"
-
-    first_run_conversation = outputs[-1].data
-    assert isinstance(first_run_conversation, list)
-    first_run_conv_list = cast(list[ChatMessage], first_run_conversation)
-    first_run_user_messages = [msg for msg in first_run_conv_list if msg.role == Role.USER]
-    assert len(first_run_user_messages) == 2
-    assert any("First run message" in msg.text for msg in first_run_user_messages if msg.text)
-
-    # Second run - should start fresh, not include first run's messages
-    triage.calls.clear()
-    specialist.calls.clear()
-
-    events = await _drain(workflow.run_stream("Second run different message"))
-    requests = [ev for ev in events if isinstance(ev, RequestInfoEvent)]
-    assert requests
-    events = await _drain(workflow.send_responses_streaming({requests[-1].request_id: "Another message"}))
-    outputs = [ev for ev in events if isinstance(ev, WorkflowOutputEvent)]
-    assert outputs, "Second run should emit output"
-
-    second_run_conversation = outputs[-1].data
-    assert isinstance(second_run_conversation, list)
-    second_run_conv_list = cast(list[ChatMessage], second_run_conversation)
-    second_run_user_messages = [msg for msg in second_run_conv_list if msg.role == Role.USER]
-    assert len(second_run_user_messages) == 2, (
-        "Second run should have exactly 2 user messages, not accumulate first run"
-    )
-    assert any("Second run different message" in msg.text for msg in second_run_user_messages if msg.text)
-    assert not any("First run message" in msg.text for msg in second_run_user_messages if msg.text), (
-        "Second run should NOT contain first run's messages"
-    )
-
-
 async def test_handoff_async_termination_condition() -> None:
     """Test that async termination conditions work correctly."""
     termination_call_count = 0
@@ -585,7 +534,7 @@ async def test_return_to_previous_state_serialization():
     coordinator._current_agent_id = "specialist_a"  # type: ignore[reportPrivateUsage]
 
     # Snapshot the state
-    state = coordinator.snapshot_state()
+    state = await coordinator.on_checkpoint_save()
 
     # Verify pattern metadata includes current_agent_id
     assert "metadata" in state
@@ -603,7 +552,7 @@ async def test_return_to_previous_state_serialization():
     )
 
     # Restore state
-    coordinator2.restore_state(state)
+    await coordinator2.on_checkpoint_restore(state)
 
     # Verify current_agent_id was restored
     assert coordinator2._current_agent_id == "specialist_a", "Current agent should be restored from checkpoint"  # type: ignore[reportPrivateUsage]

python/packages/core/tests/workflow/test_magentic.py

@@ -1,5 +1,6 @@
 # Copyright (c) Microsoft. All rights reserved.
 
+import sys
 from collections.abc import AsyncIterable
 from dataclasses import dataclass
 from typing import Any, cast
@@ -42,6 +43,11 @@ from agent_framework._workflows._magentic import (  # type: ignore[reportPrivate
     _MagenticStartMessage,  # type: ignore
 )
 
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
 
 def test_magentic_start_message_from_string():
     msg = _MagenticStartMessage.from_string("Do the thing")
@@ -101,8 +107,9 @@ class FakeManager(MagenticManagerBase):
     next_speaker_name: str = "agentA"
     instruction_text: str = "Proceed with step 1"
 
-    def snapshot_state(self) -> dict[str, Any]:
-        state = super().snapshot_state()
+    @override
+    def on_checkpoint_save(self) -> dict[str, Any]:
+        state = super().on_checkpoint_save()
         if self.task_ledger is not None:
             state = dict(state)
             state["task_ledger"] = {
@@ -111,8 +118,9 @@ class FakeManager(MagenticManagerBase):
             }
         return state
 
-    def restore_state(self, state: dict[str, Any]) -> None:
-        super().restore_state(state)
+    @override
+    def on_checkpoint_restore(self, state: dict[str, Any]) -> None:
+        super().on_checkpoint_restore(state)
         ledger_state = state.get("task_ledger")
         if isinstance(ledger_state, dict):
             ledger_dict = cast(dict[str, Any], ledger_state)
@@ -185,7 +193,6 @@ async def test_standard_manager_progress_ledger_and_fallback():
     assert ledger2.is_request_satisfied.answer is False
 
 
-@pytest.mark.skip(reason="Response handling refactored - responses no longer passed to run_stream()")
 async def test_magentic_workflow_plan_review_approval_to_completion():
     manager = FakeManager(max_round_count=10)
     wf = (
@@ -204,7 +211,7 @@ async def test_magentic_workflow_plan_review_approval_to_completion():
 
     completed = False
     output: ChatMessage | None = None
-    async for ev in wf.run_stream(
+    async for ev in wf.send_responses_streaming(
         responses={req_event.request_id: MagenticPlanReviewReply(decision=MagenticPlanReviewDecision.APPROVE)}
     ):
         if isinstance(ev, WorkflowStatusEvent) and ev.state == WorkflowRunState.IDLE:
@@ -218,7 +225,6 @@ async def test_magentic_workflow_plan_review_approval_to_completion():
     assert isinstance(output, ChatMessage)
 
 
-@pytest.mark.skip(reason="Response handling refactored - responses no longer passed to run_stream()")
 async def test_magentic_plan_review_approve_with_comments_replans_and_proceeds():
     class CountingManager(FakeManager):
         # Declare as a model field so assignment is allowed under Pydantic
@@ -250,7 +256,7 @@ async def test_magentic_plan_review_approve_with_comments_replans_and_proceeds()
     # Reply APPROVE with comments (no edited text). Expect one replan and no second review round.
     saw_second_review = False
     completed = False
-    async for ev in wf.run_stream(
+    async for ev in wf.send_responses_streaming(
         responses={
             req_event.request_id: MagenticPlanReviewReply(
                 decision=MagenticPlanReviewDecision.APPROVE,
@@ -298,7 +304,6 @@ async def test_magentic_orchestrator_round_limit_produces_partial_result():
     assert data.role == Role.ASSISTANT
 
 
-@pytest.mark.skip(reason="Response handling refactored - send_responses_streaming no longer exists")
 async def test_magentic_checkpoint_resume_round_trip():
     storage = InMemoryCheckpointStorage()
 
@@ -369,7 +374,7 @@ class _DummyExec(Executor):
         pass
 
 
-def test_magentic_agent_executor_snapshot_roundtrip():
+async def test_magentic_agent_executor_on_checkpoint_save_and_restore_roundtrip():
     backing_executor = _DummyExec("backing")
     agent_exec = MagenticAgentExecutor(backing_executor, "agentA")
     agent_exec._chat_history.extend([  # type: ignore[reportPrivateUsage]
@@ -377,10 +382,10 @@ def test_magentic_agent_executor_snapshot_roundtrip():
         ChatMessage(role=Role.ASSISTANT, text="world", author_name="agentA"),
     ])
 
-    state = agent_exec.snapshot_state()
+    state = await agent_exec.on_checkpoint_save()
 
     restored_executor = MagenticAgentExecutor(_DummyExec("backing2"), "agentA")
-    restored_executor.restore_state(state)
+    await restored_executor.on_checkpoint_restore(state)
 
     assert len(restored_executor._chat_history) == 2  # type: ignore[reportPrivateUsage]
     assert restored_executor._chat_history[0].text == "hello"  # type: ignore[reportPrivateUsage]

python/packages/core/tests/workflow/test_workflow.py

@@ -199,7 +199,10 @@ async def test_fan_out():
 
     # Each executor will emit two events: ExecutorInvokedEvent and ExecutorCompletedEvent
     # executor_b will also emit a WorkflowOutputEvent (no WorkflowCompletedEvent anymore)
-    assert len(events) == 7
+    # Each superstep will emit also emit a WorkflowStartedEvent and WorkflowCompletedEvent
+    # This workflow will converge in 2 supersteps because executor_c will send one more message
+    # after executor_b completes
+    assert len(events) == 11
 
     assert events.get_final_state() == WorkflowRunState.IDLE
     outputs = events.get_outputs()
@@ -220,7 +223,9 @@ async def test_fan_out_multiple_completed_events():
 
     # Each executor will emit two events: ExecutorInvokedEvent and ExecutorCompletedEvent
     # executor_b and executor_c will also emit a WorkflowOutputEvent (no WorkflowCompletedEvent anymore)
-    assert len(events) == 8
+    # Each superstep will emit also emit a WorkflowStartedEvent and WorkflowCompletedEvent
+    # This workflow will converge in 1 superstep because executor_a and executor_b will not send further messages
+    assert len(events) == 10
 
     # Multiple outputs are expected from both executors
     outputs = events.get_outputs()
@@ -246,7 +251,8 @@ async def test_fan_in():
 
     # Each executor will emit two events: ExecutorInvokedEvent and ExecutorCompletedEvent
     # aggregator will also emit a WorkflowOutputEvent (no WorkflowCompletedEvent anymore)
-    assert len(events) == 9
+    # Each superstep will emit also emit a WorkflowStartedEvent and WorkflowCompletedEvent
+    assert len(events) == 13
 
     assert events.get_final_state() == WorkflowRunState.IDLE
     outputs = events.get_outputs()

python/packages/devui/agent_framework_devui/_deployment.py

@@ -10,6 +10,7 @@ import uuid
 from collections.abc import AsyncGenerator
 from datetime import datetime, timezone
 from pathlib import Path
+from urllib.parse import urlparse
 
 from .models._discovery_models import Deployment, DeploymentConfig, DeploymentEvent
 
@@ -467,11 +468,18 @@ CMD ["devui", "/app/entity", "--mode", "{config.ui_mode}", "--host", "0.0.0.0",
                         await event_queue.put(
                             DeploymentEvent(type="deploy.progress", message=f"Docker build: {line_text}")
                         )
-                    elif "https://" in line_text and ".azurecontainerapps.io" in line_text:
-                        # Deployment URL detected
-                        await event_queue.put(
-                            DeploymentEvent(type="deploy.progress", message="Deployment URL generated!")
-                        )
+                    elif "https://" in line_text:
+                        # Try to extract all URLs and check if any is on azurecontainerapps.io
+                        urls = re.findall(r'https://[^\s<>"]+', line_text)
+                        for url in urls:
+                            # Strip common trailing punctuation to ensure clean URL parsing
+                            url_clean = url.rstrip(".,;:!?'\")}]")
+                            host = urlparse(url_clean).hostname
+                            if host and (host == "azurecontainerapps.io" or host.endswith(".azurecontainerapps.io")):
+                                await event_queue.put(
+                                    DeploymentEvent(type="deploy.progress", message="Deployment URL generated!")
+                                )
+                                break
 
             # Wait for process to complete
             return_code = await process.wait()

python/packages/devui/frontend/yarn.lock

@@ -24,7 +24,7 @@
   resolved "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.28.0.tgz"
   integrity sha512-60X7qkglvrap8mn1lh2ebxXdZYtUcpd7gsmy9kLaBJ4i/WdY8PqTSdxyA8qraikqKQK5C1KRBKXqznrVapyNaw==
 
-"@babel/core@^7.0.0", "@babel/core@^7.0.0-0", "@babel/core@^7.28.3":
+"@babel/core@^7.28.3":
   version "7.28.3"
   resolved "https://registry.npmjs.org/@babel/core/-/core-7.28.3.tgz"
   integrity sha512-yDBHV9kQNcr2/sUr9jghVyz9C3Y5G2zUM2H2lo+9mKv4sFgbA8s8Z9t8D1jiTkGoO/NoIfKMyKWr4s6CN23ZwQ==
@@ -168,6 +168,153 @@
     "@babel/helper-string-parser" "^7.27.1"
     "@babel/helper-validator-identifier" "^7.27.1"
 
+"@emnapi/core@^1.4.3", "@emnapi/core@^1.4.5":
+  version "1.7.1"
+  resolved "https://registry.yarnpkg.com/@emnapi/core/-/core-1.7.1.tgz#3a79a02dbc84f45884a1806ebb98e5746bdfaac4"
+  integrity sha512-o1uhUASyo921r2XtHYOHy7gdkGLge8ghBEQHMWmyJFoXlpU58kIrhhN3w26lpQb6dspetweapMn2CSNwQ8I4wg==
+  dependencies:
+    "@emnapi/wasi-threads" "1.1.0"
+    tslib "^2.4.0"
+
+"@emnapi/runtime@^1.4.3", "@emnapi/runtime@^1.4.5":
+  version "1.7.1"
+  resolved "https://registry.yarnpkg.com/@emnapi/runtime/-/runtime-1.7.1.tgz#a73784e23f5d57287369c808197288b52276b791"
+  integrity sha512-PVtJr5CmLwYAU9PZDMITZoR5iAOShYREoR45EyyLrbntV50mdePTgUn4AmOw90Ifcj+x2kRjdzr1HP3RrNiHGA==
+  dependencies:
+    tslib "^2.4.0"
+
+"@emnapi/wasi-threads@1.1.0", "@emnapi/wasi-threads@^1.0.4":
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/@emnapi/wasi-threads/-/wasi-threads-1.1.0.tgz#60b2102fddc9ccb78607e4a3cf8403ea69be41bf"
+  integrity sha512-WI0DdZ8xFSbgMjR1sFsKABJ/C5OnRrjT06JXbZKexJGrDuPTzZdDYfFlsgcCXCyf+suG5QU2e/y1Wo2V/OapLQ==
+  dependencies:
+    tslib "^2.4.0"
+
+"@esbuild/aix-ppc64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/aix-ppc64/-/aix-ppc64-0.25.9.tgz#bef96351f16520055c947aba28802eede3c9e9a9"
+  integrity sha512-OaGtL73Jck6pBKjNIe24BnFE6agGl+6KxDtTfHhy1HmhthfKouEcOhqpSL64K4/0WCtbKFLOdzD/44cJ4k9opA==
+
+"@esbuild/android-arm64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/android-arm64/-/android-arm64-0.25.9.tgz#d2e70be7d51a529425422091e0dcb90374c1546c"
+  integrity sha512-IDrddSmpSv51ftWslJMvl3Q2ZT98fUSL2/rlUXuVqRXHCs5EUF1/f+jbjF5+NG9UffUDMCiTyh8iec7u8RlTLg==
+
+"@esbuild/android-arm@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/android-arm/-/android-arm-0.25.9.tgz#d2a753fe2a4c73b79437d0ba1480e2d760097419"
+  integrity sha512-5WNI1DaMtxQ7t7B6xa572XMXpHAaI/9Hnhk8lcxF4zVN4xstUgTlvuGDorBguKEnZO70qwEcLpfifMLoxiPqHQ==
+
+"@esbuild/android-x64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/android-x64/-/android-x64-0.25.9.tgz#5278836e3c7ae75761626962f902a0d55352e683"
+  integrity sha512-I853iMZ1hWZdNllhVZKm34f4wErd4lMyeV7BLzEExGEIZYsOzqDWDf+y082izYUE8gtJnYHdeDpN/6tUdwvfiw==
+
+"@esbuild/darwin-arm64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/darwin-arm64/-/darwin-arm64-0.25.9.tgz#f1513eaf9ec8fa15dcaf4c341b0f005d3e8b47ae"
+  integrity sha512-XIpIDMAjOELi/9PB30vEbVMs3GV1v2zkkPnuyRRURbhqjyzIINwj+nbQATh4H9GxUgH1kFsEyQMxwiLFKUS6Rg==
+
+"@esbuild/darwin-x64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/darwin-x64/-/darwin-x64-0.25.9.tgz#e27dbc3b507b3a1cea3b9280a04b8b6b725f82be"
+  integrity sha512-jhHfBzjYTA1IQu8VyrjCX4ApJDnH+ez+IYVEoJHeqJm9VhG9Dh2BYaJritkYK3vMaXrf7Ogr/0MQ8/MeIefsPQ==
+
+"@esbuild/freebsd-arm64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.9.tgz#364e3e5b7a1fd45d92be08c6cc5d890ca75908ca"
+  integrity sha512-z93DmbnY6fX9+KdD4Ue/H6sYs+bhFQJNCPZsi4XWJoYblUqT06MQUdBCpcSfuiN72AbqeBFu5LVQTjfXDE2A6Q==
+
+"@esbuild/freebsd-x64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/freebsd-x64/-/freebsd-x64-0.25.9.tgz#7c869b45faeb3df668e19ace07335a0711ec56ab"
+  integrity sha512-mrKX6H/vOyo5v71YfXWJxLVxgy1kyt1MQaD8wZJgJfG4gq4DpQGpgTB74e5yBeQdyMTbgxp0YtNj7NuHN0PoZg==
+
+"@esbuild/linux-arm64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/linux-arm64/-/linux-arm64-0.25.9.tgz#48d42861758c940b61abea43ba9a29b186d6cb8b"
+  integrity sha512-BlB7bIcLT3G26urh5Dmse7fiLmLXnRlopw4s8DalgZ8ef79Jj4aUcYbk90g8iCa2467HX8SAIidbL7gsqXHdRw==
+
+"@esbuild/linux-arm@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/linux-arm/-/linux-arm-0.25.9.tgz#6ce4b9cabf148274101701d112b89dc67cc52f37"
+  integrity sha512-HBU2Xv78SMgaydBmdor38lg8YDnFKSARg1Q6AT0/y2ezUAKiZvc211RDFHlEZRFNRVhcMamiToo7bDx3VEOYQw==
+
+"@esbuild/linux-ia32@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/linux-ia32/-/linux-ia32-0.25.9.tgz#207e54899b79cac9c26c323fc1caa32e3143f1c4"
+  integrity sha512-e7S3MOJPZGp2QW6AK6+Ly81rC7oOSerQ+P8L0ta4FhVi+/j/v2yZzx5CqqDaWjtPFfYz21Vi1S0auHrap3Ma3A==
+
+"@esbuild/linux-loong64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/linux-loong64/-/linux-loong64-0.25.9.tgz#0ba48a127159a8f6abb5827f21198b999ffd1fc0"
+  integrity sha512-Sbe10Bnn0oUAB2AalYztvGcK+o6YFFA/9829PhOCUS9vkJElXGdphz0A3DbMdP8gmKkqPmPcMJmJOrI3VYB1JQ==
+
+"@esbuild/linux-mips64el@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/linux-mips64el/-/linux-mips64el-0.25.9.tgz#a4d4cc693d185f66a6afde94f772b38ce5d64eb5"
+  integrity sha512-YcM5br0mVyZw2jcQeLIkhWtKPeVfAerES5PvOzaDxVtIyZ2NUBZKNLjC5z3/fUlDgT6w89VsxP2qzNipOaaDyA==
+
+"@esbuild/linux-ppc64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/linux-ppc64/-/linux-ppc64-0.25.9.tgz#0f5805c1c6d6435a1dafdc043cb07a19050357db"
+  integrity sha512-++0HQvasdo20JytyDpFvQtNrEsAgNG2CY1CLMwGXfFTKGBGQT3bOeLSYE2l1fYdvML5KUuwn9Z8L1EWe2tzs1w==
+
+"@esbuild/linux-riscv64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/linux-riscv64/-/linux-riscv64-0.25.9.tgz#6776edece0f8fca79f3386398b5183ff2a827547"
+  integrity sha512-uNIBa279Y3fkjV+2cUjx36xkx7eSjb8IvnL01eXUKXez/CBHNRw5ekCGMPM0BcmqBxBcdgUWuUXmVWwm4CH9kg==
+
+"@esbuild/linux-s390x@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/linux-s390x/-/linux-s390x-0.25.9.tgz#3f6f29ef036938447c2218d309dc875225861830"
+  integrity sha512-Mfiphvp3MjC/lctb+7D287Xw1DGzqJPb/J2aHHcHxflUo+8tmN/6d4k6I2yFR7BVo5/g7x2Monq4+Yew0EHRIA==
+
+"@esbuild/linux-x64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/linux-x64/-/linux-x64-0.25.9.tgz#831fe0b0e1a80a8b8391224ea2377d5520e1527f"
+  integrity sha512-iSwByxzRe48YVkmpbgoxVzn76BXjlYFXC7NvLYq+b+kDjyyk30J0JY47DIn8z1MO3K0oSl9fZoRmZPQI4Hklzg==
+
+"@esbuild/netbsd-arm64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.9.tgz#06f99d7eebe035fbbe43de01c9d7e98d2a0aa548"
+  integrity sha512-9jNJl6FqaUG+COdQMjSCGW4QiMHH88xWbvZ+kRVblZsWrkXlABuGdFJ1E9L7HK+T0Yqd4akKNa/lO0+jDxQD4Q==
+
+"@esbuild/netbsd-x64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/netbsd-x64/-/netbsd-x64-0.25.9.tgz#db99858e6bed6e73911f92a88e4edd3a8c429a52"
+  integrity sha512-RLLdkflmqRG8KanPGOU7Rpg829ZHu8nFy5Pqdi9U01VYtG9Y0zOG6Vr2z4/S+/3zIyOxiK6cCeYNWOFR9QP87g==
+
+"@esbuild/openbsd-arm64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.9.tgz#afb886c867e36f9d86bb21e878e1185f5d5a0935"
+  integrity sha512-YaFBlPGeDasft5IIM+CQAhJAqS3St3nJzDEgsgFixcfZeyGPCd6eJBWzke5piZuZ7CtL656eOSYKk4Ls2C0FRQ==
+
+"@esbuild/openbsd-x64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/openbsd-x64/-/openbsd-x64-0.25.9.tgz#30855c9f8381fac6a0ef5b5f31ac6e7108a66ecf"
+  integrity sha512-1MkgTCuvMGWuqVtAvkpkXFmtL8XhWy+j4jaSO2wxfJtilVCi0ZE37b8uOdMItIHz4I6z1bWWtEX4CJwcKYLcuA==
+
+"@esbuild/openharmony-arm64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/openharmony-arm64/-/openharmony-arm64-0.25.9.tgz#2f2144af31e67adc2a8e3705c20c2bd97bd88314"
+  integrity sha512-4Xd0xNiMVXKh6Fa7HEJQbrpP3m3DDn43jKxMjxLLRjWnRsfxjORYJlXPO4JNcXtOyfajXorRKY9NkOpTHptErg==
+
+"@esbuild/sunos-x64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/sunos-x64/-/sunos-x64-0.25.9.tgz#69b99a9b5bd226c9eb9c6a73f990fddd497d732e"
+  integrity sha512-WjH4s6hzo00nNezhp3wFIAfmGZ8U7KtrJNlFMRKxiI9mxEK1scOMAaa9i4crUtu+tBr+0IN6JCuAcSBJZfnphw==
+
+"@esbuild/win32-arm64@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/win32-arm64/-/win32-arm64-0.25.9.tgz#d789330a712af916c88325f4ffe465f885719c6b"
+  integrity sha512-mGFrVJHmZiRqmP8xFOc6b84/7xa5y5YvR1x8djzXpJBSv/UsNK6aqec+6JDjConTgvvQefdGhFDAs2DLAds6gQ==
+
+"@esbuild/win32-ia32@0.25.9":
+  version "0.25.9"
+  resolved "https://registry.yarnpkg.com/@esbuild/win32-ia32/-/win32-ia32-0.25.9.tgz#52fc735406bd49688253e74e4e837ac2ba0789e3"
+  integrity sha512-b33gLVU2k11nVx1OhX3C8QQP6UHQK4ZtN56oFWvVXvz2VkDoe6fbG8TOgHFxEvqeqohmRnIHe5A1+HADk4OQww==
+
 "@esbuild/win32-x64@0.25.9":
   version "0.25.9"
   resolved "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.9.tgz"
@@ -221,7 +368,7 @@
     minimatch "^3.1.2"
     strip-json-comments "^3.1.1"
 
-"@eslint/js@^9.33.0", "@eslint/js@9.33.0":
+"@eslint/js@9.33.0", "@eslint/js@^9.33.0":
   version "9.33.0"
   resolved "https://registry.npmjs.org/@eslint/js/-/js-9.33.0.tgz"
   integrity sha512-5K1/mKhWaMfreBGJTwval43JJmkip0RmM+3+IuqupeSKNC/Th2Kc7ucaq5ovTSra/OOKB9c58CGSz3QMVbWt0A==
@@ -335,6 +482,15 @@
     "@jridgewell/resolve-uri" "^3.1.0"
     "@jridgewell/sourcemap-codec" "^1.4.14"
 
+"@napi-rs/wasm-runtime@^0.2.12":
+  version "0.2.12"
+  resolved "https://registry.yarnpkg.com/@napi-rs/wasm-runtime/-/wasm-runtime-0.2.12.tgz#3e78a8b96e6c33a6c517e1894efbd5385a7cb6f2"
+  integrity sha512-ZVWUcfwY4E/yPitQJl481FjFo3K22D6qF0DuFH6Y/nbnE11GY5uguDxZMGXPQ8WQ0128MXQD7TnfHyK4oWoIJQ==
+  dependencies:
+    "@emnapi/core" "^1.4.3"
+    "@emnapi/runtime" "^1.4.3"
+    "@tybys/wasm-util" "^0.10.0"
+
 "@nodelib/fs.scandir@2.1.5":
   version "2.1.5"
   resolved "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz"
@@ -343,7 +499,7 @@
     "@nodelib/fs.stat" "2.0.5"
     run-parallel "^1.1.9"
 
-"@nodelib/fs.stat@^2.0.2", "@nodelib/fs.stat@2.0.5":
+"@nodelib/fs.stat@2.0.5", "@nodelib/fs.stat@^2.0.2":
   version "2.0.5"
   resolved "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz"
   integrity sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==
@@ -693,6 +849,101 @@
   resolved "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-beta.32.tgz"
   integrity sha512-QReCdvxiUZAPkvp1xpAg62IeNzykOFA6syH2CnClif4YmALN1XKpB39XneL80008UbtMShthSVDKmrx05N1q/g==
 
+"@rollup/rollup-android-arm-eabi@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.47.1.tgz#6e236cd2fd29bb01a300ad4ff6ed0f1a17550e69"
+  integrity sha512-lTahKRJip0knffA/GTNFJMrToD+CM+JJ+Qt5kjzBK/sFQ0EWqfKW3AYQSlZXN98tX0lx66083U9JYIMioMMK7g==
+
+"@rollup/rollup-android-arm64@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.47.1.tgz#808f2c9c7e68161add613ebcb0eac5a058a0df3c"
+  integrity sha512-uqxkb3RJLzlBbh/bbNQ4r7YpSZnjgMgyoEOY7Fy6GCbelkDSAzeiogxMG9TfLsBbqmGsdDObo3mzGqa8hps4MA==
+
+"@rollup/rollup-darwin-arm64@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.47.1.tgz#fa41e413c8e73d61039d6375b234595f24b1e5e3"
+  integrity sha512-tV6reObmxBDS4DDyLzTDIpymthNlxrLBGAoQx6m2a7eifSNEZdkXQl1PE4ZjCkEDPVgNXSzND/k9AQ3mC4IOEQ==
+
+"@rollup/rollup-darwin-x64@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.47.1.tgz#9aac64e886435493f2e3a0aa5e4aad098a90814c"
+  integrity sha512-XuJRPTnMk1lwsSnS3vYyVMu4x/+WIw1MMSiqj5C4j3QOWsMzbJEK90zG+SWV1h0B1ABGCQ0UZUjti+TQK35uHQ==
+
+"@rollup/rollup-freebsd-arm64@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.47.1.tgz#9fc804264f7b7a7cdad3747950299f990163be1f"
+  integrity sha512-79BAm8Ag/tmJ5asCqgOXsb3WY28Rdd5Lxj8ONiQzWzy9LvWORd5qVuOnjlqiWWZJw+dWewEktZb5yiM1DLLaHw==
+
+"@rollup/rollup-freebsd-x64@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.47.1.tgz#933feaff864feb03bbbcd0c18ea351ade957cf79"
+  integrity sha512-OQ2/ZDGzdOOlyfqBiip0ZX/jVFekzYrGtUsqAfLDbWy0jh1PUU18+jYp8UMpqhly5ltEqotc2miLngf9FPSWIA==
+
+"@rollup/rollup-linux-arm-gnueabihf@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.47.1.tgz#02915e6b2c55fe5961c27404aba2d9c8ef48ac6c"
+  integrity sha512-HZZBXJL1udxlCVvoVadstgiU26seKkHbbAMLg7680gAcMnRNP9SAwTMVet02ANA94kXEI2VhBnXs4e5nf7KG2A==
+
+"@rollup/rollup-linux-arm-musleabihf@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.47.1.tgz#1afef33191b26e76ae7f0d0dc767efc6be1285ce"
+  integrity sha512-sZ5p2I9UA7T950JmuZ3pgdKA6+RTBr+0FpK427ExW0t7n+QwYOcmDTK/aRlzoBrWyTpJNlS3kacgSlSTUg6P/Q==
+
+"@rollup/rollup-linux-arm64-gnu@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.47.1.tgz#6e7f38fb99d14143de3ce33204e6cd61e1c2c780"
+  integrity sha512-3hBFoqPyU89Dyf1mQRXCdpc6qC6At3LV6jbbIOZd72jcx7xNk3aAp+EjzAtN6sDlmHFzsDJN5yeUySvorWeRXA==
+
+"@rollup/rollup-linux-arm64-musl@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.47.1.tgz#25ab09f14bbcba85a604bcee2962d2486db90794"
+  integrity sha512-49J4FnMHfGodJWPw73Ve+/hsPjZgcXQGkmqBGZFvltzBKRS+cvMiWNLadOMXKGnYRhs1ToTGM0sItKISoSGUNA==
+
+"@rollup/rollup-linux-loongarch64-gnu@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-loongarch64-gnu/-/rollup-linux-loongarch64-gnu-4.47.1.tgz#d3e3a3fd61e21b2753094391dee9b515a2bc9ecd"
+  integrity sha512-4yYU8p7AneEpQkRX03pbpLmE21z5JNys16F1BZBZg5fP9rIlb0TkeQjn5du5w4agConCCEoYIG57sNxjryHEGg==
+
+"@rollup/rollup-linux-ppc64-gnu@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.47.1.tgz#6b44445e2bd5866692010de241bf18d2ae8b0cb8"
+  integrity sha512-fAiq+J28l2YMWgC39jz/zPi2jqc0y3GSRo1yyxlBHt6UN0yYgnegHSRPa3pnHS5amT/efXQrm0ug5+aNEu9UuQ==
+
+"@rollup/rollup-linux-riscv64-gnu@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.47.1.tgz#3ff412d20d3b157e6aadabf84788e8c5cb221ba7"
+  integrity sha512-daoT0PMENNdjVYYU9xec30Y2prb1AbEIbb64sqkcQcSaR0zYuKkoPuhIztfxuqN82KYCKKrj+tQe4Gi7OSm1ow==
+
+"@rollup/rollup-linux-riscv64-musl@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.47.1.tgz#104f451497d53d82a49c6d08c13c59f5f30eed57"
+  integrity sha512-JNyXaAhWtdzfXu5pUcHAuNwGQKevR+6z/poYQKVW+pLaYOj9G1meYc57/1Xv2u4uTxfu9qEWmNTjv/H/EpAisw==
+
+"@rollup/rollup-linux-s390x-gnu@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.47.1.tgz#d04de7b21d181f30750760cb3553946306506172"
+  integrity sha512-U/CHbqKSwEQyZXjCpY43/GLYcTVKEXeRHw0rMBJP7fP3x6WpYG4LTJWR3ic6TeYKX6ZK7mrhltP4ppolyVhLVQ==
+
+"@rollup/rollup-linux-x64-gnu@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.47.1.tgz#a6ba88ff7480940a435b1e67ddbb3f207a7ae02f"
+  integrity sha512-uTLEakjxOTElfeZIGWkC34u2auLHB1AYS6wBjPGI00bWdxdLcCzK5awjs25YXpqB9lS8S0vbO0t9ZcBeNibA7g==
+
+"@rollup/rollup-linux-x64-musl@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.47.1.tgz#c912c8ffa0c242ed3175cd91cdeaef98109afa54"
+  integrity sha512-Ft+d/9DXs30BK7CHCTX11FtQGHUdpNDLJW0HHLign4lgMgBcPFN3NkdIXhC5r9iwsMwYreBBc4Rho5ieOmKNVQ==
+
+"@rollup/rollup-win32-arm64-msvc@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.47.1.tgz#ca5eaae89443554b461bb359112a056528cfdac0"
+  integrity sha512-N9X5WqGYzZnjGAFsKSfYFtAShYjwOmFJoWbLg3dYixZOZqU7hdMq+/xyS14zKLhFhZDhP9VfkzQnsdk0ZDS9IA==
+
+"@rollup/rollup-win32-ia32-msvc@4.47.1":
+  version "4.47.1"
+  resolved "https://registry.yarnpkg.com/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.47.1.tgz#34e76172515fb4b374eb990d59f54faff938246e"
+  integrity sha512-O+KcfeCORZADEY8oQJk4HK8wtEOCRE4MdOkb8qGZQNun3jzmj2nmhV/B/ZaaZOkPmJyvm/gW9n0gsB4eRa1eiQ==
+
 "@rollup/rollup-win32-x64-msvc@4.47.1":
   version "4.47.1"
   resolved "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.47.1.tgz"
@@ -711,6 +962,68 @@
     source-map-js "^1.2.1"
     tailwindcss "4.1.12"
 
+"@tailwindcss/oxide-android-arm64@4.1.12":
+  version "4.1.12"
+  resolved "https://registry.yarnpkg.com/@tailwindcss/oxide-android-arm64/-/oxide-android-arm64-4.1.12.tgz#27920fe61fa2743afe8a8ca296fa640b609d17d5"
+  integrity sha512-oNY5pq+1gc4T6QVTsZKwZaGpBb2N1H1fsc1GD4o7yinFySqIuRZ2E4NvGasWc6PhYJwGK2+5YT1f9Tp80zUQZQ==
+
+"@tailwindcss/oxide-darwin-arm64@4.1.12":
+  version "4.1.12"
+  resolved "https://registry.yarnpkg.com/@tailwindcss/oxide-darwin-arm64/-/oxide-darwin-arm64-4.1.12.tgz#e8bd4798f26ec1d012bf0683aeb77449f71505cd"
+  integrity sha512-cq1qmq2HEtDV9HvZlTtrj671mCdGB93bVY6J29mwCyaMYCP/JaUBXxrQQQm7Qn33AXXASPUb2HFZlWiiHWFytw==
+
+"@tailwindcss/oxide-darwin-x64@4.1.12":
+  version "4.1.12"
+  resolved "https://registry.yarnpkg.com/@tailwindcss/oxide-darwin-x64/-/oxide-darwin-x64-4.1.12.tgz#8ddb7e5ddfd9b049ec84a2bda99f2b04a86859f5"
+  integrity sha512-6UCsIeFUcBfpangqlXay9Ffty9XhFH1QuUFn0WV83W8lGdX8cD5/+2ONLluALJD5+yJ7k8mVtwy3zMZmzEfbLg==
+
+"@tailwindcss/oxide-freebsd-x64@4.1.12":
+  version "4.1.12"
+  resolved "https://registry.yarnpkg.com/@tailwindcss/oxide-freebsd-x64/-/oxide-freebsd-x64-4.1.12.tgz#da1c0b16b7a5f95a1e400f299a3ec94fb6fd40ac"
+  integrity sha512-JOH/f7j6+nYXIrHobRYCtoArJdMJh5zy5lr0FV0Qu47MID/vqJAY3r/OElPzx1C/wdT1uS7cPq+xdYYelny1ww==
+
+"@tailwindcss/oxide-linux-arm-gnueabihf@4.1.12":
+  version "4.1.12"
+  resolved "https://registry.yarnpkg.com/@tailwindcss/oxide-linux-arm-gnueabihf/-/oxide-linux-arm-gnueabihf-4.1.12.tgz#34e558aa6e869c6fe9867cb78ed7ba651b9fcaa4"
+  integrity sha512-v4Ghvi9AU1SYgGr3/j38PD8PEe6bRfTnNSUE3YCMIRrrNigCFtHZ2TCm8142X8fcSqHBZBceDx+JlFJEfNg5zQ==
+
+"@tailwindcss/oxide-linux-arm64-gnu@4.1.12":
+  version "4.1.12"
+  resolved "https://registry.yarnpkg.com/@tailwindcss/oxide-linux-arm64-gnu/-/oxide-linux-arm64-gnu-4.1.12.tgz#0a00a8146ab6215f81b2d385056c991441bf390e"
+  integrity sha512-YP5s1LmetL9UsvVAKusHSyPlzSRqYyRB0f+Kl/xcYQSPLEw/BvGfxzbH+ihUciePDjiXwHh+p+qbSP3SlJw+6g==
+
+"@tailwindcss/oxide-linux-arm64-musl@4.1.12":
+  version "4.1.12"
+  resolved "https://registry.yarnpkg.com/@tailwindcss/oxide-linux-arm64-musl/-/oxide-linux-arm64-musl-4.1.12.tgz#b138f494068884ae0d8c343dc1904b22f5e98dc6"
+  integrity sha512-V8pAM3s8gsrXcCv6kCHSuwyb/gPsd863iT+v1PGXC4fSL/OJqsKhfK//v8P+w9ThKIoqNbEnsZqNy+WDnwQqCA==
+
+"@tailwindcss/oxide-linux-x64-gnu@4.1.12":
+  version "4.1.12"
+  resolved "https://registry.yarnpkg.com/@tailwindcss/oxide-linux-x64-gnu/-/oxide-linux-x64-gnu-4.1.12.tgz#5b9d5f23b15cdb714639f5b9741c0df5d610f794"
+  integrity sha512-xYfqYLjvm2UQ3TZggTGrwxjYaLB62b1Wiysw/YE3Yqbh86sOMoTn0feF98PonP7LtjsWOWcXEbGqDL7zv0uW8Q==
+
+"@tailwindcss/oxide-linux-x64-musl@4.1.12":
+  version "4.1.12"
+  resolved "https://registry.yarnpkg.com/@tailwindcss/oxide-linux-x64-musl/-/oxide-linux-x64-musl-4.1.12.tgz#f68ec530d3ca6875ea9015bcd5dd0762ee5e2f5d"
+  integrity sha512-ha0pHPamN+fWZY7GCzz5rKunlv9L5R8kdh+YNvP5awe3LtuXb5nRi/H27GeL2U+TdhDOptU7T6Is7mdwh5Ar3A==
+
+"@tailwindcss/oxide-wasm32-wasi@4.1.12":
+  version "4.1.12"
+  resolved "https://registry.yarnpkg.com/@tailwindcss/oxide-wasm32-wasi/-/oxide-wasm32-wasi-4.1.12.tgz#9fd15a1ebde6076c42c445c5e305c31673ead965"
+  integrity sha512-4tSyu3dW+ktzdEpuk6g49KdEangu3eCYoqPhWNsZgUhyegEda3M9rG0/j1GV/JjVVsj+lG7jWAyrTlLzd/WEBg==
+  dependencies:
+    "@emnapi/core" "^1.4.5"
+    "@emnapi/runtime" "^1.4.5"
+    "@emnapi/wasi-threads" "^1.0.4"
+    "@napi-rs/wasm-runtime" "^0.2.12"
+    "@tybys/wasm-util" "^0.10.0"
+    tslib "^2.8.0"
+
+"@tailwindcss/oxide-win32-arm64-msvc@4.1.12":
+  version "4.1.12"
+  resolved "https://registry.yarnpkg.com/@tailwindcss/oxide-win32-arm64-msvc/-/oxide-win32-arm64-msvc-4.1.12.tgz#938bcc6a82e1120ea4fe2ce94be0a8cdf3ae92c7"
+  integrity sha512-iGLyD/cVP724+FGtMWslhcFyg4xyYyM+5F4hGvKA7eifPkXHRAUDFaimu53fpNg9X8dfP75pXx/zFt/jlNF+lg==
+
 "@tailwindcss/oxide-win32-x64-msvc@4.1.12":
   version "4.1.12"
   resolved "https://registry.npmjs.org/@tailwindcss/oxide-win32-x64-msvc/-/oxide-win32-x64-msvc-4.1.12.tgz"
@@ -746,6 +1059,13 @@
     "@tailwindcss/oxide" "4.1.12"
     tailwindcss "4.1.12"
 
+"@tybys/wasm-util@^0.10.0":
+  version "0.10.1"
+  resolved "https://registry.yarnpkg.com/@tybys/wasm-util/-/wasm-util-0.10.1.tgz#ecddd3205cf1e2d5274649ff0eedd2991ed7f414"
+  integrity sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg==
+  dependencies:
+    tslib "^2.4.0"
+
 "@types/babel__core@^7.20.5":
   version "7.20.5"
   resolved "https://registry.npmjs.org/@types/babel__core/-/babel__core-7.20.5.tgz"
@@ -818,7 +1138,7 @@
     "@types/d3-interpolate" "*"
     "@types/d3-selection" "*"
 
-"@types/estree@^1.0.6", "@types/estree@1.0.8":
+"@types/estree@1.0.8", "@types/estree@^1.0.6":
   version "1.0.8"
   resolved "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz"
   integrity sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==
@@ -828,19 +1148,19 @@
   resolved "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz"
   integrity sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==
 
-"@types/node@^20.19.0 || >=22.12.0", "@types/node@^24.3.0":
+"@types/node@^24.3.0":
   version "24.3.0"
   resolved "https://registry.npmjs.org/@types/node/-/node-24.3.0.tgz"
   integrity sha512-aPTXCrfwnDLj4VvXrm+UUCQjNEvJgNA8s5F1cvwQU+3KNltTOkBm1j30uNLyqqPNe7gE3KFzImYoZEfLhp4Yow==
   dependencies:
     undici-types "~7.10.0"
 
-"@types/react-dom@*", "@types/react-dom@^19.1.7":
+"@types/react-dom@^19.1.7":
   version "19.1.7"
   resolved "https://registry.npmjs.org/@types/react-dom/-/react-dom-19.1.7.tgz"
   integrity sha512-i5ZzwYpqjmrKenzkoLM2Ibzt6mAsM7pxB6BCIouEVVmgiqaMj1TjaK7hnA36hbW5aZv20kx7Lw6hWzPWg0Rurw==
 
-"@types/react@*", "@types/react@^19.0.0", "@types/react@^19.1.10", "@types/react@>=16.8", "@types/react@>=18.0.0":
+"@types/react@^19.1.10":
   version "19.1.10"
   resolved "https://registry.npmjs.org/@types/react/-/react-19.1.10.tgz"
   integrity sha512-EhBeSYX0Y6ye8pNebpKrwFJq7BoQ8J5SO6NlvNwwHjSj6adXJViPQrKlsyPw7hLBLvckEMO1yxeGdR82YBBlDg==
@@ -862,7 +1182,7 @@
     natural-compare "^1.4.0"
     ts-api-utils "^2.1.0"
 
-"@typescript-eslint/parser@^8.40.0", "@typescript-eslint/parser@8.40.0":
+"@typescript-eslint/parser@8.40.0":
   version "8.40.0"
   resolved "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.40.0.tgz"
   integrity sha512-jCNyAuXx8dr5KJMkecGmZ8KI61KBUhkCob+SD+C+I5+Y1FWI2Y3QmY4/cxMCC5WAsZqoEtEETVhUiUMIGCf6Bw==
@@ -890,7 +1210,7 @@
     "@typescript-eslint/types" "8.40.0"
     "@typescript-eslint/visitor-keys" "8.40.0"
 
-"@typescript-eslint/tsconfig-utils@^8.40.0", "@typescript-eslint/tsconfig-utils@8.40.0":
+"@typescript-eslint/tsconfig-utils@8.40.0", "@typescript-eslint/tsconfig-utils@^8.40.0":
   version "8.40.0"
   resolved "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.40.0.tgz"
   integrity sha512-jtMytmUaG9d/9kqSl/W3E3xaWESo4hFDxAIHGVW/WKKtQhesnRIJSAJO6XckluuJ6KDB5woD1EiqknriCtAmcw==
@@ -906,7 +1226,7 @@
     debug "^4.3.4"
     ts-api-utils "^2.1.0"
 
-"@typescript-eslint/types@^8.40.0", "@typescript-eslint/types@8.40.0":
+"@typescript-eslint/types@8.40.0", "@typescript-eslint/types@^8.40.0":
   version "8.40.0"
   resolved "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.40.0.tgz"
   integrity sha512-ETdbFlgbAmXHyFPwqUIYrfc12ArvpBhEVgGAxVYSwli26dn8Ko+lIo4Su9vI9ykTZdJn+vJprs/0eZU0YMAEQg==
@@ -986,7 +1306,7 @@ acorn-jsx@^5.3.2:
   resolved "https://registry.npmjs.org/acorn-jsx/-/acorn-jsx-5.3.2.tgz"
   integrity sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==
 
-"acorn@^6.0.0 || ^7.0.0 || ^8.0.0", acorn@^8.15.0:
+acorn@^8.15.0:
   version "8.15.0"
   resolved "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz"
   integrity sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==
@@ -1047,7 +1367,7 @@ braces@^3.0.3:
   dependencies:
     fill-range "^7.1.1"
 
-browserslist@^4.24.0, "browserslist@>= 4.21.0":
+browserslist@^4.24.0:
   version "4.25.3"
   resolved "https://registry.npmjs.org/browserslist/-/browserslist-4.25.3.tgz"
   integrity sha512-cDGv1kkDI4/0e5yON9yM5G/0A5u8sf5TnmdX5C9qHzI9PPu++sQ9zjm1k9NiOrf3riY4OkK0zSGqfvJyJsgCBQ==
@@ -1143,7 +1463,7 @@ csstype@^3.0.2:
   resolved "https://registry.npmjs.org/d3-dispatch/-/d3-dispatch-3.0.1.tgz"
   integrity sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==
 
-d3-drag@^3.0.0, "d3-drag@2 - 3":
+"d3-drag@2 - 3", d3-drag@^3.0.0:
   version "3.0.0"
   resolved "https://registry.npmjs.org/d3-drag/-/d3-drag-3.0.0.tgz"
   integrity sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==
@@ -1156,14 +1476,14 @@ d3-drag@^3.0.0, "d3-drag@2 - 3":
   resolved "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz"
   integrity sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==
 
-d3-interpolate@^3.0.1, "d3-interpolate@1 - 3":
+"d3-interpolate@1 - 3", d3-interpolate@^3.0.1:
   version "3.0.1"
   resolved "https://registry.npmjs.org/d3-interpolate/-/d3-interpolate-3.0.1.tgz"
   integrity sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==
   dependencies:
     d3-color "1 - 3"
 
-d3-selection@^3.0.0, "d3-selection@2 - 3", d3-selection@3:
+"d3-selection@2 - 3", d3-selection@3, d3-selection@^3.0.0:
   version "3.0.0"
   resolved "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz"
   integrity sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==
@@ -1300,7 +1620,7 @@ eslint-visitor-keys@^4.2.1:
   resolved "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.1.tgz"
   integrity sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ==
 
-"eslint@^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-0 || ^9.0.0", "eslint@^6.0.0 || ^7.0.0 || >=8.0.0", "eslint@^8.57.0 || ^9.0.0", eslint@^9.33.0, eslint@>=8.40:
+eslint@^9.33.0:
   version "9.33.0"
   resolved "https://registry.npmjs.org/eslint/-/eslint-9.33.0.tgz"
   integrity sha512-TS9bTNIryDzStCpJN93aC5VRSW3uTx9sClUn4B87pwiCaJh220otoI0X8mJKr+VcPtniMdN8GKjlwgWGUv5ZKA==
@@ -1546,7 +1866,7 @@ isexe@^2.0.0:
   resolved "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz"
   integrity sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==
 
-jiti@*, jiti@^2.5.1, jiti@>=1.21.0:
+jiti@^2.5.1:
   version "2.5.1"
   resolved "https://registry.npmjs.org/jiti/-/jiti-2.5.1.tgz"
   integrity sha512-twQoecYPiVA5K/h6SxtORw/Bs3ar+mLUtoPSc7iMXzQzK8d7eJ/R09wmTwAjiamETn1cXYPGfNnu7DMoHgu12w==
@@ -1557,9 +1877,9 @@ js-tokens@^4.0.0:
   integrity sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==
 
 js-yaml@^4.1.0:
-  version "4.1.0"
-  resolved "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz"
-  integrity sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==
+  version "4.1.1"
+  resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-4.1.1.tgz#854c292467705b699476e1a2decc0c8a3458806b"
+  integrity sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==
   dependencies:
     argparse "^2.0.1"
 
@@ -1603,12 +1923,57 @@ levn@^0.4.1:
     prelude-ls "^1.2.1"
     type-check "~0.4.0"
 
+lightningcss-darwin-arm64@1.30.1:
+  version "1.30.1"
+  resolved "https://registry.yarnpkg.com/lightningcss-darwin-arm64/-/lightningcss-darwin-arm64-1.30.1.tgz#3d47ce5e221b9567c703950edf2529ca4a3700ae"
+  integrity sha512-c8JK7hyE65X1MHMN+Viq9n11RRC7hgin3HhYKhrMyaXflk5GVplZ60IxyoVtzILeKr+xAJwg6zK6sjTBJ0FKYQ==
+
+lightningcss-darwin-x64@1.30.1:
+  version "1.30.1"
+  resolved "https://registry.yarnpkg.com/lightningcss-darwin-x64/-/lightningcss-darwin-x64-1.30.1.tgz#e81105d3fd6330860c15fe860f64d39cff5fbd22"
+  integrity sha512-k1EvjakfumAQoTfcXUcHQZhSpLlkAuEkdMBsI/ivWw9hL+7FtilQc0Cy3hrx0AAQrVtQAbMI7YjCgYgvn37PzA==
+
+lightningcss-freebsd-x64@1.30.1:
+  version "1.30.1"
+  resolved "https://registry.yarnpkg.com/lightningcss-freebsd-x64/-/lightningcss-freebsd-x64-1.30.1.tgz#a0e732031083ff9d625c5db021d09eb085af8be4"
+  integrity sha512-kmW6UGCGg2PcyUE59K5r0kWfKPAVy4SltVeut+umLCFoJ53RdCUWxcRDzO1eTaxf/7Q2H7LTquFHPL5R+Gjyig==
+
+lightningcss-linux-arm-gnueabihf@1.30.1:
+  version "1.30.1"
+  resolved "https://registry.yarnpkg.com/lightningcss-linux-arm-gnueabihf/-/lightningcss-linux-arm-gnueabihf-1.30.1.tgz#1f5ecca6095528ddb649f9304ba2560c72474908"
+  integrity sha512-MjxUShl1v8pit+6D/zSPq9S9dQ2NPFSQwGvxBCYaBYLPlCWuPh9/t1MRS8iUaR8i+a6w7aps+B4N0S1TYP/R+Q==
+
+lightningcss-linux-arm64-gnu@1.30.1:
+  version "1.30.1"
+  resolved "https://registry.yarnpkg.com/lightningcss-linux-arm64-gnu/-/lightningcss-linux-arm64-gnu-1.30.1.tgz#eee7799726103bffff1e88993df726f6911ec009"
+  integrity sha512-gB72maP8rmrKsnKYy8XUuXi/4OctJiuQjcuqWNlJQ6jZiWqtPvqFziskH3hnajfvKB27ynbVCucKSm2rkQp4Bw==
+
+lightningcss-linux-arm64-musl@1.30.1:
+  version "1.30.1"
+  resolved "https://registry.yarnpkg.com/lightningcss-linux-arm64-musl/-/lightningcss-linux-arm64-musl-1.30.1.tgz#f2e4b53f42892feeef8f620cbb889f7c064a7dfe"
+  integrity sha512-jmUQVx4331m6LIX+0wUhBbmMX7TCfjF5FoOH6SD1CttzuYlGNVpA7QnrmLxrsub43ClTINfGSYyHe2HWeLl5CQ==
+
+lightningcss-linux-x64-gnu@1.30.1:
+  version "1.30.1"
+  resolved "https://registry.yarnpkg.com/lightningcss-linux-x64-gnu/-/lightningcss-linux-x64-gnu-1.30.1.tgz#2fc7096224bc000ebb97eea94aea248c5b0eb157"
+  integrity sha512-piWx3z4wN8J8z3+O5kO74+yr6ze/dKmPnI7vLqfSqI8bccaTGY5xiSGVIJBDd5K5BHlvVLpUB3S2YCfelyJ1bw==
+
+lightningcss-linux-x64-musl@1.30.1:
+  version "1.30.1"
+  resolved "https://registry.yarnpkg.com/lightningcss-linux-x64-musl/-/lightningcss-linux-x64-musl-1.30.1.tgz#66dca2b159fd819ea832c44895d07e5b31d75f26"
+  integrity sha512-rRomAK7eIkL+tHY0YPxbc5Dra2gXlI63HL+v1Pdi1a3sC+tJTcFrHX+E86sulgAXeI7rSzDYhPSeHHjqFhqfeQ==
+
+lightningcss-win32-arm64-msvc@1.30.1:
+  version "1.30.1"
+  resolved "https://registry.yarnpkg.com/lightningcss-win32-arm64-msvc/-/lightningcss-win32-arm64-msvc-1.30.1.tgz#7d8110a19d7c2d22bfdf2f2bb8be68e7d1b69039"
+  integrity sha512-mSL4rqPi4iXq5YVqzSsJgMVFENoa4nGTT/GjO2c0Yl9OuQfPsIfncvLrEW6RbbB24WtZ3xP/2CCmI3tNkNV4oA==
+
 lightningcss-win32-x64-msvc@1.30.1:
   version "1.30.1"
   resolved "https://registry.npmjs.org/lightningcss-win32-x64-msvc/-/lightningcss-win32-x64-msvc-1.30.1.tgz"
   integrity sha512-PVqXh48wh4T53F/1CCu8PIPCxLzWyCnn/9T5W1Jpmdy5h9Cwd+0YQS6/LwhHXSafuc61/xg9Lv5OrCby6a++jg==
 
-lightningcss@^1.21.0, lightningcss@1.30.1:
+lightningcss@1.30.1:
   version "1.30.1"
   resolved "https://registry.npmjs.org/lightningcss/-/lightningcss-1.30.1.tgz"
   integrity sha512-xi6IyHML+c9+Q3W0S4fCQJOym42pyurFiJUHEcEyHS0CeKzia4yZDEsLlqOFykxOdHpNy0NmvVO31vcSqAxJCg==
@@ -1779,7 +2144,7 @@ picomatch@^2.3.1:
   resolved "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz"
   integrity sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==
 
-"picomatch@^3 || ^4", picomatch@^4.0.3:
+picomatch@^4.0.3:
   version "4.0.3"
   resolved "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz"
   integrity sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==
@@ -1808,7 +2173,7 @@ queue-microtask@^1.2.2:
   resolved "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz"
   integrity sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==
 
-"react-dom@^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc", "react-dom@^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", react-dom@^19.1.1, react-dom@>=16.8.0, react-dom@>=17:
+react-dom@^19.1.1:
   version "19.1.1"
   resolved "https://registry.npmjs.org/react-dom/-/react-dom-19.1.1.tgz"
   integrity sha512-Dlq/5LAZgF0Gaz6yiqZCf6VCcZs1ghAJyrsu84Q/GT0gV+mCxbfmKNoGRKBYMJ8IEdGPqu49YWXD02GCknEDkw==
@@ -1847,7 +2212,7 @@ react-style-singleton@^2.2.2, react-style-singleton@^2.2.3:
     get-nonce "^1.0.0"
     tslib "^2.0.0"
 
-"react@^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react@^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc", "react@^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", "react@^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react@^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc", react@^19.1.1, react@>=16.8, react@>=16.8.0, react@>=17, react@>=18.0.0:
+react@^19.1.1:
   version "19.1.1"
   resolved "https://registry.npmjs.org/react/-/react-19.1.1.tgz"
   integrity sha512-w8nqGImo45dmMIfljjMwOGtbmC/mk4CMYhWIicdSflH91J9TyCyczcPFXJzrZ/ZXcgGRFeP6BU0BEJTw6tZdfQ==
@@ -1947,7 +2312,7 @@ tailwind-merge@^3.3.1:
   resolved "https://registry.npmjs.org/tailwind-merge/-/tailwind-merge-3.3.1.tgz"
   integrity sha512-gBXpgUm/3rp1lMZZrM/w7D8GKqshif0zAymAhbCyIt8KMe+0v9DQ7cdYLR4FHH/cKpdTXb+A/tKKU3eolfsI+g==
 
-tailwindcss@^4.1.12, tailwindcss@4.1.12:
+tailwindcss@4.1.12, tailwindcss@^4.1.12:
   version "4.1.12"
   resolved "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.12.tgz"
   integrity sha512-DzFtxOi+7NsFf7DBtI3BJsynR+0Yp6etH+nRPTbpWnS2pZBaSksv/JGctNwSWzbFjp0vxSqknaUylseZqMDGrA==
@@ -1989,7 +2354,7 @@ ts-api-utils@^2.1.0:
   resolved "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-2.1.0.tgz"
   integrity sha512-CUgTZL1irw8u29bzrOD/nH85jqyc74D6SshFgujOIA7osm2Rz7dYH77agkx7H4FBNxDq7Cjf+IjaX/8zwFW+ZQ==
 
-tslib@^2.0.0, tslib@^2.1.0:
+tslib@^2.0.0, tslib@^2.1.0, tslib@^2.4.0, tslib@^2.8.0:
   version "2.8.1"
   resolved "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz"
   integrity sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==
@@ -2016,7 +2381,7 @@ typescript-eslint@^8.39.1:
     "@typescript-eslint/typescript-estree" "8.40.0"
     "@typescript-eslint/utils" "8.40.0"
 
-typescript@>=4.8.4, "typescript@>=4.8.4 <6.0.0", typescript@~5.8.3:
+typescript@~5.8.3:
   version "5.8.3"
   resolved "https://registry.npmjs.org/typescript/-/typescript-5.8.3.tgz"
   integrity sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ==
@@ -2056,12 +2421,12 @@ use-sidecar@^1.1.3:
     detect-node-es "^1.1.0"
     tslib "^2.0.0"
 
-use-sync-external-store@^1.2.2, use-sync-external-store@>=1.2.0:
+use-sync-external-store@^1.2.2:
   version "1.5.0"
   resolved "https://registry.npmjs.org/use-sync-external-store/-/use-sync-external-store-1.5.0.tgz"
   integrity sha512-Rb46I4cGGVBmjamjphe8L/UnvJD+uPPtTkNvX5mZgqdbavhI4EbgIWJiIHXJ8bc/i9EQGPRh4DwEURJ552Do0A==
 
-"vite@^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0", "vite@^5.2.0 || ^6 || ^7", vite@^7.1.11:
+vite@^7.1.11:
   version "7.1.12"
   resolved "https://registry.npmjs.org/vite/-/vite-7.1.12.tgz"
   integrity sha512-ZWyE8YXEXqJrrSLvYgrRP7p62OziLW7xI5HYGWFzOvupfAlrLvURSzv/FyGyy0eidogEM3ujU+kUG1zuHgb6Ug==

python/packages/devui/tests/test_checkpoints.py

@@ -37,10 +37,14 @@ class WorkflowHILRequest:
 class WorkflowTestExecutor(Executor):
     """Test executor with HIL."""
 
+    def __init__(self, id: str) -> None:
+        super().__init__(id=id)
+        self._data_value: str | None = None
+
     @handler
     async def process(self, data: WorkflowTestData, ctx: WorkflowContext) -> None:
         """Process data and request approval."""
-        await ctx.set_executor_state({"data_value": data.value})
+        self._data_value = data.value
 
         # Request HIL (checkpoint created here)
         await ctx.request_info(request_data=WorkflowHILRequest(question=f"Approve {data.value}?"), response_type=str)
@@ -50,8 +54,7 @@ class WorkflowTestExecutor(Executor):
         self, original_request: WorkflowHILRequest, response: str, ctx: WorkflowContext[str]
     ) -> None:
         """Handle HIL response."""
-        state = await ctx.get_executor_state() or {}
-        value = state.get("data_value", "")
+        value = self._data_value or ""
         await ctx.send_message(f"{value}_approved" if response.lower() == "yes" else f"{value}_rejected")
 
 

python/samples/README.md

@@ -17,11 +17,11 @@ This directory contains samples demonstrating the capabilities of Microsoft Agen
 | [`getting_started/agents/anthropic/anthropic_basic.py`](./getting_started/agents/anthropic/anthropic_basic.py) | Agent with Anthropic Client |
 | [`getting_started/agents/anthropic/anthropic_advanced.py`](./getting_started/agents/anthropic/anthropic_advanced.py) | Advanced sample with `thinking` and hosted tools. |
 
-### Azure AI
+### Azure AI (based on `azure-ai-agents` V1 package)
 
 | File | Description |
 |------|-------------|
-| [`getting_started/agents/azure_ai_agent/azure_ai_basic.py`](./getting_started/agents/azure_ai/azure_ai_basic.py) | Azure AI Agent Basic Example |
+| [`getting_started/agents/azure_ai_agent/azure_ai_basic.py`](./getting_started/agents/azure_ai_agent/azure_ai_basic.py) | Azure AI Agent Basic Example |
 | [`getting_started/agents/azure_ai_agent/azure_ai_with_azure_ai_search.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_azure_ai_search.py) | Azure AI Agent with Azure AI Search Example |
 | [`getting_started/agents/azure_ai_agent/azure_ai_with_bing_grounding.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_bing_grounding.py) | Azure AI agent with Bing Grounding search for real-time web information |
 | [`getting_started/agents/azure_ai_agent/azure_ai_with_code_interpreter.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_code_interpreter.py) | Azure AI Agent with Code Interpreter Example |
@@ -36,6 +36,28 @@ This directory contains samples demonstrating the capabilities of Microsoft Agen
 | [`getting_started/agents/azure_ai_agent/azure_ai_with_openapi_tools.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_openapi_tools.py) | Azure AI agent with OpenAPI tools |
 | [`getting_started/agents/azure_ai_agent/azure_ai_with_thread.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_thread.py) | Azure AI Agent with Thread Management Example |
 
+### Azure AI (based on `azure-ai-projects` V2 package)
+
+| File | Description |
+|------|-------------|
+| [`getting_started/agents/azure_ai/azure_ai_basic.py`](./getting_started/agents/azure_ai/azure_ai_basic.py) | Azure AI Agent Basic Example |
+| [`getting_started/agents/azure_ai/azure_ai_use_latest_version.py`](./getting_started/agents/azure_ai/azure_ai_use_latest_version.py) | Azure AI Agent latest version reuse example |
+| [`getting_started/agents/azure_ai/azure_ai_with_azure_ai_search.py`](./getting_started/agents/azure_ai/azure_ai_with_azure_ai_search.py) | Azure AI Agent with Azure AI Search Example |
+| [`getting_started/agents/azure_ai/azure_ai_with_bing_grounding.py`](./getting_started/agents/azure_ai/azure_ai_with_bing_grounding.py) | Azure AI Agent with Bing Grounding Example |
+| [`getting_started/agents/azure_ai/azure_ai_with_bing_custom_search.py`](./getting_started/agents/azure_ai/azure_ai_with_bing_custom_search.py) | Azure AI Agent with Bing Custom Search Example |
+| [`getting_started/agents/azure_ai/azure_ai_with_browser_automation.py`](./getting_started/agents/azure_ai/azure_ai_with_browser_automation.py) | Azure AI Agent with Browser Automation Example |
+| [`getting_started/agents/azure_ai/azure_ai_with_code_interpreter.py`](./getting_started/agents/azure_ai/azure_ai_with_code_interpreter.py) | Azure AI Agent with Code Interpreter Example |
+| [`getting_started/agents/azure_ai/azure_ai_with_existing_agent.py`](./getting_started/agents/azure_ai/azure_ai_with_existing_agent.py) | Azure AI Agent with Existing Agent Example |
+| [`getting_started/agents/azure_ai/azure_ai_with_existing_conversation.py`](./getting_started/agents/azure_ai/azure_ai_with_existing_conversation.py) | Azure AI Agent with Existing Conversation Example |
+| [`getting_started/agents/azure_ai/azure_ai_with_explicit_settings.py`](./getting_started/agents/azure_ai/azure_ai_with_explicit_settings.py) | Azure AI Agent with Explicit Settings Example |
+| [`getting_started/agents/azure_ai/azure_ai_with_file_search.py`](./getting_started/agents/azure_ai/azure_ai_with_file_search.py) | Azure AI Agent with File Search Example |
+| [`getting_started/agents/azure_ai/azure_ai_with_hosted_mcp.py`](./getting_started/agents/azure_ai/azure_ai_with_hosted_mcp.py) | Azure AI Agent with Hosted MCP Example |
+| [`getting_started/agents/azure_ai/azure_ai_with_response_format.py`](./getting_started/agents/azure_ai/azure_ai_with_response_format.py) | Azure AI Agent with Structured Output Example |
+| [`getting_started/agents/azure_ai/azure_ai_with_thread.py`](./getting_started/agents/azure_ai/azure_ai_with_thread.py) | Azure AI Agent with Thread Management Example |
+| [`getting_started/agents/azure_ai/azure_ai_with_image_generation.py`](./getting_started/agents/azure_ai/azure_ai_with_image_generation.py) | Azure AI Agent with Image Generation Example |
+| [`getting_started/agents/azure_ai/azure_ai_with_microsoft_fabric.py`](./getting_started/agents/azure_ai/azure_ai_with_microsoft_fabric.py) | Azure AI Agent with Microsoft Fabric Example |
+| [`getting_started/agents/azure_ai/azure_ai_with_web_search.py`](./getting_started/agents/azure_ai/azure_ai_with_web_search.py) | Azure AI Agent with Web Search Example |
+
 ### Azure OpenAI
 
 | File | Description |

python/samples/getting_started/agents/README.md

@@ -8,7 +8,8 @@ This folder contains examples demonstrating how to create and use agents with di
 
 | Folder | Description |
 |--------|-------------|
-| **[`azure_ai/`](azure_ai/)** | Create agents using Azure AI Foundry Agent Service with various tools including function tools, code interpreter, MCP integration, and thread management |
+| **[`azure_ai_agent/`](azure_ai_agent/)** | Create agents using Azure AI Agent Service (based on `azure-ai-agents` V1 package) including function tools, code interpreter, MCP integration, thread management, and more. |
+| **[`azure_ai/`](azure_ai/)** | Create agents using Azure AI Agent Service (based on `azure-ai-projects` [V2](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/CHANGELOG.md#200b1-2025-11-11) package) including function tools, code interpreter, MCP integration, thread management, and more. |
 
 ### Microsoft Copilot Studio Examples
 

python/samples/getting_started/agents/anthropic/README.md

@@ -9,10 +9,16 @@ This folder contains examples demonstrating how to use Anthropic's Claude models
 | [`anthropic_basic.py`](anthropic_basic.py) | Demonstrates how to setup a simple agent using the AnthropicClient, with both streaming and non-streaming responses. |
 | [`anthropic_advanced.py`](anthropic_advanced.py) | Shows advanced usage of the AnthropicClient, including hosted tools and `thinking`. |
 | [`anthropic_skills.py`](anthropic_skills.py) | Illustrates how to use Anthropic-managed Skills with an agent, including the Code Interpreter tool and file generation and saving. |
+| [`anthropic_foundry.py`](anthropic_foundry.py) | Example of using Foundry's Anthropic integration with the Agent Framework. |
 
 ## Environment Variables
 
 Set the following environment variables before running the examples:
 
 - `ANTHROPIC_API_KEY`: Your Anthropic API key (get one from [Anthropic Console](https://console.anthropic.com/))
-- `ANTHROPIC_MODEL`: The Claude model to use (e.g., `claude-haiku-4-5`, `claude-sonnet-4-5-20250929`)
+- `ANTHROPIC_CHAT_MODEL_ID`: The Claude model to use (e.g., `claude-haiku-4-5`, `claude-sonnet-4-5-20250929`)
+
+Or, for Foundry:
+- `ANTHROPIC_FOUNDRY_API_KEY`: Your Foundry Anthropic API key
+- `ANTHROPIC_FOUNDRY_ENDPOINT`: The endpoint URL for your Foundry Anthropic resource
+- `ANTHROPIC_CHAT_MODEL_ID`: The Claude model to use in Foundry (e.g., `claude-haiku-4-5`)

python/samples/getting_started/agents/anthropic/anthropic_foundry.py

@@ -0,0 +1,63 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import HostedMCPTool, HostedWebSearchTool, TextReasoningContent, UsageContent
+from agent_framework.anthropic import AnthropicClient
+from anthropic import AsyncAnthropicFoundry
+
+"""
+Anthropic Foundry Chat Agent Example
+
+This sample demonstrates using Anthropic with:
+- Setting up an Anthropic-based agent with hosted tools.
+- Using the `thinking` feature.
+- Displaying both thinking and usage information during streaming responses.
+
+This example requires `anthropic>=0.74.0` and an endpoint in Foundry for Anthropic.
+
+To use the Foundry integration ensure you have the following environment variables set:
+- ANTHROPIC_FOUNDRY_API_KEY
+    Alternatively you can pass in a azure_ad_token_provider function to the AsyncAnthropicFoundry constructor.
+- ANTHROPIC_FOUNDRY_ENDPOINT
+    Should be something like https://<your-resource-name>.services.ai.azure.com/anthropic/
+- ANTHROPIC_CHAT_MODEL_ID
+    Should be something like claude-haiku-4-5
+"""
+
+
+async def main() -> None:
+    """Example of streaming response (get results as they are generated)."""
+    agent = AnthropicClient(anthropic_client=AsyncAnthropicFoundry()).create_agent(
+        name="DocsAgent",
+        instructions="You are a helpful agent for both Microsoft docs questions and general questions.",
+        tools=[
+            HostedMCPTool(
+                name="Microsoft Learn MCP",
+                url="https://learn.microsoft.com/api/mcp",
+            ),
+            HostedWebSearchTool(),
+        ],
+        # anthropic needs a value for the max_tokens parameter
+        # we set it to 1024, but you can override like this:
+        max_tokens=20000,
+        additional_chat_options={"thinking": {"type": "enabled", "budget_tokens": 10000}},
+    )
+
+    query = "Can you compare Python decorators with C# attributes?"
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run_stream(query):
+        for content in chunk.contents:
+            if isinstance(content, TextReasoningContent):
+                print(f"\033[32m{content.text}\033[0m", end="", flush=True)
+            if isinstance(content, UsageContent):
+                print(f"\n\033[34m[Usage so far: {content.details}]\033[0m\n", end="", flush=True)
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+
+    print("\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_ai/README.md

@@ -1,6 +1,6 @@
 # Azure AI Agent Examples
 
-This folder contains examples demonstrating different ways to create and use agents with the Azure AI client from the `agent_framework.azure` package.
+This folder contains examples demonstrating different ways to create and use agents with the Azure AI client from the `agent_framework.azure` package. These examples use the `AzureAIClient` with the `azure-ai-projects` 2.x (V2) API surface (see [changelog](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/CHANGELOG.md#200b1-2025-11-11)). For V1 (`azure-ai-agents` 1.x) samples using `AzureAIAgentClient`, see the [Azure AI V1 examples folder](../azure_ai_agent/).
 
 ## Examples
 
@@ -8,6 +8,7 @@ This folder contains examples demonstrating different ways to create and use age
 |------|-------------|
 | [`azure_ai_basic.py`](azure_ai_basic.py) | The simplest way to create an agent using `AzureAIClient`. Demonstrates both streaming and non-streaming responses with function tools. Shows automatic agent creation and basic weather functionality. |
 | [`azure_ai_use_latest_version.py`](azure_ai_use_latest_version.py) | Demonstrates how to reuse the latest version of an existing agent instead of creating a new agent version on each instantiation using the `use_latest_version=True` parameter. |
+| [`azure_ai_with_agent_to_agent.py`](azure_ai_with_agent_to_agent.py) | Shows how to use Agent-to-Agent (A2A) capabilities with Azure AI agents to enable communication with other agents using the A2A protocol. Requires an A2A connection configured in your Azure AI project. |
 | [`azure_ai_with_azure_ai_search.py`](azure_ai_with_azure_ai_search.py) | Shows how to use Azure AI Search with Azure AI agents to search through indexed data and answer user questions with proper citations. Requires an Azure AI Search connection and index configured in your Azure AI project. |
 | [`azure_ai_with_bing_grounding.py`](azure_ai_with_bing_grounding.py) | Shows how to use Bing Grounding search with Azure AI agents to search the web for current information and provide grounded responses with citations. Requires a Bing connection configured in your Azure AI project. |
 | [`azure_ai_with_bing_custom_search.py`](azure_ai_with_bing_custom_search.py) | Shows how to use Bing Custom Search with Azure AI agents to search custom search instances and provide responses with relevant results. Requires a Bing Custom Search connection and instance configured in your Azure AI project. |
@@ -19,6 +20,7 @@ This folder contains examples demonstrating different ways to create and use age
 | [`azure_ai_with_file_search.py`](azure_ai_with_file_search.py) | Shows how to use the `HostedFileSearchTool` with Azure AI agents to upload files, create vector stores, and enable agents to search through uploaded documents to answer user questions. |
 | [`azure_ai_with_hosted_mcp.py`](azure_ai_with_hosted_mcp.py) | Shows how to integrate hosted Model Context Protocol (MCP) tools with Azure AI Agent. |
 | [`azure_ai_with_response_format.py`](azure_ai_with_response_format.py) | Shows how to use structured outputs (response format) with Azure AI agents using Pydantic models to enforce specific response schemas. |
+| [`azure_ai_with_sharepoint.py`](azure_ai_with_sharepoint.py) | Shows how to use SharePoint grounding with Azure AI agents to search through SharePoint content and answer user questions with proper citations. Requires a SharePoint connection configured in your Azure AI project. |
 | [`azure_ai_with_thread.py`](azure_ai_with_thread.py) | Demonstrates thread management with Azure AI agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. |
 | [`azure_ai_with_image_generation.py`](azure_ai_with_image_generation.py) | Shows how to use the `ImageGenTool` with Azure AI agents to generate images based on text prompts. |
 | [`azure_ai_with_microsoft_fabric.py`](azure_ai_with_microsoft_fabric.py) | Shows how to use Microsoft Fabric with Azure AI agents to query Fabric data sources and provide responses based on data analysis. Requires a Microsoft Fabric connection configured in your Azure AI project. |

python/samples/getting_started/agents/azure_ai/azure_ai_with_agent_to_agent.py

@@ -0,0 +1,42 @@
+# Copyright (c) Microsoft. All rights reserved.
+import asyncio
+import os
+
+from agent_framework.azure import AzureAIClient
+from azure.identity.aio import AzureCliCredential
+
+"""
+Azure AI Agent with Agent-to-Agent (A2A) Example
+
+This sample demonstrates usage of AzureAIClient with Agent-to-Agent (A2A) capabilities
+to enable communication with other agents using the A2A protocol.
+
+Prerequisites:
+1. Set AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME environment variables.
+2. Ensure you have an A2A connection configured in your Azure AI project
+    and set A2A_PROJECT_CONNECTION_ID environment variable.
+"""
+
+
+async def main() -> None:
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIClient(async_credential=credential).create_agent(
+            name="MyA2AAgent",
+            instructions="""You are a helpful assistant that can communicate with other agents.
+            Use the A2A tool when you need to interact with other agents to complete tasks
+            or gather information from specialized agents.""",
+            tools={
+                "type": "a2a_preview",
+                "project_connection_id": os.environ["A2A_PROJECT_CONNECTION_ID"],
+            },
+        ) as agent,
+    ):
+        query = "What can the secondary agent do?"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Result: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())