{"id":3011,"date":"2024-07-23T12:26:02","date_gmt":"2024-07-23T19:26:02","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/semantic-kernel\/?p=3011"},"modified":"2024-07-23T12:26:02","modified_gmt":"2024-07-23T19:26:02","slug":"planning-with-semantic-kernel-using-automatic-function-calling","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/agent-framework\/planning-with-semantic-kernel-using-automatic-function-calling\/","title":{"rendered":"Planning with Semantic Kernel using Automatic Function Calling"},"content":{"rendered":"

Hello, everyone!<\/p>\n

AI planning is a powerful tool that allows to generate and execute complex workflows in applications based on specified goal. In Semantic Kernel, it’s possible to implement planning logic using FunctionCallingStepwisePlanner<\/code> class. Today we want to introduce a new way how to achieve the same results by using Automatic Function Calling. This approach produces the results more reliably and uses fewer tokens comparing to FunctionCallingStepwisePlanner<\/code>.<\/p>\n

Setup<\/strong><\/h2>\n

For demonstration purposes, we will use 2 plugins to get current date\/time and weather:<\/p>\n

public sealed class TimePlugin\r\n{\r\n    [KernelFunction]\r\n    [Description(\"Retrieves the current time in UTC\")]\r\n    public string GetCurrentUtcTime() => DateTime.UtcNow.ToString(\"R\");\r\n}\r\n\r\npublic sealed class WeatherPlugin\r\n{\r\n    [KernelFunction]\r\n    [Description(\"Gets the current weather for the specified city\")]\r\n    public string GetWeatherForCity(string cityName) =>\r\n        cityName switch\r\n        {\r\n            \"Boston\" => \"61 and rainy\",\r\n            \"London\" => \"55 and cloudy\",\r\n            \"Miami\" => \"80 and sunny\",\r\n            \"Paris\" => \"60 and rainy\",\r\n            \"Tokyo\" => \"50 and sunny\",\r\n            \"Sydney\" => \"75 and sunny\",\r\n            \"Tel Aviv\" => \"80 and sunny\",\r\n            _ => \"31 and snowing\",\r\n        };\r\n}\r\n<\/code><\/pre>\n
For simplicity, let’s define a helper function to initialize Kernel<\/code> instance to use it across examples in this article:<\/p>\n
public static Kernel GetKernel()\r\n{\r\n    Kernel kernel = Kernel\r\n        .CreateBuilder()\r\n        .AddOpenAIChatCompletion(\"gpt-4\", Environment.GetEnvironmentVariable(\"OpenAI__ApiKey\"))\r\n        .Build();\r\n\r\n    \/\/ Import sample plugins.\r\n    kernel.ImportPluginFromType<TimePlugin>();\r\n    kernel.ImportPluginFromType<WeatherPlugin>();\r\n\r\n    return kernel;\r\n}\r\n<\/code><\/pre>\n
Old approach with FunctionCallingStepwisePlanner<\/strong><\/h2>\n
Here is an example how to generate and execute a plan with FunctionCallingStepwisePlanner<\/code>:<\/p>\n
\/\/ Get kernel\r\nKernel kernel = GetKernel();\r\n\r\n\/\/ Initialize planner\r\nFunctionCallingStepwisePlanner planner = new();\r\n\r\n\/\/ Generate and execute a plan\r\nFunctionCallingStepwisePlannerResult plannerResult = await planner.ExecuteAsync(kernel, \"Check current UTC time and return current weather in Boston city.\");\r\n\r\nConsole.WriteLine($\"Planner execution result: {plannerResult.FinalAnswer}\");\r\n\r\n\/\/ Output:\r\n\/\/ Planner execution result: The current UTC time is Sat, 06 Jul 2024 02:11:10 GMT and the weather in Boston is 61 and rainy.\r\n<\/code><\/pre>\n
It’s possible to get access to generated plan and see details for each step by using plannerResult.ChatHistory<\/code>.\nIn current scenario with 2 plugins and defined goal, approximately 1380<\/strong> tokens were used.<\/p>\n
New approach with Automatic Function Calling<\/strong><\/h2>\n
For Automatic Function Calling, Kernel<\/code> object should be used with ToolCallBehavior.AutoInvokeKernelFunctions<\/code> configured in execution settings. Here is an example:<\/p>\n
\/\/ Get kernel\r\nKernel kernel = GetKernel();\r\n\r\n\/\/ Enable Automatic Function Calling\r\nOpenAIPromptExecutionSettings executionSettings = new() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions };\r\n\r\n\/\/ Generate and execute a plan\r\nFunctionResult result = await kernel.InvokePromptAsync(\"Check current UTC time and return current weather in Boston city.\", new(executionSettings));\r\n\r\nConsole.WriteLine($\"Auto Function Calling execution result: {result}\");\r\n\r\n\/\/ Output:\r\n\/\/ Auto Function Calling execution result: The current UTC time is Sat, 06 Jul 2024 02:11:16 GMT. The weather right now in Boston is 61 degrees and rainy.\r\n<\/code><\/pre>\n
With Automatic Function Calling, planning result is the same, but token usage is significantly smaller – approximately 240<\/strong> tokens.<\/p>\n
Get generated plan with Automatic Function Calling<\/h3>\n
In both FunctionCallingStepwisePlanner<\/code> and Automatic Function Calling approaches, generated plan lives in ChatHistory<\/code> object. To get access to generated plan with Automatic Function Calling, IChatCompletionService<\/code> should be used:<\/p>\n
\/\/ Get kernel\r\nKernel kernel = GetKernel();\r\n\r\n\/\/ Get chat completion service\r\nIChatCompletionService chatCompletionService = kernel.GetRequiredService();\r\n\r\n\/\/ Enable Automatic Function Calling\r\nOpenAIPromptExecutionSettings executionSettings = new() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions };\r\n\r\n\/\/ Initialize chat history\r\nChatHistory chatHistory = new();\r\nchatHistory.AddUserMessage(\"Check current UTC time and return current weather in Boston city.\");\r\n\r\n\/\/ Generate and execute a plan\r\nChatMessageContent result = await chatCompletionService.GetChatMessageContentAsync(chatHistory, executionSettings, kernel);\r\n\r\n\/\/ Result variable contains the result of executed plan.\r\n\/\/ ChatHistory contains generated plan with details for each step - function, arguments, function invocation result.\r\n<\/code><\/pre>\n
Summary<\/strong><\/h2>\n
Provided example shows how to use a new recommended approach for planning with Automatic Function Calling to achieve specified goal.<\/p>\n
By following links, you can find and run more examples for different planning scenarios such as telemetry for plan generation and execution, plan caching for reusability, using filters to control plan execution and more:<\/p>\n