06-03-01 — Semantic Kernel: plugins, kernel, AI services

Arquitetura do Kernel

O Kernel é o container central. Você registra nele:

• AI Services — LLMs, embedding models, chat completion
• Plugins — coleções de funções (kernel functions) que o LLM pode invocar
• Memory/VectorStore — para RAG e memória semântica
• Filters — middleware para logging, safety, retry

Exemplo completo em C#

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.AzureOpenAI;

// 1. Construir o Kernel com Azure OpenAI
var kernel = Kernel.CreateBuilder()
    .AddAzureOpenAIChatCompletion(
        deploymentName: "gpt-4o",
        endpoint: "https://meu-recurso.openai.azure.com/",
        apiKey: Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY")!)
    .Build();

// 2. Definir um Plugin com KernelFunction
public class ClimaPlugin
{
    [KernelFunction("obter_clima")]
    [Description("Retorna a temperatura atual de uma cidade")]
    public async Task<string> ObterClimaAsync(
        [Description("Nome da cidade")] string cidade)
    {
        // Integração real com API de clima aqui
        return $"Temperatura em {cidade}: 28°C, parcialmente nublado";
    }
}

// 3. Registrar o plugin
kernel.Plugins.AddFromType<ClimaPlugin>();

// 4. Invocar com tool calling automático
var settings = new AzureOpenAIPromptExecutionSettings
{
    ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions
};

var result = await kernel.InvokePromptAsync(
    "Qual o clima em São Paulo hoje? Devo levar guarda-chuva?",
    new KernelArguments(settings));

Console.WriteLine(result);

Semantic Functions — prompts como funções

// Prompt templates como funções do kernel
var summarizeFunction = kernel.CreateFunctionFromPrompt(
    promptTemplate: "Resuma o seguinte texto em 3 bullets:\n\n{{$input}}",
    functionName: "Resumir",
    description: "Resume um texto em bullets"
);

var resumo = await kernel.InvokeAsync(summarizeFunction, new KernelArguments
{
    ["input"] = textoLongo
});

// Ou via arquivo .skprompt.txt + config.json (para prompts complexos)
var plugin = kernel.ImportPluginFromPromptDirectory("./Plugins/Escrita");

Exemplo em Python

import asyncio
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
from semantic_kernel.functions import kernel_function

kernel = Kernel()

# Adiciona Azure OpenAI como AI service
kernel.add_service(AzureChatCompletion(
    deployment_name="gpt-4o",
    endpoint="https://meu-recurso.openai.azure.com/",
    api_key=os.environ["AZURE_OPENAI_KEY"]
))

# Define plugin Python
class ClimaPlugin:
    @kernel_function(description="Retorna temperatura de uma cidade")
    def obter_clima(self, cidade: str) -> str:
        return f"Temperatura em {cidade}: 25°C"

kernel.add_plugin(ClimaPlugin(), plugin_name="Clima")

# Função semântica inline
resposta = await kernel.invoke_prompt(
    "Qual o clima em {{$cidade}}? Vale a pena sair?",
    arguments=KernelArguments(cidade="Rio de Janeiro")
)

Planners

Planners são agentes que decompõem um objetivo em passos usando os plugins disponíveis:

• FunctionChoiceBehavior.Auto() — tool calling automático (recomendado para modelos modernos)
• Handlebars Planner — gera um plano em template Handlebars, mais determinístico
• Stepwise Planner — loop ReAct clássico

// Planner via tool calling nativo (recomendado)
var executionSettings = new OpenAIPromptExecutionSettings
{
    FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
};

var chatHistory = new ChatHistory();
chatHistory.AddUserMessage("Pesquise o clima e me diga que roupa usar hoje em SP");

var chatService = kernel.GetRequiredService<IChatCompletionService>();
var response = await chatService.GetChatMessageContentAsync(
    chatHistory,
    executionSettings,
    kernel);

Memory e RAG

// SK com Azure AI Search como vector store
using Microsoft.SemanticKernel.Connectors.AzureAISearch;

var memoryBuilder = new MemoryBuilder()
    .WithAzureOpenAITextEmbeddingGeneration("text-embedding-3-small", endpoint, apiKey)
    .WithMemoryStore(new AzureAISearchMemoryStore(searchEndpoint, searchApiKey));

var memory = memoryBuilder.Build();

// Salvar e buscar memórias
await memory.SaveInformationAsync("contratos", 
    id: "contrato-vale-2024",
    text: "Contrato Vale: valor R$2M, prazo 24 meses, multa 10%");

var resultado = await memory.SearchAsync("contratos", "multa contratual Vale");