Adicionar código nativo como um plug-in
A maneira mais fácil de fornecer a um agente de IA recursos que não têm suporte nativo é encapsular o código nativo em um plug-in. Isso permite que você aproveite suas habilidades existentes como desenvolvedor de aplicativos para estender os recursos de seus agentes de IA.
Nos bastidores, o Semantic Kernel usará as descrições que você fornecer, juntamente com a reflexão, para descrever semanticamente o plug-in para o agente de IA. Isso permite que o agente de IA entenda os recursos do plug-in e como interagir com ele.
Fornecendo ao LLM as informações corretas
Ao criar um plug-in, você precisa fornecer ao agente de IA as informações corretas para entender os recursos do plug-in e suas funções. Isso inclui:
- O nome do plugin
- Os nomes das funções
- As descrições das funções
- Os parâmetros das funções
- O esquema dos parâmetros
O valor do Semantic Kernel é que ele pode gerar automaticamente a maioria dessas informações a partir do próprio código. Como desenvolvedor, isso significa apenas que você deve fornecer as descrições semânticas das funções e parâmetros para que o agente de IA possa entendê-los. Se você comentar e anotar corretamente seu código, no entanto, provavelmente já tem essas informações em mãos.
Abaixo, veremos as duas maneiras diferentes de fornecer código nativo ao seu agente de IA e como fornecer essas informações semânticas.
Definindo um plug-in usando uma classe
A maneira mais fácil de criar um plug-in nativo é começar com uma classe e, em seguida, adicionar métodos anotados com o KernelFunction atributo. Também é recomendável usar liberalmente a Description anotação para fornecer ao agente de IA as informações necessárias para entender a função.
public class LightsPlugin
{
private readonly List<LightModel> _lights;
public LightsPlugin(LoggerFactory loggerFactory, List<LightModel> lights)
{
_lights = lights;
}
[KernelFunction("get_lights")]
[Description("Gets a list of lights and their current state")]
[return: Description("An array of lights")]
public async Task<List<LightModel>> GetLightsAsync()
{
return _lights;
}
[KernelFunction("change_state")]
[Description("Changes the state of the light")]
[return: Description("The updated state of the light; will return null if the light does not exist")]
public async Task<LightModel?> ChangeStateAsync(LightModel changeState)
{
// Find the light to change
var light = _lights.FirstOrDefault(l => l.Id == changeState.Id);
// If the light does not exist, return null
if (light == null)
{
return null;
}
// Update the light state
light.IsOn = changeState.IsOn;
light.Brightness = changeState.Brightness;
light.Color = changeState.Color;
return light;
}
}
from typing import List, Optional, Annotated
class LightsPlugin:
def __init__(self, lights: List[LightModel]):
self._lights = lights
@kernel_function
async def get_lights(self) -> Annotated[List[LightModel], "An array of lights"]:
"""Gets a list of lights and their current state."""
return self._lights
@kernel_function
async def change_state(
self,
change_state: LightModel
) -> Annotated[Optional[LightModel], "The updated state of the light; will return null if the light does not exist"]:
"""Changes the state of the light."""
for light in self._lights:
if light["id"] == change_state["id"]:
light["is_on"] = change_state.get("is_on", light["is_on"])
light["brightness"] = change_state.get("brightness", light["brightness"])
light["hex"] = change_state.get("hex", light["hex"])
return light
return None
public class LightsPlugin {
// Mock data for the lights
private final Map<Integer, LightModel> lights = new HashMap<>();
public LightsPlugin() {
lights.put(1, new LightModel(1, "Table Lamp", false, LightModel.Brightness.MEDIUM, "#FFFFFF"));
lights.put(2, new LightModel(2, "Porch light", false, LightModel.Brightness.HIGH, "#FF0000"));
lights.put(3, new LightModel(3, "Chandelier", true, LightModel.Brightness.LOW, "#FFFF00"));
}
@DefineKernelFunction(name = "get_lights", description = "Gets a list of lights and their current state")
public List<LightModel> getLights() {
System.out.println("Getting lights");
return new ArrayList<>(lights.values());
}
@DefineKernelFunction(name = "change_state", description = "Changes the state of the light")
public LightModel changeState(
@KernelFunctionParameter(
name = "model",
description = "The new state of the model to set. Example model: " +
"{\"id\":99,\"name\":\"Head Lamp\",\"isOn\":false,\"brightness\":\"MEDIUM\",\"color\":\"#FFFFFF\"}",
type = LightModel.class) LightModel model
) {
System.out.println("Changing light " + model.getId() + " " + model.getIsOn());
if (!lights.containsKey(model.getId())) {
throw new IllegalArgumentException("Light not found");
}
lights.put(model.getId(), model);
return lights.get(model.getId());
}
}
Dica
Como os LLMs são predominantemente treinados em código Python, é recomendável usar snake_case para nomes e parâmetros de função (mesmo se você estiver usando C# ou Java). Isso ajudará o agente de IA a entender melhor a função e seus parâmetros.
Se sua função tiver um objeto complexo como uma variável de entrada, o Semantic Kernel também gerará um esquema para esse objeto e o passará para o agente de IA. Semelhante às funções, você deve fornecer Description anotações para propriedades que não são óbvias para a IA. Abaixo está a definição da LightState classe e da Brightness enumeração.
using System.Text.Json.Serialization;
public class LightModel
{
[JsonPropertyName("id")]
public int Id { get; set; }
[JsonPropertyName("name")]
public string? Name { get; set; }
[JsonPropertyName("is_on")]
public bool? IsOn { get; set; }
[JsonPropertyName("brightness")]
public enum? Brightness { get; set; }
[JsonPropertyName("color")]
[Description("The color of the light with a hex code (ensure you include the # symbol)")]
public string? Color { get; set; }
}
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum Brightness
{
Low,
Medium,
High
}
from typing import TypedDict
class LightModel(TypedDict):
id: int
name: str
is_on: bool | None
brightness: int | None
hex: str | None
public class LightModel {
private int id;
private String name;
private Boolean isOn;
private Brightness brightness;
private String color;
public enum Brightness {
LOW,
MEDIUM,
HIGH
}
public LightModel(int id, String name, Boolean isOn, Brightness brightness, String color) {
this.id = id;
this.name = name;
this.isOn = isOn;
this.brightness = brightness;
this.color = color;
}
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public Boolean getIsOn() {
return isOn;
}
public void setIsOn(Boolean isOn) {
this.isOn = isOn;
}
public Brightness getBrightness() {
return brightness;
}
public void setBrightness(Brightness brightness) {
this.brightness = brightness;
}
public String getColor() {
return color;
}
public void setColor(String color) {
this.color = color;
}
}
Observação
Embora este seja um exemplo "divertido", ele faz um bom trabalho mostrando o quão complexos os parâmetros de um plug-in podem ser. Neste único caso, temos um objeto complexo com quatro tipos diferentes de propriedades: um inteiro, string, booleano e enum. O valor do Semantic Kernel é que ele pode gerar automaticamente o esquema para esse objeto e passá-lo para o agente de IA e empacotar os parâmetros gerados pelo agente de IA no objeto correto.
Quando terminar de criar sua classe de plugin, você pode adicioná-la ao kernel usando os AddFromType<> métodos or AddFromObject .
Dica
Ao criar uma função, sempre pergunte a si mesmo "como posso dar ajuda adicional à IA para usar essa função?" Isso pode incluir o uso de tipos de entrada específicos (evite cadeias de caracteres sempre que possível), fornecendo descrições e exemplos.
Adicionando um plugin usando o AddFromObject método
O AddFromObject método permite que você adicione uma instância da classe de plug-in diretamente à coleção de plug-ins, caso queira controlar diretamente como o plug-in é construído.
Por exemplo, o LightsPlugin construtor da classe requer a lista de luzes. Nesse caso, você pode criar uma instância da classe de plug-in e adicioná-la à coleção de plug-ins.
List<LightModel> lights = new()
{
new LightModel { Id = 1, Name = "Table Lamp", IsOn = false, Brightness = Brightness.Medium, Color = "#FFFFFF" },
new LightModel { Id = 2, Name = "Porch light", IsOn = false, Brightness = Brightness.High, Color = "#FF0000" },
new LightModel { Id = 3, Name = "Chandelier", IsOn = true, Brightness = Brightness.Low, Color = "#FFFF00" }
};
kernel.Plugins.AddFromObject(new LightsPlugin(lights));
Adicionando um plugin usando o AddFromType<> método
Ao usar o AddFromType<> método, o kernel usará automaticamente a injeção de dependência para criar uma instância da classe de plug-in e adicioná-la à coleção de plug-ins.
Isso é útil se o construtor exigir que serviços ou outras dependências sejam injetados no plug-in. Por exemplo, nossa LightsPlugin classe pode exigir que um agente e um serviço de luz sejam injetados nele em vez de uma lista de luzes.
public class LightsPlugin
{
private readonly Logger _logger;
private readonly LightService _lightService;
public LightsPlugin(LoggerFactory loggerFactory, LightService lightService)
{
_logger = loggerFactory.CreateLogger<LightsPlugin>();
_lightService = lightService;
}
[KernelFunction("get_lights")]
[Description("Gets a list of lights and their current state")]
[return: Description("An array of lights")]
public async Task<List<LightModel>> GetLightsAsync()
{
_logger.LogInformation("Getting lights");
return lightService.GetLights();
}
[KernelFunction("change_state")]
[Description("Changes the state of the light")]
[return: Description("The updated state of the light; will return null if the light does not exist")]
public async Task<LightModel?> ChangeStateAsync(LightModel changeState)
{
_logger.LogInformation("Changing light state");
return lightService.ChangeState(changeState);
}
}
Com a Injeção de Dependência, você pode adicionar os serviços e plug-ins necessários ao construtor de kernel antes de compilar o kernel.
var builder = Kernel.CreateBuilder();
// Add dependencies for the plugin
builder.Services.AddLogging(loggingBuilder => loggingBuilder.AddConsole().SetMinimumLevel(LogLevel.Trace));
builder.Services.AddSingleton<LightService>();
// Add the plugin to the kernel
builder.Plugins.AddFromType<LightsPlugin>("Lights");
// Build the kernel
Kernel kernel = builder.Build();
Definindo um plug-in usando uma coleção de funções
Menos comum, mas ainda útil, é definir um plugin usando uma coleção de funções. Isso é particularmente útil se você precisar criar dinamicamente um plug-in a partir de um conjunto de funções em tempo de execução.
O uso desse processo requer que você use a fábrica de funções para criar funções individuais antes de adicioná-las ao plug-in.
kernel.Plugins.AddFromFunctions("time_plugin",
[
KernelFunctionFactory.CreateFromMethod(
method: () => DateTime.Now,
functionName: "get_time",
description: "Get the current time"
),
KernelFunctionFactory.CreateFromMethod(
method: (DateTime start, DateTime end) => (end - start).TotalSeconds,
functionName: "diff_time",
description: "Get the difference between two times in seconds"
)
]);
Estratégias adicionais para adicionar código nativo com Injeção de Dependência
Se você estiver trabalhando com Injeção de Dependência, existem estratégias adicionais que você pode adotar para criar e adicionar plug-ins ao kernel. Abaixo estão alguns exemplos de como você pode adicionar um plug-in usando a injeção de dependência.
Injetar uma coleção de plug-ins
Dica
Recomendamos tornar sua coleção de plug-ins um serviço transitório para que ela seja descartada após cada uso, pois a coleção de plug-ins é mutável. Criar uma nova coleção de plugins para cada uso é barato, portanto, não deve ser uma preocupação de desempenho.
var builder = Host.CreateApplicationBuilder(args);
// Create native plugin collection
builder.Services.AddTransient((serviceProvider)=>{
KernelPluginCollection pluginCollection = [];
pluginCollection.AddFromType<LightsPlugin>("Lights");
return pluginCollection;
});
// Create the kernel service
builder.Services.AddTransient<Kernel>((serviceProvider)=> {
KernelPluginCollection pluginCollection = serviceProvider.GetRequiredService<KernelPluginCollection>();
return new Kernel(serviceProvider, pluginCollection);
});
Dica
Conforme mencionado no artigo do kernel, o kernel é extremamente leve, portanto, criar um novo kernel para cada uso como um transiente não é uma preocupação de desempenho.
Gere seus plugins como singletons
Os plug-ins não são mutáveis, portanto, normalmente é seguro criá-los como singletons. Isso pode ser feito usando a fábrica de plug-ins e adicionando o plug-in resultante à sua coleção de serviços.
var builder = Host.CreateApplicationBuilder(args);
// Create singletons of your plugin
builder.Services.AddKeyedSingleton("LightPlugin", (serviceProvider, key) => {
return KernelPluginFactory.CreateFromType<LightsPlugin>();
});
// Create a kernel service with singleton plugin
builder.Services.AddTransient((serviceProvider)=> {
KernelPluginCollection pluginCollection = [
serviceProvider.GetRequiredKeyedService<KernelPlugin>("LightPlugin")
];
return new Kernel(serviceProvider, pluginCollection);
});
Adicionando um plugin usando o add_plugin método
O add_plugin método permite adicionar uma instância de plug-in ao kernel. Abaixo está um exemplo de como você pode construir a LightsPlugin classe e adicioná-la ao kernel.
# Create the kernel
kernel = Kernel()
# Create dependencies for the plugin
lights = [
{"id": 1, "name": "Table Lamp", "is_on": False, "brightness": 100, "hex": "FF0000"},
{"id": 2, "name": "Porch light", "is_on": False, "brightness": 50, "hex": "00FF00"},
{"id": 3, "name": "Chandelier", "is_on": True, "brightness": 75, "hex": "0000FF"},
]
# Create the plugin
lights_plugin = LightsPlugin(lights)
# Add the plugin to the kernel
kernel.add_plugin(lights_plugin)
Adicionando um plugin usando o createFromObject método
O createFromObject método permite que você construa um plug-in de kernel a partir de um objeto com métodos anotados.
// Import the LightsPlugin
KernelPlugin lightPlugin = KernelPluginFactory.createFromObject(new LightsPlugin(),
"LightsPlugin");
Este plugin pode então ser adicionado a um kernel.
// Create a kernel with Azure OpenAI chat completion and plugin
Kernel kernel = Kernel.builder()
.withAIService(ChatCompletionService.class, chatCompletionService)
.withPlugin(lightPlugin)
.build();
Próximas etapas
Agora que você sabe como criar um plug-in, pode aprender a usá-lo com seu agente de IA. Dependendo do tipo de funções que você adicionou aos seus plug-ins, existem diferentes padrões que você deve seguir. Para funções de recuperação, consulte o artigo usando funções de recuperação. Para funções de automação de tarefas, consulte o artigo usando funções de automação de tarefas.