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

Matthew Bolanos

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.

1. Add Models collection to PromptTemplateConfig Update PromptTemplateConfig to support multiple AI models
2. Remove SKParameterAttribute and related code
3. Rename ImportAIPluginAsync Update plugin import method and planner, and rename AIPlugin to Plugin
4. Extract semantic functions from Kernel.Core
5. Refactor planners, memory config, and function extensions
6. Rename ImportXXXPlugins methods to ImportXXXFunctions for GRPC
7. Rename ImportXXXPlugins methods to ImportXXXFunctions
8. Merge planner packages2
9. Rename ‘Skills’ -> ‘Plugins’ – Part 5
10. Refactor PlannerConfig classes for better organization
11. Rename ‘Skills’ -> ‘Plugins’ – Part 3
12. Remove IServiceConfig as it is not used
13. Removing IsSemantic and IsAsync properties from ISKFunction and FunctionView
14. Replacing FunctionsView class with List
15. New result types – FunctionResult and KernelResult
16. Rename ‘Skills’ -> ‘Plugins’ – Part 2
17. Rename ‘Skills’ -> ‘Plugins’ – Part 1
18. Making ContextVariables into a proper Dictionary
19. Update StepwisePlannerConfig to Improve MaxPromptTokens Calculation and Add Tests for Edge Cases
20. Make planner constructors more similar
21. Adding IKernel property the SKContext – Phase 1
22. Removing Kernel.Func() shorthand
23. Option #3 – Refactor to support generic LLM request settings (use AIRequestSettings)
24. Removed GPT3Tokenizer and related files

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.

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

Removed GPT3Tokenizer and related files

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

PR #2809

Matthew Bolanos

Follow