0
# Core Kernel and Functions
1
2
The foundational layer of Semantic Kernel providing the main orchestration class, function creation and execution, plugin management, and core workflow capabilities.
3
4
## Capabilities
5
6
### Kernel Class
7
8
Central orchestrator that manages AI services, plugins, functions, and execution flow. The Kernel serves as the primary entry point for all Semantic Kernel operations.
9
10
```python { .api }
11
class Kernel:
12
"""
13
The main entry point for Semantic Kernel operations.
14
15
Manages AI services, plugins, functions, and execution flow.
16
"""
17
18
def __init__(
19
self,
20
plugins: KernelPlugin | dict[str, KernelPlugin] | list[KernelPlugin] | None = None,
21
services: AI_SERVICE_CLIENT_TYPE | list[AI_SERVICE_CLIENT_TYPE] | dict[str, AI_SERVICE_CLIENT_TYPE] | None = None,
22
ai_service_selector: AIServiceSelector | None = None,
23
**kwargs
24
):
25
"""
26
Initialize a new Kernel instance.
27
28
Parameters:
29
- plugins: Plugins to add to the kernel
30
- services: AI services to register with the kernel
31
- ai_service_selector: Service selector for choosing AI services
32
- **kwargs: Additional configuration options
33
"""
34
35
async def invoke(
36
self,
37
plugin_name: str | None = None,
38
function_name: str | None = None,
39
arguments: KernelArguments | None = None,
40
**kwargs
41
) -> FunctionResult:
42
"""
43
Invoke a kernel function.
44
45
Parameters:
46
- plugin_name: Name of the plugin containing the function
47
- function_name: Name of the function to invoke
48
- arguments: Arguments to pass to the function
49
- **kwargs: Additional arguments
50
51
Returns:
52
FunctionResult containing the execution result
53
"""
54
55
async def invoke_prompt(
56
self,
57
prompt: str,
58
arguments: KernelArguments | None = None,
59
template_format: str = "semantic-kernel",
60
**kwargs
61
) -> FunctionResult:
62
"""
63
Invoke a prompt-based function.
64
65
Parameters:
66
- prompt: The prompt string to execute
67
- arguments: Arguments for prompt variables
68
- template_format: Template format (semantic-kernel, handlebars, jinja2)
69
- **kwargs: Additional execution settings
70
71
Returns:
72
FunctionResult containing the AI response
73
"""
74
75
async def invoke_stream(
76
self,
77
plugin_name: str | None = None,
78
function_name: str | None = None,
79
arguments: KernelArguments | None = None,
80
**kwargs
81
):
82
"""
83
Invoke a function with streaming response.
84
85
Parameters:
86
- plugin_name: Name of the plugin containing the function
87
- function_name: Name of the function to invoke
88
- arguments: Arguments to pass to the function
89
- **kwargs: Additional arguments
90
91
Yields:
92
Streaming content as it becomes available
93
"""
94
95
def add_service(
96
self,
97
service: AI_SERVICE_CLIENT_TYPE,
98
overwrite: bool = False
99
) -> Kernel:
100
"""
101
Add an AI service to the kernel.
102
103
Parameters:
104
- service: The AI service instance to add
105
- overwrite: Whether to overwrite existing service with same ID
106
107
Returns:
108
Self for method chaining
109
"""
110
111
def add_plugin(
112
self,
113
plugin: KernelPlugin | dict | object,
114
plugin_name: str | None = None
115
) -> KernelPlugin:
116
"""
117
Add a plugin to the kernel.
118
119
Parameters:
120
- plugin: Plugin instance, dict of functions, or object with kernel_function methods
121
- plugin_name: Name for the plugin (auto-generated if not provided)
122
123
Returns:
124
The added KernelPlugin instance
125
"""
126
127
def get_plugin(self, plugin_name: str) -> KernelPlugin:
128
"""
129
Get a plugin by name.
130
131
Parameters:
132
- plugin_name: Name of the plugin to retrieve
133
134
Returns:
135
The requested KernelPlugin instance
136
"""
137
138
def get_function(self, plugin_name: str, function_name: str) -> KernelFunction:
139
"""
140
Get a function from a plugin.
141
142
Parameters:
143
- plugin_name: Name of the plugin containing the function
144
- function_name: Name of the function to retrieve
145
146
Returns:
147
The requested KernelFunction instance
148
"""
149
```
150
151
### Function Creation and Decoration
152
153
Tools for creating executable functions from Python methods and prompt templates.
154
155
```python { .api }
156
@kernel_function
157
def kernel_function(
158
description: str | None = None,
159
name: str | None = None
160
) -> Callable:
161
"""
162
Decorator to convert a Python method into a KernelFunction.
163
164
Parameters:
165
- description: Description of what the function does
166
- name: Name for the function (defaults to method name)
167
168
Returns:
169
Decorated function that can be used by the kernel
170
"""
171
172
class KernelFunction:
173
"""
174
Represents an executable function in the kernel.
175
"""
176
177
def __init__(
178
self,
179
function: Callable,
180
metadata: KernelFunctionMetadata,
181
plugin_name: str | None = None
182
):
183
"""
184
Initialize a KernelFunction.
185
186
Parameters:
187
- function: The callable Python function
188
- metadata: Function metadata including parameters and description
189
- plugin_name: Name of the plugin this function belongs to
190
"""
191
192
async def invoke(
193
self,
194
kernel: Kernel,
195
arguments: KernelArguments | None = None
196
) -> FunctionResult:
197
"""
198
Invoke the function with given arguments.
199
200
Parameters:
201
- kernel: The kernel instance for execution context
202
- arguments: Arguments to pass to the function
203
204
Returns:
205
FunctionResult containing the execution result
206
"""
207
208
@property
209
def name(self) -> str:
210
"""Get the function name."""
211
212
@property
213
def plugin_name(self) -> str:
214
"""Get the plugin name this function belongs to."""
215
216
@property
217
def description(self) -> str:
218
"""Get the function description."""
219
220
@property
221
def parameters(self) -> list[KernelParameterMetadata]:
222
"""Get the function parameter metadata."""
223
224
class KernelFunctionFromMethod(KernelFunction):
225
"""
226
A KernelFunction created from a Python method.
227
"""
228
229
def __init__(
230
self,
231
method: Callable,
232
plugin_name: str | None = None,
233
function_name: str | None = None,
234
description: str | None = None
235
):
236
"""
237
Create a KernelFunction from a Python method.
238
239
Parameters:
240
- method: The Python method to wrap
241
- plugin_name: Name of the plugin this function belongs to
242
- function_name: Name for the function (defaults to method name)
243
- description: Description of the function
244
"""
245
246
class KernelFunctionFromPrompt(KernelFunction):
247
"""
248
A KernelFunction created from a prompt template.
249
"""
250
251
def __init__(
252
self,
253
function_name: str,
254
plugin_name: str,
255
description: str,
256
prompt: str,
257
template_format: str = "semantic-kernel",
258
prompt_execution_settings: PromptExecutionSettings | None = None
259
):
260
"""
261
Create a KernelFunction from a prompt template.
262
263
Parameters:
264
- function_name: Name of the function
265
- plugin_name: Name of the plugin this function belongs to
266
- description: Description of the function
267
- prompt: The prompt template string
268
- template_format: Template format (semantic-kernel, handlebars, jinja2)
269
- prompt_execution_settings: Execution settings for the AI service
270
"""
271
```
272
273
### Plugin Management
274
275
Tools for organizing and managing collections of related functions.
276
277
```python { .api }
278
class KernelPlugin:
279
"""
280
A collection of related kernel functions.
281
"""
282
283
def __init__(
284
self,
285
name: str,
286
description: str | None = None,
287
functions: dict[str, KernelFunction] | None = None
288
):
289
"""
290
Initialize a KernelPlugin.
291
292
Parameters:
293
- name: Name of the plugin
294
- description: Description of the plugin's purpose
295
- functions: Dictionary of functions in this plugin
296
"""
297
298
def add_function(self, function: KernelFunction) -> None:
299
"""
300
Add a function to this plugin.
301
302
Parameters:
303
- function: The KernelFunction to add
304
"""
305
306
def get_function(self, function_name: str) -> KernelFunction:
307
"""
308
Get a function by name.
309
310
Parameters:
311
- function_name: Name of the function to retrieve
312
313
Returns:
314
The requested KernelFunction
315
"""
316
317
@property
318
def name(self) -> str:
319
"""Get the plugin name."""
320
321
@property
322
def description(self) -> str:
323
"""Get the plugin description."""
324
325
@property
326
def functions(self) -> dict[str, KernelFunction]:
327
"""Get all functions in this plugin."""
328
329
class KernelArguments:
330
"""
331
Arguments container for kernel function invocations.
332
"""
333
334
def __init__(self, **kwargs):
335
"""
336
Initialize KernelArguments with keyword arguments.
337
338
Parameters:
339
- **kwargs: Named arguments for function invocation
340
"""
341
342
def __getitem__(self, key: str):
343
"""Get argument value by key."""
344
345
def __setitem__(self, key: str, value):
346
"""Set argument value by key."""
347
348
def get(self, key: str, default=None):
349
"""
350
Get argument value with optional default.
351
352
Parameters:
353
- key: Argument name
354
- default: Default value if key not found
355
356
Returns:
357
Argument value or default
358
"""
359
360
class FunctionResult:
361
"""
362
Container for function execution results.
363
"""
364
365
def __init__(
366
self,
367
function: KernelFunction,
368
value: Any = None,
369
metadata: dict | None = None
370
):
371
"""
372
Initialize a FunctionResult.
373
374
Parameters:
375
- function: The function that was executed
376
- value: The result value from function execution
377
- metadata: Additional metadata about the execution
378
"""
379
380
@property
381
def value(self) -> Any:
382
"""Get the result value."""
383
384
@property
385
def metadata(self) -> dict:
386
"""Get the result metadata."""
387
388
def __str__(self) -> str:
389
"""String representation of the result."""
390
```
391
392
### Function Metadata
393
394
Metadata classes for describing function signatures, parameters, and capabilities.
395
396
```python { .api }
397
class KernelFunctionMetadata:
398
"""
399
Metadata describing a kernel function's signature and capabilities.
400
"""
401
402
def __init__(
403
self,
404
name: str,
405
plugin_name: str,
406
description: str | None = None,
407
parameters: list[KernelParameterMetadata] | None = None,
408
return_parameter: KernelParameterMetadata | None = None
409
):
410
"""
411
Initialize function metadata.
412
413
Parameters:
414
- name: Function name
415
- plugin_name: Plugin name containing this function
416
- description: Function description
417
- parameters: List of parameter metadata
418
- return_parameter: Return type metadata
419
"""
420
421
@property
422
def name(self) -> str:
423
"""Get the function name."""
424
425
@property
426
def plugin_name(self) -> str:
427
"""Get the plugin name."""
428
429
@property
430
def description(self) -> str:
431
"""Get the function description."""
432
433
@property
434
def parameters(self) -> list[KernelParameterMetadata]:
435
"""Get the parameter metadata list."""
436
437
class KernelParameterMetadata:
438
"""
439
Metadata describing a function parameter.
440
"""
441
442
def __init__(
443
self,
444
name: str,
445
description: str,
446
default_value: str | None = None,
447
type_: str = "str",
448
is_required: bool = True
449
):
450
"""
451
Initialize parameter metadata.
452
453
Parameters:
454
- name: Parameter name
455
- description: Parameter description
456
- default_value: Default value if parameter is optional
457
- type_: Parameter type as string
458
- is_required: Whether parameter is required
459
"""
460
461
@property
462
def name(self) -> str:
463
"""Get the parameter name."""
464
465
@property
466
def description(self) -> str:
467
"""Get the parameter description."""
468
469
@property
470
def default_value(self) -> str | None:
471
"""Get the default value."""
472
473
@property
474
def type_(self) -> str:
475
"""Get the parameter type."""
476
477
@property
478
def is_required(self) -> bool:
479
"""Check if parameter is required."""
480
```
481
482
## Usage Examples
483
484
### Creating a Simple Plugin
485
486
```python
487
from semantic_kernel import Kernel
488
from semantic_kernel.functions import kernel_function
489
490
class WeatherPlugin:
491
@kernel_function(
492
description="Get current weather for a location",
493
name="get_weather"
494
)
495
def get_current_weather(self, location: str, units: str = "fahrenheit") -> str:
496
"""Get weather information for a location."""
497
# Implementation would call actual weather API
498
return f"The weather in {location} is 72°{units[0].upper()}"
499
500
# Use the plugin
501
kernel = Kernel()
502
weather_plugin = WeatherPlugin()
503
kernel.add_plugin(weather_plugin, plugin_name="weather")
504
505
# Invoke the function
506
result = await kernel.invoke("weather", "get_weather", location="Seattle")
507
print(result.value) # "The weather in Seattle is 72°F"
508
```
509
510
### Creating Functions from Prompts
511
512
```python
513
from semantic_kernel.functions import KernelFunctionFromPrompt
514
515
# Create a prompt-based function
516
summarize_function = KernelFunctionFromPrompt(
517
function_name="summarize",
518
plugin_name="text",
519
description="Summarize text content",
520
prompt="Summarize the following text in 2-3 sentences: {{$input}}"
521
)
522
523
# Add to kernel and use
524
kernel.add_plugin({"summarize": summarize_function}, plugin_name="text")
525
result = await kernel.invoke("text", "summarize", input="Long text to summarize...")
526
```