Semantic Kernel: What It Does, How to Set It Up, and Common Errors Fixed

The first thing to get right is the package installation. The Semantic Kernel NuGet package for .NET is Microsoft.SemanticKernel, and for most applications that's the only package you need to start. Open a terminal in your project directory and run:

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.Extensions.Logging
dotnet add package Microsoft.Extensions.Logging.Console

The logging packages aren't optional noise, they're how you see what the kernel is actually doing. Without them, when function calling goes wrong, you'll see nothing. With them set to LogLevel.Trace, you'll see every HTTP request, every function invocation, every model response. That visibility is what separates a five-minute debugging session from a three-hour one.

A common mistake is installing mismatched package versions. If you're working in an existing project that already has some Microsoft.Extensions packages, run dotnet list package --outdated after installing to spot version conflicts. Semantic Kernel 1.0+ follows a no-breaking-changes commitment across C#, Python, and Java, but mixing a 1.x kernel with 0.x extension packages will cause runtime failures that look completely unrelated to versioning.

After installation, open your .csproj file and confirm the package references look like:

<PackageReference Include="Microsoft.SemanticKernel" Version="1.*" />
<PackageReference Include="Microsoft.Extensions.Logging" Version="8.*" />
<PackageReference Include="Microsoft.Extensions.Logging.Console" Version="8.*" />

If you see multiple competing versions in the same project, run dotnet restore --force to reset the package graph. You should see Restore completed with zero errors before moving on.

Once your packages are in place, you're ready to build your first Semantic Kernel kernel builder configuration. The kernel is the central object, everything else hangs off of it. Here's the exact code to create it with Azure OpenAI:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;
using Microsoft.SemanticKernel.Connectors.OpenAI;

var modelId = Environment.GetEnvironmentVariable("AZURE_OAI_DEPLOYMENT");
var endpoint = Environment.GetEnvironmentVariable("AZURE_OAI_ENDPOINT");
var apiKey = Environment.GetEnvironmentVariable("AZURE_OAI_KEY");

var builder = Kernel.CreateBuilder()
    .AddAzureOpenAIChatCompletion(modelId, endpoint, apiKey);

builder.Services.AddLogging(services =>
    services.AddConsole().SetMinimumLevel(LogLevel.Trace));

Kernel kernel = builder.Build();

Two things to notice here. First, Kernel.CreateBuilder() returns a builder, not a kernel, you must call .Build() at the end or you'll get a InvalidOperationException when you try to use it. I've watched junior developers spend 20 minutes on that one. Second, AddAzureOpenAIChatCompletion() is an extension method on the builder, not the kernel itself. If IntelliSense doesn't show it, your Connectors.OpenAI package isn't installed or isn't resolving correctly, check your imports.

After builder.Build(), immediately retrieve the chat completion service:

var chatCompletionService =
    kernel.GetRequiredService<IChatCompletionService>();

If this line throws InvalidOperationException: No service for type 'IChatCompletionService' has been registered, it means AddAzureOpenAIChatCompletion() didn't complete successfully, which almost always means one of your three credential variables was null or empty at build time.

This is where Semantic Kernel plugin registration and the AI agent function calling pipeline come in, and where most developers hit their second major wall. A plugin is just a C# class with methods decorated with the [KernelFunction] attribute. Here's the classic lights plugin example from the official docs, expanded with better error handling:

using Microsoft.SemanticKernel;

public class LightsPlugin
{
    private bool _isOn = false;

    [KernelFunction("GetState")]
    [Description("Gets the current state of the light")]
    public string GetState() => _isOn ? "on" : "off";

    [KernelFunction("ChangeState")]
    [Description("Changes the light state. Pass true to turn on, false to turn off.")]
    public string ChangeState(bool newState)
    {
        _isOn = newState;
        return _isOn ? "on" : "off";
    }
}

Register it on the kernel before your chat loop starts:

kernel.Plugins.AddFromType<LightsPlugin>("Lights");

The string "Lights" becomes the plugin name the AI model references. If you change it, the model's function calls will reference whatever name you use, this matters if you're troubleshooting logs and don't recognize which plugin the AI is trying to invoke.

One thing that catches people: the [Description] attribute on each function isn't optional fluff. The AI model reads these descriptions to decide which function to call. Vague or missing descriptions mean the model will either call the wrong function or skip function calling entirely and just hallucinate an answer. Write them like you're explaining to a smart but context-free assistant what each function does.

If your plugin registers but never gets called, check your FunctionChoiceBehavior setting in the next step, that's the switch that tells the model it's allowed to use functions at all.

For Semantic Kernel automatic function calling to work, where the AI decides on its own when to call your plugins, you need to configure execution settings correctly. This is the part the official docs touch on briefly but don't fully explain the implications of:

OpenAIPromptExecutionSettings openAIPromptExecutionSettings = new()
{
    FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
};

Then pass these settings every time you call the chat completion service:

var result = await chatCompletionService.GetChatMessageContentAsync(
    history,
    executionSettings: openAIPromptExecutionSettings,
    kernel: kernel);

Notice that kernel: kernel parameter. This is not optional. Without it, even if FunctionChoiceBehavior.Auto() is set, the model may signal that it wants to call a function but the kernel has no context to resolve it against, and the call silently returns nothing or throws a cryptic exception like KernelException: The function "Lights-GetState" was not found in the kernel.

FunctionChoiceBehavior.Auto() tells the AI it can call functions whenever it determines that's the right move. The alternative is FunctionChoiceBehavior.None() (no function calls allowed) or manually specifying allowed functions. For most getting-started scenarios, Auto() is what you want. The AI handles its own planning, it figures out which functions to call, in what order, and how many times, and Semantic Kernel orchestrates all of that behind the scenes without you writing any orchestration logic yourself.

Once this is wired up correctly, you should see log output like [DBG] Function LightsPlugin.GetState() invoked when you ask the AI about the light state.

The last piece is the conversation loop itself. Semantic Kernel ChatHistory management is how the kernel maintains context across multiple turns of conversation, without it, the AI forgets everything you said in the previous message. Here's the full working loop:

var history = new ChatHistory();

string? userInput;
do
{
    Console.Write("User > ");
    userInput = Console.ReadLine();

    if (string.IsNullOrWhiteSpace(userInput)) break;

    history.AddUserMessage(userInput);

    var result = await chatCompletionService.GetChatMessageContentAsync(
        history,
        executionSettings: openAIPromptExecutionSettings,
        kernel: kernel);

    Console.WriteLine("Assistant > " + result);

    history.AddMessage(result.Role, result.Content ?? string.Empty);

} while (userInput is not null);

Two additions here compared to the raw sample: the null-whitespace guard and the explicit null-coalesce on result.Content. In practice, when the model's last action is a function call that returns a result, result.Content can come back as null, the content is in the tool call result, not the message content directly. Without that ?? string.Empty, you'll get a NullReferenceException on the history.AddMessage() call and the conversation dies silently.

When everything is working, the console output for "Please toggle the light" should look something like this, with the function calls happening invisibly in the background:

User > Please toggle the light
Assistant > The light is now on

In the trace logs you'll see the full picture: GetState() called, returned "off", then ChangeState(true) called, returned "on", then the AI generated the human-readable response. That three-step sequence happening automatically, driven by the AI's own planning, is the core value proposition of the Semantic Kernel middleware architecture.