You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -2,128 +2,217 @@ Plugins are a key component of the Semantic Kernel SDK. Plugins allow you to enc
2
2
3
3
## Creating a plugin
4
4
5
-
For the Semantic Kernel to correctly route requests to your functions, the plugins you create must include details that describe the function's behavior. The details need to be written in a way that can be understood by the AI. The function's input, output and side effects should be described so that they AI can use the function. To create a plugin function, you add the following attributes to your function: `KernelFunction`, `Description`, and `return` if there's data returned from the function. Here's an example of a task management plugin with a function and its description:
5
+
For the Semantic Kernel to correctly route requests to your functions, the plugins you create must include details that describe the function's behavior. The details need to be written in a way that can be understood by the AI. The function's input, output and side effects should be described so that the AI can use the function.
6
6
7
-
```c#
8
-
usingSystem.ComponentModel;
9
-
usingMicrosoft.SemanticKernel;
7
+
::: zone pivot="csharp"
10
8
11
-
publicclassTaskManagementPlugin
12
-
{
13
-
// Mock data for the tasks
14
-
privatereadonlyList<TaskModel> tasks=new()
15
-
{
16
-
newTaskModel { Id=1, Title="Design homepage", Description="Create a modern homepage layout", Status="In Progress", Priority="High" },
17
-
newTaskModel { Id=2, Title="Fix login bug", Description="Resolve the issue with login sessions timing out", Status="To Do", Priority="Critical" },
18
-
newTaskModel { Id=3, Title="Update documentation", Description="Improve API reference for developers", Status="Completed", Priority="Medium" }
19
-
};
9
+
To create a plugin function in C#, you add the following attributes to your function: `[KernelFunction]`, `[Description]`, and `[return: Description]` if there's data returned from the function. Here’s a minimal example:
20
10
21
-
[KernelFunction("complete_task")]
22
-
[Description("Updates the status of the specified task to Completed")]
23
-
[return: Description("The updated task; will return null if the task does not exist")]
24
-
publicTaskModel? CompleteTask(intid)
25
-
{
26
-
vartask=tasks.FirstOrDefault(task=>task.Id==id);
11
+
```csharp
12
+
using Microsoft.SemanticKernel;
27
13
28
-
if (task==null)
14
+
public class TaskManagementPlugin
15
+
{
16
+
[KernelFunction("complete_task")]
17
+
[Description("Marks a task as completed by its ID.")]
18
+
[return: Description("The updated task, or null if not found.")]
19
+
public TaskModel? CompleteTask(int id)
29
20
{
30
-
returnnull;
21
+
// ...complete the task logic...
31
22
}
23
+
}
24
+
```
32
25
33
-
task.Status="Completed";
26
+
::: zone-end
34
27
35
-
returntask;
36
-
}
37
-
}
38
-
```
28
+
::: zone pivot="python"
29
+
30
+
To create a plugin function in Python, you use the `@kernel_function` decorator with a description parameter. The return type is specified in the function signature (for example, `-> dict | None`). Here’s a minimal example:
31
+
32
+
```python
33
+
from semantic_kernel import kernel_function, KernelPlugin
34
+
35
+
class TaskManagementPlugin(KernelPlugin):
36
+
@kernel_function(name="complete_task", description="Marks a task as completed by its ID.")
37
+
def complete_task(self, id: int) -> dict | None:
38
+
# ...complete the task logic...
39
+
pass
40
+
```
41
+
42
+
::: zone-end
43
+
44
+
> [!INOTE]
45
+
>
46
+
> ::: zone pivot="csharp"
47
+
>
48
+
> In C#, plugin functions use attributes such as `[KernelFunction]` and `[Description]` to provide metadata for the Semantic Kernel. Chat history is managed using the `ChatHistory` class and its methods, such as `AddUserMessage`.
49
+
>
50
+
> ::: zone-end
51
+
>
52
+
> ::: zone pivot="python"
53
+
>
54
+
> In Python, plugin functions use decorators such as `@kernel_function` to provide metadata for the Semantic Kernel. Chat history is typically represented as a list of dictionaries, each with a `role` and `content` key.
55
+
>
56
+
> ::: zone-end
57
+
58
+
In this example, only the essentials are shown: the function signature, attributes, and a placeholder for your logic.
39
59
40
-
In this example, there's a simple `CompleteTask` function that marks a task as complete. To call your function, you need to add the plugin to the kernel using `Plugins.AddFromType`. This will give the kernel access to the plugin's functions. Afterwards you can invoke a function using the `InvokeAsync` method.
60
+
To call your function, register the plugin and invoke the function as shown below:
var arguments = new KernelArguments { ["id"] = 1 };
69
+
var updatedTask = await kernel.InvokeAsync("TaskManagement", "complete_task", arguments);
70
+
```
53
71
54
-
Using plugin functions allows your agent to perform tasks beyond the capabilities of a typical LLM, such as managing data, interacting with external systems, or handling specific business logic. The modularity of plugins make it easy to add new functionality to your agent without modifying core logic. This approach keeps your code organized, reusable, and easier to maintain.
Using plugin functions allows your agent to perform tasks beyond the capabilities of a typical LLM, such as managing data, interacting with external systems, or handling specific business logic. The modularity of plugins makes it easy to add new functionality to your agent without modifying core logic. This approach keeps your code organized, reusable, and easier to maintain.
55
89
56
90
## Invoke functions automatically
57
91
58
92
The Semantic Kernel SDK enables the LLM to automatically invoke your plugin functions. Automatically invoking functions allows your application to respond more intelligently to user input. Instead of requiring explicit commands to trigger specific actions, the AI can determine the appropriate function to call based on the user's request. This enhances the user experience by making interactions more natural and reducing the need for precise instructions.
59
93
60
-
To enable functions to be invoked automatically, you must set the `FunctionChoiceBehavior` property of the `OpenAIPromptExecutionSettings` object to `Auto()`. Afterwards, user prompts will be able to trigger your plugin functions.
94
+
To enable functions to be invoked automatically:
95
+
96
+
::: zone pivot="csharp"
97
+
98
+
Set the `FunctionChoiceBehavior` property of the `OpenAIPromptExecutionSettings` object to `Auto()`. Afterwards, user prompts will be able to trigger your plugin functions.
99
+
100
+
::: zone-end
101
+
102
+
::: zone pivot="python"
103
+
104
+
Set `function_call="auto"` in the `OpenAIChatCompletionSettings` object. This allows user prompts to automatically trigger your plugin functions based on the LLM's understanding of the user's intent.
105
+
106
+
::: zone-end
61
107
62
108
Suppose the `TaskManagementPlugin` contains a `GetCriticalTasks` function:
63
109
64
-
```c#
65
-
[KernelFunction("get_critical_tasks")]
66
-
[Description("Gets a list of all tasks marked as 'Critical' priority")]
The output of this code would be similar to the following text:
167
+
```python
168
+
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletionSettings
106
169
107
-
```output
108
-
Assistant: The only critical task is "Fix login bug". The task is currently in the "To Do" status and its description is "Resolve the issue with login sessions timing out".
Notice that the results of the function are passed to the LLM and a generated response is returned. Automatic function invocation makes your application smarter and more user-friendly. This feature can enhance the overall usability and adaptability of your solution.
172
+
history = [{"role": "user", "content": "What are all of the critical tasks?"}]
result = await chat_completion_service.get_chat_message_content(
176
+
history=history,
177
+
execution_settings=settings,
178
+
kernel=kernel
179
+
)
180
+
181
+
print("Assistant:", result)
182
+
```
183
+
184
+
::: zone-end
185
+
186
+
The output of this code would be similar to:
187
+
188
+
```console
189
+
Assistant: The only critical task is "Fix login bug". The task is currently in the "To Do" status and its description is "Resolve the issue with login sessions timing out".
190
+
```
191
+
192
+
Notice that the results of the function are passed to the LLM and a generated response is returned. Automatic function invocation makes your application smarter and more user-friendly.
112
193
113
194
## Make plugins AI-friendly
114
195
115
196
To enhance the LLM's ability to understand and utilize your plugin functions, consider the following guidelines:
116
197
117
-
-**Use descriptive and concise function names**
118
-
119
-
Names that clearly convey the function's purpose will help the model understand when to call the function. Avoid using abbreviations or acronyms to shorten function names. The DescriptionAttribute increases token consumption, so use it to provide context and instructions when necessary.
198
+
-**Use descriptive and concise function names**
199
+
200
+
::: zone pivot="csharp"
201
+
202
+
Names that clearly convey the function's purpose will help the model understand when to call the function. Avoid abbreviations or acronyms. Use the `Description` attribute to provide context and instructions when necessary.
203
+
204
+
::: zone-end
205
+
206
+
::: zone pivot="python"
207
+
208
+
Names that clearly convey the function's purpose will help the model understand when to call the function. Avoid abbreviations or acronyms. Use the `description` parameter in the `@kernel_function` decorator to provide context and instructions when necessary.
120
209
121
-
-**Minimize function parameters**
122
-
123
-
Limit the number of function parameters and use primitive types whenever possible. This approach reduces token consumption and simplifies the function signature, making it easier for the LLM to match function parameters effectively.
210
+
::: zone-end
124
211
125
-
-**Name function parameters clearly**
212
+
-**Minimize function parameters**
213
+
Limit the number of function parameters and use primitive types whenever possible. This reduces token consumption and simplifies the function signature.
126
214
127
-
Use descriptive parameter names that clarify their purpose. The parameter names help the LLM assign accurate values, so avoid using abbreviations or acronyms to shorten parameter names.
215
+
-**Name function parameters clearly**
216
+
Use descriptive parameter names that clarify their purpose. Avoid abbreviations or acronyms.
128
217
129
-
Plugins in the Semantic Kernel SDK make it easy to extend your AI application's capabilities. They allow your functions to interact seamlessly with the LLM, whether invoked manually or automatically, creating smarter and more user-friendly experiences. By following best practices for naming and structuring plugins, you ensure the AI can effectively use your functions, keeping your code organized and adaptable to future needs.
218
+
Plugins in the Semantic Kernel SDK make it easy to extend your AI application's capabilities. They allow your functions to interact seamlessly with the LLM, whether invoked manually or automatically, creating smarter and more user-friendly experiences. By following best practices for naming and structuring plugins, you ensure the AI can effectively use your functions, keeping your code organized and adaptable to future needs.
0 commit comments