chore: import upstream snapshot with attribution

dotnet/samples/Demos/AgentFrameworkWithAspire/ChatWithAgent.ApiService/ChatWithAgent.ApiService.csproj

@@ -0,0 +1,32 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <NoWarn>$(NoWarn);SKEXP0010;SKEXP0001</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <EmbeddedResource Include="Resources\AgentDefinition.yaml" />
+    <EmbeddedResource Include="Resources\AgentWithRagDefinition.yaml" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Aspire.Azure.AI.OpenAI" />
+    <PackageReference Include="Aspire.Azure.Search.Documents" />
+    <PackageReference Include="Microsoft.SemanticKernel.Connectors.AzureAISearch" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Agents\Core\Agents.Core.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Connectors\Connectors.AzureOpenAI\Connectors.AzureOpenAI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Connectors\Connectors.OpenAI\Connectors.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Extensions\PromptTemplates.Handlebars\PromptTemplates.Handlebars.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Functions\Functions.Yaml\Functions.Yaml.csproj" />
+    <ProjectReference Include="..\..\..\..\src\SemanticKernel.Abstractions\SemanticKernel.Abstractions.csproj" />
+    <ProjectReference Include="..\..\..\..\src\SemanticKernel.Core\SemanticKernel.Core.csproj" />
+    <ProjectReference Include="..\ChatWithAgent.ServiceDefaults\ChatWithAgent.ServiceDefaults.csproj" />
+    <ProjectReference Include="..\ChatWithAgent.Configuration\ChatWithAgent.Configuration.csproj" IsAspireProjectResource="false" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/Demos/AgentFrameworkWithAspire/ChatWithAgent.ApiService/Config/ServiceConfig.cs

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using ChatWithAgent.Configuration;
+using Microsoft.Extensions.Configuration;
+
+namespace ChatWithAgent.ApiService.Config;
+
+/// <summary>
+/// Service configuration.
+/// </summary>
+public sealed class ServiceConfig
+{
+    private readonly HostConfig _hostConfig;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ServiceConfig"/> class.
+    /// </summary>
+    /// <param name="configurationManager">The configuration manager.</param>
+    public ServiceConfig(ConfigurationManager configurationManager)
+    {
+        this._hostConfig = new HostConfig(configurationManager);
+    }
+
+    /// <summary>
+    /// Host configuration.
+    /// </summary>
+    public HostConfig Host => this._hostConfig;
+}

dotnet/samples/Demos/AgentFrameworkWithAspire/ChatWithAgent.ApiService/Controllers/AgentCompletionRequest.cs

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.SemanticKernel.ChatCompletion;
+
+namespace ChatWithAgent.ApiService;
+
+/// <summary>
+/// The agent completion request model.
+/// </summary>
+public sealed class AgentCompletionRequest
+{
+    /// <summary>
+    /// Gets or sets the prompt.
+    /// </summary>
+    public required string Prompt { get; set; }
+
+    /// <summary>
+    /// Gets or sets the chat history.
+    /// </summary>
+    public required ChatHistory ChatHistory { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether streaming is requested.
+    /// </summary>
+    public bool IsStreaming { get; set; }
+}

dotnet/samples/Demos/AgentFrameworkWithAspire/ChatWithAgent.ApiService/Controllers/AgentCompletionsController.cs

@@ -0,0 +1,115 @@
+// 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.AspNetCore.Mvc;
+using Microsoft.Extensions.Logging;
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Agents;
+using Microsoft.SemanticKernel.ChatCompletion;
+
+namespace ChatWithAgent.ApiService;
+
+/// <summary>
+/// Controller for agent completions.
+/// </summary>
+[ApiController]
+[Route("agent/completions")]
+public sealed class AgentCompletionsController : ControllerBase
+{
+    private readonly ChatCompletionAgent _agent;
+    private readonly ILogger<AgentCompletionsController> _logger;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AgentCompletionsController"/> class.
+    /// </summary>
+    /// <param name="agent">The agent.</param>
+    /// <param name="logger">The logger.</param>
+    public AgentCompletionsController(ChatCompletionAgent agent, ILogger<AgentCompletionsController> logger)
+    {
+        this._agent = agent;
+        this._logger = logger;
+    }
+
+    /// <summary>
+    /// Completes the agent request.
+    /// </summary>
+    /// <param name="request">The request.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    [HttpPost]
+    public async Task<IActionResult> CompleteAsync([FromBody] AgentCompletionRequest request, CancellationToken cancellationToken)
+    {
+        ValidateChatHistory(request.ChatHistory);
+
+        // Add the "question" argument used in the agent template.
+        var arguments = new KernelArguments
+        {
+            ["question"] = request.Prompt
+        };
+
+        request.ChatHistory.AddUserMessage(request.Prompt);
+
+        if (request.IsStreaming)
+        {
+            return this.Ok(this.CompleteSteamingAsync(request.ChatHistory, arguments, cancellationToken));
+        }
+
+        return this.Ok(this.CompleteAsync(request.ChatHistory, arguments, cancellationToken));
+    }
+
+    /// <summary>
+    /// Completes the agent request.
+    /// </summary>
+    /// <param name="chatHistory">The chat history.</param>
+    /// <param name="arguments">The kernel arguments.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The completion result.</returns>
+    private async IAsyncEnumerable<ChatMessageContent> CompleteAsync(ChatHistory chatHistory, KernelArguments arguments, [EnumeratorCancellation] CancellationToken cancellationToken)
+    {
+        var thread = new ChatHistoryAgentThread(chatHistory);
+        IAsyncEnumerable<AgentResponseItem<ChatMessageContent>> content =
+            this._agent.InvokeAsync(thread, options: new() { KernelArguments = arguments }, cancellationToken: cancellationToken);
+
+        await foreach (ChatMessageContent item in content.ConfigureAwait(false))
+        {
+            yield return item;
+        }
+    }
+
+    /// <summary>
+    /// Completes the agent request with streaming.
+    /// </summary>
+    /// <param name="chatHistory">The chat history.</param>
+    /// <param name="arguments">The kernel arguments.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The completion result.</returns>
+    private async IAsyncEnumerable<StreamingChatMessageContent> CompleteSteamingAsync(ChatHistory chatHistory, KernelArguments arguments, [EnumeratorCancellation] CancellationToken cancellationToken)
+    {
+        var thread = new ChatHistoryAgentThread(chatHistory);
+        IAsyncEnumerable<AgentResponseItem<StreamingChatMessageContent>> content =
+            this._agent.InvokeStreamingAsync(thread, options: new() { KernelArguments = arguments }, cancellationToken: cancellationToken);
+
+        await foreach (StreamingChatMessageContent item in content.ConfigureAwait(false))
+        {
+            yield return item;
+        }
+    }
+
+    /// <summary>
+    /// Validates the chat history.
+    /// </summary>
+    /// <param name="chatHistory">The chat history to validate.</param>
+    private static void ValidateChatHistory(ChatHistory chatHistory)
+    {
+        foreach (ChatMessageContent content in chatHistory)
+        {
+            if (content.Role == AuthorRole.System)
+            {
+                throw new ArgumentException("A system message is provided by the agent and should not be included in the chat history.");
+            }
+        }
+    }
+}

dotnet/samples/Demos/AgentFrameworkWithAspire/ChatWithAgent.ApiService/Program.cs

@@ -0,0 +1,242 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.ClientModel.Primitives;
+using Azure.Identity;
+using ChatWithAgent.ApiService.Config;
+using ChatWithAgent.ApiService.Resources;
+using ChatWithAgent.Configuration;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.Extensions.Azure;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Agents;
+using Microsoft.SemanticKernel.Data;
+using Microsoft.SemanticKernel.PromptTemplates.Handlebars;
+
+namespace ChatWithAgent.ApiService;
+
+/// <summary>
+/// Defines the Program class containing the application's entry point.
+/// </summary>
+public static class Program
+{
+    /// <summary>
+    /// The main entry point for the application.
+    /// </summary>
+    /// <param name="args">The command-line arguments.</param>
+    public static void Main(string[] args)
+    {
+        var builder = WebApplication.CreateBuilder(args);
+
+        // Enable diagnostics.
+        AppContext.SetSwitch("Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnostics", true);
+
+        // Uncomment the following line to enable diagnostics with sensitive data: prompts, completions, function calls, and more.
+        //AppContext.SetSwitch("Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnosticsSensitive", true);
+
+        // Enable SK traces using OpenTelemetry.Extensions.Hosting extensions.
+        // An alternative approach to enabling traces can be found here: https://learn.microsoft.com/en-us/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-aspire-dashboard?tabs=Powershell&pivots=programming-language-csharp 
+        builder.Services.AddOpenTelemetry().WithTracing(b => b.AddSource("Microsoft.SemanticKernel*"));
+
+        // Enable SK metrics using OpenTelemetry.Extensions.Hosting extensions.
+        // An alternative approach to enabling metrics can be found here: https://learn.microsoft.com/en-us/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-aspire-dashboard?tabs=Powershell&pivots=programming-language-csharp
+        builder.Services.AddOpenTelemetry().WithMetrics(b => b.AddMeter("Microsoft.SemanticKernel*"));
+
+        // Enable SK logs.
+        // Log source and log level for SK is configured in appsettings.json.
+        // An alternative approach to enabling logs can be found here: https://learn.microsoft.com/en-us/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-aspire-dashboard?tabs=Powershell&pivots=programming-language-csharp
+
+        // Add service defaults & Aspire client integrations.
+        builder.AddServiceDefaults();
+
+        builder.Services.AddControllers();
+
+        // Add services to the container.
+        builder.Services.AddProblemDetails();
+
+        // Load the service configuration.
+        var config = new ServiceConfig(builder.Configuration);
+
+        // Add Kernel
+        builder.Services.AddKernel();
+
+        // Add AI services.
+        AddAIServices(builder, config.Host);
+
+        // Add Vector Store.
+        AddVectorStore(builder, config.Host);
+
+        // Add Agent.
+        AddAgent(builder, config.Host);
+
+        var app = builder.Build();
+
+        // Configure the HTTP request pipeline.
+        app.UseExceptionHandler();
+
+        app.MapDefaultEndpoints();
+
+        app.MapControllers();
+
+        app.Run();
+    }
+
+    /// <summary>
+    /// Adds AI services for chat completion and text embedding generation.
+    /// </summary>
+    /// <param name="builder">The web application builder.</param>
+    /// <param name="config">Service configuration.</param>
+    /// <exception cref="NotSupportedException"></exception>
+    private static void AddAIServices(WebApplicationBuilder builder, HostConfig config)
+    {
+        // Add AzureOpenAI client.
+        if (config.AIChatService == AzureOpenAIChatConfig.ConfigSectionName || config.Rag.AIEmbeddingService == AzureOpenAIEmbeddingsConfig.ConfigSectionName)
+        {
+            builder.AddAzureOpenAIClient(
+                connectionName: HostConfig.AzureOpenAIConnectionStringName,
+                configureSettings: (settings) => settings.Credential = builder.Environment.IsProduction()
+                    ? new DefaultAzureCredential()
+                    : new AzureCliCredential(),
+                configureClientBuilder: clientBuilder =>
+                {
+                    clientBuilder.ConfigureOptions((options) =>
+                    {
+                        options.RetryPolicy = new ClientRetryPolicy(maxRetries: 3);
+                    });
+                });
+        }
+
+        // Add OpenAI client.
+        if (config.AIChatService == AzureOpenAIChatConfig.ConfigSectionName || config.Rag.AIEmbeddingService == OpenAIEmbeddingsConfig.ConfigSectionName)
+        {
+            builder.AddOpenAIClient(HostConfig.OpenAIConnectionStringName);
+        }
+
+        // Add chat completion services.
+        switch (config.AIChatService)
+        {
+            case AzureOpenAIChatConfig.ConfigSectionName:
+            {
+                builder.Services.AddAzureOpenAIChatCompletion(config.AzureOpenAIChat.DeploymentName, modelId: config.AzureOpenAIChat.ModelName);
+                break;
+            }
+            case OpenAIChatConfig.ConfigSectionName:
+            {
+                builder.Services.AddOpenAIChatCompletion(config.OpenAIChat.ModelName);
+                break;
+            }
+            default:
+                throw new NotSupportedException($"AI chat service '{config.AIChatService}' is not supported.");
+        }
+
+        // Add text embedding generation services.
+        switch (config.Rag.AIEmbeddingService)
+        {
+            case AzureOpenAIEmbeddingsConfig.ConfigSectionName:
+            {
+                builder.Services.AddAzureOpenAIEmbeddingGenerator(config.AzureOpenAIEmbeddings.DeploymentName, modelId: config.AzureOpenAIEmbeddings.ModelName);
+                break;
+            }
+            case OpenAIEmbeddingsConfig.ConfigSectionName:
+            {
+                builder.Services.AddOpenAIEmbeddingGenerator(config.OpenAIEmbeddings.ModelName);
+                break;
+            }
+            default:
+                throw new NotSupportedException($"AI embeddings service '{config.Rag.AIEmbeddingService}' is not supported.");
+        }
+    }
+
+    /// <summary>
+    /// Adds the vector store to the service collection.
+    /// </summary>
+    /// <param name="builder">The web application builder.</param>
+    /// <param name="config">The host configuration.</param>
+    private static void AddVectorStore(WebApplicationBuilder builder, HostConfig config)
+    {
+        // Don't add vector store if no collection name is provided. Allows for a basic experience where no data has been uploaded to the vector store yet.
+        if (string.IsNullOrWhiteSpace(config.Rag.CollectionName))
+        {
+            return;
+        }
+
+        // Add Vector Store
+        switch (config.Rag.VectorStoreType)
+        {
+            case AzureAISearchConfig.ConfigSectionName:
+            {
+                builder.AddAzureSearchClient(
+                    connectionName: AzureAISearchConfig.ConnectionStringName,
+                    configureSettings: (settings) => settings.Credential = builder.Environment.IsProduction()
+                        ? new DefaultAzureCredential()
+                        : new AzureCliCredential()
+                );
+                builder.Services.AddAzureAISearchCollection<TextSnippet<string>>(config.Rag.CollectionName);
+                builder.Services.AddVectorStoreTextSearch<TextSnippet<string>>();
+                break;
+            }
+            default:
+                throw new NotSupportedException($"Vector store type '{config.Rag.VectorStoreType}' is not supported.");
+        }
+    }
+
+    /// <summary>
+    /// Adds the chat completion agent to the service collection.
+    /// </summary>
+    /// <param name="builder">The web application builder.</param>
+    /// <param name="config">The host configuration.</param>
+    private static void AddAgent(WebApplicationBuilder builder, HostConfig config)
+    {
+        // Register agent without RAG if no collection name is provided. Allows for a basic experience where no data has been uploaded to the vector store yet.
+        if (string.IsNullOrEmpty(config.Rag.CollectionName))
+        {
+            PromptTemplateConfig templateConfig = KernelFunctionYaml.ToPromptTemplateConfig(EmbeddedResource.Read("AgentDefinition.yaml"));
+
+            builder.Services.AddTransient<ChatCompletionAgent>((sp) =>
+            {
+                return new ChatCompletionAgent(templateConfig, new HandlebarsPromptTemplateFactory())
+                {
+                    Kernel = sp.GetRequiredService<Kernel>(),
+                };
+            });
+        }
+        else
+        {
+            // Register agent with RAG.
+            PromptTemplateConfig templateConfig = KernelFunctionYaml.ToPromptTemplateConfig(EmbeddedResource.Read("AgentWithRagDefinition.yaml"));
+
+            switch (config.Rag.VectorStoreType)
+            {
+                case AzureAISearchConfig.ConfigSectionName:
+                {
+                    AddAgentWithRag<string>(builder, templateConfig);
+                    break;
+                }
+                default:
+                    throw new NotSupportedException($"Vector store type '{config.Rag.VectorStoreType}' is not supported.");
+            }
+        }
+
+        static void AddAgentWithRag<TKey>(WebApplicationBuilder builder, PromptTemplateConfig templateConfig)
+        {
+            builder.Services.AddTransient<ChatCompletionAgent>((sp) =>
+            {
+                Kernel kernel = sp.GetRequiredService<Kernel>();
+                VectorStoreTextSearch<TextSnippet<TKey>> vectorStoreTextSearch = sp.GetRequiredService<VectorStoreTextSearch<TextSnippet<TKey>>>();
+
+                // Add a search plugin to the kernel which we will use in the agent template
+                // to do a vector search for related information to the user query.
+                kernel.Plugins.Add(vectorStoreTextSearch.CreateWithGetTextSearchResults("SearchPlugin"));
+
+                return new ChatCompletionAgent(templateConfig, new HandlebarsPromptTemplateFactory())
+                {
+                    Kernel = kernel,
+                };
+            });
+        }
+    }
+}

dotnet/samples/Demos/AgentFrameworkWithAspire/ChatWithAgent.ApiService/Rag/TextSnippet.cs

@@ -0,0 +1,34 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.VectorData;
+using Microsoft.SemanticKernel.Data;
+
+namespace ChatWithAgent.ApiService;
+
+/// <summary>
+/// Data model for storing a section of text with an embedding and an optional reference link.
+/// </summary>
+/// <typeparam name="TKey">The type of the data model key.</typeparam>
+internal sealed class TextSnippet<TKey>
+{
+    [VectorStoreKey]
+    [JsonPropertyName("chunk_id")]
+    public required TKey Key { get; set; }
+
+    [VectorStoreData]
+    [JsonPropertyName("chunk")]
+    [TextSearchResultValue]
+    public string? Text { get; set; }
+
+    [VectorStoreData]
+    [JsonPropertyName("title")]
+    [TextSearchResultName]
+    [TextSearchResultLink]
+    public string? Reference { get; set; }
+
+    [VectorStoreVector(1536)]
+    [JsonPropertyName("text_vector")]
+    public ReadOnlyMemory<float> TextEmbedding { get; set; }
+}

dotnet/samples/Demos/AgentFrameworkWithAspire/ChatWithAgent.ApiService/Resources/AgentDefinition.yaml

@@ -0,0 +1,9 @@
+name: AnalysisMaster
+template: Perform comprehensive analysis and provide accurate insights and recommendations on the topics and data sets provided.
+template_format: handlebars
+description: |
+  A highly capable agent designed to perform comprehensive analysis on various data sets and topics.
+  It utilizes advanced algorithms and methodologies to provide accurate insights and recommendations.
+execution_settings:
+  default:
+    temperature: 0

dotnet/samples/Demos/AgentFrameworkWithAspire/ChatWithAgent.ApiService/Resources/AgentWithRagDefinition.yaml

@@ -0,0 +1,24 @@
+name: AnalysisMaster
+template: |
+  Perform comprehensive analysis and provide accurate insights and recommendations on the topics and data sets provided.
+  Use this information to answer the question and include the source.
+  {{#with (SearchPlugin-GetTextSearchResults question)}}  
+      {{#each this}}
+      -----------------
+      Name: {{Name}}
+      Value: {{Value}}
+      Link: {{Link}}
+      -----------------
+      {{/each}}
+  {{/with}}
+template_format: handlebars
+description: |
+  A highly capable agent designed to perform comprehensive analysis on various data sets and topics.
+  It utilizes advanced algorithms and methodologies to provide accurate insights and recommendations.
+input_variables:
+  - name: question
+    description: The question to be answered.
+    is_required: true
+execution_settings:
+  default:
+    temperature: 0

dotnet/samples/Demos/AgentFrameworkWithAspire/ChatWithAgent.ApiService/Resources/EmbeddedResource.cs

@@ -0,0 +1,34 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.IO;
+using System.Reflection;
+
+namespace ChatWithAgent.ApiService.Resources;
+
+/// <summary>
+/// Reads embedded resources from the assembly.
+/// </summary>
+public static class EmbeddedResource
+{
+    private static readonly string? s_namespace = typeof(EmbeddedResource).Namespace;
+
+    internal static string Read(string fileName)
+    {
+        // Get the current assembly. Note: this class is in the same assembly where the embedded resources are stored.
+        Assembly assembly =
+            typeof(EmbeddedResource).GetTypeInfo().Assembly ??
+            throw new InvalidOperationException($"[{s_namespace}] {fileName} assembly not found");
+
+        // Resources are mapped like types, using the namespace and appending "." (dot) and the file name
+        var resourceName = $"{s_namespace}." + fileName;
+        using Stream resource =
+            assembly.GetManifestResourceStream(resourceName) ??
+            throw new InvalidOperationException($"{resourceName} resource not found");
+
+        // Return the resource content, in text format.
+        using var reader = new StreamReader(resource);
+
+        return reader.ReadToEnd();
+    }
+}

dotnet/samples/Demos/AgentFrameworkWithAspire/ChatWithAgent.ApiService/appsettings.json

@@ -0,0 +1,10 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning",
+      "Microsoft.SemanticKernel": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}