Guia Prático: Como Criar Agentes com Semantic Kernel, Azure OpenAI Services e Azure Functions

Last Updated: outubro 15, 2024By alexandre.izefler@gmail.comTags: Azure AI Services, Azure Functions, Semantic Kernel

A criação de agentes inteligentes, que unem o poder da IA com a automação de processos, está transformando empresas em diversos setores — e o impacto é ainda maior na construção civil. Agora, imagine um agente capaz de planejar obras residenciais de alto padrão, oferecendo suporte a engenheiros e arquitetos na definição de cronogramas detalhados, na criação de EAPs e na organização automatizada de tarefas. Esse tipo de solução não é mais um sonho distante, mas uma realidade acessível. Neste guia, vamos te mostrar como desenvolver agentes de IA que potencializam essas capacidades, utilizando ferramentas como o Semantic Kernel, Azure OpenAI Services e Functions. Prepare-se para descobrir como a tecnologia pode revolucionar o planejamento de obras. Vamos começar!

Objetivo do Artigo

Neste guia passo a passo, você aprenderá como criar um agente especialista em planejamento de obras residenciais utilizando o Semantic Kernel, integrado com Azure OpenAI Services e Functions. O objetivo é oferecer uma abordagem prática e diferente, permitindo que você consuma o agente por meio de um endpoint HTTP. Vamos abordar desde a criação do serviço no Azure até a configuração de plugins e persona, explorando cada etapa com exemplos claros e diretos.

Visão Geral

Neste guia, abordaremos a criação de um agente especialista em planejamento de obras residenciais, utilizando o Semantic Kernel, o Azure OpenAI Services e Azure Functions. O agente terá como objetivo auxiliar engenheiros e arquitetos na organização de cronogramas, estruturação de projetos e definição de tarefas. Chamado de Clariane, este agente será projetado para fornecer suporte inteligente a partir de uma interface HTTP, utilizando plugins e inteligência artificial para expandir suas habilidades.

Passo 1: Provisionando o Azure OpenAI Services

O primeiro passo para criar nosso agente é garantir que você tenha o serviço Azure OpenAI Services provisionado na sua assinatura Azure. Este serviço será a base para interagirmos com os modelos distribuídos pela OpenAI, como o GPT, que será utilizado para dar vida ao agente.

Como provisionar:

Acesse o portal do Azure e crie uma nova instância de Azure OpenAI Services ou utilize uma existente.
Distribua o modelo desejado (neste caso, GPT-4 ou GPT-4o), estou usando o GPT-4o.

Nota: Certifique-se de que o serviço esteja ativo e disponível, e que você tenha todas as permissões configuradas corretamente, pois será necessário a Apikey e Endpoint para que possamos integrá-lo ao código mais adiante.

Veja as imagens em ordem abaixo dos passos necessários para provisionamento do recurso e distribuição do modelo.

Passo 2: Criando o Projeto no Visual Studio

Com o Azure OpenAI Services provisionado, é hora de criar o projeto no Visual Studio. O exemplo deste guia será baseado em uma Azure Function com gatilho HTTP para facilitar a interação via API. Você pode optar por usar o Visual Studio, Visual Studio Code, ou a CLI, conforme sua preferência.

Instruções:

Crie um novo projeto de Azure Functions com o gatilho HTTP.
Adicione os seguintes pacotes via NuGet:
- Microsoft.SemanticKernel
- Microsoft.SemanticKernel.Core
- Microsoft.SemanticKernel.Plugins.Core

Dica: Estou usando o Visual Studio com .NET 8. Caso precise de mais informações sobre Azure Functions, consulte a documentação oficial.

Passo 3: Configurando o Código Inicial do Semantic Kernel

Agora, com o projeto configurado, vamos configurar o código inicial para testar o Semantic Kernel. Nessa etapa, vamos garantir que a integração entre a Azure Function e o Azure OpenAI Services está funcionando corretamente, sem adicionar plugins ainda.

Copy to Clipboard

namespace AlexandreIzefler.AI.SK.Demos.Demo1
{
    public class SK_PlanningEAP_Agent_1
    {
        private readonly ILogger<SK_PlanningEAP_Agent_1> _logger;
        private readonly string _model;
        private readonly string _endpoint;
        private readonly string _key;

public SK_PlanningEAP_Agent_1(ILogger<SK_PlanningEAP_Agent_1> logger, IConfiguration configuration)
        {
            _logger = logger;
            _model = configuration["AZURE_OPENAI_SERVICES_MODEL"]!;
            _endpoint = configuration["AZURE_OPENAI_SERVICES_ENDPOINT"]!;
            _key = configuration["AZURE_OPENAI_SERVICES_KEY"]!;
        }

[Function("SK_PlanningEAP_Agent_1_Http")]
        public async Task<IActionResult> Run([HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req)
        {
            _logger.LogInformation("C# HTTP trigger function iniciando o processamento.");

var builder = Kernel.CreateBuilder();
            builder.AddAzureOpenAIChatCompletion(_model, _endpoint, _key);
            var kernel = builder.Build();

var chatCompletionService = kernel.GetRequiredService<IChatCompletionService>();

var history = new ChatHistory("Como posso ajudá-lo?");

if (!string.IsNullOrEmpty(req.Form["question"]))
            {
                string userInput = req.Form["question"]!;
                history.AddUserMessage(userInput);
            }

var result = await chatCompletionService.GetChatMessageContentAsync(
                history,
                kernel: kernel);

return new OkObjectResult(result.ToString());
        }
    }
}

Confira nas imagens abaixo os testes realizados no Postman. Observe que o agente responde a qualquer pergunta, mesmo aquelas que estão fora do contexto ao qual será projetado.

Passo 4: Criando o Agente “Clariane”

Agora chegamos à parte mais empolgante: a criação do nosso agente! Como mencionado anteriormente, um agente é composto por três elementos principais:

Plugins (Ferramentas)
Planner (Orquestração)
Persona (Identidade)

Persona “Clariane”:

Nossa persona será uma especialista em planejamento de obras residenciais, com foco em moradias como casas térreas e sobrados de alto padrão. A identidade do agente será responsável por suas decisões e limitações. A persona foi criada utilizando o ChatGPT para definir suas características e o escopo de atuação.

Dica: Ao definir um contexto específico, o agente será mais eficiente e relevante para as demandas do usuário.

Copy to Clipboard

namespace AlexandreIzefler.AI.SK.Demos.Demo1
{
    public class SK_PlanningEAP_Agent_2
    {
        private readonly ILogger<SK_PlanningEAP_Agent_2> _logger;
        private readonly string _model;
        private readonly string _endpoint;
        private readonly string _key;

public SK_PlanningEAP_Agent_2(ILogger<SK_PlanningEAP_Agent_2> logger, IConfiguration configuration)
        {
            _logger = logger;
            _model = configuration["AZURE_OPENAI_SERVICES_MODEL"]!;
            _endpoint = configuration["AZURE_OPENAI_SERVICES_ENDPOINT"]!;
            _key = configuration["AZURE_OPENAI_SERVICES_KEY"]!;
        }

[Function("SK_PlanningEAP_Agent_2_Http")]
        public async Task<IActionResult> Run([HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req)
        {
            _logger.LogInformation("C# HTTP trigger function iniciando o processamento.");

var builder = Kernel.CreateBuilder();
            builder.AddAzureOpenAIChatCompletion(_model, _endpoint, _key);
            var kernel = builder.Build();

var chatCompletionService = kernel.GetRequiredService<IChatCompletionService>();

// Definição do prompt para o agente Clariane
            var promptSystem = @"
                O seu nome é Clariane, uma engenheira Civil Especialista em Planejamento de Obras Residenciais de Alto Padrão, 
                com foco em projetos de casas térreas e sobrados. Experiência em definir cronogramas, custos, recursos, 
                e em elaborar EAP detalhada para projetos com acabamentos de luxo, sustentabilidade, e integração de tecnologias como energia solar e aquecimento de piscina.

O seu objetivo: Apoiar na criação de uma Estrutura Analítica do Projeto (EAP) detalhada e clara para a construção de uma casa térrea ou sobrado de alto padrão, 
                garantindo uma visão completa e estruturada das fases do projeto.

Entrada do Usuário:
                - Tipo de projeto (casa térrea ou sobrado).
                - Metros quadrados da construção.
                - Ambientes desejados (número de quartos, banheiros, áreas sociais).
                - Requisitos específicos (energia solar, aquecimento de piscina, acabamentos de luxo).

Resultado Esperado:
                - Apresentação da entrada do usuário, exemplo: Você deseja construir uma casa térrea com 300m², 3 quartos, 3 banheiros, área social integrada, energia solar e piscina aquecida.
                - Um descritivo em formato de EAP conforme as diretrizes para o planejamento de obras residenciais de alto padrão, dividido em entregáveis e tarefas, organizados de forma hierárquica, que servirá como base para o cronograma e execução do projeto.
                ";
            var history = new ChatHistory(promptSystem);

if (!string.IsNullOrEmpty(req.Form["question"]))
            {
                string userInput = req.Form["question"]!;
                history.AddUserMessage(userInput);
            }

var result = await chatCompletionService.GetChatMessageContentAsync(
                history,
                kernel: kernel);

return new OkObjectResult(result.ToString());
        }
    }
}

Nas imagens abaixo, você pode ver os testes realizados no Postman. Agora, o agente exibe uma mensagem de boas-vindas e responde apenas dentro do contexto para o qual foi projetado. No próximo tópico, vamos adicionar plugins para ampliar as capacidades do agente.

Importante: Para o teste da requisição http, foi usado o seguinte valor “O tipo será cassa térrea, 240 metros quadrados, com acabamento de luxo, serão 4 quarto, 1 escritório, 1 sala para dois ambientes, 1 cozinha estilo americana, 1 espaço goumert, 1 piscina e 5 vagas de garagem, disposição para energia solar e aquecimento de agua para a casa e piscina.” para o parâmetro “question”.

Passo 5: Adicionando Plugins e Configurando o Planner

Com a persona definida, é hora de dar mais poder ao nosso agente adicionando plugins e configurando o planner para orquestrar suas funções. Para nosso exemplo, vamos criar um plugin que ajude a gerar e salvar uma Estrutura Analítica de Projeto (EAP).

Plugins Criados:

EAP Cronograma: Responsável por direcionar as regras para geração das datas do cronograma.
EAP Salvar: Salva a EAP em um arquivo TXT para consulta futura.

Importante: Note que, além de adicionarmos os plugins no código, também ajustamos o prompt do nosso agente. Os três últimos itens são os mais relevantes para ativar os plugins configurados.

Exemplo do código:

Copy to Clipboard

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Configuration;
using Microsoft.SemanticKernel.ChatCompletion;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;
using Microsoft.SemanticKernel.Plugins.Core;
using Microsoft.Extensions.DependencyInjection;
using AlexandreIzefler.AI.SK.Demos.Demo1.Plugins;

namespace AlexandreIzefler.AI.SK.Demos.Demo1
{
    public class SK_PlanningEAP_Agent_3
    {
        private readonly ILogger<SK_PlanningEAP_Agent_3> _logger;
        private readonly string _model;
        private readonly string _endpoint;
        private readonly string _key;

public SK_PlanningEAP_Agent_3(ILogger<SK_PlanningEAP_Agent_3> logger, IConfiguration configuration)
        {
            _logger = logger;
            _model = configuration["AZURE_OPENAI_SERVICES_MODEL"]!;
            _endpoint = configuration["AZURE_OPENAI_SERVICES_ENDPOINT"]!;
            _key = configuration["AZURE_OPENAI_SERVICES_KEY"]!;
        }

[Function("SK_PlanningEAP_Agent_3_Http")]
        public async Task<IActionResult> Run([HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req)
        {
            _logger.LogInformation("C# HTTP trigger function iniciando o processamento.");

var builder = Kernel.CreateBuilder();
            builder.AddAzureOpenAIChatCompletion(_model, _endpoint, _key);
            
            /********************************************************************************************************************
             * Adicionando referencia do logging para visualização dos logs e ver o planning em ação
             ********************************************************************************************************************/
            builder.Services.AddLogging(loggingBuilder => loggingBuilder.AddConsole().SetMinimumLevel(LogLevel.Trace));

/********************************************************************************************************************
             *  Aqui estamos sendo adicionado os plugins: 
             *  - TimePlugin: plugin que fornece funções para manipulação de datas e horas.
             *  - EAPPlugin: plugin com fornece a regra de cronograma da EAP e salvar a EAP no disco.
             ********************************************************************************************************************/
            builder.Plugins.AddFromType<TimePlugin>();
            builder.Plugins.AddFromType<EAPPlugin>();

var kernel = builder.Build();

var chatCompletionService = kernel.GetRequiredService<IChatCompletionService>();

/********************************************************************************************************************
             * Definição do Planner com a opção de escolha automática de funções
             * Com apenas esta instrução o sistema irá escolher automaticamente a função que melhor se encaixa na solicitação
             ********************************************************************************************************************/
            OpenAIPromptExecutionSettings openAIPromptExecutionSettings = new()
            {
                FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
            };

/********************************************************************************************************************
             * Definição do prompt para o agente Clariane
             ********************************************************************************************************************/
            var promptSystem = @"
                O seu nome é Clariane, uma engenheira Civil Especialista em Planejamento de Obras Residenciais de Alto Padrão, 
                com foco em projetos de casas térreas e sobrados. Experiência em definir cronogramas, custos, recursos, 
                e em elaborar EAP detalhada para projetos com acabamentos de luxo, sustentabilidade, e integração de tecnologias como energia solar e aquecimento de piscina.

O seu objetivo: Apoiar na criação de uma Estrutura Analítica do Projeto (EAP) detalhada e formatada conforme as DIRETRIZES PARA O PLANEJAMENTO de forma clara para a construção de uma casa térrea ou sobrado de alto padrão, 
                garantindo uma visão completa e estruturada das fases do projeto.

Mensagem de Boas-Vindas: 
                'Olá! Eu sou a Clariane, sua especialista em planejamento de obras residenciais de alto padrão. 
                Estou aqui para ajudá-lo a criar um plano detalhado e eficiente para sua construção, desde a fundação até os acabamentos de luxo. 
                Juntos, vamos desenvolver uma EAP completa que irá garantir o sucesso do seu projeto! Qual é o tipo de obra que você está planejando hoje?'
                
                **IMPORTANTE**: Eu só posso responder perguntas relacionadas ao planejamento de obras residenciais e a elaboração de uma EAP. Se você fizer uma pergunta fora desse contexto, minha resposta será a seguinte: 
                'Desculpe, essa pergunta não faz parte do meu escopo de especialização. Posso ajudar com algo relacionado ao planejamento de obras residenciais ou a EAP?'
                
                Diretrizes para o planejamento da EAP:
                1. Identificar e listar todas as principais fases da obra, desde a concepção inicial até o acabamento final.
                2. Definir os entregáveis e marcos críticos do projeto.
                3. Incluir atividades detalhadas para cada fase, como fundação, estrutura, elétrica, hidráulica, acabamento, e paisagismo.
                4. Considerar as necessidades de integração de tecnologias (sistemas de energia solar, automação residencial).
                5. Garantir que a EAP esteja adequada para controle de tempo e custos, com a possibilidade de ajustes durante a obra.
                6. Focar na sustentabilidade e uso de materiais de alta qualidade para garantir o padrão do projeto.
                7. Gerar cronograma para as atividades e marcos, considerando prazos realistas e margens de segurança.
                8. Utilize a data atual para definir o início e término das atividades, considerando a duração de cada uma.
                9. Salvar a EAP em um arquivo TXT.

Resultado Esperado:
                - Apresentação da entrada do usuário, exemplo: Você deseja construir uma casa térrea com 300m², 3 quartos, 3 banheiros, área social integrada, energia solar e piscina aquecida.
                - Um descritivo em formato de EAP, dividido em entregáveis e tarefas, organizados de forma hierárquica, que servirá como base para o cronograma e execução do projeto.
                ";

var history = new ChatHistory(promptSystem);

if (!string.IsNullOrEmpty(req.Form["question"]))
            {
                string userInput = req.Form["question"]!;
                history.AddUserMessage(userInput);
            }

var result = await chatCompletionService.GetChatMessageContentAsync(
                history,
                // Adicionando as configurações de execução do prompt (Planner)
                executionSettings: openAIPromptExecutionSettings,
                kernel: kernel);

return new OkObjectResult(result.ToString());
        }
    }
}

No código a seguir temos a implementação do plugin EAP.

Copy to Clipboard

Nas imagens a seguir poderá visualizar os resultados do nosso agente.

Tenha acesso ao código completo deste artigo em meu repositório no Github.

Conclusão

Neste guia, abordamos como criar um agente especialista em planejamento de obras residenciais utilizando o poder do Semantic Kernel e Azure OpenAI Services. Passamos pelo provisionamento dos serviços, configuração do projeto e criação de plugins e personas. Esta solução pode ser expandida para inúmeras outras funcionalidades, como sumarização de documentos, cálculos avançados e automação de processos de engenharia.

Se você gostou deste conteúdo, deixe seu comentário e compartilhe suas dúvidas. Em breve, lançarei um projeto completo com práticas de segurança e observabilidade para uso corporativo!

Referências e Recursos Adicionais

Microsoft Learn Agents: https://learn.microsoft.com/en-us/semantic-kernel/frameworks/agent/?pivots=programming-language-csharp

Microsoft Learn Function Calling: https://learn.microsoft.com/en-us/semantic-kernel/concepts/ai-services/chat-completion/function-calling/?pivots=programming-language-csharp

latest video

Introdução ao Azure Integration Services: O que é iPaaS e por que sua empresa precisa disso?
setembro 10, 2024

Inscreva-se para saber em primeira mão as notificações dos novos artigos

categories

popular posts

Guia Prático: Como Criar Agentes com Semantic Kernel, Azure OpenAI Services e Azure Functions

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

Como Azure AI Services impulsiona a automação empresarial

Guia Prático: Como Criar Agentes com Semantic Kernel, Azure OpenAI Services e Azure Functions

Passo 1: Provisionando o Azure OpenAI Services

Passo 2: Criando o Projeto no Visual Studio

Passo 3: Configurando o Código Inicial do Semantic Kernel