Introdução ao Semantic Kernel: Como Construir Agentes de IA com Eficiência

semantic-kernelagentes-iamicrosoftinteligencia-artificialautomacao

Agents AI Semantic Kernel

Introdução

O Semantic Kernel é um kit de desenvolvimento leve e de código aberto criado pela Microsoft que está revolucionando a forma como construímos agentes de IA. Se você já se perguntou como criar agentes inteligentes que se integram perfeitamente aos seus sistemas existentes, este artigo é para você.

O que é o Semantic Kernel?

O Semantic Kernel é um framework desenvolvido pela Microsoft que permite a criação de agentes de IA de forma:

✅ Simples e intuitiva
✅ Altamente flexível
✅ Integrada com sistemas existentes
✅ Suporte a múltiplas linguagens (C#, Python, Java)
✅ Open-source e gratuito

Por que escolher o Semantic Kernel?

Leveza: Framework minimalista sem complexidade desnecessária
Flexibilidade: Adapta-se a qualquer cenário de negócio
Escalabilidade: Desde protótipos até soluções empresariais
Integração: Conecta facilmente com APIs e serviços existentes
Comunidade: Suportado pela Microsoft e comunidade ativa

Componentes Fundamentais

Building Blocks

O Semantic Kernel é construído sobre três pilares fundamentais:

1. Plugins 🔌

Os plugins são o coração do Semantic Kernel. Eles permitem que seus agentes de IA:

Executem ações externas
Conectem-se a APIs existentes
Acessem bases de dados
Interajam com serviços web
Processem documentos

Exemplo de Plugin:

public class EmailPlugin
{
    [KernelFunction("enviar_email")]
    [Description("Envia um email profissional")]
    public async Task<string> EnviarEmailAsync(
        [Description("Destinatário do email")] string destinatario,
        [Description("Assunto do email")] string assunto,
        [Description("Corpo do email")] string corpo)
    {
        // Lógica para enviar email
        await emailService.SendAsync(destinatario, assunto, corpo);
        return "Email enviado com sucesso!";
    }
}

2. Planner 🎯

O planner é o cérebro organizacional do seu agente. Ele:

Cria sequências de ações
Organiza tarefas complexas
Decide qual plugin usar
Otimiza a execução de tarefas

Exemplo de Uso do Planner:

// Configurar o planner
var planner = new FunctionCallingStepwisePlanner();
 
// Criar um plano para uma tarefa complexa
var plan = await planner.CreatePlanAsync(
    kernel, 
    "Analise os dados de vendas do último trimestre e envie um relatório por email para a diretoria"
);
 
// Executar o plano
var resultado = await plan.InvokeAsync(kernel);

3. Persona 🎭

A persona define a personalidade e comportamento do seu agente:

Tom de comunicação
Expertise específica
Regras de comportamento
Contexto de atuação

Exemplo de Persona:

var personaAssistente = @"
Você é Marina, uma assistente executiva experiente com 15 anos de experiência.
Suas características:
- Comunicação profissional e concisa
- Expertise em gestão de agenda e projetos
- Sempre confirma ações importantes
- Proativa em sugerir melhorias
- Mantém confidencialidade absoluta
 
Você deve sempre:
- Ser prestativa e eficiente
- Confirmar detalhes importantes
- Sugerir otimizações quando apropriado
- Manter um tom respeitoso e profissional
";
 
var kernel = Kernel.CreateBuilder()
    .AddAzureOpenAIChatCompletion(deploymentName, endpoint, apiKey)
    .Build();
 
var response = await kernel.InvokePromptAsync($"{personaAssistente}\n\nTarefa: {tarefaUsuario}");

Exemplo Prático 1: Agente de Automação de Email

Vamos criar um agente que automatiza o envio de emails profissionais:

Configuração Inicial

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;
 
// Configurar o kernel
var builder = Kernel.CreateBuilder();
builder.AddAzureOpenAIChatCompletion(
    deploymentName: "gpt-4",
    endpoint: "https://seu-recurso.openai.azure.com/",
    apiKey: "sua-chave-api"
);
 
var kernel = builder.Build();

Plugin de Email

public class EmailAutomationPlugin
{
    private readonly IEmailService _emailService;
    
    public EmailAutomationPlugin(IEmailService emailService)
    {
        _emailService = emailService;
    }
    
    [KernelFunction("redigir_email_profissional")]
    [Description("Redige um email profissional com base no contexto")]
    public async Task<string> RedigirEmailProfissionalAsync(
        [Description("Contexto ou objetivo do email")] string contexto,
        [Description("Tom desejado (formal, amigável, urgente)")] string tom = "formal")
    {
        var prompt = $@"
        Redija um email profissional com as seguintes características:
        Contexto: {contexto}
        Tom: {tom}
        
        O email deve ter:
        - Assunto claro e objetivo
        - Saudação apropriada
        - Corpo bem estruturado
        - Fechamento profissional
        - Assinatura padrão
        ";
        
        var resultado = await kernel.InvokePromptAsync(prompt);
        return resultado.GetValue<string>();
    }
    
    [KernelFunction("enviar_email")]
    [Description("Envia o email redigido")]
    public async Task<string> EnviarEmailAsync(
        [Description("Email do destinatário")] string destinatario,
        [Description("Assunto do email")] string assunto,
        [Description("Corpo do email")] string corpo)
    {
        await _emailService.SendEmailAsync(destinatario, assunto, corpo);
        return $"Email enviado com sucesso para {destinatario}";
    }
}

Uso do Agente

// Registrar o plugin
kernel.Plugins.AddFromType<EmailAutomationPlugin>();
 
// Definir a persona
var personaAssistente = @"
Você é um assistente de comunicação corporativa especializado.
Sempre redija emails claros, profissionais e eficazes.
Mantenha um tom respeitoso e objetivo.
";
 
// Usar o agente
var instrucao = $@"{personaAssistente}
 
Tarefa: Preciso enviar um email para o cliente João Silva (joao@empresa.com) 
informando que o projeto foi finalizado e está pronto para entrega. 
Use um tom profissional mas amigável.
";
 
var resultado = await kernel.InvokePromptAsync(instrucao);
Console.WriteLine(resultado);

Exemplo Prático 2: Agente de Gestão de Projetos

Vamos criar um agente que automatiza tarefas de gestão de projetos:

Plugin de Projetos

public class ProjectManagementPlugin
{
    private readonly IProjectService _projectService;
    
    [KernelFunction("criar_tarefa")]
    [Description("Cria uma nova tarefa no projeto")]
    public async Task<string> CriarTarefaAsync(
        [Description("Nome da tarefa")] string nomeTarefa,
        [Description("Descrição detalhada")] string descricao,
        [Description("Prioridade (baixa, média, alta)")] string prioridade,
        [Description("Data de vencimento no formato dd/MM/yyyy")] string dataVencimento)
    {
        var tarefa = new Tarefa
        {
            Nome = nomeTarefa,
            Descricao = descricao,
            Prioridade = prioridade,
            DataVencimento = DateTime.ParseExact(dataVencimento, "dd/MM/yyyy", null)
        };
        
        await _projectService.CriarTarefaAsync(tarefa);
        return $"Tarefa '{nomeTarefa}' criada com sucesso";
    }
    
    [KernelFunction("listar_tarefas_pendentes")]
    [Description("Lista todas as tarefas pendentes")]
    public async Task<string> ListarTarefasPendentesAsync()
    {
        var tarefas = await _projectService.GetTarefasPendentesAsync();
        
        var lista = string.Join("\n", tarefas.Select(t => 
            $"- {t.Nome} (Prioridade: {t.Prioridade}, Vencimento: {t.DataVencimento:dd/MM/yyyy})"));
            
        return $"Tarefas pendentes:\n{lista}";
    }
    
    [KernelFunction("gerar_relatorio_status")]
    [Description("Gera relatório de status do projeto")]
    public async Task<string> GerarRelatorioStatusAsync(
        [Description("ID do projeto")] string projetoId)
    {
        var projeto = await _projectService.GetProjetoAsync(projetoId);
        var tarefasConcluidas = await _projectService.GetTarefasConcluidasAsync(projetoId);
        var tarefasPendentes = await _projectService.GetTarefasPendentesAsync(projetoId);
        
        var percentualConclusao = (double)tarefasConcluidas.Count / 
                                 (tarefasConcluidas.Count + tarefasPendentes.Count) * 100;
        
        return $@"
        📊 RELATÓRIO DE STATUS - {projeto.Nome}
        
        📈 Progresso: {percentualConclusao:F1}%
        ✅ Tarefas concluídas: {tarefasConcluidas.Count}
        ⏳ Tarefas pendentes: {tarefasPendentes.Count}
        📅 Data prevista: {projeto.DataPrevista:dd/MM/yyyy}
        
        🎯 Próximas ações críticas:
        {string.Join("\n", tarefasPendentes.Take(3).Select(t => $"- {t.Nome}"))}
        ";
    }
}

Agente Inteligente de Projetos

public class AgenteGestorProjetos
{
    private readonly Kernel _kernel;
    
    public AgenteGestorProjetos(Kernel kernel)
    {
        _kernel = kernel;
        _kernel.Plugins.AddFromType<ProjectManagementPlugin>();
    }
    
    public async Task<string> ProcessarSolicitacaoAsync(string solicitacao)
    {
        var personaGestor = @"
        Você é Alex, um gerente de projetos sênior com 10 anos de experiência.
        Especialidades:
        - Metodologias ágeis (Scrum, Kanban)
        - Gestão de riscos e prazos
        - Comunicação eficaz com stakeholders
        - Otimização de processos
        
        Você deve:
        - Ser proativo em identificar problemas
        - Sugerir melhorias nos processos
        - Manter foco na entrega de valor
        - Comunicar de forma clara e objetiva
        ";
        
        var prompt = $@"{personaGestor}
        
        Solicitação: {solicitacao}
        
        Analise a solicitação e execute as ações necessárias usando as ferramentas disponíveis.
        ";
        
        var resultado = await _kernel.InvokePromptAsync(prompt);
        return resultado.GetValue<string>();
    }
}

Exemplo de Uso

var agente = new AgenteGestorProjetos(kernel);
 
// Exemplos de solicitações
var solicitacoes = new[]
{
    "Crie uma tarefa para revisar a documentação técnica com prioridade alta para 15/12/2024",
    "Me mostre todas as tarefas que estão pendentes",
    "Gere um relatório de status do projeto PRJ-001",
    "Analise o projeto e me diga se estamos dentro do prazo"
};
 
foreach (var solicitacao in solicitacoes)
{
    Console.WriteLine($"📝 Solicitação: {solicitacao}");
    var resposta = await agente.ProcessarSolicitacaoAsync(solicitacao);
    Console.WriteLine($"🤖 Resposta: {resposta}\n");
}

Integração com Azure Functions

Function para Agente via HTTP

[Function("AgenteSemanticKernel")]
public async Task<HttpResponseData> RunAsync(
    [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequestData req)
{
    // Ler a solicitação
    var requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    var request = JsonSerializer.Deserialize<AgenteRequest>(requestBody);
    
    // Configurar o kernel
    var kernel = Kernel.CreateBuilder()
        .AddAzureOpenAIChatCompletion(
            deploymentName: Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT"),
            endpoint: Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT"),
            apiKey: Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")
        )
        .Build();
    
    // Registrar plugins
    kernel.Plugins.AddFromType<EmailAutomationPlugin>();
    kernel.Plugins.AddFromType<ProjectManagementPlugin>();
    
    // Processar solicitação
    var resposta = await kernel.InvokePromptAsync(request.Mensagem);
    
    // Retornar resposta
    var response = req.CreateResponse(HttpStatusCode.OK);
    await response.WriteStringAsync(JsonSerializer.Serialize(new 
    { 
        resposta = resposta.GetValue<string>(),
        timestamp = DateTime.UtcNow
    }));
    
    return response;
}
 
public class AgenteRequest
{
    public string Mensagem { get; set; }
    public string? Contexto { get; set; }
}

Padrões Avançados

1. Chain of Responsibility para Agentes

public abstract class AgenteHandler
{
    protected AgenteHandler _nextHandler;
    
    public AgenteHandler SetNext(AgenteHandler handler)
    {
        _nextHandler = handler;
        return handler;
    }
    
    public abstract Task<string> HandleAsync(string request);
}
 
public class AgenteEmail : AgenteHandler
{
    public override async Task<string> HandleAsync(string request)
    {
        if (request.Contains("email") || request.Contains("enviar"))
        {
            // Processar solicitação de email
            return await ProcessarEmailAsync(request);
        }
        
        return await _nextHandler?.HandleAsync(request) ?? "Não consegui processar esta solicitação";
    }
}
 
public class AgenteProjeto : AgenteHandler
{
    public override async Task<string> HandleAsync(string request)
    {
        if (request.Contains("projeto") || request.Contains("tarefa"))
        {
            // Processar solicitação de projeto
            return await ProcessarProjetoAsync(request);
        }
        
        return await _nextHandler?.HandleAsync(request) ?? "Não consegui processar esta solicitação";
    }
}

2. Factory Pattern para Agentes

public interface IAgenteFactory
{
    IAgenteSemanticKernel CriarAgente(TipoAgente tipo);
}
 
public class AgenteFactory : IAgenteFactory
{
    private readonly Kernel _kernel;
    
    public IAgenteSemanticKernel CriarAgente(TipoAgente tipo)
    {
        return tipo switch
        {
            TipoAgente.Email => new AgenteEmail(_kernel),
            TipoAgente.Projeto => new AgenteProjeto(_kernel),
            TipoAgente.Atendimento => new AgenteAtendimento(_kernel),
            TipoAgente.Vendas => new AgenteVendas(_kernel),
            _ => throw new ArgumentException($"Tipo de agente não suportado: {tipo}")
        };
    }
}

Monitoramento e Observabilidade

Logging Estruturado

public class AgenteComLogging
{
    private readonly ILogger<AgenteComLogging> _logger;
    private readonly Kernel _kernel;
    
    public async Task<string> ProcessarAsync(string input)
    {
        using var activity = Activity.StartActivity("ProcessarSolicitacao");
        activity?.SetTag("input.length", input.Length);
        
        _logger.LogInformation("Iniciando processamento da solicitação", new { Input = input });
        
        var stopwatch = Stopwatch.StartNew();
        
        try
        {
            var resultado = await _kernel.InvokePromptAsync(input);
            stopwatch.Stop();
            
            _logger.LogInformation("Solicitação processada com sucesso", new 
            { 
                DuracaoMs = stopwatch.ElapsedMilliseconds,
                TokensUsados = resultado.Metadata?["Usage"]
            });
            
            return resultado.GetValue<string>();
        }
        catch (Exception ex)
        {
            stopwatch.Stop();
            _logger.LogError(ex, "Erro ao processar solicitação", new 
            { 
                DuracaoMs = stopwatch.ElapsedMilliseconds,
                Input = input 
            });
            throw;
        }
    }
}

Métricas Customizadas

public class AgenteMetrics
{
    private static readonly Counter<long> RequestCounter = 
        Meter.CreateCounter<long>("agente.requests.total");
        
    private static readonly Histogram<double> RequestDuration = 
        Meter.CreateHistogram<double>("agente.request.duration");
        
    private static readonly Gauge<int> ActiveRequests = 
        Meter.CreateGauge<int>("agente.requests.active");
    
    public async Task<string> ProcessarComMetricasAsync(string input)
    {
        var tags = new TagList { ["input.type"] = ClassificarInput(input) };
        
        RequestCounter.Add(1, tags);
        ActiveRequests.Record(1, tags);
        
        var stopwatch = Stopwatch.StartNew();
        
        try
        {
            var resultado = await ProcessarAsync(input);
            return resultado;
        }
        finally
        {
            stopwatch.Stop();
            RequestDuration.Record(stopwatch.Elapsed.TotalSeconds, tags);
            ActiveRequests.Record(-1, tags);
        }
    }
}

Segurança e Boas Práticas

1. Validação de Entrada

public class ValidadorEntrada
{
    private readonly List<string> _palavrasProibidas = new()
    {
        "DELETE", "DROP", "TRUNCATE", "exec", "script"
    };
    
    public bool ValidarEntrada(string input)
    {
        if (string.IsNullOrWhiteSpace(input))
            return false;
            
        if (input.Length > 10000)
            return false;
            
        if (_palavrasProibidas.Any(p => input.Contains(p, StringComparison.OrdinalIgnoreCase)))
            return false;
            
        return true;
    }
}

2. Rate Limiting

public class RateLimiter
{
    private readonly Dictionary<string, DateTime> _lastRequests = new();
    private readonly TimeSpan _interval = TimeSpan.FromSeconds(5);
    
    public bool PodeProcessar(string userId)
    {
        if (!_lastRequests.ContainsKey(userId))
        {
            _lastRequests[userId] = DateTime.UtcNow;
            return true;
        }
        
        var ultimaRequisicao = _lastRequests[userId];
        if (DateTime.UtcNow - ultimaRequisicao >= _interval)
        {
            _lastRequests[userId] = DateTime.UtcNow;
            return true;
        }
        
        return false;
    }
}

3. Gerenciamento de Secrets

public class ConfiguracaoSegura
{
    public static Kernel CriarKernelSeguro()
    {
        var configuration = new ConfigurationBuilder()
            .AddAzureKeyVault(
                vaultUri: Environment.GetEnvironmentVariable("KEY_VAULT_URI"),
                credential: new DefaultAzureCredential()
            )
            .Build();
        
        return Kernel.CreateBuilder()
            .AddAzureOpenAIChatCompletion(
                deploymentName: configuration["AzureOpenAI:DeploymentName"],
                endpoint: configuration["AzureOpenAI:Endpoint"],
                apiKey: configuration["AzureOpenAI:ApiKey"]
            )
            .Build();
    }
}

Casos de Uso Empresariais

1. Assistente Virtual de RH

public class AgenteRH
{
    [KernelFunction("consultar_politicas")]
    public async Task<string> ConsultarPoliticasAsync(string tema)
    {
        // Busca em base de conhecimento de políticas
        return await _baseConhecimento.BuscarAsync($"políticas {tema}");
    }
    
    [KernelFunction("calcular_ferias")]
    public string CalcularFerias(DateTime dataAdmissao, int diasUsados)
    {
        var diasDisponiveis = (DateTime.Now - dataAdmissao).Days / 365 * 30 - diasUsados;
        return $"Você tem {diasDisponiveis} dias de férias disponíveis";
    }
}

2. Agente de Vendas

public class AgenteVendas
{
    [KernelFunction("qualificar_lead")]
    public async Task<string> QualificarLeadAsync(string dadosLead)
    {
        var prompt = $@"
        Analise o lead a seguir e forneça uma pontuação de 1-10:
        {dadosLead}
        
        Considere: orçamento, necessidade, autoridade, timeline
        ";
        
        return await _kernel.InvokePromptAsync(prompt);
    }
    
    [KernelFunction("gerar_proposta")]
    public async Task<string> GerarPropostaAsync(string requisitos)
    {
        // Gera proposta personalizada baseada nos requisitos
        return await GerarPropostaPersonalizadaAsync(requisitos);
    }
}

Performance e Otimização

1. Cache de Respostas

public class AgenteComCache
{
    private readonly IMemoryCache _cache;
    private readonly TimeSpan _cacheDuration = TimeSpan.FromMinutes(30);
    
    public async Task<string> ProcessarComCacheAsync(string input)
    {
        var cacheKey = $"agente_response_{input.GetHashCode()}";
        
        if (_cache.TryGetValue(cacheKey, out string cachedResponse))
        {
            return cachedResponse;
        }
        
        var response = await ProcessarAsync(input);
        _cache.Set(cacheKey, response, _cacheDuration);
        
        return response;
    }
}

2. Processamento Assíncrono

public class AgenteAssincrono
{
    public async Task<string> ProcessarLoteAsync(IEnumerable<string> solicitacoes)
    {
        var tasks = solicitacoes.Select(async solicitacao =>
        {
            try
            {
                return await ProcessarAsync(solicitacao);
            }
            catch (Exception ex)
            {
                return $"Erro ao processar: {ex.Message}";
            }
        });
        
        var resultados = await Task.WhenAll(tasks);
        return string.Join("\n---\n", resultados);
    }
}

Testes e Qualidade

Testes Unitários

[TestClass]
public class AgenteEmailTests
{
    private Mock<IEmailService> _emailServiceMock;
    private Kernel _kernel;
    
    [TestInitialize]
    public void Setup()
    {
        _emailServiceMock = new Mock<IEmailService>();
        _kernel = Kernel.CreateBuilder()
            .AddOpenAIChatCompletion("gpt-3.5-turbo", "test-key")
            .Build();
        
        _kernel.Plugins.AddFromObject(new EmailAutomationPlugin(_emailServiceMock.Object));
    }
    
    [TestMethod]
    public async Task DeveEnviarEmailComSucesso()
    {
        // Arrange
        var destinatario = "teste@exemplo.com";
        var assunto = "Teste";
        var corpo = "Corpo do email";
        
        // Act
        var resultado = await _kernel.InvokeAsync("EmailAutomationPlugin", "enviar_email", 
            new() { ["destinatario"] = destinatario, ["assunto"] = assunto, ["corpo"] = corpo });
        
        // Assert
        _emailServiceMock.Verify(x => x.SendEmailAsync(destinatario, assunto, corpo), Times.Once);
        Assert.IsTrue(resultado.GetValue<string>().Contains("sucesso"));
    }
}

Testes de Integração

[TestClass]
public class AgenteIntegrationTests
{
    [TestMethod]
    public async Task DeveProcessarSolicitacaoCompleta()
    {
        // Arrange
        var agente = new AgenteGestorProjetos(CriarKernelReal());
        var solicitacao = "Crie uma tarefa de teste com prioridade baixa para amanhã";
        
        // Act
        var resultado = await agente.ProcessarSolicitacaoAsync(solicitacao);
        
        // Assert
        Assert.IsNotNull(resultado);
        Assert.IsTrue(resultado.Contains("tarefa"));
    }
    
    private Kernel CriarKernelReal()
    {
        return Kernel.CreateBuilder()
            .AddAzureOpenAIChatCompletion(
                TestConfiguration.DeploymentName,
                TestConfiguration.Endpoint,
                TestConfiguration.ApiKey
            )
            .Build();
    }
}

Vantagens do Semantic Kernel

✅ Simplicidade

API intuitiva e bem documentada
Curva de aprendizado suave
Exemplos práticos abundantes

✅ Flexibilidade

Suporte a múltiplas linguagens
Plugins extensíveis
Integração com qualquer API

✅ Escalabilidade

Desde protótipos até aplicações enterprise
Suporte a diferentes provedores de IA
Arquitetura modular

✅ Produtividade

Desenvolvimento rápido de agentes
Reutilização de plugins
Testabilidade integrada

✅ Comunidade

Suporte oficial da Microsoft
Documentação extensa
Comunidade ativa no GitHub

Roadmap e Futuro

Funcionalidades Emergentes

Multimodalidade Nativa
- Processamento de imagens
- Análise de áudio
- Interpretação de vídeos
Agentes Autônomos
- Tomada de decisão independente
- Aprendizado contínuo
- Adaptação automática
Orquestração Avançada
- Coordenação entre múltiplos agentes
- Workflows complexos
- Distribuição de tarefas

Tendências

Edge Computing: Agentes executando localmente
Federação: Agentes colaborando entre organizações
Especialização: Agentes verticais por indústria

Conclusão

O Semantic Kernel está redefinindo como construímos e implantamos agentes de IA. Sua abordagem modular e flexível permite que desenvolvedores de todos os níveis criem soluções sofisticadas sem complexidade desnecessária.

Principais Takeaways

✅ Framework leve e poderoso da Microsoft
✅ Open-source com comunidade ativa
✅ Integração simples com sistemas existentes
✅ Escalabilidade desde protótipos até enterprise
✅ Flexibilidade para qualquer cenário de uso

Próximos Passos

Experimente com exemplos básicos
Identifique casos de uso em sua organização
Desenvolva um piloto focado
Expanda gradualmente as funcionalidades
Monitore e otimize continuamente

O futuro da automação inteligente está aqui, e o Semantic Kernel é sua porta de entrada para esse novo mundo de possibilidades.

Recursos Adicionais

Alexandre Izefler é Arquiteto de Sistemas especializado em Azure e IA, com mais de 20 anos de experiência em desenvolvimento de soluções inovadoras.