Merge branch 'main' into gok/feat/nvidia

Author: markwallace-microsoft

dotnet/samples/A2AClientServer/A2AServer/Program.cs

@@ -104,7 +104,10 @@ You specialize in handling queries related to logistics.
     throw new ArgumentException("Either A2AServer:ApiKey or A2AServer:ConnectionString & agentId must be provided");
 }
 
-var a2aTaskManager = app.MapA2A(hostA2AAgent, path: "/", agentCard: hostA2AAgentCard);
-app.MapWellKnownAgentCard(a2aTaskManager, "/");
+var a2aTaskManager = app.MapA2A(
+    hostA2AAgent,
+    path: "/",
+    agentCard: hostA2AAgentCard,
+    taskManager => app.MapWellKnownAgentCard(taskManager, "/"));
 
 await app.RunAsync();

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

@@ -24,7 +24,8 @@
     "pirate",
     instructions: "You are a pirate. Speak like a pirate",
     description: "An agent that speaks like a pirate.",
-    chatClientServiceKey: "chat-model");
+    chatClientServiceKey: "chat-model")
+    .WithInMemoryThreadStore();
 
 builder.AddAIAgent("knights-and-knaves", (sp, key) =>
 {

dotnet/src/Microsoft.Agents.AI.Hosting.A2A.AspNetCore/EndpointRouteBuilderExtensions.cs

@@ -1,8 +1,10 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System;
 using A2A;
 using A2A.AspNetCore;
 using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hosting;
 using Microsoft.Agents.AI.Hosting.A2A;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Routing;
@@ -23,10 +25,21 @@ public static class MicrosoftAgentAIHostingA2AEndpointRouteBuilderExtensions
     /// <param name="agentName">The name of the agent to use for A2A protocol integration.</param>
     /// <param name="path">The route group to use for A2A endpoints.</param>
     /// <returns>Configured <see cref="ITaskManager"/> for A2A integration.</returns>
-    public static ITaskManager MapA2A(this IEndpointRouteBuilder endpoints, string agentName, string path)
+    public static IEndpointConventionBuilder MapA2A(this IEndpointRouteBuilder endpoints, string agentName, string path)
+        => endpoints.MapA2A(agentName, path, _ => { });
+
+    /// <summary>
+    /// Attaches A2A (Agent2Agent) communication capabilities via Message processing to the specified web application.
+    /// </summary>
+    /// <param name="endpoints">The <see cref="IEndpointRouteBuilder"/> to add the A2A endpoints to.</param>
+    /// <param name="agentName">The name of the agent to use for A2A protocol integration.</param>
+    /// <param name="path">The route group to use for A2A endpoints.</param>
+    /// <param name="configureTaskManager">The callback to configure <see cref="ITaskManager"/>.</param>
+    /// <returns>Configured <see cref="ITaskManager"/> for A2A integration.</returns>
+    public static IEndpointConventionBuilder MapA2A(this IEndpointRouteBuilder endpoints, string agentName, string path, Action<ITaskManager> configureTaskManager)
     {
         var agent = endpoints.ServiceProvider.GetRequiredKeyedService<AIAgent>(agentName);
-        return endpoints.MapA2A(agent, path);
+        return endpoints.MapA2A(agent, path, configureTaskManager);
     }
 
     /// <summary>
@@ -42,10 +55,27 @@ public static ITaskManager MapA2A(this IEndpointRouteBuilder endpoints, string a
     /// <see href="https://github.com/a2aproject/A2A/blob/main/docs/topics/agent-discovery.md#2-curated-registries-catalog-based-discovery">Curated Registries (Catalog-Based Discovery)</see>
     /// discovery mechanism.
     /// </remarks>
-    public static ITaskManager MapA2A(this IEndpointRouteBuilder endpoints, string agentName, string path, AgentCard agentCard)
+    public static IEndpointConventionBuilder MapA2A(this IEndpointRouteBuilder endpoints, string agentName, string path, AgentCard agentCard)
+        => endpoints.MapA2A(agentName, path, agentCard, _ => { });
+
+    /// <summary>
+    /// Attaches A2A (Agent2Agent) communication capabilities via Message processing to the specified web application.
+    /// </summary>
+    /// <param name="endpoints">The <see cref="IEndpointRouteBuilder"/> to add the A2A endpoints to.</param>
+    /// <param name="agentName">The name of the agent to use for A2A protocol integration.</param>
+    /// <param name="path">The route group to use for A2A endpoints.</param>
+    /// <param name="agentCard">Agent card info to return on query.</param>
+    /// <param name="configureTaskManager">The callback to configure <see cref="ITaskManager"/>.</param>
+    /// <returns>Configured <see cref="ITaskManager"/> for A2A integration.</returns>
+    /// <remarks>
+    /// This method can be used to access A2A agents that support the
+    /// <see href="https://github.com/a2aproject/A2A/blob/main/docs/topics/agent-discovery.md#2-curated-registries-catalog-based-discovery">Curated Registries (Catalog-Based Discovery)</see>
+    /// discovery mechanism.
+    /// </remarks>
+    public static IEndpointConventionBuilder MapA2A(this IEndpointRouteBuilder endpoints, string agentName, string path, AgentCard agentCard, Action<ITaskManager> configureTaskManager)
     {
         var agent = endpoints.ServiceProvider.GetRequiredKeyedService<AIAgent>(agentName);
-        return endpoints.MapA2A(agent, path, agentCard);
+        return endpoints.MapA2A(agent, path, agentCard, configureTaskManager);
     }
 
     /// <summary>
@@ -55,11 +85,26 @@ public static ITaskManager MapA2A(this IEndpointRouteBuilder endpoints, string a
     /// <param name="agent">The agent to use for A2A protocol integration.</param>
     /// <param name="path">The route group to use for A2A endpoints.</param>
     /// <returns>Configured <see cref="ITaskManager"/> for A2A integration.</returns>
-    public static ITaskManager MapA2A(this IEndpointRouteBuilder endpoints, AIAgent agent, string path)
+    public static IEndpointConventionBuilder MapA2A(this IEndpointRouteBuilder endpoints, AIAgent agent, string path)
+        => endpoints.MapA2A(agent, path, _ => { });
+
+    /// <summary>
+    /// Attaches A2A (Agent2Agent) communication capabilities via Message processing to the specified web application.
+    /// </summary>
+    /// <param name="endpoints">The <see cref="IEndpointRouteBuilder"/> to add the A2A endpoints to.</param>
+    /// <param name="agent">The agent to use for A2A protocol integration.</param>
+    /// <param name="path">The route group to use for A2A endpoints.</param>
+    /// <param name="configureTaskManager">The callback to configure <see cref="ITaskManager"/>.</param>
+    /// <returns>Configured <see cref="ITaskManager"/> for A2A integration.</returns>
+    public static IEndpointConventionBuilder MapA2A(this IEndpointRouteBuilder endpoints, AIAgent agent, string path, Action<ITaskManager> configureTaskManager)
     {
         var loggerFactory = endpoints.ServiceProvider.GetRequiredService<ILoggerFactory>();
-        var taskManager = agent.MapA2A(loggerFactory: loggerFactory);
-        return endpoints.MapA2A(taskManager, path);
+        var agentThreadStore = endpoints.ServiceProvider.GetKeyedService<AgentThreadStore>(agent.Name);
+        var taskManager = agent.MapA2A(loggerFactory: loggerFactory, agentThreadStore: agentThreadStore);
+        var endpointConventionBuilder = endpoints.MapA2A(taskManager, path);
+
+        configureTaskManager(taskManager);
+        return endpointConventionBuilder;
     }
 
     /// <summary>
@@ -75,11 +120,33 @@ public static ITaskManager MapA2A(this IEndpointRouteBuilder endpoints, AIAgent
     /// <see href="https://github.com/a2aproject/A2A/blob/main/docs/topics/agent-discovery.md#2-curated-registries-catalog-based-discovery">Curated Registries (Catalog-Based Discovery)</see>
     /// discovery mechanism.
     /// </remarks>
-    public static ITaskManager MapA2A(this IEndpointRouteBuilder endpoints, AIAgent agent, string path, AgentCard agentCard)
+    public static IEndpointConventionBuilder MapA2A(this IEndpointRouteBuilder endpoints, AIAgent agent, string path, AgentCard agentCard)
+        => endpoints.MapA2A(agent, path, agentCard, _ => { });
+
+    /// <summary>
+    /// Attaches A2A (Agent2Agent) communication capabilities via Message processing to the specified web application.
+    /// </summary>
+    /// <param name="endpoints">The <see cref="IEndpointRouteBuilder"/> to add the A2A endpoints to.</param>
+    /// <param name="agent">The agent to use for A2A protocol integration.</param>
+    /// <param name="path">The route group to use for A2A endpoints.</param>
+    /// <param name="agentCard">Agent card info to return on query.</param>
+    /// <param name="configureTaskManager">The callback to configure <see cref="ITaskManager"/>.</param>
+    /// <returns>Configured <see cref="ITaskManager"/> for A2A integration.</returns>
+    /// <remarks>
+    /// This method can be used to access A2A agents that support the
+    /// <see href="https://github.com/a2aproject/A2A/blob/main/docs/topics/agent-discovery.md#2-curated-registries-catalog-based-discovery">Curated Registries (Catalog-Based Discovery)</see>
+    /// discovery mechanism.
+    /// </remarks>
+    public static IEndpointConventionBuilder MapA2A(this IEndpointRouteBuilder endpoints, AIAgent agent, string path, AgentCard agentCard, Action<ITaskManager> configureTaskManager)
     {
         var loggerFactory = endpoints.ServiceProvider.GetRequiredService<ILoggerFactory>();
-        var taskManager = agent.MapA2A(agentCard: agentCard, loggerFactory: loggerFactory);
-        return endpoints.MapA2A(taskManager, path);
+        var agentThreadStore = endpoints.ServiceProvider.GetKeyedService<AgentThreadStore>(agent.Name);
+        var taskManager = agent.MapA2A(agentCard: agentCard, agentThreadStore: agentThreadStore, loggerFactory: loggerFactory);
+        var endpointConventionBuilder = endpoints.MapA2A(taskManager, path);
+
+        configureTaskManager(taskManager);
+
+        return endpointConventionBuilder;
     }
 
     /// <summary>
@@ -90,14 +157,12 @@ public static ITaskManager MapA2A(this IEndpointRouteBuilder endpoints, AIAgent
     /// <param name="taskManager">Pre-configured A2A TaskManager to use for A2A endpoints handling.</param>
     /// <param name="path">The route group to use for A2A endpoints.</param>
     /// <returns>Configured <see cref="ITaskManager"/> for A2A integration.</returns>
-    public static ITaskManager MapA2A(this IEndpointRouteBuilder endpoints, TaskManager taskManager, string path)
+    public static IEndpointConventionBuilder MapA2A(this IEndpointRouteBuilder endpoints, ITaskManager taskManager, string path)
     {
         // note: current SDK version registers multiple `.well-known/agent.json` handlers here.
         // it makes app return HTTP 500, but will be fixed once new A2A SDK is released.
         // see https://github.com/microsoft/agent-framework/issues/476 for details
         A2ARouteBuilderExtensions.MapA2A(endpoints, taskManager, path);
-        endpoints.MapHttpA2A(taskManager, path);
-
-        return taskManager;
+        return endpoints.MapHttpA2A(taskManager, path);
     }
 }

dotnet/src/Microsoft.Agents.AI.Hosting.A2A/AIAgentExtensions.cs

@@ -20,29 +20,37 @@ public static class AIAgentExtensions
     /// <param name="agent">Agent to attach A2A messaging processing capabilities to.</param>
     /// <param name="taskManager">Instance of <see cref="TaskManager"/> to configure for A2A messaging. New instance will be created if not passed.</param>
     /// <param name="loggerFactory">The logger factory to use for creating <see cref="ILogger"/> instances.</param>
+    /// <param name="agentThreadStore">The store to store thread contents and metadata.</param>
     /// <returns>The configured <see cref="TaskManager"/>.</returns>
-    public static TaskManager MapA2A(
+    public static ITaskManager MapA2A(
         this AIAgent agent,
-        TaskManager? taskManager = null,
-        ILoggerFactory? loggerFactory = null)
+        ITaskManager? taskManager = null,
+        ILoggerFactory? loggerFactory = null,
+        AgentThreadStore? agentThreadStore = null)
     {
         ArgumentNullException.ThrowIfNull(agent);
         ArgumentNullException.ThrowIfNull(agent.Name);
 
-        taskManager ??= new();
+        var hostAgent = new AIHostAgent(
+            innerAgent: agent,
+            threadStore: agentThreadStore ?? new NoopAgentThreadStore());
 
+        taskManager ??= new TaskManager();
         taskManager.OnMessageReceived += OnMessageReceivedAsync;
-
         return taskManager;
 
         async Task<A2AResponse> OnMessageReceivedAsync(MessageSendParams messageSendParams, CancellationToken cancellationToken)
         {
-            var response = await agent.RunAsync(
+            var contextId = messageSendParams.Message.ContextId ?? Guid.NewGuid().ToString("N");
+            var thread = await hostAgent.GetOrCreateThreadAsync(contextId, cancellationToken).ConfigureAwait(false);
+
+            var response = await hostAgent.RunAsync(
                 messageSendParams.ToChatMessages(),
+                thread: thread,
                 cancellationToken: cancellationToken).ConfigureAwait(false);
-            var contextId = messageSendParams.Message.ContextId ?? Guid.NewGuid().ToString("N");
-            var parts = response.Messages.ToParts();
 
+            await hostAgent.SaveThreadAsync(contextId, thread, cancellationToken).ConfigureAwait(false);
+            var parts = response.Messages.ToParts();
             return new AgentMessage
             {
                 MessageId = response.ResponseId ?? Guid.NewGuid().ToString("N"),
@@ -60,14 +68,16 @@ async Task<A2AResponse> OnMessageReceivedAsync(MessageSendParams messageSendPara
     /// <param name="agentCard">The agent card to return on query.</param>
     /// <param name="taskManager">Instance of <see cref="TaskManager"/> to configure for A2A messaging. New instance will be created if not passed.</param>
     /// <param name="loggerFactory">The logger factory to use for creating <see cref="ILogger"/> instances.</param>
+    /// <param name="agentThreadStore">The store to store thread contents and metadata.</param>
     /// <returns>The configured <see cref="TaskManager"/>.</returns>
-    public static TaskManager MapA2A(
+    public static ITaskManager MapA2A(
         this AIAgent agent,
         AgentCard agentCard,
-        TaskManager? taskManager = null,
-        ILoggerFactory? loggerFactory = null)
+        ITaskManager? taskManager = null,
+        ILoggerFactory? loggerFactory = null,
+        AgentThreadStore? agentThreadStore = null)
     {
-        taskManager = agent.MapA2A(taskManager, loggerFactory);
+        taskManager = agent.MapA2A(taskManager, loggerFactory, agentThreadStore);
 
         taskManager.OnAgentCardQuery += (context, query) =>
         {

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

@@ -0,0 +1,73 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI.Hosting;
+
+/// <summary>
+/// Provides a hosting wrapper around an <see cref="AIAgent"/> that adds thread persistence capabilities
+/// for server-hosted scenarios where conversations need to be restored across requests.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <see cref="AIHostAgent"/> wraps an existing agent implementation and adds the ability to
+/// persist and restore conversation threads using an <see cref="AgentThreadStore"/>.
+/// </para>
+/// <para>
+/// This wrapper enables thread persistence without requiring type-specific knowledge of the thread type,
+/// as all thread operations work through the base <see cref="AgentThread"/> abstraction.
+/// </para>
+/// </remarks>
+public class AIHostAgent : DelegatingAIAgent
+{
+    private readonly AgentThreadStore _threadStore;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AIHostAgent"/> class.
+    /// </summary>
+    /// <param name="innerAgent">The underlying agent implementation to wrap.</param>
+    /// <param name="threadStore">The thread store to use for persisting conversation state.</param>
+    /// <exception cref="ArgumentNullException">
+    /// <paramref name="innerAgent"/> or <paramref name="threadStore"/> is <see langword="null"/>.
+    /// </exception>
+    public AIHostAgent(AIAgent innerAgent, AgentThreadStore threadStore)
+        : base(innerAgent)
+    {
+        this._threadStore = Throw.IfNull(threadStore);
+    }
+
+    /// <summary>
+    /// Gets an existing agent thread for the specified conversation, or creates a new one if none exists.
+    /// </summary>
+    /// <param name="conversationId">The unique identifier of the conversation for which to retrieve or create the agent thread. Cannot be null,
+    /// empty, or consist only of white-space characters.</param>
+    /// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the agent thread associated with the
+    /// specified conversation. If no thread exists, a new thread is created and returned.</returns>
+    public ValueTask<AgentThread> GetOrCreateThreadAsync(string conversationId, CancellationToken cancellationToken = default)
+    {
+        _ = Throw.IfNullOrWhitespace(conversationId);
+
+        return this._threadStore.GetThreadAsync(this.InnerAgent, conversationId, cancellationToken);
+    }
+
+    /// <summary>
+    /// Persists a conversation thread to the thread store.
+    /// </summary>
+    /// <param name="conversationId">The unique identifier for the conversation.</param>
+    /// <param name="thread">The thread to persist.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.</param>
+    /// <returns>A task that represents the asynchronous save operation.</returns>
+    /// <exception cref="ArgumentException"><paramref name="conversationId"/> is null or whitespace.</exception>
+    /// <exception cref="ArgumentNullException"><paramref name="thread"/> is <see langword="null"/>.</exception>
+    public ValueTask SaveThreadAsync(string conversationId, AgentThread thread, CancellationToken cancellationToken = default)
+    {
+        _ = Throw.IfNullOrWhitespace(conversationId);
+        _ = Throw.IfNull(thread);
+
+        return this._threadStore.SaveThreadAsync(this.InnerAgent, conversationId, thread, cancellationToken);
+    }
+}