Semantic Kernel Recipes (.NET)
Ready-to-use C# patterns for Semantic Kernel — ASP.NET Core endpoints, agents with dependency injection, orchestrations, RAG and streaming.
Targets
Microsoft.SemanticKernel1.81.0 (checked 2026-11-19). Agents needMicrosoft.SemanticKernel.Agents.Core; orchestrations need the preview packagesMicrosoft.SemanticKernel.Agents.Orchestrationand.Agents.Runtime.InProcessand<NoWarn>$(NoWarn);SKEXP0110</NoWarn>. For new agent projects consider Microsoft Agent Framework, Semantic Kernel’s successor.
See also: language-agnostic recipes · comprehensive .NET guide
1. ASP.NET Core minimal API with a transient kernel
Section titled “1. ASP.NET Core minimal API with a transient kernel”using Azure.Identity;using Microsoft.SemanticKernel;
var builder = WebApplication.CreateBuilder(args);
// AI services are registered once (they are thread-safe and hold HTTP clients)...builder.Services.AddAzureOpenAIChatCompletion( deploymentName: builder.Configuration["AzureOpenAI:Deployment"]!, endpoint: builder.Configuration["AzureOpenAI:Endpoint"]!, credentials: new DefaultAzureCredential());
builder.Services.AddSingleton<WeatherPlugin>(); // WeatherPlugin: see the comprehensive guide, section 4.1
// ...but the Kernel is transient, so plugins and filters added per request do not leakbuilder.Services.AddTransient(sp =>{ var kernel = new Kernel(sp); kernel.Plugins.AddFromObject(sp.GetRequiredService<WeatherPlugin>(), "weather"); return kernel;});
var app = builder.Build();
app.MapPost("/api/chat", async (ChatRequest request, Kernel kernel, ILogger<Program> logger) =>{ try { var answer = await kernel.InvokePromptAsync<string>( "Answer the following question concisely: {{$input}}", new() { ["input"] = request.Message }); return Results.Ok(new { response = answer }); } catch (HttpOperationException ex) { logger.LogError(ex, "Model call failed"); return Results.Problem("The AI service is unavailable.", statusCode: 503); // don't leak exception text }});
app.Run();
public sealed record ChatRequest(string Message);HttpOperationException is what the OpenAI and Azure OpenAI connectors throw for HTTP failures; its StatusCode tells you whether retrying makes sense.
2. A chat endpoint that keeps conversation state
Section titled “2. A chat endpoint that keeps conversation state”using System.Collections.Concurrent;using Microsoft.SemanticKernel;using Microsoft.SemanticKernel.Agents;using Microsoft.SemanticKernel.ChatCompletion;
public sealed class ConversationService(Kernel kernel){ // Demo only: use a distributed store (Redis, SQL) in production and serialise the ChatHistory private static readonly ConcurrentDictionary<string, ChatHistory> Histories = new();
private readonly ChatCompletionAgent _agent = new() { Name = "Support", Instructions = "You are a concise support assistant.", Kernel = kernel, };
public async Task<string> SendAsync(string sessionId, string message) { var history = Histories.GetOrAdd(sessionId, _ => new ChatHistory()); var thread = new ChatHistoryAgentThread(history);
string reply = ""; await foreach (var item in _agent.InvokeAsync(message, thread)) reply = item.Message.Content ?? ""; return reply; }}
// builder.Services.AddTransient<ConversationService>();ChatHistoryAgentThread appends to the ChatHistory you give it, so the dictionary entry stays current.
3. Research-and-write pipeline with dependency injection
Section titled “3. Research-and-write pipeline with dependency injection”using Microsoft.SemanticKernel;using Microsoft.SemanticKernel.Agents;using Microsoft.SemanticKernel.Agents.Orchestration;using Microsoft.SemanticKernel.Agents.Orchestration.Sequential;using Microsoft.SemanticKernel.Agents.Runtime.InProcess;
public interface IAgentOrchestrator{ Task<string> ProcessAsync(string input, CancellationToken ct = default);}
public sealed class ResearchWritingOrchestrator(Kernel kernel, ILogger<ResearchWritingOrchestrator> logger) : IAgentOrchestrator{ public async Task<string> ProcessAsync(string input, CancellationToken ct = default) { ChatCompletionAgent researcher = new() { Name = "Researcher", Description = "Gathers facts", Instructions = "Research the topic and list key facts with sources.", Kernel = kernel, }; ChatCompletionAgent writer = new() { Name = "Writer", Description = "Writes the article", Instructions = "Write a 200-word article from the research notes.", Kernel = kernel, };
SequentialOrchestration orchestration = new(researcher, writer) { ResponseCallback = msg => { logger.LogInformation("[{Agent}] {Length} chars", msg.AuthorName, msg.Content?.Length ?? 0); return ValueTask.CompletedTask; }, };
InProcessRuntime runtime = new(); await runtime.StartAsync(ct); try { var result = await orchestration.InvokeAsync(input, runtime, ct); return await result.GetValueAsync(TimeSpan.FromMinutes(3), ct); } finally { await runtime.RunUntilIdleAsync(); } }}
// builder.Services.AddScoped<IAgentOrchestrator, ResearchWritingOrchestrator>();A sequential orchestration has a defined end point (the last agent’s answer), so there is no need to rely on the model saying a stop word.
4. Streaming tokens over Server-Sent Events
Section titled “4. Streaming tokens over Server-Sent Events”app.MapGet("/api/stream", async (string q, Kernel kernel, HttpResponse response, CancellationToken ct) =>{ response.Headers.ContentType = "text/event-stream"; await foreach (var chunk in kernel.InvokePromptStreamingAsync<string>(q, cancellationToken: ct)) { await response.WriteAsync($"data: {System.Text.Json.JsonSerializer.Serialize(chunk)}\n\n", ct); await response.Body.FlushAsync(ct); }});5. RAG tool from a vector store
Section titled “5. RAG tool from a vector store”using CommunityToolkit.VectorData.InMemory;using Microsoft.Extensions.AI;using Microsoft.Extensions.VectorData;using Microsoft.SemanticKernel.Data;
public sealed class Doc{ [VectorStoreKey] public string Id { get; set; } = ""; [VectorStoreData, TextSearchResultValue] public string Text { get; set; } = ""; [VectorStoreVector(1536)] public string Embedding => Text;}
var store = new InMemoryVectorStore(new(){ EmbeddingGenerator = kernel.GetRequiredService<IEmbeddingGenerator<string, Embedding<float>>>(),});var docs = store.GetCollection<string, Doc>("docs");await docs.EnsureCollectionExistsAsync();await docs.UpsertAsync(new Doc { Id = "1", Text = "Refunds are processed within 5 working days." });
kernel.Plugins.Add(new VectorStoreTextSearch<Doc>(docs).CreateWithGetTextSearchResults("Docs"));// An agent with FunctionChoiceBehavior.Auto() can now call Docs.GetTextSearchResultsRegister the embedding generator with builder.AddOpenAIEmbeddingGenerator("text-embedding-3-small", apiKey) (or the Azure equivalent).
For more, see the comprehensive guide, the production guide and the general recipes.
Revision history
Section titled “Revision history”| Date | Version | Changes |
|---|---|---|
| 2026-10-21 | 1.81.0 | Rewritten on current APIs (orchestrations, CommunityToolkit.VectorData); all blocks compile against 1.81.0. |