Introducing the v1.0.0 Beta1 for the .NET Semantic Kernel SDK

Semantic Kernel v1.0 has shipped and the contents of this blog entry is now out of date.

As mentioned in the Skills to Plugins blog post, the Semantic Kernel team has been preparing the Semantic Kernel SDK for v1.0.0. Today, we’re making our first big push by releasing the first release candidate: v1.0.0-beta1.

This release has several breaking changes that are necessary for us to get the SDK into spot where we can lock the API down for v1.0.0. To help existing developers using Semantic Kernel today, we’ve prepared this blog post to outline all the changes and how to resolve them when you uptake the initial release candidate.

At a high-level, the main breaking changes consist of the following:

We are moving away from using the term “Skills” and standardizing on the term “Plugins” instead. To avoid confusion in the future we have renamed packages and classes that used the term “Skill” to now use “Plugin”. Functions and properties that use “Skill” in their names have been marked as obsolete and new equivalents provided. To learn more about our reasoning, check out the Skills to Plugins blog post.
We are changing Semantic Kernel core to be AI service agnostic. A few of the Semantic Kernel abstractions were very OpenAI specific. We have fixed this to make the Semantic Kernel AI provider agnostic.
We have consolidated our planner implementations into a single package and introduced more code sharing. This will make it easier for developer to create their own custom planner implementations.

The following sections provide a more detailed migration guide for developers using a pre-release candidate of the .NET version of Semantic Kernel.

Migration overview for Semantic Kernel v1.0.0-beta1 (.Net)

Full list of breaking changes.

Below is the full list of PRs we’ve merged into v1.0.0.0-beta1 that resulted in breaking changes. Each of the PRs have a dedicated section in this blog post describing what was changed and how to update your code. Continue reading to learn more about these changes.

Updating your NuGet packages.

Before updating your code, you’ll want to make sure you’re using the latest NuGet packages. As part of this release, several packages have been renamed and some new packages have been introduced. Below is a table that describes the changes.

Previous name	`Microsoft.SemanticKernel`
New name	`Microsoft.SemanticKernel` (no name change)
Notes	Meta package has been updated to include core Semantic Kernel functionality, for more details see here.
Previous name	`Microsoft.SemanticKernel.Abstractions`
New name	`Microsoft.SemanticKernel.Abstractions` (no name change)
Notes	Some unused abstractions have been removed.
Previous name	`Microsoft.SemanticKernel.Core`
New name	`Microsoft.SemanticKernel.Core` (no name change)
Notes	Some functionality has been extracted to separate packages, see below.
Previous name	N/A
New name	`Microsoft.SemanticKernel.TemplateEngine.Basic`
Notes	Default prompt template engine has been extracted to this package.
Previous name	N/A
New name	`Microsoft.SemanticKernel.Reliability.Basic`
Notes	Default prompt template engine has been extracted to this package.
Previous name	N/A
New name	`Microsoft.SemanticKernel.Reliability.Polly`
Notes	Polly based reliability support has been extracted to this package.
Previous name	N/A
New name	`Microsoft.SemanticKernel.Functions.Semantic`
Notes	Semantic Function support has been extracted to this package.
Previous name	N/A
New name	`Microsoft.SemanticKernel.Plugins.Memory`
Notes	Semantic Kernel memory support has been extracted to this package.
Previous name	`Microsoft.SemanticKernel.Skills.Grpc`
New name	`Microsoft.SemanticKernel.Functions.Grpc`
Notes	Package renamed to reflect it’s purpose.
Previous name	`Microsoft.SemanticKernel.Skills.OpenAPI`
New name	`Microsoft.SemanticKernel.Functions.OpenAPI`
Notes	Package renamed to reflect it’s purpose.
Previous name	`Microsoft.SemanticKernel.Skills.OpenAPI`
New name	`Microsoft.SemanticKernel.Functions.OpenAPI`
Notes	Package renamed to reflect it’s purpose.
Previous name	`Microsoft.SemanticKernel.Planning.ActionPlanner` `Microsoft.SemanticKernel.Planning.SequentialPlanner` `Microsoft.SemanticKernel.Planning.StepwisePlanner`
New name	`Microsoft.SemanticKernel.Planners.Core`
Notes	Planner packages have been consolidated into a single package.
Previous name	`Microsoft.SemanticKernel.Skills.Core`
New name	`Microsoft.SemanticKernel.Plugins.Core`
Notes	Rename from `Skills` to `Plugins`
Previous name	`Microsoft.SemanticKernel.Skills.Document`
New name	`Microsoft.SemanticKernel.Plugins.Document`
Notes	Rename from `Skills` to `Plugins`
Previous name	`Microsoft.SemanticKernel.Skills.MsGraph`
New name	`Microsoft.SemanticKernel.Plugins.MsGraph`
Notes	Rename from `Skills` to `Plugins`
Previous name	`Microsoft.SemanticKernel.Skills.Web`
New name	`Microsoft.SemanticKernel.Plugins.Web`
Notes	Rename from `Skills` to `Plugins`

Updating your code.

Rename ImportAIPluginAsync Update plugin import method and planner, and rename AIPlugin to Plugin in

Rename ImportAIPluginAsync to ImportPluginFunctionsAsync

PR #2968

Extract semantic functions from Kernel.Core

All functionality related to semantic functions has been extracted from the Microsoft.SemanticKernel.Core package and moved to Microsoft.SemanticKernel.Functions.Semantic

PR #2961

Refactor planners, memory config, and function extensions

When creating a SequentialPlanner change:

var planner = new SequentialPlanner(kernel, new SequentialPlannerConfig { RelevancyThreshold = 0.5, Memory = kernel.Memory });
// to..
var planner = new SequentialPlanner(kernel, new SequentialPlannerConfig { SemanticMemoryConfig = new() { RelevancyThreshold = 0.5, Memory = kernel.Memory } });

PR #2949

Rename ImportXXXPlugins methods to ImportXXXFunctions for GRPC

Rename OpenApiPluginExecutionParameters to OpenApiFunctionExecutionParameters
Rename ImportGrpcPluginFromFile or ImportGrpcSkillFromFile to ImportGrpcFunctionsFromFile

PR #2943

Rename ImportXXXPlugins methods to ImportXXXFunctions

As part of the Skill -> Plugin rename the ImportSkill and ImportSemanticSkillFromDirectory are renamed to use the term Function because these methods actually import functions to the Kernel so this PR renames them to match what they actually do.

Note: We want to reserve the ImportPlugin method for later use for when we add more plugin support to Semantic Kernel.

PR #2937

Merge planner packages2

Packages Microsoft.SemanticKernel.Planning.ActionPlanner, Microsoft.SemanticKernel.Planning.SequentialPlanner, Microsoft.SemanticKernel.Planning.StepwisePlanner have been merged into Microsoft.SemanticKernel.Planners.Core
Namespaces for all planners have been changed from Microsoft.SemanticKernel.Planning to Microsoft.SemanticKernel.Planners

PR #2931

Rename ‘Skills’ -> ‘Plugins’ – Part 5

These changes only impact our samples

PR #2918

Refactor PlannerConfig classes for better organization

Moved common properties and methods from SequentialPlannerConfig and StepwisePlannerConfig to the base class PlannerConfigBase.

PR #2912

Rename ‘Skills’ -> ‘Plugins’ – Part 3

Remove the Microsoft.SemanticKernel.SkillDefinition namespace and promote classes previously contained to Microsoft.SemanticKernel, this is to reduce the number of usings that client code required.
Rename variable/function names using skillName to pluginName.
Rename skill collection interfaces/classes to use function collection in naming:
- IReadOnlySkillCollection -> IReadOnlyFunctionCollection
- SkillCollection -> FunctionCollection
Leave some obsolete methods/properties to help with the upgrade from earlier releases.

PR #2904

Remove IServiceConfig as it is not used

IServiceConfig (and the associated implementation ServiceConfig) has been removed as it was not being used.

PR #2886

Removing IsSemantic and IsAsync properties from ISKFunction and FunctionView

ISKFunction.IsSemantic is obsolete and will be removed in a future release.

PR #2881

Replacing FunctionsView class with List

The FunctionsView class has been simplified to have a single list containing native and semantic functions

To iterate over all functions associated with a kernel do this:

var functions = kernel.Functions.GetFunctionViews();
foreach (FunctionView func in functions)
{
    Console.WriteLine($"{func.Name}: {func.Description}");
}

PR #2878

New result types – FunctionResult and KernelResult

PR #2864

The return type from ISKFunction.InvokeAsync has been changed from Task<SKContext> to Task<FunctionResult>
- FunctionResult – new return type from single function invocation. It contains object? Value which can be any primitive, complex type or IAsyncEnumerable<T>.
The return type from IKernel.RunAsync has been changed from Task<SKContext> to Task<KernelResult>
- KernelResult – new return type from Kernel invocation. It contains object? Value which can be any primitive, complex type or IAsyncEnumerable<T>.
Update your code to use result.GetValue<string> instead of result.Result.

KernelResult – new return type in Kernel.RunAsync method. It doesn’t contain SKContext, just object? Value to get execution result. FunctionResult also contains Metadata – property, that contains additional data, including AI model response (e.g. token usage). KernelResult contains collection of FunctionResult – all function results from pipeline, so it’s possible to check result of each function in pipeline, observe result value, AI-related information, like amount of tokens etc.

Syntax in examples and tests were changed from result.Result to result.GetValue, but now it should be possible to get any type as a result and not only string.

Rename ‘Skills’ -> ‘Plugins’ – Part 1

The following packages have been renamed and :

Microsoft.SemanticKernel.Skills.Core -> Microsoft.SemanticKernel.Plugins.Core
Microsoft.SemanticKernel.Skills.Document -> Microsoft.SemanticKernel.Plugins.Document
Microsoft.SemanticKernel.Skills.MsGraph -> Microsoft.SemanticKernel.Plugins.MsGraph
Microsoft.SemanticKernel.Skills.Web -> Microsoft.SemanticKernel.Plugins.Web

All classes ending in Skill have been renamed to end in Plugin.

All namespaces that included Skills have been changed to use Plugins instead.

PR #2854

Making ContextVariables into a proper Dictionary

Simplifying ContextVariables by making it into an actual Dictionary<string, string> instead of implementing IDictionary<string, string>.

PR #2852

Update StepwisePlannerConfig to Improve MaxPromptTokens Calculation and Add Tests for Edge Cases

This pull request updates the StepwisePlannerConfig class in the Planning.StepwisePlanner project to improve the calculation of the MaxPromptTokens property, ensuring that the maximum number of iterations allowed in a plan is properly taken into account.

PR #2850

Make planner constructors more similar

This change addresses inconsistencies in planner constructors.

Added GetPromptTemplate delegate function to the planner base config. All planners will use this to get the prompt override.
Removed logger factory argument from ActionPlanner constructor. Used the Kernel’s logger factory to create a new logger within each planner constructor.
Renamed private Config private instance field to _config.

PR #2849

Adding IKernel property the SKContext – Phase 1

This change is to support using IKernel.RunAsync as the primary way to invoke functions. If you code is currently using ISKFunction.InvokeAsync it is recommended that you change to use IKernel.RunAsync as this pattern will be enforced in a future update.

PR #2846

Removing Kernel.Func() shorthand

This helper function is being removed and instead developers should call kernel.Functions.GetFunction(skill, functionName); instead.

PR #2836

Refactor to support generic LLM request settings (use AIRequestSettings)

This change is requested to allow the Semantic Kernel abstractions to be AI Service agnostic i.e., remove OpenAI specific properties. For more information on the reason for this breaking change see ADR 0008-support-generic-llm-request-settings.md

Introduces AIRequestSettings to replace PromptTemplateConfig.CompletionConfig. This is the base class for all AI Service request settings.
Introduces OpenAIRequestSettings as the OpenAI specific request settings class.
Update code and samples to use AIRequestSettings or OpenAIRequestSettings to configure AI Service request settings.

All of the Kernel Syntax Examples have been updated to use the new pattern.

PR #2829

GPT3Tokenizer has been removed from Semantic Kernel repository
Alternatives:
- Microsoft Tokenizer
- SharpToken

PR #2809

Introducing the v1.0.0 Beta1 for the .NET Semantic Kernel SDK