DEV Community: Wanderson Alves Rodrigues

UTCP: um protocolo alternativo ao MCP para chamada de ferramentas

Wanderson Alves Rodrigues — Tue, 23 Dec 2025 19:10:32 +0000

Introdução

Com a rápida evolução dos agentes de IA, um novo desafio se tornou evidente:
como permitir que modelos chamem ferramentas externas (APIs, CLIs, serviços e streams) de forma padronizada, segura e eficiente?

Grande parte das soluções atuais depende de camadas intermediárias, servidores “wrappers” ou protocolos que exigem infraestrutura adicional. É nesse contexto que surge o UTCP (Universal Tool Calling Protocol), um protocolo aberto que propõe uma abordagem mais direta e simples.

Essa postagem analisa o que é o UTCP, seus diferenciais técnicos, riscos, comparações com alternativas como MCP e onde ele faz mais sentido na prática.

O que é o UTCP?

O UTCP (Universal Tool Calling Protocol) é um protocolo aberto que descreve como ferramentas podem ser chamadas por agentes de IA usando diretamente seus protocolos nativos, sem a necessidade de servidores intermediários.

A ideia central é simples e poderosa:

“Se um humano consegue chamar uma ferramenta, um agente de IA também deveria conseguir sem wrappers adicionais.”

O UTCP atua como um contrato descritivo, informando:

quais ferramentas existem;
como elas são chamadas;
quais parâmetros aceitam;
quais protocolos utilizam (HTTP, WebSocket, CLI, streaming etc.), todos protocolos suportados Protocols.

Os quatro princípios centrais do UTCP

O UTCP foi concebido em torno de quatro princípios que o tornam atraente:

Sem wrapper tax: Ferramentas existentes funcionam como estão não há necessidade de reescrever API ou deployar camadas extras.
Aproveitar infraestrutura nativa: Autenticação, autorização e políticas de segurança são simplesmente reaproveitados da forma como a ferramenta já funciona.
Comunicação direta e eficiente: Ao evitar servidores intermediários, o agente chama o serviço diretamente o que reduz latência, overhead e complexidade.
Compatibilidade universal: UTCP suporta diversos protocolos HTTP, WebSockets, gRPC, CLI tornando-o aplicável mesmo em ambientes heterogêneos.

Como o UTCP funciona (de forma prática)

O padrão define três componentes principais:

Manuais

São documentos JSON padronizados que descrevem todas as ferramentas disponíveis, suas entradas, saídas, a forma de chamá-las e requisitos de autenticação.

Ferramentas

Definições específicas de cada funcionalidade que o agente pode invocar com seu nome, parâmetros e esquema de resposta.

Provedores

Os canais de comunicação (HTTP, CLI, WebSockets, etc.) que permitem ao agente falar diretamente com a ferramenta.

O fluxo segue três fases:

Descoberta: O agente busca o manual UTCP (ex. em /utcp).

Comunicação direta: O agente chama o endpoint nativo da ferramenta, conforme descrito no manual.

Processamento do resultado: A resposta é recebida na forma nativa e usada pelo agente sem transformação intermediária.

Esse processo elimina intermediários e centraliza a descoberta e a chamada de ferramentas em um único padrão leve.

O problema que o UTCP resolve

Hoje, a integração entre IA e ferramentas geralmente envolve:

APIs adaptadas especificamente para IA
servidores intermediários (middleware)
duplicação de lógica de autenticação
aumento de latência
maior complexidade operacional

Protocolos como MCP, por exemplo, introduzem uma camada adicional de servidor, o que pode ser útil para governança, mas também cria acoplamento e custo.

O UTCP propõe o caminho oposto:

menos infraestrutura
menos abstração
mais proximidade com a ferramenta real

Principais características do UTCP

1. Chamada direta de ferramentas

O agente chama a ferramenta usando o protocolo original, sem tradução intermediária.

Isso reduz:

latência;
pontos de falha;
dependência de infraestrutura extra.

2. Suporte a múltiplos protocolos

O UTCP não se limita a HTTP. Ele pode descrever ferramentas baseadas em:

REST APIs
WebSocket
SSE (streaming)
CLI (linha de comando)
gRPC
outros protocolos customizados

Isso o torna extremamente flexível para ambientes heterogêneos.

3. Integração com padrões existentes

O protocolo pode reaproveitar especificações já conhecidas, como:

OpenAPI
definições de comandos CLI
contratos já documentados

Ou seja, não exige “recriar” APIs para IA.

4. Open Source e extensível

O UTCP é aberto e orientado à comunidade, permitindo:

auditoria do protocolo;
extensões customizadas;
adaptação a diferentes domínios (enterprise, edge, on-premise).

Segurança: ponto crítico (e responsabilidade do implementador)

Um aspecto importante: UTCP não é um sandbox de segurança por si só.

O próprio projeto deixa claro que:

segurança depende de boas práticas de implementação;
chamadas CLI precisam ser extremamente bem controladas;
autenticação, autorização e rate limit continuam sendo responsabilidade da ferramenta.

Em outras palavras:

O UTCP não remove riscos ele não adiciona riscos extras, desde que usado corretamente.

Para ambientes críticos, recomenda-se:

escopo mínimo de permissões;
isolamento de execução;
auditoria e logging;
restrições claras para ferramentas locais.

Ao contrário de abordagens que centralizam autenticação no servidor intermediário, o UTCP herda a segurança do próprio serviço integrado:

Credenciais e tokens são usados como fariam usuários humanos;
Controle de acesso se mantém conforme já está implementado;
Logging e auditoria podem usar os mecanismos nativos do serviço.

UTCP vs MCP: não são concorrentes diretos

Enquanto o MCP se baseia em servidores que:

ficam entre o agente e a ferramenta;
gerenciam autenticação e tradução;
exigem manutenção contínua,

o UTCP é construído para ser simples, direto e sem camadas extras. O que isso significa na prática:

sem proxy = menor latência e menos custo operacional;
sem necessidade de reimplementar autenticação;

Embora muitas comparações sejam feitas, UTCP e MCP resolvem problemas diferentes.

Aspecto	UTCP	MCP
Servidor intermediário	Não	Sim
Latência	Menor	Maior
Infraestrutura	Mínima	Mais complexa
Governança central	Limitada	Forte
Flexibilidade	Alta	Média
Uso ideal	Integração direta	Ambientes altamente controlados

Em muitos cenários, UTCP e MCP podem coexistir, dependendo do nível de controle e abstração desejado.

Onde o UTCP faz mais sentido

O UTCP é especialmente interessante para:

plataformas de agentes autônomos
integrações enterprise com APIs já existentes
ambientes on-premise e edge
sistemas que precisam de alto desempenho
times que querem evitar lock-in de infraestrutura

Por outro lado, pode não ser ideal para:

ambientes que exigem governança central rígida;
organizações que preferem tudo mediado por um único servidor controlador.

Limitações e contras do uso do UTCP

Apesar de o UTCP (Universal Tool Calling Protocol) trazer ganhos claros de simplicidade e desempenho, ele não é uma bala de prata. Sua filosofia de “chamada direta” implica trade-offs importantes que precisam ser considerados.

1 - Responsabilidade total de segurança fica com o implementador

O UTCP não impõe uma camada de segurança própria.
Isso significa que:

Não há sandbox automático
Não há isolamento de execução por padrão
Não há política centralizada de autorização

Em protocolos como MCP, parte desse controle pode ser centralizado no servidor intermediário. No UTCP, tudo depende da maturidade da API existente.

2 - Risco elevado ao expor ferramentas locais (CLI)

Um dos recursos mais poderosos do UTCP — suporte a CLI — também é um dos mais perigosos.

Sem isolamento adequado:

comandos podem ser encadeados;
variáveis de ambiente podem ser expostas;
arquivos sensíveis podem ser acessados.

Consequência

UTCP não deve ser usado ingenuamente para:

shells de produção;
servidores críticos;
máquinas com permissões amplas.

3 - Complexidade deslocada, não eliminada

O UTCP reduz complexidade arquitetural, mas pode aumentar complexidade operacional:

Cada API precisa estar bem documentada
Esquemas de entrada/saída precisam ser claros
Erros precisam ser semanticamente corretos

Caso contrário:

agentes falham silenciosamente;
resultados inconsistentes aparecem;
debugging se torna difícil.

4 - Ecossistema ainda jovem

Apesar do crescimento:

UTCP ainda não é um padrão amplamente adotado;
há poucos cases enterprise públicos;
ferramentas e SDKs ainda estão amadurecendo.

Risco

mudanças no protocolo;
ajustes de compatibilidade;
necessidade de manutenção contínua.

5 - Não substitui completamente MCP ou Function Calling

UTCP não elimina a necessidade de:

Function Calling para casos simples;
MCP em ambientes com controle rígido;
Orquestradores de workflow complexos.

Mão na massa

Vou desenvolver um exemplo simples o objetivo é simular uma situação em que já existem uma ou várias APIs e precisamos integrá-las a uma LLM ou SLM. Foi usada dotnet 10 C# porém poderia ser usada qualquer linguagem de programação, para a interação com LLM optei usar da OpenAI por dar suporte a ferramentas.

Foi utilizada uma abordagem de descoberta de ferramentas ou manual usando GET/api/v1/utcp.

{
  "manual_version": "1.0.0",
  "utcp_version": "1.1.0",
  "name": "Weather API",
  "description": "API para informações e previsões meteorológicas",
  "tools": [
    {
      "name": "get_current_weather",
      "description": "Obter o clima atual para uma localização específica",
      "tags": [
        "clima",
        "atual",
        "temperatura"
      ],
      "inputs": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "Nome da cidade ou coordenadas (por exemplo, Londres ou 51.5074,-0.1278)",
            "enum": null,
            "minimum": null,
            "maximum": null
          },
          "units": {
            "type": "string",
            "description": "Unidades de temperatura",
            "enum": [
              "celsius",
              "fahrenheit"
            ],
            "minimum": null,
            "maximum": null
          }
        },
        "required": [
          "location"
        ]
      },
      "output": {
        "type": "object",
        "description": "Informações do clima atual"
      },
      "average_response_size": 512,
      "tool_call_template": {
        "call_template_type": "http",
        "url": "https://localhost:7247/api/v1/weatherforecast/api/v1/current",
        "http_method": "GET",
        "headers": null,
        "query_params": {
          "location": "${location}",
          "units": "${units}"
        },
        "body": null
      }
    },
    {
      "name": "get_forecast",
      "description": "Obter a previsão do tempo para os próximos dias",
      "tags": [
        "clima",
        "previsão",
        "prognóstico"
      ],
      "inputs": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "Nome da cidade",
            "enum": null,
            "minimum": null,
            "maximum": null
          },
          "days": {
            "type": "integer",
            "description": "Número de dias (1-7)",
            "enum": null,
            "minimum": 1,
            "maximum": 7
          }
        },
        "required": [
          "location",
          "days"
        ]
      },
      "output": {
        "type": "array",
        "description": "Array de previsões diárias"
      },
      "average_response_size": 2048,
      "tool_call_template": {
        "call_template_type": "http",
        "url": "https://localhost:7247/api/v1/weatherforecast/api/v1/forecast",
        "http_method": "GET",
        "headers": null,
        "query_params": {
          "location": "${location}",
          "days": "${days}"
        },
        "body": null
      }
    }
  ],
  "auth": null
}

A estrutura é usada para alimentar um LLM com informações sobre como funcionam nossas APIs. Claro, aqui é apenas uma demonstração; é possível melhorar e deixá-la mais enxuta, até mesmo para consumir menos tokens.

O código abaixo mostra a parte de obtenção das ferramentas habilitadas e a integração com um LLM, que, por meio da ferramenta, escolhe aquela que melhor atende à pergunta. Feita essa descoberta, a API correspondente é chamada e, com o retorno, a resposta é elaborada.

using API.Models;
using Microsoft.Extensions.Options;
using OpenAI.Chat;
using System.Text.Json;

namespace API.Services;

public interface IChatService
{
    Task<string> SendMessageAsync(string userMessage);
}

public class ChatService : IChatService
{
    private readonly ChatClient _chat;
    private readonly IUtcpService _utcpService;
    private readonly UTCPSettings _utcpSetting;

    public ChatService(IUtcpService utpcService, IOptions<OpenAISettings> settings, IOptions<UTCPSettings> utcpSetting)
    {
        _utcpService = utpcService;
        _chat = new ChatClient(
            model: settings.Value.Model,
            apiKey: settings.Value.ApiKey
        );
        _utcpSetting = utcpSetting.Value;
    }

    public async Task<string> SendMessageAsync(string userMessage)
    {
        var messages = new List<ChatMessage>
        {
            new SystemChatMessage("Você é um assistente que usa ferramentas quando necessário."),
            new UserChatMessage(userMessage)
        };

        foreach (var manualUrl in _utcpSetting.ManualUrls)
        {
            try
            {
                await _utcpService.DiscoverToolsAsync(manualUrl);
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Failed to discover tools: {ex.Message}");
                throw;
            }
        }

        var options = new ChatCompletionOptions();

        // Add UTCP tools discovered from the manual
        foreach (var tool in _utcpService.GetToolsForOpenAI())
        {
            options.Tools.Add(tool);
        }

        var response = await _chat.CompleteChatAsync(messages, options);
        var assistantMessage = response.Value;

        // Handle tool calls
        if (assistantMessage.ToolCalls.Count > 0)
        {
            var toolCall = assistantMessage.ToolCalls[0];

            // Parse arguments from OpenAI
            var argsJson = JsonSerializer.Deserialize<JsonElement>(
                toolCall.FunctionArguments.ToString()
            );

            // Execute UTCP tool
            var toolResult = await _utcpService.ExecuteAsync(
                toolCall.FunctionName,
                argsJson
            );

            // Add assistant message with tool call
            messages.Add(new AssistantChatMessage(assistantMessage));

            // Add tool result
            messages.Add(new ToolChatMessage(
                toolCall.Id,
                JsonSerializer.Serialize(toolResult)
            ));

            // Get final response from OpenAI
            var finalResponse = await _chat.CompleteChatAsync(messages, options);
            return finalResponse.Value.Content[0].Text;
        }

        return assistantMessage.Content[0].Text;
    }
}

Vamos ao teste:

1° - "Qual a temperatura da cidade de Vitória?"

Chamou: GET/api/v1/weatherforecast/api/v1/current

Resposta:

{
  "response": "A temperatura atual em Vitória é de 22,5 °C, com condições de céu parcialmente nublado. A umidade está em 65% e a velocidade do vento é de 12,5 km/h vindo do noroeste."
}

2° - "Qual foi a temperatura da cidade de Vitória para próximos 3 dias?"

Chamou: GET/api/v1/weatherforecast/api/v1/forecast

Resposta:

{
   "response":"Aqui está a previsão do tempo para Vitória nos próximos 3 dias:\n\n- **25 de dezembro**: \n  - Temperatura máxima: 25°C \n  - Temperatura mínima: 15°C \n  - Condições: Ensolarado \n  - Chance de precipitação: 0%\n\n- **26 de dezembro**: \n  - Temperatura máxima: 26°C \n  - Temperatura mínima: 16°C \n  - Condições: Nublado \n  - Chance de precipitação: 10%\n\n- **27 de dezembro**: \n  - Temperatura máxima: 27°C \n  - Temperatura mínima: 17°C \n  - Condições: Ensolarado \n  - Chance de precipitação: 20% \n\nSe precisar de mais informações, é só avisar!"
}

Impacto no futuro dos agentes de IA

O UTCP aponta para uma tendência clara: agentes de IA cada vez mais próximos da infraestrutura real.

Em vez de “simular” chamadas via camadas artificiais, os agentes passam a operar como atores de primeira classe, usando as mesmas interfaces que humanos e sistemas tradicionais.

Isso abre espaço para:

agentes mais autônomos;
menor custo operacional;
maior interoperabilidade entre sistemas.

Conclusão

O UTCP é um protocolo simples na ideia, mas profundo nas implicações.
Ele não tenta substituir tudo, nem ser uma solução mágica, mas propõe algo fundamental: menos abstração desnecessária entre IA e ferramentas reais.

Ele funciona melhor quando:

APIs já são bem projetadas;
segurança já está resolvida;
o time entende os riscos;
simplicidade e desempenho são prioridades.

Em ambientes imaturos ou excessivamente regulados, o UTCP pode amplificar problemas existentes, em vez de resolvê-los.

Se adotado com responsabilidade, o UTCP pode se tornar um padrão importante na próxima geração de sistemas baseados em agentes, especialmente em ambientes técnicos, enterprise e distribuídos.

O projeto completo: Github

Referência:

UTCP
GitHub UTCP

Tool Calling dando mãos e olhos aos modelos de linguagem (LLMs)

Wanderson Alves Rodrigues — Fri, 24 Oct 2025 00:29:49 +0000

Grandes Modelos de Linguagem (LLMs), como o GPT-4, o Llama 3, Claude 3 e DeepSeek, são modelos treinados com enormes quantidades de informações. Eles funcionam como “cérebros”, construídos a partir de uma vasta representação do conhecimento humano, capazes de escrever e sintetizar informações em um nível sem precedentes. No entanto, além de apenas gerar texto, um LLM pode identificar que uma ação precisa ser executada e, então, solicitar que essa ação seja realizada por uma função externa.

Um LLM, por padrão, não sabe que horas são. Ele não sabe como está o tempo lá fora. Ele não pode acessar as notícias de hoje, verificar o preço de uma ação ou fazer uma reserva no seu restaurante favorito. Seu conhecimento é estático, congelado no tempo no momento em que seu treinamento foi concluído.

É aqui que entra o Tool Calling (ou Function Calling), uma das capacidades mais transformadoras no campo da IA. Este é o mecanismo que finalmente dá "mãos e olhos" a esses cérebros, permitindo-lhes interagir com o mundo exterior.

A Analogia: O Cérebro na Sala Fechada

Imagine um gênio trancado em uma biblioteca. Ele leu todos os livros, mas não tem janelas, relógio ou telefone. Se você perguntar a ele sobre a história da Roma Antiga, ele lhe dará uma resposta brilhante. Se você perguntar: "Está chovendo em Paris agora?", ele só poderá dizer: "Com base nos padrões climáticos históricos descritos nos livros, Paris frequentemente tem chuvas..."

O Tool Calling é o equivalente a instalar um intercomunicador nessa sala.

Através desse intercomunicador, o gênio (o LLM) não pode sair, mas ele pode pedir a alguém do lado de fora (sua aplicação) para fazer algo por ele. Ele pode dizer: "Por favor, ligue para o serviço de meteorologia e pergunte o tempo em Paris."

Como Funciona o "Tool Calling"?

O processo não é mágico, trata-se de um fluxo de dados elegante e estruturado entre o LLM e o código da sua aplicação. Esse fluxo de chamadas de ferramentas nada mais é do que a execução de funções,classes, métodos, scripts ou serviços externos que expomos para que a IA realize algo em nosso nome.

Outro ponto bastante interessante, que muitas pessoas confundem, é que o LLM não executa diretamente a ferramenta, ele apenas tem conhecimento da sua existência. Quando uma conversa é direcionada para algo que uma ferramenta disponível pode resolver, a IA apenas envia uma solicitação para que essa ferramenta seja executada. Ou seja, quem de fato implementa e realiza a chamada da ferramenta somos nós, por meio do código da aplicação.

Vamos ao mão na massa.

A Definição (O Desenvolvedor Informa as Ferramentas)

Primeiro, nós, como desenvolvedores, temos que dizer ao LLM quais "ferramentas" ele tem à sua disposição.

Para esse primeiro passo, vamos criar a ferramenta para multiplicar dois números de ponto flutuante.

from langchain.chat_models import init_chat_model
from langchain.tools import BaseTool, tool
from langchain_core.messages import (
    AIMessage,
    BaseMessage,
    HumanMessage,
    SystemMessage,
    ToolMessage,
)
from rich import print
from dotenv import load_dotenv

load_dotenv()

@tool()
def multiply(a: float, b: float) -> float:
    """Multipy a * b and return the result
    Args:
        a (float): The first number
        b (float): The second number
    Returns:
        float: The resulting foat of the equation a * b"""
    return a * b

Depois que decoramos a função com @tool, ela se torna uma ferramenta que pode ser utilizada por LLMs. No entanto, a partir desse momento, ela deixa de ser apenas uma função simples e passa a ser uma instância da classe StructuredTool ou seja, uma ferramenta enriquecida com metadados e descrição, que o LLM pode compreender e utilizar de forma estruturada.Se imprimir a função multiply vamos ter algo como abaixo.

StructuredTool(
  name='multiply',
  description='Multipy a * b and return the result\n    Args:\n        a (float): The first number\n        b (float):
  The second number\n    Returns:\n        float: The resulting foat of the equation a * b',
  args_schema=<class 'langchain_core.utils.pydantic.multiply'>,
  func=<function multiply at 0x7532c41da2a0>
)

Vamos agora fazer uma chamada ao modelo GPT-4o-mini: inicialmente sem ferramentas e, em seguida, com elas.

llm = init_chat_model("gpt-4o-mini", temperature=0)
system_message = SystemMessage(
    content=""" Você é um assistente de matemática prestativo. Você tem acesso a ferramentas. 
                Quando o usuário pedir algo, primeiro verifique se você possui uma ferramenta que resolva esse problema."""
)
human_message = HumanMessage("Oi eu sou Goku")
messages: list[BaseMessage] = [
    system_message,
    human_message,
]
result = llm.invoke(messages)

A saída de result segue abaixo. Na mensagem de retorno AIMessage -> content, temos a resposta do modelo: 'Oi, Goku! Como posso ajudar você hoje? Se precisar de ajuda com matemática ou qualquer outra coisa, é só me avisar!'.

AIMessage(
    content='Oi, Goku! Como posso ajudar você hoje? Se precisar de ajuda com matemática ou qualquer outra coisa, é só me avisar!',
    additional_kwargs={'refusal': None},
    response_metadata={
        'token_usage': {
            'completion_tokens': 28,
            'prompt_tokens': 54,
            'total_tokens': 82,
            'completion_tokens_details': {'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0},
            'prompt_tokens_details': {'audio_tokens': 0, 'cached_tokens': 0}
        },
        'model_provider': 'openai',
        'model_name': 'gpt-4o-mini-2024-07-18',
        'system_fingerprint': 'fp_560af6e559',
        'id': 'chatcmpl-CSuxFiARtuT2nfkJYzXlnQRg656Dl',
        'service_tier': 'default',
        'finish_reason': 'stop',
        'logprobs': None
    },
    id='lc_run--18e23d3f-ba97-4d4b-8dc4-8bc2a55a4d4b-0',
    usage_metadata={'input_tokens': 54, 'output_tokens': 28, 'total_tokens': 82, 'input_token_details': {'audio': 0, 'cache_read': 0}, 'output_token_details': {'audio': 0, 'reasoning': 0}}
)

Vamos agora adicionar uma ferramenta à conversa e observar o resultado. O código completo segue abaixo:

from langchain.chat_models import init_chat_model
from langchain.tools import BaseTool, tool
from langchain_core.messages import (
    BaseMessage,
    HumanMessage,
    SystemMessage,
)
from rich import print

from dotenv import load_dotenv

load_dotenv()

@tool()
def multiply(a: float, b: float) -> float:
    """Multipy a * b and return the result
    Args:
        a (float): The first number
        b (float): The second number
    Returns:
        float: The resulting foat of the equation a * b"""
    return a * b


llm = init_chat_model("gpt-4o-mini", temperature=0)

system_message = SystemMessage(
    content=""" Você é um assistente de matemática prestativo. Você tem acesso a ferramentas. 
                Quando o usuário pedir algo, primeiro verifique se você possui uma ferramenta que resolva esse problema."""
)
human_message = HumanMessage("Oi eu sou Goku, quanto é 12.5 multiplicado por 3.4?")
messages: list[BaseMessage] = [
    system_message,
    human_message,
]
tools: list[BaseTool] = [
    multiply,
]

llm_with_tools = llm.bind_tools(tools)

if __name__ == "__main__":
    result = llm_with_tools.invoke(messages)
    print(result)

As principais diferenças entre uma chamada sem ferramentas ou seja, uma conversa simples e uma conversa com ferramentas estão na adição da função multiply, que representa nossa ferramenta responsável por executar uma ação específica no caso a multiplicação de dois pontos flutuantes, e na criação da lista de ferramentas disponíveis. Além disso, a mensagem agora é diferente da primeira chamada “Oi, eu sou o Goku! Quanto é 12.5 multiplicado por 3.4?”. Com base nessa solicitação, o LLM identifica a intenção do usuário e sugere a ferramenta mais adequada para resolver a tarefa, neste caso, a função responsável por realizar a multiplicação.

Nesse exemplo, temos apenas uma ferramenta, mas poderíamos incluir várias, cada uma com sua função e finalidade. No entanto, é importante ter cuidado: quanto maior o número de ferramentas disponíveis, maior a complexidade do processo de decisão do modelo. Isso pode levar a comportamentos inesperados ou alucinações, especialmente se as ferramentas tiverem propósitos semelhantes ou se o contexto da solicitação não for claro.

Portanto, ao adicionar múltiplas ferramentas, é recomendável definir descrições claras e propósitos bem delimitados para cada uma delas, garantindo que a LLM saiba quando e como utilizá-las corretamente.

@tool()
def multiply(a: float, b: float) -> float:
    """Multipy a * b and return the result
    Args:
        a (float): The first number
        b (float): The second number
    Returns:
        float: The resulting foat of the equation a * b"""
    return a * b

tools: list[BaseTool] = [
    multiply,
]
llm_with_tools = llm.bind_tools(tools)

Após realizar a chamada ao LLM com a ferramenta configurada, observamos a seguinte saída gerada pelo modelo:

AIMessage(
    content='',
    additional_kwargs={'refusal': None},
    response_metadata={
        'token_usage': {
            'completion_tokens': 21,
            'prompt_tokens': 144,
            'total_tokens': 165,
            'completion_tokens_details': {
                'accepted_prediction_tokens': 0,
                'audio_tokens': 0,
                'reasoning_tokens': 0,
                'rejected_prediction_tokens': 0
            },
            'prompt_tokens_details': {'audio_tokens': 0, 'cached_tokens': 0}
        },
        'model_provider': 'openai',
        'model_name': 'gpt-4o-mini-2024-07-18',
        'system_fingerprint': 'fp_560af6e559',
        'id': 'chatcmpl-CTyJBbjWwJJ4ehSSIMqmXzxFIhEXn',
        'service_tier': 'default',
        'finish_reason': 'tool_calls',
        'logprobs': None
    },
    id='lc_run--961d6734-1a03-4c3a-afe5-2d0a9a34861c-0',
    tool_calls=[
        {
            'name': 'multiply',
            'args': {'a': 12.5, 'b': 3.4},
            'id': 'call_CezDcbeqTBbMvVMp8WMSNZD8',
            'type': 'tool_call'
        }
    ],
    usage_metadata={
        'input_tokens': 144,
        'output_tokens': 21,
        'total_tokens': 165,
        'input_token_details': {'audio': 0, 'cache_read': 0},
        'output_token_details': {'audio': 0, 'reasoning': 0}
    }
)

A parte mais importante da resposta é a tag tool_calls, pois é nela que o LLM indica qual ou quais ferramentas são mais adequadas para atender à solicitação do usuário.

Dentro dessa estrutura, encontramos o nome da função selecionada 'name': 'multiply', os argumentos utilizados 'args': {'a': 12.5, 'b': 3.4} e um identificador único da chamada 'id': 'call_CezDcbeqTBbMvVMp8WMSNZD8'.

Esse identificador é útil para rastrear a execução da ferramenta ou correlacionar respostas quando há múltiplas chamadas dentro da mesma interação. Em resumo, o bloco tool_calls representa o momento em que o modelo decide invocar uma ação externa para gerar uma resposta mais precisa.

    tool_calls=[
        {
            'name': 'multiply',
            'args': {'a': 12.5, 'b': 3.4},
            'id': 'call_CezDcbeqTBbMvVMp8WMSNZD8',
            'type': 'tool_call'
        }
    ],

Agora vem o pulo do gato: não é a LLM que executa a função, e sim o seu código. Todas as ferramentas são identificadas a partir do contexto da conversa, e o modelo apenas sugere qual(is) delas devem ser utilizadas.

Cabe ao seu código desenvolvido por você executar efetivamente as funções com os parâmetros indicados pela LLM. Isso permite que várias ferramentas sejam acionadas conforme necessário, enriquecendo a conversa com informações adicionais, sem que o modelo precise realizar cálculos ou ações externas por conta própria.

É bastante interessante entender como isso funciona nos bastidores. Quando você utiliza frameworks como LangGraph, CrewAI, Microsoft Agent Framework, Semantic Kernel, entre outros, a execução dessas funções fica abstraída, facilitando a integração e a automação, sem que você precise lidar com todos os detalhes de implementação manualmente. Vamos ver agora como podemos executar nossa ferramenta.

from langchain.chat_models import init_chat_model
from langchain.tools import BaseTool, tool
from langchain_core.messages import (
    BaseMessage,
    HumanMessage,
    SystemMessage,
    AIMessage,
    ToolMessage,
)
from rich import print

from dotenv import load_dotenv

load_dotenv()


@tool()
def multiply(a: float, b: float) -> float:
    """Multipy a * b and return the result
    Args:
        a (float): The first number
        b (float): The second number
    Returns:
        float: The resulting foat of the equation a * b"""
    return a * b


llm = init_chat_model("gpt-4o-mini", temperature=0)
system_message = SystemMessage(
    content=""" Você é um assistente de matemática prestativo. Você tem acesso a ferramentas. 
                Quando o usuário pedir algo, primeiro verifique se você possui uma ferramenta que resolva esse problema."""
)
human_message = HumanMessage("Oi eu sou Goku, quanto é 12.5 multiplicado por 3.4?")
messages: list[BaseMessage] = [
    system_message,
    human_message,
]
tools: list[BaseTool] = [
    multiply,
]
tools_by_name = {tool.name: tool for tool in tools}

llm_with_tools = llm.bind_tools(tools)


def run_tool(response):
    if isinstance(response, AIMessage) and getattr(response, "tool_calls", None):
        call = response.tool_calls[-1]
        name, args, id_ = call["name"], call["args"], call["id"]

        try:
            content = tools_by_name[name].invoke(args)
            status = "success"
        except (KeyError, IndexError, TypeError, ValueError) as error:
            content = f"Erro: Ferramenta '{name}' não encontrada.{error}"
            status = "error"
        tool_message = ToolMessage(content=content, tool_call_id=id_, status=status)
        messages.append(tool_message)
        llm_response = llm_with_tools.invoke(messages)
        messages.append(llm_response)
        print(messages)


if __name__ == "__main__":
    llm_response = llm_with_tools.invoke(messages)
    messages.append(llm_response)
    run_tool(llm_response)

O que tem de novidades nesse código:

tools_by_name = {tool.name: tool for tool in tools}: Nesse ponto, estamos pegando todos os nomes das ferramentas (funções) que foram passadas para a LLM e criando um dicionário que mapeia cada nome para o respectivo objeto da ferramenta. Isso permite acessar rapidamente qualquer ferramenta pelo seu nome quando a LLM indicar que ela deve ser utilizada.
run_tool: Executando ferramentas sugeridas pela LLM a função run_tool é responsável por executar de fato a função indicada pela LLM para realizar a ação desejada. Ela recebe a resposta da LLM, verifica se há chamadas de ferramentas (tool_calls) e, se houver, executa a ferramenta correspondente e registra a resposta.

Vamos analisar o trecho de código linha a linha e entender o que ele faz:

def run_tool(response):
    if isinstance(response, AIMessage) and getattr(response, "tool_calls", None):
        call = response.tool_calls[-1]
        name, args, id_ = call["name"], call["args"], call["id"]

        try:
            content = tools_by_name[name].invoke(args)
            status = "success"
        except (KeyError, IndexError, TypeError, ValueError) as error:
            content = f"Erro: Ferramenta '{name}' não encontrada.{error}"
            status = "error"
        tool_message = ToolMessage(content=content, tool_call_id=id_, status=status)
        messages.append(tool_message)
        llm_response = llm_with_tools.invoke(messages)
        messages.append(llm_response)
        print(messages)

    if isinstance(response, AIMessage) and getattr(response, "tool_calls", None):

Verifica duas coisas:

Se response é uma instância da classe AIMessage.
Se response possui um atributo chamado tool_calls (usando getattr para evitar erro se não existir).
Ou seja, só prossegue se a mensagem veio do LLM e contém chamadas para ferramentas.

   call = response.tool_calls[-1]

Pega a última chamada de ferramenta presente na lista tool_calls.
Cada call é esperado ser um dicionário com informações sobre a ferramenta a ser executada.

    name, args, id_ = call["name"], call["args"], call["id"]

Extrai três informações da chamada da ferramenta:

name: nome da ferramenta a ser chamada.
args: argumentos que a ferramenta precisa.
id_: identificador da chamada (usado para rastrear qual mensagem gerou a ação).

        try:
            content = tools_by_name[name].invoke(args)
            status = "success"

Tenta executar a ferramenta:

tools_by_name é um dicionário que mapeia nomes de ferramentas para objetos/funções.
.invoke(args) executa a ferramenta com os argumentos fornecidos.
Se funcionar, define status como "success" e salva a saída em content.

        except (KeyError, IndexError, TypeError, ValueError) as error:
            content = f"Erro: Ferramenta '{name}' não encontrada.{error}"
            status = "error"

Se houver algum erro ao chamar a ferramenta (ex: nome não existe, argumentos incorretos), captura a exceção e:

Define content com uma mensagem de erro.
Marca status como "error".

        tool_message = ToolMessage(content=content, tool_call_id=id_, status=status)

Cria uma mensagem do tipo ToolMessage que representa a execução da ferramenta:

content: resultado ou mensagem de erro.
tool_call_id: liga a mensagem ao ID da chamada da ferramenta original.
status: sucesso ou erro.

        messages.append(tool_message)

Adiciona a mensagem da ferramenta à lista messages, que é o histórico da conversa.

        llm_response = llm_with_tools.invoke(messages)

Envia o histórico atualizado (messages) de volta para o LLM, agora incluindo a resposta da ferramenta.

A saída após a execução da chamada com ferramentas é:

[
    SystemMessage(
        content=' Você é um assistente de matemática prestativo. Você tem acesso a ferramentas. \n                Quando o usuário pedir algo, primeiro verifique se você possui uma ferramenta 
que resolva esse problema.',
        additional_kwargs={},
        response_metadata={}
    ),
    HumanMessage(content='Oi eu sou Goku, quanto é 12.5 multiplicado por 3.4?', additional_kwargs={}, response_metadata={}),
    AIMessage(
        content='',
        additional_kwargs={'refusal': None},
        response_metadata={
            'token_usage': {
                'completion_tokens': 21,
                'prompt_tokens': 144,
                'total_tokens': 165,
                'completion_tokens_details': {'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0},
                'prompt_tokens_details': {'audio_tokens': 0, 'cached_tokens': 0}
            },
            'model_provider': 'openai',
            'model_name': 'gpt-4o-mini-2024-07-18',
            'system_fingerprint': 'fp_560af6e559',
            'id': 'chatcmpl-CTzPwOcFISxRtpXMgNEVDTDacTsio',
            'service_tier': 'default',
            'finish_reason': 'tool_calls',
            'logprobs': None
        },
        id='lc_run--f5058b1e-863d-47af-a444-963f3252a01c-0',
        tool_calls=[{'name': 'multiply', 'args': {'a': 12.5, 'b': 3.4}, 'id': 'call_boELMe3XRPYIlgCW5XlJaQzI', 'type': 'tool_call'}],
        usage_metadata={
            'input_tokens': 144,
            'output_tokens': 21,
            'total_tokens': 165,
            'input_token_details': {'audio': 0, 'cache_read': 0},
            'output_token_details': {'audio': 0, 'reasoning': 0}
        }
    ),
    ToolMessage(content='42.5', tool_call_id='call_boELMe3XRPYIlgCW5XlJaQzI'),
    AIMessage(
        content='Oi Goku! O resultado de 12.5 multiplicado por 3.4 é 42.5.',
        additional_kwargs={'refusal': None},
        response_metadata={
            'token_usage': {
                'completion_tokens': 25,
                'prompt_tokens': 175,
                'total_tokens': 200,
                'completion_tokens_details': {'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0},
                'prompt_tokens_details': {'audio_tokens': 0, 'cached_tokens': 0}
            },
            'model_provider': 'openai',
            'model_name': 'gpt-4o-mini-2024-07-18',
            'system_fingerprint': 'fp_560af6e559',
            'id': 'chatcmpl-CTzPxR7YftzqdNVl3UIKezdPJ6sAz',
            'service_tier': 'default',
            'finish_reason': 'stop',
            'logprobs': None
        },
        id='lc_run--57a0afb7-aaa3-4a71-986a-c42f167d35d0-0',
        usage_metadata={
            'input_tokens': 175,
            'output_tokens': 25,
            'total_tokens': 200,
            'input_token_details': {'audio': 0, 'cache_read': 0},
            'output_token_details': {'audio': 0, 'reasoning': 0}
        }
    )
]

O fluxo de mensagens:

a - SystemMessage

SystemMessage(
    content='Você é um assistente de matemática prestativo. Você tem acesso a ferramentas. Quando o usuário pedir algo, primeiro verifique se você possui uma ferramenta que resolva esse problema.'
)

Define o contexto e instruções do assistente.
Indica que o modelo pode usar ferramentas externas para responder.
Funciona como a “base” do diálogo, informando como o assistente deve se comportar.

b - HumanMessage

HumanMessage(content='Oi eu sou Goku, quanto é 12.5 multiplicado por 3.4?')

Representa a pergunta do usuário.
Nesse caso, o usuário quer calcular uma multiplicação.

c - AIMessage (primeira resposta)

AIMessage(
    content='',
    tool_calls=[{'name': 'multiply', 'args': {'a': 12.5, 'b': 3.4}, 'id': 'call_boELMe3XRPYIlgCW5XlJaQzI'}],
    response_metadata={'finish_reason': 'tool_calls'}
)

O modelo não respondeu diretamente ao usuário ainda (content='').
Identificou que uma ferramenta deve ser usada: multiply.
Preencheu tool_calls com:
- name: nome da ferramenta a ser chamada.
- args: argumentos necessários para a execução.
- id: identificador da chamada.

d - ToolMessage

ToolMessage(content='42.5', tool_call_id='call_boELMe3XRPYIlgCW5XlJaQzI')

Contém o resultado da execução da ferramenta.
Aqui, a multiplicação foi realizada pelo código (run_tool) e retornou 42.5.
Associado à chamada específica pelo tool_call_id.

e - AIMessage (resposta final)

AIMessage(
    content='Oi Goku! O resultado de 12.5 multiplicado por 3.4 é 42.5.',
    response_metadata={'finish_reason': 'stop'}
)

O código completo: Github

Referências:

An introduction to function calling and tool use

What is tool calling?

Tool calling

Tools & Function Calling in LLMs and AI Agents: A Hands-On Guide

Tool Calling for LLMs: A Detailed Tutorial

Introdução ao Microsoft Agent Framework

Introdução ao LangGraph: Orquestrando agentes com fluxos baseados em grafos

Wanderson Alves Rodrigues — Fri, 02 May 2025 00:37:25 +0000

A construção de aplicações com Large Language Models (LLMs) evoluiu rapidamente. Frameworks como LangChain nos deram as ferramentas para conectar LLMs com fontes externas, memória, e agentes capazes de tomar decisões. Mas à medida que a complexidade dos fluxos aumenta, surge um desafio comum: como orquestrar o comportamento dos agentes de forma flexível, controlável e com lógica mais rica que simples pipelines lineares?

É aqui que entra o LangGraph.

O que é o LangGraph?

O LangGraph é uma extensão do LangChain que permite construir fluxos de execução orientados a grafos para LLMs e agentes. Em vez de seguir uma sequência fixa de passos (como num pipeline tradicional), você define nós (nodes) e arestas (edges) que representam o comportamento dinâmico do sistema.

Com ele, é possível criar aplicações onde o fluxo depende do estado atual da execução, decisões do agente ou resultados intermediários algo essencial para sistemas multiagentes, diálogos complexos, rotas condicionais e muito mais.

Por que usar LangGraph?

Algumas razões para considerar o LangGraph:

Controle total sobre o fluxo de execução, incluindo loops, decisões condicionais e bifurcações.
Escalabilidade para agentes mais complexos, sem se perder em estruturas monolíticas.
Modelagem de estado simples e transparente, facilitando o debug e a manutenção.
Composição modular, onde cada nó do grafo pode representar um agente, ferramenta ou processo.

Conceitos-chave

Antes de mostrar um exemplo, vale entender os conceitos básicos:

Node (nó): uma função ou agente que processa o estado atual.
Edge (aresta): uma transição entre nós, baseada em uma regra.
State (estado): dados compartilhados que são passados entre os nós.
Graph (grafo): a definição do fluxo completo da aplicação.

Mão na Massa

Vamos começar de exemplos mais simples e evoluir para algo mais interessante.

Requisitos:

Python >= 3.10
uv

01 - Simples ChatBot

Vamos criar um chatbot interativo que responde em tempo real usando a biblioteca LangGraph, um wrapper para fluxos de conversa com LLMs, e LiteLLM, que pode ser usado com modelos da OpenAI ou vários outros desde LLM até SLM (neste caso, gpt-4.1-nano).

A imagem acima mostra o fluxo. Apesar de ser bem simples, ele começa, passa pelo chat e termina. É claro que podemos ter fluxos mais complexos, porém, para este primeiro exemplo, optei por um mais simples.

Ao executar o uv run chat_bot.py o usuário poderá em linguagem natural interagir com o chat que vai executar o fluxo e usar a LLM da OpenAI para retornar.

Código completo:

import os
from dotenv import load_dotenv
from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langchain_litellm import ChatLiteLLM

load_dotenv()
os.environ['OPENAI_API_KEY'] = os.getenv("OPENAI_API_KEY")
llm = ChatLiteLLM(model="gpt-4.1-nano", temperature=0.1)

class State(TypedDict):
    messages: Annotated[list, add_messages]

def send(state: State):
    return {"messages": [llm.invoke(state["messages"])]}

graph_builder = StateGraph(State)
graph_builder.add_node("chatbot", send)
graph_builder.add_edge(START, "chatbot")
graph_builder.add_edge("chatbot", END)
graph = graph_builder.compile()

def stream_graph_updates(user_input: str):
    for event in graph.stream({"messages": [{"role": "user", "content": user_input}]}):
        for value in event.values():
            print("Assistant:", value["messages"][-1].content)


while True:
    try:
        user_input = input("User: ")
        if user_input.lower() in ["quit", "exit", "q"]:
            print("Goodbye!")
            break
        stream_graph_updates(user_input)
    except:
        user_input = "What do you know about LangGraph?"
        print("User: " + user_input)
        stream_graph_updates(user_input)
        break

a - Importações e configuração de ambiente

import os
from dotenv import load_dotenv
from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langchain_litellm import ChatLiteLLM

Carrega variáveis de ambiente do .env.
Usa ChatLiteLLM vamos usar com um SDK para acessar vários LLMs.
Usa LangGraph, que permite construir fluxos de estados conversacionais com LLMs.
add_messages é um utilitário do LangGraph que facilita o histórico de mensagens.

StateGraph

É a classe principal usada para construir grafos de estado no LangGraph.
Permite definir nós (funções que manipulam o estado), e como os estados/nós se conectam.
É uma forma estruturada de montar pipelines de execução com LLMs, mantendo o controle do fluxo de dados (estado).

Exemplo de uso:

graph_builder = StateGraph(State)

Aqui você está dizendo: quero construir um grafo de estados baseado no tipo de estado State.

START

Representa o ponto de entrada do grafo — onde a execução começa.
Ao adicionar uma aresta partindo de START, você define qual será o primeiro nó a ser executado.

Exemplo:

graph_builder.add_edge(START, "chatbot")

Isso diz: “comece no nó chatbot”.

END

Representa o ponto final do grafo — onde a execução termina.
Você adiciona uma aresta para END a partir do último nó do seu fluxo.

Exemplo:

graph_builder.add_edge("chatbot", END)

Isso significa: depois de executar chatbot, finalize o grafo.

b - Carrega a chave da API e configura o modelo

load_dotenv()
os.environ['OPENAI_API_KEY'] = os.getenv("OPENAI_API_KEY")
llm = ChatLiteLLM(model="gpt-4.1-nano", temperature=0.1)

Carrega a chave da API a partir do arquivo .env.
Configura o modelo LLM para ser usado nas respostas.

c - Define o estado da conversa

class State(TypedDict):
    messages: Annotated[list, add_messages]

O estado é um dicionário tipado com uma chave messages, que é uma lista anotada com add_messages.
Isso permite que LangGraph trate corretamente o histórico da conversa.

d - Função que envia mensagens para o modelo

def send(state: State):
    return {"messages": [llm.invoke(state["messages"])]}

Recebe o histórico da conversa e chama o modelo com ele (llm.invoke(...)).
Retorna uma nova mensagem (resposta do assistente) dentro da chave messages.

e - Constrói o fluxo do grafo conversacional

graph_builder = StateGraph(State)
graph_builder.add_node("chatbot", send)
graph_builder.add_edge(START, "chatbot")
graph_builder.add_edge("chatbot", END)
graph = graph_builder.compile()

Cria um grafo de estados:

Começa em START, vai para o nó chatbot (função send) e termina em END.
Um fluxo simples de entrada → resposta.

02 - Avaliador de Redação

Nesse outro exemplo vamos criar agentes IA para avaliar redações. Um coisa muito legal no LangGraph é ter fluxos condicionais, onde podemos criar condições e navegar pelas arestas. Este código implementa um sistema automatizado de avaliação de redações usando IA (LLMs) e um fluxo de trabalho baseado em grafo com a biblioteca LangGraph.

a - Objetivo Geral

Avaliar automaticamente uma redação com base em quatro critérios:

Relevância com o tema
Gramática
Estrutura do texto
Profundidade da análise

Cada critério recebe uma pontuação de 0 a 1, e uma pontuação final ponderada é calculada.

Relevância do Conteúdo: Avalia quão bem a redação aborda o tema proposto
Verificação Gramatical: Avalia o uso da linguagem e a correção gramatical da redação
Análise da Estrutura: Examina a organização e o fluxo de ideias na redação
Profundidade de Análise: Mede o nível de pensamento crítico e insight apresentado
Cada etapa é executada condicionalmente com base nas pontuações das etapas anteriores, permitindo o término antecipado de redações de baixa qualidade. A pontuação final é uma média ponderada de todas as pontuações dos componentes individuais.

b - Funções de Avaliação

Cada função chama o LLM com um prompt específico e extrai a nota da resposta:

verificar_relevancia(state): Avalia o quanto a redação está relacionada ao tema.
verificar_gramatica(state): Avalia a correção gramatical.
analizar_estrutura(state): Avalia a estrutura do texto.
avaliar_profundidade(state): Avalia a profundidade da análise e argumentação.
extrair_pontuacao(content): Função auxiliar para extrair o número da resposta do LLM.

c - Cálculo da Nota Final

calcular_pontuacao_final(state): Combina as notas com pesos:

Relevância: 30%
Gramática: 20%
Estrutura: 20%
Profundidade: 30%

d - Fluxo com LangGraph

Um grafo de execução (workflow) é construído com as etapas acima.
Fluxo condicional: Se uma nota for muito baixa, pode pular avaliações seguintes. Ex: Se a relevância ≤ 0.5, vai direto calcular a nota final.

Código completo:

import os
from dotenv import load_dotenv
from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, END
from langgraph.graph.message import add_messages
from langchain_litellm import ChatLiteLLM
from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
import re

class State(TypedDict):
    """ Representa o estado do processo de avaliação da redação """
    redacao: str
    pontuacao_relevancia: float
    pontuacao_gramatica: float
    pontuacao_estrutura: float
    pontuacao_profundidade: float
    pontuacao_final: float

load_dotenv()
os.environ['OPENAI_API_KEY'] = os.getenv("OPENAI_API_KEY")
llm = ChatLiteLLM(model="gpt-4.1-nano", temperature=0.1)

def extrair_pontuacao(content: str) -> float:
    """Extrai a pontuação numérica da resposta do LLM."""
    match = re.search(r'Pontuação:\s*(\d+(\.\d+)?)', content)
    if match:
        return float(match.group(1))
    raise ValueError(f"Não foi possível extrair a pontuação de: {content}")

def verificar_relevancia(state: State) -> State:
    """Verifica a relevância da redação."""
    messages = [
        HumanMessage(
            content=    "Analise a relevância da seguinte redação em relação ao tema dado, prezando pela excelência da Língua Portuguesa. "
                        "Forneça uma pontuação de relevância entre 0 e 1. "
                        "Sua resposta deve começar com 'Pontuação: ' seguida da pontuação numérica, "
                        "depois forneça sua explicação.\n\nRedação: {redacao}".format(redacao=state["redacao"])
        )
    ]
    result = llm.invoke(messages)
    try:
        state["pontuacao_relevancia"] = extrair_pontuacao(result.content)
    except ValueError as e:
        print(f"Erro em verificar_relevancia: {e}")
        state["pontuacao_relevancia"] = 0.0
    return state

def verificar_gramatica(state: State) -> State:
    """Verifica a gramática da redação."""
    messages = [
        HumanMessage(
        content=        "Analise a gramática da Língua Portuguesa na seguinte redação. "
                        "Forneça uma pontuação de gramática entre 0 e 1. "
                        "Sua resposta deve começar com 'Pontuação: ' seguida da pontuação numérica, "
                        "depois forneça sua explicação.\n\nRedação: {redacao}".format(redacao=state["redacao"])
        )
    ]
    result = llm.invoke(messages)
    try:
        state["pontuacao_gramatica"] = extrair_pontuacao(result.content)
    except ValueError as e:
        print(f"Erro em verificar_gramatica: {e}")
        state["pontuacao_gramatica"] = 0.0
    return state

def analizar_estrutura(state: State) -> State:
    """Analisa a estrutura da redação."""
    messages = [
        HumanMessage(
        content=            "Analise a estrutura de acordo com a normal culta da Língua Portuguesa na seguinte redação. "
                            "Forneça uma pontuação de estrutura entre 0 e 1. "
                            "Sua resposta deve começar com 'Pontuação: ' seguida da pontuação numérica, "
                            "depois forneça sua explicação.\n\nRedação: {redacao}".format(redacao=state["redacao"])
        )
    ]
    result = llm.invoke(messages)
    try:
        state["pontuacao_estrutura"] = extrair_pontuacao(result.content)
    except ValueError as e:
        print(f"Erro em analizar_estrutura: {e}")
        state["pontuacao_estrutura"] = 0.0
    return state

def avaliar_profundidade(state: State) -> State:
    """Avalia a profundidade de análise na redação."""
    messages = [
        HumanMessage(
        content=           "Avalie a profundidade de análise na seguinte redação. "
                            "Forneça uma pontuação de profundidade entre 0 e 1. "
                            "Sua resposta deve começar com 'Pontuação: ' seguida da pontuação numérica, "
                            "depois forneça sua explicação.\n\nRedação: {redacao}".format(redacao=state["redacao"])
        )
    ]
    result = llm.invoke(messages)
    try:
        state["pontuacao_profundidade"] = extrair_pontuacao(result.content)
    except ValueError as e:
        print(f"Erro em avaliar_profundidade: {e}")
        state["pontuacao_profundidade"] = 0.0
    return state

def calcular_pontuacao_final(state: State) -> State:
    """Calcula a pontuação final com base nas pontuações dos componentes individuais."""
    state["pontuacao_final"] = (
        state["pontuacao_relevancia"] * 0.3 +
        state["pontuacao_gramatica"] * 0.2 +
        state["pontuacao_estrutura"] * 0.2 +
        state["pontuacao_profundidade"] * 0.3
    )
    return state

# Inicializa o StateGraph
workflow = StateGraph(State)

# Adiciona nós ao grafo
workflow.add_node("verificar_relevancia", verificar_relevancia)
workflow.add_node("verificar_gramatica", verificar_gramatica)
workflow.add_node("analizar_estrutura", analizar_estrutura)
workflow.add_node("avaliar_profundidade", avaliar_profundidade)
workflow.add_node("calcular_pontuacao_final", calcular_pontuacao_final)

# Define e adiciona arestas condicionais
workflow.add_conditional_edges(
    "verificar_relevancia",
    lambda x: "verificar_gramatica" if x["pontuacao_relevancia"] > 0.5 else "calcular_pontuacao_final"
)
workflow.add_conditional_edges(
    "verificar_gramatica",
    lambda x: "analizar_estrutura" if x["pontuacao_gramatica"] > 0.6 else "calcular_pontuacao_final"
)
workflow.add_conditional_edges(
    "analizar_estrutura",
    lambda x: "avaliar_profundidade" if x["pontuacao_estrutura"] > 0.7 else "calcular_pontuacao_final"
)
workflow.add_conditional_edges(
    "avaliar_profundidade",
    lambda x: "calcular_pontuacao_final"
)

# Define o ponto de entrada
workflow.set_entry_point("verificar_relevancia")

# Define o ponto de saída
workflow.add_edge("calcular_pontuacao_final", END)


# Compila o grafo
app = workflow.compile()


def avaliar_redacao(redacao: str) -> dict:
    """Avalia a redação fornecida usando o fluxo de trabalho definido."""
    initial_state = State(
        redacao=redacao,
        pontuacao_relevancia=0.0,
        pontuacao_gramatica=0.0,
        pontuacao_estrutura=0.0,
        pontuacao_profundidade=0.0,
        pontuacao_final=0.0
    )
    result = app.invoke(initial_state)
    return result

exemplo_redacao = """[REDACAO_AQUI]"""

# Avalia a redação de exemplo
result = avaliar_redacao(exemplo_redacao)

# Converte as pontuações de 0-1 para 0-10
pontuacao_final = result['pontuacao_final'] * 10
pontuacao_relevancia = result['pontuacao_relevancia'] * 10
pontuacao_gramatica = result['pontuacao_gramatica'] * 10
pontuacao_estrutura = result['pontuacao_estrutura'] * 10
pontuacao_profundidade = result['pontuacao_profundidade'] * 10

# Exibe os resultados
print(f"Pontuação Final da Redação: {pontuacao_final:.2f}/10\n")
print(f"Pontuação de Relevância: {pontuacao_relevancia:.2f}/10")
print(f"Pontuação de Gramática: {pontuacao_gramatica:.2f}/10")
print(f"Pontuação de Estrutura: {pontuacao_estrutura:.2f}/10")
print(f"Pontuação de Profundidade: {pontuacao_profundidade:.2f}/10")

Explicação do fluxo:

a - Entrada: começa no nó verificar_relevancia.

b - Se a pontuação de relevância > 0.5, vai para
verificar_gramatica. Caso contrário, vai direto para calcular_pontuacao_final.

c - Em verificar_gramatica:

Se a pontuação de gramática > 0.6, continua para analizar_estrutura.
Caso contrário, vai para calcular_pontuacao_final.

d - Em analizar_estrutura:

Se a pontuação de estrutura > 0.7, segue para avaliar_profundidade.
Caso contrário, vai para calcular_pontuacao_final.

e - avaliar_profundidade sempre leva para
calcular_pontuacao_final.

f - calcular_pontuacao_final é o último nó antes do fim (END).

Saída:

uv run avalidaor_redacao.py
Pontuação Final da Redação: 8.35/10

Pontuação de Relevância: 9.00/10
Pontuação de Gramática: 8.50/10
Pontuação de Estrutura: 8.50/10
Pontuação de Profundidade: 7.50/10

03 - RAG recuperar documentos

Neste exemplo, vamos adicionar alguns documentos ao RAG(Retrieval-Augmented Generation). Assim, de acordo com o que for solicitado, o sistema exibirá informações desses documentos, caso existam; caso contrário, buscará na internet. Segue abaixo o fluxo dos grafos.

O código implementa um fluxo completo de RAG (Retrieval-Augmented Generation) usando LangChain com documentos científicos da USP e busca web como fallback.
Recebe uma pergunta do usuário e tenta respondê-la com base em documentos previamente carregados e indexados. Se os documentos não forem suficientes, ele reformula a pergunta e realiza uma busca na web. Por fim, gera uma resposta baseada em todos os dados relevantes.

Explicação do Fluxo

Imports e Configuração Inicial

Importa bibliotecas do LangChain, dotenv, e ferramentas de busca na Web (Tavily).
Carrega as variáveis de ambiente, incluindo a chave da Tavily.

Carregamento e Indexação de Documentos

Três artigos científicos da Revista de Biologia da USP são baixados.
O conteúdo é dividido em pedaços menores (chunks).
Os pedaços são vetorizados e armazenados no ChromaDB.
É criado um retriever para buscar chunks relevantes com base em similaridade semântica.

Configuração dos LLMs e Prompts

Dois modelos da OpenAI são configurados: um para gerar respostas e outro para reescrita e avaliação.
São definidos prompts:

rag_prompt: Geração da resposta final.

grade_prompt: Avaliação da relevância dos documentos.

re_write_prompt: Reescrita da pergunta para melhorar a busca.

Ferramenta de busca na web (Tavily) configurada.

Definição do Estado do Grafo

Define-se a estrutura do estado compartilhado entre os nós, contendo: pergunta, documentos, resultado da geração, etc.

Funções dos Nós

recuperar: Usa o retriever para buscar documentos relevantes.
avaliar_documentos: Filtra documentos realmente relevantes com LLM.
transformar_pergunta: Reescreve a pergunta para buscar melhor.
busca_web: Realiza busca online com Tavily e adiciona os resultados como documentos.
gerar_resposta: Gera a resposta final com base no contexto (documentos).
decidir_geracao: Decide se precisa buscar na web com base na relevância dos documentos.

Construção do Grafo (LangGraph)

O grafo é construído com os nós acima conectados:

Início: START → recuperar → avaliar_documentos

Condicional: se não há documentos suficientes → transformar_pergunta → busca_web → gerar_resposta

Senão → gerar_resposta → END

Execução

Pergunta: "Prevalência e detecção de resistência de Staphylococcus"
O grafo é executado passo a passo, e os resultados de cada nó são mostrados.

         START
           ↓
      [recuperar]
           ↓
 [avaliar_documentos]
     ↙             ↘
[transformar]   [gerar_resposta]
     ↓
[busca_web]
     ↓
[gerar_resposta]
     ↓
          END

Código completo:

import os
from dotenv import load_dotenv
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_community.document_loaders import WebBaseLoader
from langchain_community.vectorstores import Chroma
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.pydantic_v1 import BaseModel, Field
from langchain_core.output_parsers import StrOutputParser
from langchain.schema import Document
from langchain import hub
from langchain_community.tools.tavily_search import TavilySearchResults
from langgraph.graph import END, StateGraph, START
from typing import List
from typing_extensions import TypedDict
from pprint import pprint

# -----------------------------
# Carregar variáveis de ambiente
# -----------------------------
load_dotenv()
os.environ['TAVILY_API_KEY'] = os.getenv("TAVILY_API_KEY")

# -----------------------------
# Carregamento e indexação de documentos
# -----------------------------
urls = [
    "https://www.revistas.usp.br/revbiologia/article/view/217747",
    "https://www.revistas.usp.br/revbiologia/article/view/206105",
    "https://www.revistas.usp.br/revbiologia/article/view/219858",
]

raw_docs = [doc for url in urls for doc in WebBaseLoader(url).load()]

text_splitter = RecursiveCharacterTextSplitter.from_tiktoken_encoder(chunk_size=250, chunk_overlap=0)
doc_chunks = text_splitter.split_documents(raw_docs)

vectorstore = Chroma.from_documents(
    documents=doc_chunks,
    collection_name="rag-chroma",
    embedding=OpenAIEmbeddings(),
)
retriever = vectorstore.as_retriever()

llm_main = ChatOpenAI(model_name="gpt-4.1-nano", temperature=0)
llm_advanced = ChatOpenAI(model="gpt-4.1-nano", temperature=0)

rag_prompt = hub.pull("rlm/rag-prompt")
rag_chain = rag_prompt | llm_main | StrOutputParser()

class GradeDocuments(BaseModel):
    binary_score: str = Field(description="Os documentos são relevantes à pergunta, 'sim' ou 'não'")

grade_prompt = ChatPromptTemplate.from_messages([
    ("system", "Você é um avaliador que verifica a relevância de um documento recuperado em relação a uma pergunta do usuário. Responda apenas em português do Brasil."),
    ("human", "Documento recuperado:\n\n{document}\n\nPergunta do usuário: {question}"),
])
retrieval_grader = grade_prompt | llm_advanced.with_structured_output(GradeDocuments)

re_write_prompt = ChatPromptTemplate.from_messages([
    ("system", "Você é um reescritor de perguntas que transforma a entrada em uma versão melhor para busca. Responda em português do Brasil."),
    ("human", "Pergunta inicial:\n\n{question}\n\nFormule uma pergunta melhorada."),
])
question_rewriter = re_write_prompt | llm_advanced | StrOutputParser()

web_search_tool = TavilySearchResults(k=3)

class GraphState(TypedDict):
    question: str
    generation: str
    web_search: str
    documents: List[Document]
    full_context: str

def recuperar(state):
    print(">>> Recuperar documentos")
    question = state["question"]
    documents = retriever.get_relevant_documents(question)
    return {"documents": documents, "question": question}

def avaliar_documentos(state):
    print(">>> Avaliar relevância dos documentos")
    question = state["question"]
    documents = state["documents"]

    filtered_docs = []
    for doc in documents:
        score = retrieval_grader.invoke({"question": question, "document": doc.page_content})
        if score.binary_score.lower() == "sim":
            filtered_docs.append(doc)

    web_search = "Sim" if len(filtered_docs) < 1 else "Não"
    return {"documents": filtered_docs, "question": question, "web_search": web_search}

def transformar_pergunta(state):
    print(">>> Reescrever pergunta")
    question = state["question"]
    better_question = question_rewriter.invoke({"question": question})
    return {"documents": state["documents"], "question": better_question}

def busca_web(state):
    print(">>> Buscar na Web")
    question = state["question"]
    docs = web_search_tool.invoke({"query": question})
    web_results = "\n".join([d["content"] for d in docs])
    state["documents"].append(Document(page_content=web_results))
    return {"documents": state["documents"], "question": question}

def gerar_resposta(state):
    print(">>> Gerar resposta")
    return {
        "documents": state["documents"],
        "question": state["question"],
        "generation": rag_chain.invoke({"context": state["documents"], "question": state["question"]}),
        "web_search": state.get("web_search", "Não"),
        "full_context": "\n\n".join([doc.page_content for doc in state["documents"]])
    }

def decidir_geracao(state):
    if state["web_search"] == "Sim":
        return "transformar_pergunta"
    return "gerar_resposta"

# -----------------------------
# Construção do grafo
# -----------------------------
workflow = StateGraph(GraphState)
workflow.add_node("recuperar", recuperar)
workflow.add_node("avaliar_documentos", avaliar_documentos)
workflow.add_node("transformar_pergunta", transformar_pergunta)
workflow.add_node("busca_web", busca_web)
workflow.add_node("gerar_resposta", gerar_resposta)

workflow.add_edge(START, "recuperar")
workflow.add_edge("recuperar", "avaliar_documentos")
workflow.add_conditional_edges("avaliar_documentos", decidir_geracao, {
    "transformar_pergunta": "transformar_pergunta",
    "gerar_resposta": "gerar_resposta"
})
workflow.add_edge("transformar_pergunta", "busca_web")
workflow.add_edge("busca_web", "gerar_resposta")
workflow.add_edge("gerar_resposta", END)

app = workflow.compile()

# -----------------------------
# Execução
# -----------------------------
inputs = {"question": "Prevalência e detecção de resistência de Staphylococcus"}
for output in app.stream(inputs):
    for key, value in output.items():
        pprint(f"Nó '{key}':")
    pprint("\n---\n")

# Resposta final
pprint(value["full_context"])

Os códigos completos: GitHub

Referências:
LangGraph
Agent AI with LangGraph: A Modular
Framework for Enhancing Machine Translation
Using Large Language Models
LiteLLM
Corrective Retrieval Augmented Generation
UV
Scoras Academy

Agent AI a automação inteligente com CrewAI

Wanderson Alves Rodrigues — Thu, 06 Mar 2025 00:57:19 +0000

A inteligência artificial tem evoluído rapidamente, e um dos conceitos mais promissores dessa revolução é o Agent AI. Esses agentes inteligentes não apenas processam informações, mas também tomam decisões autônomas e interagem com sistemas e usuários de forma proativa. Vamos explorar o que são Agent AIs, como funcionam e como podem ser aplicados para transformar a automação inteligente e também aplicar usando CrewAI.

O que é um Agent AI?

Um Agent AI (Agente de Inteligência Artificial) é um sistema baseado em IA capaz de operar de forma autônoma para atingir objetivos específicos. Diferente de um chatbot tradicional, que apenas responde a comandos, um Agent AI pode raciocinar, planejar ações e executar tarefas sem intervenção humana constante.

Esses agentes podem ser usados para uma variedade de finalidades, como:

Automação de processos complexos: Monitoramento de sistemas, tomada de decisões em tempo real e otimização de fluxos de trabalho.
Atendimento ao cliente avançado: Resolução de problemas, recomendações personalizadas e suporte técnico automatizado.
Análise de dados inteligente: Coleta, filtragem e interpretação de grandes volumes de dados para tomada de decisões estratégicas.

Como funciona um Agent AI?

Os Agent AIs utilizam diversas tecnologias e abordagens para alcançar um comportamento autônomo e inteligente. Alguns dos principais componentes incluem:

a. Modelos de Machine Learning e LLMs (Large Language Models): Utilizam aprendizado de máquina para processar linguagem natural, reconhecer padrões e tomar decisões baseadas em dados.
b. Raciocínio e Planejamento: Incorporam técnicas como Planejamento Automático e Aprendizado por Reforço para definir estratégias e agir de forma autônoma.
c. Interação com APIs e sistemas externos: Conectam-se a bancos de dados, CRMs, ERPs e outras ferramentas para buscar e processar informações.
d. Memória e Contexto: Diferente de assistentes básicos, os agentes podem manter um histórico de interações e aprender com cada experiência, tornando-se mais eficientes com o tempo.

Aplicações dos Agent AIs

Os Agent AIs estão sendo adotados em diversas indústrias e setores para resolver problemas de maneira inovadora:

a. Empresas e Automação Corporativa

Empresas estão utilizando agentes inteligentes para automatizar tarefas repetitivas, gerenciar fluxos de trabalho e melhorar a eficiência operacional.

b. Assistentes Pessoais e Atendimento ao Cliente

Chatbots tradicionais estão evoluindo para agentes mais inteligentes que conseguem manter contexto, antecipar necessidades do usuário e oferecer recomendações mais precisas.

c. Cibersegurança e Detecção de Ameaças

Com o uso de IA, agentes podem monitorar redes em tempo real, identificar padrões suspeitos e responder automaticamente a possíveis ataques cibernéticos.

d. Pesquisa e Desenvolvimento

Empresas de tecnologia e inovação utilizam Agent AIs para buscar informações, sintetizar relatórios e acelerar o desenvolvimento de novos produtos e soluções.

Desafios na Implementação de Agent AIs

Como nem tudo são flores, apesar dos benefícios, há desafios a serem superados na adoção de agentes de IA:

Privacidade e Segurança de Dados: Como esses agentes lidam com grandes volumes de informações, é essencial implementar medidas rigorosas de proteção de dados.
Ética e Transparência: Evitar viés algorítmico e garantir que os agentes tomem decisões justas e imparciais.
Complexidade Técnica: Desenvolver e treinar agentes de IA requer expertise em machine learning e integração com sistemas empresariais.
Recursos Computacionais: O processamento de modelos avançados demanda infraestrutura robusta, impactando custos e escalabilidade.
Alucinação: Como os modelos de IA podem gerar respostas imprecisas ou fictícias, há o risco de fornecer informações erradas, o que pode impactar a confiabilidade dos agentes em aplicações críticas.
Não-determinismo: Como a IA pode gerar respostas diferentes para a mesma entrada, isso dificulta a previsibilidade e a consistência dos resultados, sendo um desafio para aplicações que exigem decisões padronizadas.

Tipos de Agent AIs

As organizações utilizam diferentes tipos de agentes inteligentes para atender a necessidades específicas:

a. Agentes Reflexos Simples

Operam com base em regras predefinidas e dados imediatos, sendo ideais para tarefas simples.Tomam decisões baseadas apenas na percepção atual, respondendo a sinais ambientais imediatos sem qualquer memória interna de acontecimentos passados.
Exemplos:

um sistema de resposta automática que redefine senhas ao detectar palavras-chave em solicitações de suporte.
um termóstato que liga o ar condicionado quando a temperatura atual ultrapassa um determinado limite é um agente reflexo simples.

b. Agentes Reflexos Baseados em Modelos

Possuem mecanismos de decisão mais avançados, avaliando consequências antes de agir, criando um modelo interno do ambiente percebido.
Exemplo:

um sistema de controle de tráfego que ajusta sinais de trânsito com base no fluxo de veículos detectado.

c. Agentes Baseados em Metas

Comparam diferentes abordagens para alcançar objetivos de maneira eficiente, sendo aplicados em processamento de linguagem natural e robótica.Utilizam sensores para recolher informações e consideram o historial de percepções, permitindo uma tomada de decisões mais sofisticada.
Exemplos:

um robô autônomo que navega por um armazém para coletar e organizar pacotes com base em metas de entrega.
uma IA que joga xadrez e que considera o histórico de jogadas e o estado atual do tabuleiro para decidir a próxima jogada é um agente baseado em modelos.

d. Agentes Baseados em Serviços Utilitários

Usam algoritmos para maximizar benefícios aos usuários, analisando cenários para tomar decisões otimizadas.
Exemplo:

um agente que monitora preços de passagens aéreas e recomenda a melhor compra com base na relação custo-benefício.
uma IA de consultor de investimentos que avalia várias opções de investimento com base em potenciais retornos e riscos é um agente baseado em objetivos.

e. Agentes de Aprendizagem

Melhoram continuamente com base em experiências passadas, utilizando feedback para aprimorar decisões ao longo do tempo.Um elemento de aprendizagem permite-lhes adquirir novos conhecimentos e ajustar o seu comportamento com base na experiência.
Exemplos:

um assistente virtual que aprende preferências do usuário para sugerir conteúdos ou ajustar configurações automaticamente.
um filtro de spam que aprende a identificar novos tipos de e-mails de spam com base no feedback do utilizador é um agente de aprendizagem.

f. Agentes Hierárquicos

Compostos por múltiplos agentes organizados em camadas, onde agentes superiores delegam tarefas a subordinados para otimizar execuções complexas.Esta organização permite o tratamento eficiente de tarefas complexas através da divisão de responsabilidades entre diferentes níveis.
Exemplos:

um sistema de gerenciamento logístico onde agentes individuais coordenam transporte, estoque e distribuição de mercadorias.
num processo de fabrico, um sistema de agentes hierárquicos pode ter um agente de alto nível que gere os objetivos globais de produção e agentes de nível inferior que controlam máquinas individuais.

O que é CrewAI?

CrewAI é um conceito que envolve a criação de times de agentes de IA com habilidades complementares, que trabalham juntos para alcançar objetivos específicos. Diferente de um único modelo de IA que tenta resolver tudo sozinho, o CrewAI distribui responsabilidades entre agentes especializados, melhorando a precisão, a eficiência e a escalabilidade das soluções.

Como funciona?

O CrewAI opera baseado na colaboração entre agentes, onde cada um desempenha um papel específico. A estrutura geral inclui:

Papel dos Agentes – Cada agente possui uma especialização, como processamento de dados, análise de contexto, geração de texto, ou tomada de decisão.
Coordenação – Um sistema central ou um agente líder distribui tarefas e gerencia a comunicação entre os agentes.
Execução e Feedback – Os agentes executam suas partes da tarefa e compartilham resultados entre si para refinar a solução final.

Benefícios do CrewAI

Maior Eficiência – Distribuir tarefas entre agentes especializados melhora a performance.

Redução de Erros – O trabalho colaborativo permite verificações cruzadas entre agentes.

Escalabilidade – Equipes de agentes podem crescer ou se adaptar às necessidades do sistema.

Tomada de Decisão Melhorada – A especialização dos agentes leva a análises mais detalhadas.

Desafios do CrewAI

Coordenação Complexa – Garantir que os agentes colaborem de forma eficaz pode exigir sistemas sofisticados de comunicação.

Uso de Recursos – Dependendo da complexidade, a execução pode demandar alto poder computacional.

Interpretação e Consistência – Integrar diferentes respostas pode gerar variações inesperadas nos resultados.

Mão na Massa

Para os exemplos, vamos criar os seguintes agentes usando o CrewAI:

Um agente para redigir blogs;
Um agente que utiliza linguagem natural para realizar consultas em uma base de dados;
Um agente interpretador de código, que recebe comandos em linguagem natural e os executa no sistema operacional.

Requisitos:

- Python >= 3.12;
- Gerenciador de pacotes uv;
- Docker

O Agente no CrewAI e composto por:

role: É fundamental porque ele dá identidade ao agente. É o role que orienta o agente sobre suas responsabilidades e o que se espera dele. Por exemplo, se o agente tem o papel de 'Pesquisador', ele sabe que deve focar em coletar informações e analisar dados.
goal: É como o norte de uma bússola para o agente.Ele orienta todas as ações e decisões do agente, garantindo que ele esteja sempre trabalhando em direção ao objetivo desejado. Por exemplo, um agente com o goal de 'coletar dados de mercado' vai focar todas as suas atividades em encontrar, analisar e compilar informações relevantes sobre o mercado.
backstory: Este atributo é como o histórico de um personagem em um filme ou livro. Ele fornece contexto e profundidade ao agente, moldando suas ações e decisões de maneira que façam sentido dentro do seu "universo". No CrewAI, o backstory de um agente é fundamental para criar agentes que não apenas realizam tarefas, mas que também possuem uma lógica interna consistente para suas ações. O backstory é crucial porque ele influencia diretamente como o agente se comporta e responde a diferentes situações. Por exemplo, um agente com um histórico de 'Pesquisador Acadêmico' abordará um problema de maneira muito diferente de um agente com um histórico de 'Empreendedor'. O primeiro pode ser mais meticuloso e detalhista, enquanto o segundo pode ser mais inovador e orientado a riscos. Esse contexto adicional ajuda a definir as expectativas e a prever o comportamento do agente, tornando suas ações mais coerentes e previsíveis.

O Tarefa no CrewAI e composto por:

agent: No CrewAI, todo agente é designado para uma task. Isso significa que, antes de criar uma tarefa no CrewAI, você deve criar o agente. Isso ocorre porque, na declaração da task, espera-se a especificação de um agente.
description: No CrewAI, a 'description' é o coração de uma task. Ela diz exatamente o que precisa ser feito, como e por quê. Pensar em uma 'description' é como escrever o roteiro de um filme, você precisa ser claro, conciso e detalhado o suficiente para que ninguém se perca no meio do caminho.
expected_output: O expected_output funciona como um acordo entre você e o agente. Ele especifica exatamente o que deve ser entregue ao final da execução da tarefa. Isso é crucial para garantir que os agentes estejam alinhados com os objetivos do projeto e que o resultado final esteja de acordo com o que foi solicitado.

Tanto Agente quanto Tarefa podemos usar a "mente pensante" que são os LLM ou SLM, podemos adicionar através da propriedade llm.

Existem outros atributos, para mais detalhes acesse a documentação CrewAI Docs.

Os exemplos que vou disponibilizar usaram:

openai/gpt-4o-mini
deepseek/deepseek-chat
ollama/deepseek-r1:8b

Além de usar as plataformas online da openai e deepseek foi usado local na minha maquina com Ollama.

Requisitos da minha máquina:

OS: Linux Mint 21.1 x86_64
NVIDIA GeForce GTX 1660 Ti 6GB GDDR6
32GB de RAM
CPU: Intel i7-9750H (12) @ 4.500GHz

Para rodar os exemplo na raiz do projeto:

Para rodar o Redigir Blog:

  uv run python ./blogs/main.py

Para rodar o SQL Query AI:

  uv run python ./query/main.py

Para rodar Interpretador:

  uv run python ./interpretador/main.py

1. Agentes para redigir blogs;

A criação da equipe de agentes é clara, simples e intuitiva. Cada agente possui um papel específico, metas individuais e tarefas a serem executadas, todas alinhadas para alcançar o objetivo final de maneira colaborativa e eficaz.

import os
from dotenv import load_dotenv
from crewai import Agent, Task, Crew, Process, LLM
from llm_model import LLMModel
from llm_type import LLMType

class CreateBlogWriter:

    def __init__(self, type):
        load_dotenv ()
        llm_model = LLMModel()
        self.llm = (
          llm_model.open_ai_gpt_4o_mini() if LLMType(type) == LLMType.OPEN_AI_GPT_4O_MINI 
          else llm_model.deepseek(os.getenv("DEEPSEEK_API_KEY")) if LLMType(type) == LLMType.DEEPSEEK
          else llm_model.ollama_deepseek()
        )
        self.create_crew()

    def create_crew(self):
      """
       Agentes
      """
      self.planner = Agent(
        role = "Planejador de Conteúdo",
        goal = "Planejar conteúdo envolvente e factualmente preciso sobre {topic}",
        backstory = "Você está trabalhando no planejamento de um artigo de blog "
                    "sobre o tema: {topic} no 'https://medium.com/'."
                    "Você coleta informações que ajudam o "
                    "público a aprender algo e tomar decisões informadas. "
                    "Você precisa preparar um esboço detalhado "
                    "com os tópicos e subtópicos relevantes que devem fazer parte do artigo de blog."
                    "Seu trabalho é a base para o Redator de Conteúdo escrever um artigo sobre este tema.",
        llm = self.llm, 
        allow_delegation = False,
        verbose = True
      )

      self.writer = Agent(
        role =  "Redator de Conteúdo",
        goal =  "Escrever um artigo de opinião perspicaz e factualmente preciso "
                "sobre o tema: {topic}",
        backstory = "Você está trabalhando na escrita de um "
                    "novo artigo de opinião sobre o tema: {topic} no 'https://medium.com/'. "
                    "Você baseia sua escrita no trabalho do Planejador de Conteúdo, que fornece um esboço e contexto relevante sobre o tema. "
                    "Você segue os principais objetivos e direção do esboço, conforme fornecido pelo Planejador de Conteúdo. "
                    "Você também fornece insights objetivos e imparciais e os embasa com informações fornecidas pelo Planejador de Conteúdo. "
                    "Você reconhece em seu artigo de opinião quando suas afirmações são opiniões e não declarações objetivas.",
        allow_delegation = False,
        llm = self.llm, 
        verbose = True
      )

      self.editor = Agent(
        role = "Editor",
        goal =  "Editar um post de blog dado para alinhar com "
                "o estilo de escrita da organização 'https://medium.com/'. ",
        backstory = "Você é um editor que recebe um post de blog do Redator de Conteúdo. "
                    "Seu objetivo é revisar o post de blog para garantir que ele siga as melhores práticas jornalísticas,"
                    "forneça pontos de vista equilibrados ao apresentar opiniões ou afirmações, "
                    "e também evite tópicos controversos ou opiniões, sempre que possível.",
        llm = self.llm, 
        allow_delegation = False,
        verbose = True
      )
      """
       Tarefas
      """
      self.plan = Task(
        description = (
        "1. Priorize as últimas tendências, principais players, "
        "e notícias relevantes sobre {topic}.\n"
        "2. Identifique o público-alvo, considerando "
        "seus interesses e pontos de dor.\n"
        "3. Desenvolva um esboço detalhado do conteúdo, incluindo "
        "uma introdução, pontos principais e uma chamada para ação.\n"
        "4. Inclua palavras-chave de SEO e dados ou fontes relevantes."
        ),
        expected_output = "Um documento de plano de conteúdo abrangente "
                          "com um esboço, análise do público, palavras-chave de SEO e recursos.",
        agent = self.planner,
      )

      self.write = Task(
        description = (
        "1. Use o plano de conteúdo para criar um post de blog envolvente "
        "sobre {topic}.\n"
        "2. Incorpore palavras-chave de SEO de forma natural.\n"
        "3. As seções/Subtítulos são nomeadas de forma apropriada "
        "e envolvente.\n"
        "4. Certifique-se de que o post esteja estruturado com uma "
        "introdução envolvente, corpo perspicaz, "
        "e uma conclusão resumida.\n"
        "5. Revise erros gramaticais e "
        "alinhamento com a voz da marca.\n"
        ),
        expected_output = "Um post de blog bem escrito "
                          "em formato markdown, pronto para publicação, cada seção deve ter 2 ou 3 parágrafos.",
        agent = self.writer,
      )

      self.edit = Task(
        description = ( "Revise o post de blog dado para verificar "
                        "erros gramaticais e alinhamento com a voz da marca."),
        expected_output = "Um post de blog bem escrito em formato markdown, "
                          "pronto para publicação, cada seção deve ter 2 ou 3 parágrafos.",
        agent = self.editor
      )
      """
        Crew
      """
      self.crew = Crew(
      agents = [self.planner, self.writer, self.editor],
      tasks = [self.plan, self.write, self.edit],
      process = Process.sequential,
      verbose = True
      )

    def kickoff(self, topic):
        result = self.crew.kickoff(inputs={"topic":topic})
        return result

Fluxo

O fluxo representa um sistema de geração de conteúdo estruturado usando agentes de IA para automatizar o processo de criação de um artigo de blog. Ele é baseado em um pipeline onde diferentes agentes desempenham papéis específicos no planejamento, redação e edição do conteúdo antes da publicação.

Componentes Principais

a. Agentes (Agents)

Planejador de Conteúdo (self.planner): Responsável por estruturar um esboço detalhado do artigo, identificando tópicos relevantes, tendências, público-alvo e palavras-chave de SEO.
Redator de Conteúdo (self.writer): Baseando-se no plano do Planejador, escreve um artigo bem estruturado, utilizando palavras-chave e seguindo um estilo envolvente e informativo.
Editor (self.editor): Faz a revisão do artigo para garantir que esteja alinhado com o estilo da plataforma, corrigindo erros e ajustando a estrutura para melhor legibilidade.

b. Tarefas (Tasks)

Planejamento (self.plan): Criação do esboço do artigo, definição do público-alvo e levantamento de informações relevantes.
Escrita (self.write): Redação do artigo com base no plano, garantindo estrutura coerente e aplicação de SEO.
Edição (self.edit): Revisão do artigo para garantir qualidade, coerência e alinhamento com a voz da marca.

c. Execução (Crew)

O sistema orquestra os agentes e tarefas de forma sequencial, garantindo que cada etapa seja concluída antes da próxima.
Cada agente recebe suas respectivas tarefas e executa suas funções até o artigo estar pronto para publicação.

d. Fluxo de Trabalho

O Planejador de Conteúdo analisa o tópico e cria um esboço estruturado com palavras-chave, público-alvo e seções importantes.
O Redator de Conteúdo usa esse esboço para escrever o artigo, organizando bem a informação e garantindo uma leitura fluida.
O **Editor revisa **o texto para corrigir erros, melhorar o estilo e garantir que o artigo siga o padrão esperado.
O artigo final passa pelo processo completo e fica pronto para publicação.

2. Agente que utiliza linguagem natural para realizar consultas em uma base de dados

Usa inteligência artificial para gerar consultas SQL otimizadas a partir de descrições textuais do usuário. Ele combina agentes inteligentes da CrewAI e modelos de linguagem grandes (LLMs) para interpretar a estrutura do banco e construir queries eficientes.

Saída:

🔍 Consulta SQL Gerada:

SELECT nome, preco
FROM produtos
WHERE preco > 100
ORDER BY preco
LIMIT 5;
                     nome   preco
0     Bola de Futebol Pro  129.90
1  Controle Sem Fio Elite  249.90
2   Tênis Esportivo Ultra  259.90
3   Fone Bluetooth SoundX  299.90
4     Conjunto de Panelas  299.90

import os
from dotenv import load_dotenv
from crewai import Agent, Task, Crew, Process
from crewai_tools import FileReadTool

from llm_model import LLMModel
from llm_type import LLMType

class SQLQueryAI:
    def __init__(self, type):
        load_dotenv() 
        llm_model = LLMModel()
        self.llm = (
            llm_model.open_ai_gpt_4o_mini() if LLMType(type) == LLMType.OPEN_AI_GPT_4O_MINI 
            else llm_model.deepseek(os.getenv("DEEPSEEK_API_KEY")) if LLMType(type) == LLMType.DEEPSEEK
            else llm_model.ollama_deepseek()
        )
        self.schema_tool = FileReadTool()
        self.crew = None
        self.create_crew()

    def create_crew(self):
        """Agente especialista em SQL"""
        self.sql_agent = Agent(
            role="Especialista em SQL",
            goal="Gerar consultas SQL precisas e otimizadas para diferentes bancos de dados.",
            backstory=(
                "Você é um renomado especialista em SQL, com conhecimento avançado em diversas bases de dados, incluindo Postgres, MySQL e SQL Server. "
                "Sua missão é interpretar descrições textuais e transformá-las em consultas SQL eficientes, sempre considerando a estrutura do banco de dados."
            ),
            tools=[self.schema_tool],
            verbose=True,
            memory=True,
            llm=self.llm
        )
        """Tarefa que o agente executará"""
        self.task = Task(
            description=(
                r"""A partir do meu gerenciador {database_type}, 
                no banco de dados '{database_name}',
                e do esquema fornecido no arquivo 
                YAML localizado em {yaml_path}, 
                gere uma consulta SQL otimizada para 
                atender ao seguinte pedido: 

                {user_request}. 

                Certifique-se de usar as tabelas e colunas 
                corretas conforme a estrutura do YAML.

                O valor inserido em 'json_output' é {json_output}.

                IMPORTANTE:
                - **Formato de Retorno:**  
                  Se 'json_output' for **True**, a consulta deve retornar os dados em formato JSON, 
                  usando as funções apropriadas para cada banco de dados:  
                    - **Postgres:** 'row_to_json()' ou 'json_agg()'  
                    - **MySQL:** 'JSON_OBJECT()' ou 'JSON_ARRAYAGG()'  
                    - **SQL Server:** 'FOR JSON AUTO'  
                    - **Oracle:** 'JSON_OBJECT()'  
                  Caso contrário, a consulta deve ser otimizada para um **retorno tabular tradicional**.

                - **Otimização:**  
                  - Sempre utilize **índices disponíveis** para melhorar a performance.  
                  - Se houver junções ('JOINs'), prefira **chaves indexadas** para evitar scans desnecessários.  
                  - Ordene os resultados de maneira lógica se necessário ('ORDER BY').  

                - **Considerações Específicas:**  
                  - Evite selecionar colunas desnecessárias (`SELECT *` não é recomendado).  
                  - Se a consulta precisar de filtros ('WHERE'), utilize os campos de indexação do banco de dados para maior eficiência.  
                  - Para valores nulos, utilize funções adequadas como `COALESCE()` para garantir legibilidade no resultado.  

                """
            ),
            expected_output="Uma consulta SQL válida e otimizada para o banco de dados especificado.",
            agent=self.sql_agent
        )

        self.crew = Crew(
            agents=[self.sql_agent],
            tasks=[self.task],
            process=Process.sequential
        )

    def kickoff(self, inputs):
        """
        Executa o processo de geração de consultas SQL.

        Args:
            inputs (dict): Dicionário contendo os parâmetros de entrada:
                - database_type (str): Tipo do banco de dados (Postgres, MySQL, etc.).
                - database_name (str): Nome do banco de dados.
                - yaml_path (str): Caminho do arquivo YAML contendo a estrutura do banco.
                - user_request (str): Pedido textual para gerar a consulta SQL.
                - json_output (bool): Define se a consulta deve retornar um JSON ou um formato tabular.

        Returns:
            str: A consulta SQL gerada no formato esperado.
        """
        result = self.crew.kickoff(inputs=inputs).raw
        result = result.replace("sql","")
        result = result.replace("", "")

        return result

a. Definição do Agente (sql_agent)

self.sql_agent = Agent(
    role="Especialista em SQL",
    goal="Gerar consultas SQL precisas e otimizadas para diferentes bancos de dados.",
    backstory=(
        "Você é um renomado especialista em SQL, com conhecimento avançado em diversas bases de dados, incluindo Postgres, MySQL e SQL Server. "
        "Sua missão é interpretar descrições textuais e transformá-las em consultas SQL eficientes, sempre considerando a estrutura do banco de dados."
    ),
    tools=[self.schema_tool],
    verbose=True,
    memory=True,
    llm=self.llm
)

Cria um agente de IA chamado sql_agent, que tem o papel de especialista em SQL.
O agente possui um objetivo claro: gerar consultas SQL precisas e otimizadas.
Sua história reforça que ele tem conhecimento avançado em SQL e deve transformar descrições textuais em queries eficientes.
O agente pode usar ferramentas (tools), sendo que self.schema_tool é uma ferramenta para ler o esquema do banco de dados (YAML).
O modelo de linguagem (llm) escolhido é passado para que o agente utilize ao gerar as respostas.

As opções:

verbose=True: Faz com que o agente forneça logs detalhados de suas ações.
memory=True: Permite que o agente retenha informações entre execuções.

b. Definição da Tarefa (task)

self.task = Task(
    description=(
        r"""A partir do meu gerenciador {database_type}, 
        no banco de dados '{database_name}',
        e do esquema fornecido no arquivo 
        YAML localizado em {yaml_path}, 
        gere uma consulta SQL otimizada para 
        atender ao seguinte pedido: 

        {user_request}. 

        Certifique-se de usar as tabelas e colunas 
        corretas conforme a estrutura do YAML.

        O valor inserido em `json_output` é {json_output}.

        IMPORTANTE:
        - **Formato de Retorno:**  
          Se `json_output` for **True**, a consulta deve retornar os dados em formato JSON, 
          usando as funções apropriadas para cada banco de dados:  
            - **Postgres:** `row_to_json()` ou `json_agg()`  
            - **MySQL:** `JSON_OBJECT()` ou `JSON_ARRAYAGG()`  
            - **SQL Server:** `FOR JSON AUTO`  
            - **Oracle:** `JSON_OBJECT()`  
          Caso contrário, a consulta deve ser otimizada para um **retorno tabular tradicional**.

        - **Otimização:**  
          - Sempre utilize **índices disponíveis** para melhorar a performance.  
          - Se houver junções (`JOINs`), prefira **chaves indexadas** para evitar scans desnecessários.  
          - Ordene os resultados de maneira lógica se necessário (`ORDER BY`).  

        - **Considerações Específicas:**  
          - Evite selecionar colunas desnecessárias (`SELECT *` não é recomendado).  
          - Se a consulta precisar de filtros (`WHERE`), utilize os campos de indexação do banco de dados para maior eficiência.  
          - Para valores nulos, utilize funções adequadas como `COALESCE()` para garantir legibilidade no resultado.  

        """
    ),
    expected_output="Uma consulta SQL válida e otimizada para o banco de dados especificado.",
    agent=self.sql_agent
)

Define a tarefa do agente (task), que é gerar uma consulta SQL otimizada com base em:

O gerenciador de banco de dados (database_type, como Postgres ou MySQL).
O nome do banco de dados (database_name).
O arquivo YAML contendo o esquema (yaml_path).
A solicitação do usuário (user_request).
O formato de saída esperado (json_output).

Diretrizes importantes:

Se json_output for True, a query deve retornar um JSON, usando a função apropriada para o banco de dados.
Caso contrário, a consulta deve ser otimizada para um formato tabular tradicional.

O agente deve seguir boas práticas de SQL:

Evitar '*SELECT **'.
Usar índices para melhorar a performance.
Escolher chaves indexadas para JOINs.
Aplicar filtros eficientes com WHERE.
Usar COALESCE() para lidar com valores NULL.

Fluxo Geral

O objeto SQLQueryAI é instanciado e um modelo LLM (como GPT-4o, DeepSeek ou Ollama) é escolhido.
O agente sql_agent é criado como um especialista em SQL.
Uma tarefa é definida, instruindo o agente a gerar consultas SQL otimizadas.

A equipe (crew) é formada, incluindo o agente e sua tarefa.
Quando o método kickoff(inputs) for chamado:

O agente recebe os parâmetros (database_type, database_name, yaml_path, user_request, json_output).
Ele lê o esquema do banco no arquivo YAML.
O LLM gera uma consulta SQL otimizada seguindo as regras definidas.
O resultado é formatado e retornado ao usuário.

3. Agente interpretador de código, que recebe comandos em linguagem natural e os executa no sistema operacional

Define um sistema baseado na biblioteca CrewAI, no qual um agente chamado Software Engineer pode executar comandos de linha de comando (CLI) de forma automatizada, utilizando o Open Interpreter para interpretar e executar esses comandos.

from crewai import Agent, Task, Crew, Process, LLM
from cli_tool import CLITool

class Command:

    def __init__(self):
        self.llm = LLM(model="openai/gpt-4o-mini", )
        self.cli = CLITool()
        self.create_crew()

    def create_crew(self):
        """Agent Software Engineer."""
        self.software_engineer = Agent(
          role="Software Engineer",
          goal="Always use Executor Tool. Ability to perform CLI operations, write programs and execute using Exector Tool",
          backstory='Expert in command line operations, creating and executing code.',
          tools=[self.cli.execute_cli_command],
          llm=self.llm,
          verbose=True
        )
        self.software_engineer_task = Task(
          description="Execute the command {command} using the Executor Tool.",
          expected_output="The expected output of the executed CLI command.",
          agent=self.software_engineer,
          tools=[self.cli.execute_cli_command],
          verbose=True
        )
        self.crew = Crew(
          agents=[self.software_engineer],
          tasks=[ self.software_engineer_task],
          process=Process.sequential,
          manager_llm=self.llm,
          verbose=True
        )

    def kickoff(self, inputs):
        result = self.crew.kickoff(inputs=inputs)
        return result

Ferramenta CLI:

from crewai.tools import tool
from interpreter import interpreter

class CLITool:

    interpreter.auto_run = True
    interpreter.llm.model = "openai/gpt-4o-mini"

    @tool("executor")
    def execute_cli_command(command:str):
        """Create an Execute code using Open Interpreter."""
        result = interpreter.chat(command)
        return result

Fluxo:

a. Criação do Agente (software_engineer)

Ele tem o papel de Engenheiro de Software e pode executar comandos CLI.
Usa a ferramenta Executor Tool (self.cli.execute_cli_command).

b. Criação da Tarefa (software_engineer_task)

Instrução clara: "Execute o comando {command} usando Executor Tool".
A saída esperada é o resultado do comando.

c. Criação da Equipe (Crew)

Agrupa o agente e a tarefa.
Garante que os comandos sejam executados um de cada vez (Process.sequential).
Usa GPT-4o-mini para gerenciar a execução.

🛠 Como Esse Código Funciona na Prática?

Exemplo de Execução:

cmd = Command()
result = cmd.kickoff({"command": "ls -l"})
print(result)

O agente recebe o comando "ls -l".
Ele usa a ferramenta Executor Tool para executar o comando.
O resultado da execução (lista de arquivos) é retornado.

O Futuro dos Agent AIs

A tendência é que os Agent AIs se tornem cada vez mais sofisticados, combinando IA generativa, aprendizado por reforço e interações multimodais (texto, voz e imagem). Esses agentes terão um impacto significativo na automação e na experiência do usuário.

Desde o atendimento ao cliente até a gestão empresarial e segurança digital.

O código completo: Agent AI

Referências

ARCHITECTURE FOR ADAPTIVE INTELLIGENT
SYSTEMS

Docs Crewai

Processamento de Linguagem Natural

Livro Inteligência Artificial - Uma Abordagem de Aprendizado de Máquina

Sandeco Professor e Pesquisador - IFG e UFG

Signal Angular: Gerenciamento de estado reativo

Wanderson Alves Rodrigues — Mon, 23 Dec 2024 23:19:42 +0000

O Angular está constantemente evoluindo, e uma das mais recentes inovações introduzidas ao ecossistema é o Signal. Este recurso, inspirado por conceitos de reatividade, promete mudar a forma como desenvolvedores Angular lidam com estados reativos e comunicação entre componentes.

Exploraremos o que é o Signal, como ele funciona, e como pode ser usado para tornar suas aplicações Angular mais performáticas e fáceis de manter.

O que é o Signal no Angular?

São uma nova API reativa introduzida no Angular que simplifica o gerenciamento e a reatividade de dados em aplicações,baseados em um padrão chamado Observer Design Pattern. De acordo com esse padrão, temos um Publisher que armazena algum valor junto com uma lista de Subscribers que estão interessados nele, e quando o valor muda, eles recebem uma notificação.

Em essência, o Signal:

Armazena um valor reativo.
Notifica os consumidores automaticamente quando o valor muda.
Facilita a escrita de código reativo.

Por que usar Signals no Angular?

Simplicidade: Simplificam a criação de estados reativos. Comparados aos Observables do RxJS, eles exigem menos código para configurar e são mais intuitivos para iniciantes no Angular.
Desempenho: Otimizam atualizações de estado e visualizações. Apenas os componentes diretamente dependentes de um Signal são atualizados, evitando renderizações desnecessárias.
Menos Dependências: Não dependem do RxJS para cenários básicos. Isso reduz a curva de aprendizado e facilita a transição para o Angular.
Escalabilidade: São projetados para funcionar perfeitamente em arquiteturas complexas.

Como Funcionam no Angular?

Os Signals no Angular seguem três conceitos principais:

Criação de Signals: Você cria um Signal para armazenar um valor reativo.
Leitura de Signals: Você pode acessar o valor do Signal diretamente.
Atualização de Signals: Você pode alterar o valor e notificar os consumidores.

Vamos colocar a mão na massa!

Para alterar o valor do signal.

O primeiro é por set que define o signal para um novo valor;

app.component.html

<p>
Nosso Signal: {{exemploSignal()}}
</p>

<button (click)="executar()">Executar</button>

app.component.ts

import { Component, signal } from '@angular/core';
import { RouterOutlet } from '@angular/router';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [
    RouterOutlet,
  ],
  templateUrl: './app.component.html',
  styleUrl: './app.component.css',
})
export class AppComponent {
  title = 'exemplos';

  protected exemploSignal = signal('angular');

  constructor() {
  }

  executar(){
    this.exemploSignal.set('Framework Angular');
  }
}

o segundo é por update que define com base no valor atual;

app.component.html

<p>
Nosso Signal: {{exemploCount()}}
</p>

<button (click)="executar()">Executar</button>

app.component.ts

import { Component, signal } from '@angular/core';
import { RouterOutlet } from '@angular/router';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [
    RouterOutlet,
  ],
  templateUrl: './app.component.html',
  styleUrl: './app.component.css',
})
export class AppComponent {
  title = 'exemplos';

  protected exemploCount = signal(1);

  constructor() {
  }

  executar(){
    this.exemploCount.update(atual => atual + 1);
  }
}

1 - Exemplo Contador

Para o primeiro exemplo, vamos desenvolver um contador bem simples para testa o conhecimento.

contador.component.html

<div class="container">
  <button (click)="incrementar()">Incrementar</button>
  <label>Contador: {{ contador() }}</label>
  <button (click)="decrementar()">Decrementar</button>
  <button (click)="limpar()">Limpar</button>
</div>

contador.component.css

:host {
  display: block;
}

.container {
  display: flex;
  gap: 10px;
}

contador.component.ts

import { Component, signal } from '@angular/core';

@Component({
  selector: 'app-contador',
  standalone: true,
  imports: [],
  templateUrl: './contador.component.html',
  styleUrl: './contador.component.css'
})
export class ContadorComponent {
contador = signal(0);

  incrementar(){
    this.contador.update(valor => valor + 1);
  }

  decrementar(){
    this.contador.update(valor => valor - 1);
  }

  limpar(){
    this.contador.set(0);
  }
}

Qual a jogada nesse código, tem agora o signal que adicionamos um valor inicial na linha:

contador = signal(0);

Nas funções incrementar e decrementar, usamos a função update do writable signal para pegar o valor anterior e incrementar ou decrementar um valor novo.

  incrementar(){
    this.contador.update(valor => valor + 1);
  }

  decrementar(){
    this.contador.update(valor => valor - 1);
  }

Para limpar foi usado,a função set para adicionar um novo valor porém não considerando o valor anterior.

Agora como podemos usar a atualização do valor no html?. É bem simples para mostrar o valor alterado na visualização e só chamar como fosse uma "função".

  <label>Contador: {{ contador() }}</label>

2 - Computed signals

Signals computados são signals somente leitura que derivam seu valor de outros signals. Você define signals computados usando a função computed e especificando uma derivação:

  contador = signal(0);
  contadorVezesDois: Signal<number> = computed(() => this.contador() * 2);

No nosso exemplo, quando o valor do contador for atualizado o contadorVezesDois será alterado pois depende do contador.

o Código completo:

contador-v2.component.html

<div class="container">
  <button (click)="incrementar()">Incrementar</button>
  <label>Contador: {{ contador() }}</label>
  <button (click)="decrementar()">Decrementar</button>
  <button (click)="limpar()">Limpar</button>
</div>

<div class="result">
  <label>Valor do contador vezes 2: {{ contadorVezesDois() }}</label>
</div>

contador-v2.component.css

:host {
  display: block;
}

.container {
  display: flex;
  gap: 10px;
}

.result{
  margin-top: 10px;
}

contador-v2.component.ts

import { Component, computed, Signal, signal } from '@angular/core';

@Component({
  selector: 'app-contador-v2',
  standalone: true,
  imports: [],
  templateUrl: './contador-v2.component.html',
  styleUrl: './contador-v2.component.css'
})
export class ContadorV2Component {
  contador = signal(0);
  contadorVezesDois: Signal<number> = computed(() => this.contador() * 2);

  incrementar(){
    this.contador.update(valor => valor + 1);
  }

  decrementar(){
    this.contador.update(valor => valor - 1);
  }

  limpar(){
    this.contador.set(0);
  }
}

3 - Effects

Signal notificam os consumidores interessados quando eles mudam. Effect é uma operação que é executada sempre que um ou mais valores de Signal mudam.

Para esse exemplo, vamos criar um serviço root.

import { Injectable, signal } from "@angular/core";

@Injectable({ providedIn: 'root' })
export class Store {
  contador = signal(0);

  incrementar(){
    this.contador.update(valor => valor + 1);
  }

  decrementar(){
    this.contador.update(valor => valor - 1);
  }

  limpar(){
    this.contador.set(0);
  }
}

O componente contador agora vai ficar assim.

contador-v3.component.html

<div class="container">
  <button (click)="store.incrementar()">Incrementar</button>
  <label>Contador: {{ store.contador() }}</label>
  <button (click)="store.decrementar()">Decrementar</button>
  <button (click)="store.limpar()">Limpar</button>
</div>

contador-v3.component.css

:host {
  display: block;
}

.container {
  display: flex;
  gap: 10px;
}

.result{
  margin-top: 10px;
}

contador-v3.component.ts

import { Component, inject } from '@angular/core';
import { Store } from '../store';

@Component({
  selector: 'app-contador-v3',
  standalone: true,
  imports: [],
  templateUrl: './contador-v3.component.html',
  styleUrl: './contador-v3.component.css'
})
export class ContadorV3Component {
 protected store = inject(Store);
}

Na app.component, temos o effect.

<app-contador-v3></app-contador-v3>

import { Component, effect, inject } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { ContadorV3Component } from './contador-v3/contador-v3.component';
import { Store } from './store';
@Component({
  selector: 'app-root',
  standalone: true,
  imports: [
    RouterOutlet,
    ContadorV3Component,
  ],
  templateUrl: './app.component.html',
  styleUrl: './app.component.css',
})
export class AppComponent {
  protected store = inject(Store)

  constructor() {
    effect(() => {
      const contador = this.store.contador();
      if(contador < 0) {
        console.log('Negativo')
      }
      else{
      const par = contador % 2 === 0;
      if(par) {
        console.log('Par')
      } else {
        console.log('Impar')
      }
    }
    });
  }
}

Então quando incremento, decremento ou limpar será notificado ao effect, onde fiz uma simples impressão em console.

effect será acionado pelo menos uma vez.
effect será acionado após pelo menos um dos Signal dos quais ele depende (lê seu valor) mudar.
effect será chamado um número mínimo de vezes. Isso significa que se vários Signals dos quais o effect depende mudarem seus valores ao mesmo tempo, o código será executado apenas uma vez.

4 - On Push Compooent

O Angular só verificará as alterações quando o input for modificado ou algum evento for disparado. Portanto, se o seu componente estiver usando changeDetection: ChangeDetectionStrategy.OnPush, as alterações só serão refletidas na DOM nos casos citados.

No primeiro exemplo, vamos criar um atributo chamado valor e colocar um temporizador no construtor que vai incrementar. Mesmo com a incrementação do valor não afeta a exibição no DOM.

on-push-teste.component.ts

import { ChangeDetectionStrategy, Component, signal } from "@angular/core";

@Component({
  selector: 'app-on-push-teste',
  standalone: true,
  template: `
    <h1>OnPush Teste</h1>
    <p>O valor é: {{valor}}</p>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class OnPushTesteComponent {
valor = 1;

constructor(){
  setInterval(() => {
    this.valor++;
    console.log('Mudou o valor: ', this.valor);
  }, 1000);
}
}

Console sendo incrementado:

Tela não sendo alterada:

Porém quando utilizamos signal o comportamento fica totalmente diferente, como segue abaixo:

on-push-teste.component.ts

import { ChangeDetectionStrategy, Component, signal } from "@angular/core";

@Component({
  selector: 'app-on-push-teste',
  standalone: true,
  template: `
    <h1>OnPush Teste</h1>
    <p>O valor é: {{valor()}}</p>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class OnPushTesteComponent {
valor = signal(1);

constructor(){
  setInterval(() => {
    this.valor.update(valor => valor + 1);
    console.log('Mudou o valor: ', this.valor());
  }, 1000);
}
}

A tela o valor agora é incrementado:

app.component.html

<app-on-push-teste></app-on-push-teste>

app.component.ts

import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { OnPushTesteComponent } from './on-push-teste/on-push-teste.component';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [
    RouterOutlet,
    OnPushTesteComponent
  ],
  templateUrl: './app.component.html',
  styleUrl: './app.component.css',
})
export class AppComponent {

  constructor() {
  }
}

Por qual motivo isso acontece?. Como agora definimos a valor = signal(1); como signal, qualquer alteração nele notifica que precisa se renderizado o novo valor.

O código completo: Github

Referência:

Angular Signals

Micro front-end module federation: Aplicação extensível

Wanderson Alves Rodrigues — Tue, 17 Sep 2024 01:00:09 +0000

A arquitetura de micro front-end é uma abordagem que visa trazer os princípios de microserviços para o desenvolvimento de front-ends, permitindo que grandes aplicações web sejam divididas em unidades menores e independentes. Uma das tecnologias-chave que possibilita essa abordagem é o Module Federation, um recurso poderoso do Webpack 5. Vamos exploraremos o que é o Module Federation, como ele funciona e como pode ser utilizado para construir aplicações modernas e escaláveis.

O que é Module Federation?

O Module Federation é um recurso do Webpack 5 que permite a execução de módulos JavaScript compartilhados entre diferentes aplicações ou diferentes partes de uma mesma aplicação. Ele facilita a criação de aplicações distribuídas, onde diferentes equipes podem desenvolver e implantar partes distintas da aplicação de forma independente.

Com o Module Federation, você pode:

Compartilhar Módulos: Permite que módulos sejam compartilhados entre diferentes aplicações sem a necessidade de duplicação.
Carregar Módulos Dinamicamente: Carregar módulos de forma dinâmica a partir de diferentes origens, o que é ideal para aplicações que utilizam uma arquitetura de micro front-end.
Atualizar Módulos Independentemente: Atualizar uma parte da aplicação sem precisar republicar toda a aplicação.

Como Funciona o Module Federation?

O funcionamento do Module Federation baseia-se em dois conceitos principais:

Host Application: É a aplicação que consome módulos de outras aplicações. Pode ser vista como a aplicação principal que integra outros módulos.
Remote Application: São as aplicações ou partes de aplicações que expõem módulos para outras aplicações. Eles fornecem seus módulos de forma que podem ser consumidos por aplicações host.

Vamos colocar a mão na massa!

Vamos desenvolver a aplicação com Angular onde teremos uma aplicação host e duas aplicações remotas isolad.

Requisitos:

Angular 18
Node 20.17.0

Bibliotecas:

No nosso caso teremos uma aplicação Host e duas outras que será os plugins das aplicações remotas

1 - Host Application

Para criar om mfe-host execute o comando:

ng new mfe-app-host
ng add @angular-architects/module-federation --project mfe-app-host --port 4200 --type host --skip-confirmation

a - app/home

home.component.ts

import { Component } from '@angular/core';

@Component({
  selector: 'app-home',
  standalone: true,
  imports: [],
  templateUrl: './home.component.html',
  styleUrl: './home.component.css',
})
export class HomeComponent {}

home.component.html

<h1>Home</h1>

b - app/navbar

nabbar.component.ts

import { Component } from '@angular/core';
import { RouterLink } from '@angular/router';

@Component({
  selector: 'app-navbar',
  standalone: true,
  imports: [RouterLink],
  templateUrl: './nabbar.component.html',
  styleUrl: './nabbar.component.css',
})
export class NavbarComponent {}

nabbar.component.html

<nav class="navbar">
  <div class="logo">
    <a href="#home">MFE</a>
  </div>
  <div class="nav-links">
    <a routerLink="/home">Home</a>
    <a routerLink="/dashboard-one">Dashboard One</a>
    <a routerLink="/dashboard-two">Dashboard Two</a>
  </div>
</nav>

nabbar.component.css

.navbar {
  background-color: #333;
  overflow: hidden;
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 10px 20px;
}

.navbar a {
  color: white;
  text-decoration: none;
  padding: 14px 16px;
}

.navbar a:hover {
  background-color: #ddd;
  color: black;
}

.logo {
  font-size: 24px;
  font-weight: bold;
}

.nav-links {
  display: flex;
}

@media screen and (max-width: 600px) {
  .navbar {
    flex-direction: column;
  }

  .nav-links {
    flex-direction: column;
    width: 100%;
  }

  .navbar a {
    text-align: center;
  }
}

c) App Component

app.component.ts

import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { NavbarComponent } from './navbar/nabbar.component';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [RouterOutlet, NavbarComponent],
  templateUrl: './app.component.html',
  styleUrl: './app.component.css',
})
export class AppComponent {
  title = 'mfe-app-host';
}

app.component.html

<app-navbar></app-navbar>
<router-outlet />

d) Routes

app.routes.ts

import { Routes } from '@angular/router';
import { loadRemoteModule } from '@angular-architects/module-federation';
import { HomeComponent } from './home/home.component';

export const routes: Routes = [
  {
    path: 'mfe-dashboard-one',
    loadComponent: () =>
      loadRemoteModule({
        type: 'module',
        remoteEntry: 'http://localhost:4201/remoteEntry.js',
        exposedModule: './Component',
      }).then((m) => m.AppComponent),
  },
  {
    path: 'mfe-dashboard-two',
    loadComponent: () =>
      loadRemoteModule({
        type: 'module',
        remoteEntry: 'http://localhost:4202/remoteEntry.js',
        exposedModule: './Component',
      }).then((m) => m.AppComponent),
  },
  { path: 'home', component: HomeComponent },
  { path: '', redirectTo: '/home', pathMatch: 'full' },
];

Detalhes:

Este código é uma configuração de rotas em um projeto Angular que utiliza a Federação de Módulos para carregar dinamicamente componentes de micro front-end remotos. Vamos detalhar cada parte do código:

Importações

import { Routes } from '@angular/router';
import { loadRemoteModule } from '@angular-architects/module-federation';
import { HomeComponent } from './home/home.component';

Routes: É a interface do Angular usada para definir as rotas da aplicação. Uma rota associa um caminho (URL) a um componente ou módulo específico.
loadRemoteModule: Função fornecida pela biblioteca @angular-architects/module-federation. Ela é usada para carregar dinamicamente módulos ou componentes expostos por microfrontends remotos, permitindo que a aplicação principal consuma esses componentes sem carregá-los no início.
HomeComponent: O componente local que será renderizado quando a rota /home for acessada.

Definição de Rotas

export const routes: Routes = [
  {
    path: 'dashboard-one',
    loadComponent: () =>
      loadRemoteModule({
        type: 'module',
        remoteEntry: 'http://localhost:4201/remoteEntry.js',
        exposedModule: './Component', // Expondo o componente standalone
      }).then((m) => m.AppComponent), // Nome do componente standalone
  },
  {
    path: 'dashboard-two',
    loadComponent: () =>
      loadRemoteModule({
        type: 'module',
        remoteEntry: 'http://localhost:4202/remoteEntry.js',
        exposedModule: './Component', // Expondo o componente standalone
      }).then((m) => m.AppComponent), // Nome do componente standalone
  },
  { path: 'home', component: HomeComponent },
  { path: '', redirectTo: '/home', pathMatch: 'full' },
];

Rota dashboard-one

{
  path: 'dashboard-one',
  loadComponent: () =>
    loadRemoteModule({
      type: 'module',
      remoteEntry: 'http://localhost:4201/remoteEntry.js',
      exposedModule: './Component',
    }).then((m) => m.AppComponent),
},

path: 'dashboard-one': Define o caminho da URL para esta rota. Quando o usuário acessar /dashboard-one, esta rota será ativada.
loadComponent: Esta chave define que o componente para esta rota será carregado dinamicamente, em vez de ser carregado logo no início da aplicação. Isso ajuda a melhorar o tempo de carregamento inicial.
loadRemoteModule(): Função que carrega o módulo ou componente de um micro front-end remoto. O módulo exposto é definido no remoteEntry.js da aplicação remota que está rodando em http://localhost:4201/. A função carrega o módulo remoto e expõe o componente AppComponent.

type: 'module': Especifica que o tipo de módulo a ser carregado é um JavaScript ES module.

remoteEntry: 'http://localhost:4201/remoteEntry.js': Define o local do ponto de entrada (entry point) do micro front-end remoto, que é o arquivo remoteEntry.js gerado durante o build.

exposedModule: './Component': Este caminho especifica qual módulo ou componente foi exposto no micro front-end remoto. O remoteEntry.js expõe esse componente.

then((m) => m.AppComponent): Após carregar o módulo remoto, a função .then() extrai o componente específico (neste caso, AppComponent) e o associa à rota. Esse AppComponent é o componente standalone que foi exposto pelo micro front-end.

Rota dashboard-two

{
  path: 'dashboard-two',
  loadComponent: () =>
    loadRemoteModule({
      type: 'module',
      remoteEntry: 'http://localhost:4202/remoteEntry.js',
      exposedModule: './Component',
    }).then((m) => m.AppComponent),
},

Esta rota é semelhante à dashboard-one, mas carrega um componente de outro micro front-end, disponível em http://localhost:4202/remoteEntry.js.

Rota home

{ path: 'home', component: HomeComponent },

Define a rota /home, que carrega o componente local HomeComponent quando acessada. Este componente já está no projeto principal, então não requer carregamento dinâmico.

Rota padrão (redirecionamento)

{ path: '', redirectTo: '/home', pathMatch: 'full' },

path: '': Define a rota padrão (a rota vazia).
redirectTo: '/home': Redireciona qualquer usuário que acessar a raiz (/) da aplicação diretamente para a rota /home.
pathMatch: 'full': Garante que o redirecionamento ocorra apenas quando o caminho completo for igual a '' (raiz). Isso evita redirecionamentos em URLs parciais.

e) Webpack

webpack.config.js

const {
  shareAll,
  withModuleFederationPlugin,
} = require("@angular-architects/module-federation/webpack");

module.exports = withModuleFederationPlugin({
  remotes: {
    mfeDashboardOne: "http://localhost:4201/remoteEntry.js",
    mfeDashboardTwo: "http://localhost:4202/remoteEntry.js",
  },

  shared: {
    ...shareAll({
      singleton: true,
      strictVersion: true,
      requiredVersion: "auto",
    }),
  },
});

Detalhes:

Este código configura a Module Federation no Webpack em um projeto Angular, permitindo que múltiplas aplicações compartilhem módulos de forma dinâmica. Vamos detalhar cada parte:

Importações

const { 
  shareAll, 
  withModuleFederationPlugin 
} = require("@angular-architects/module-federation/webpack");

shareAll: Esta função faz parte do pacote @angular-architects/module-federation e é usada para compartilhar dependências entre micro front-end. Ela permite que você especifique quais bibliotecas ou módulos devem ser compartilhados entre as diferentes aplicações que estão federadas, como dependências comuns (Angular, RxJS, etc.).
withModuleFederationPlugin: Essa função é um wrapper em torno do ModuleFederationPlugin do Webpack. O objetivo dela é simplificar a configuração do plugin, tornando-o mais fácil de usar com Angular. Ela gera a configuração necessária para a federação de módulos e integra-se automaticamente ao processo de build do Angular.

Exportação da Configuração

module.exports = withModuleFederationPlugin({
  remotes: {
    mfeDashboardOne: "http://localhost:4201/remoteEntry.js",
    mfeDashboardTwo: "http://localhost:4202/remoteEntry.js",
  },

remotes: Esta chave define quais micro front-end serão carregados remotamente.

No caso, foi definido dois micro front-end:

mfeDashboardOne: O micro front-end disponível no endereço http://localhost:4201/remoteEntry.js. Esse remoteEntry.js é o ponto de entrada da aplicação federada, gerado durante o build.
mfeDashboardTwo: O segundo micro front-end, disponível em http://localhost:4202/remoteEntry.js.

Cada micro front-end tem sua própria aplicação Angular rodando e exporta componentes, módulos ou serviços que podem ser consumidos por outros aplicativos.

Dependências Compartilhadas

  shared: {
    ...shareAll({
      singleton: true,
      strictVersion: true,
      requiredVersion: "auto",
    }),
  },
});

shared: Esta chave especifica as dependências que serão compartilhadas entre a aplicação principal e os micro front-end. O uso de dependências compartilhadas permite que você evite carregar múltiplas cópias de bibliotecas (como Angular ou outras bibliotecas comuns) em cada micro front-end, o que melhora o desempenho e reduz o tamanho do bundle.

O método shareAll() instrui a aplicação a compartilhar todas as dependências que já foram instaladas no node_modules, com algumas opções:

singleton: true: Esta opção garante que apenas uma instância de cada biblioteca será carregada e compartilhada entre os micro front-end. Isso é importante, especialmente no caso de bibliotecas como o Angular, que não funcionam corretamente se houver múltiplas instâncias da mesma dependência rodando.

strictVersion: true: Garante que todos os micro front-end usarão exatamente a mesma versão das bibliotecas compartilhadas. Isso previne problemas de incompatibilidade entre diferentes versões da mesma biblioteca.

requiredVersion: "auto": O Webpack irá automaticamente definir qual versão das dependências será usada, baseada no que está no arquivo package.json da aplicação.

2 - Remote Application Dashboard One

Para criar om mfe-dashboard-one execute o comando:

ng new mfe-dashboard-one
ng add @angular-architects/module-federation --project mfe-dashboard-one --port 4201 --type remote --skip-confirmation
npm install chart.js

a - App Component

app.component.ts

import { Component, OnInit } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { Chart } from 'chart.js/auto';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [RouterOutlet],
  templateUrl: './app.component.html',
  styleUrl: './app.component.css',
})
export class AppComponent implements OnInit {
  ngOnInit() {
    this.createBarChart();
  }

  createBarChart() {
    new Chart('barChart', {
      type: 'bar',
      data: {
        labels: ['Janeiro', 'Fevereiro', 'Março', 'Abril', 'Maio', 'Junho'],
        datasets: [
          {
            label: 'Vendas',
            data: [12, 19, 3, 5, 2, 3],
            backgroundColor: 'rgba(75, 192, 192, 0.6)',
          },
        ],
      },
      options: {
        responsive: true,
        scales: {
          y: {
            beginAtZero: true,
          },
        },
      },
    });
  }
}

app.component.html

<div class="dashboard">
  <h1>Dashboard</h1>
  <div class="chart-container">
    <canvas id="barChart"></canvas>
  </div>
</div>

app.component.css

.dashboard {
  padding: 20px;
}
.chart-container {
  width: 100%;
  max-width: 600px;
  margin-bottom: 20px;
}

b - Webpack

webpack.config.js

const {
  shareAll,
  withModuleFederationPlugin,
} = require("@angular-architects/module-federation/webpack");

module.exports = withModuleFederationPlugin({
  name: "mfe-dashboard-one",

  exposes: {
    "./Component": "./src/app/app.component.ts",
  },

  shared: {
    ...shareAll({
      singleton: true,
      strictVersion: true,
      requiredVersion: "auto",
    }),
  },
});

Este código configura o Module Federation no Webpack para expor um componente de um micro front-end Angular chamado mfe-dashboard-one. Esse micro front-end poderá ser consumido por outras aplicações remotas. Vamos explicar cada parte em detalhes:

const { 
  shareAll, 
  withModuleFederationPlugin 
} = require("@angular-architects/module-federation/webpack");

shareAll: Função que facilita o compartilhamento de dependências entre a aplicação principal e os micro front-end. Ela configura o que será compartilhado, como bibliotecas de terceiros ou módulos Angular comuns.
withModuleFederationPlugin: Função usada para configurar o Module Federation Plugin no Webpack de uma forma simplificada para projetos Angular. Ela ajuda a integrar as configurações necessárias da federação de módulos com o processo de build do Angular.

Exportação da Configuração

module.exports = withModuleFederationPlugin({
  name: "mfe-dashboard-one",

  exposes: {
    "./Component": "./src/app/app.component.ts",
  },

name: "mfe-dashboard-one": Define o nome da aplicação federada. Esse nome é utilizado internamente no Webpack e também quando outras aplicações querem consumir os módulos ou componentes expostos por este micro front-end. No caso, o nome do micro front-end é "mfe-dashboard-one".
exposes: Esta chave define quais módulos ou componentes do micro front-end estarão disponíveis para outras aplicações consumirem. No caso:

"./Component": Esse é o nome do módulo ou caminho pelo qual o componente será acessado externamente. Quando outra aplicação precisar usar esse componente, ela o referenciará como mfe-dashboard-one/Component.

"./src/app/app.component.ts": Especifica o arquivo onde o componente está localizado no projeto. Neste caso, o componente a ser exposto é o AppComponent, que está definido no arquivo app.component.ts **dentro do diretório **src/app.

Isso significa que o componente AppComponent será exportado e poderá ser carregado dinamicamente por outras aplicações usando o caminho exposto (./Component).

Dependências Compartilhadas

  shared: {
    ...shareAll({
      singleton: true,
      strictVersion: true,
      requiredVersion: "auto",
    }),
  },
});

shared: Esta chave é usada para definir as dependências que serão compartilhadas entre o micro front-end e outras aplicações que consomem este micro front-end. O objetivo é evitar carregar múltiplas instâncias das mesmas dependências, o que otimiza a performance e reduz o tamanho do bundle.

shareAll: A função shareAll compartilha todas as bibliotecas instaladas no node_modules, configurando as opções para controlar o compartilhamento.

singleton: true: Esta opção garante que somente uma instância de cada biblioteca seja carregada e utilizada em toda a aplicação e nos micro front-end. Isso é crucial, especialmente para bibliotecas que não funcionam corretamente com múltiplas instâncias, como o Angular.

strictVersion: true: Assegura que as versões das bibliotecas compartilhadas sejam exatamente as mesmas entre as diferentes aplicações e micro front-end. Isso evita problemas de compatibilidade de versões.

requiredVersion: "auto": Permite ao Webpack determinar automaticamente a versão correta das bibliotecas a serem compartilhadas, com base nas versões definidas no package.json.

3 - Remote Application Dashboard two

Para criar **mfe-dashboard-two **execute o comando:

ng new mfe-dashboard-one
ng add @angular-architects/module-federation --project mfe-dashboard-two --port 4202 --type remote --skip-confirmation
npm install chart.js

a - App Component

app.component.ts

import { Component, OnInit } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { Chart } from 'chart.js/auto';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [RouterOutlet],
  templateUrl: './app.component.html',
  styleUrl: './app.component.css',
})
export class AppComponent implements OnInit {
  ngOnInit() {
    this.createPieChart();
  }

  createPieChart() {
    new Chart('pieChart', {
      type: 'pie',
      data: {
        labels: ['Vermelho', 'Azul', 'Amarelo'],
        datasets: [
          {
            label: 'Cores Favoritas',
            data: [300, 50, 100],
            backgroundColor: [
              'rgb(255, 99, 132)',
              'rgb(54, 162, 235)',
              'rgb(255, 205, 86)',
            ],
          },
        ],
      },
      options: {
        responsive: true,
      },
    });
  }
}

app.component.html

<div class="dashboard">
  <h1>Dashboard</h1>
  <div class="chart-container">
    <canvas id="pieChart"></canvas>
  </div>
</div>

app.component.css

.dashboard {
  padding: 20px;
}
.chart-container {
  width: 100%;
  max-width: 600px;
  margin-bottom: 20px;
}

b - Webpack

webpack.config

const {
  shareAll,
  withModuleFederationPlugin,
} = require("@angular-architects/module-federation/webpack");

module.exports = withModuleFederationPlugin({
  name: "mfe-dashboard-two",

  exposes: {
    "./Component": "./src/app/app.component.ts",
  },

  shared: {
    ...shareAll({
      singleton: true,
      strictVersion: true,
      requiredVersion: "auto",
    }),
  },
});

4 - Testar

Para testar execute cada aplicação com o comando:

npm start

Acesse o link http://localhost:4200/, ao abrir será apresentado a tela:

Ao acessar no menu Dashboard Barra ou Dashboard Pizza, será apresentada as aplicações remotas que estão sendo executadas nas portas 4201 e 4202.

O código completo: https://github.com/wandealves/arquitetura-microfront-end

5 - Rotas Dinâmicas

Podemos usar rotas dinâmicas para acessar as aplicações remotas. Neste exemplo, teremos o HOST, que é a aplicação principal, e outras aplicações remotas que serão renderizadas dentro dela. Para disponibilizar essas aplicações, utilizaremos uma aplicação responsável por fornecê-las.

5.1 - Aplicação HOST

A criação é a mesma que já foi apresentada, o que muda é a forma como vamos obter as rotas de maneira dinâmica.

No app.config.ts, foi adicionado withHashLocation e provideHttpClient():

import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
import { provideRouter, withHashLocation } from '@angular/router';

import { routes } from './app.routes';
import { provideHttpClient } from '@angular/common/http';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZoneChangeDetection({ eventCoalescing: true }),
    provideHttpClient(),
    provideRouter(routes, withHashLocation()),
  ],
};

Foi criado o route-loader.service.ts, responsável por obter as rotas:

import { Injectable, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { Routes } from '@angular/router';
import { map, Observable } from 'rxjs';

import { loadRemoteModule } from '@angular-architects/module-federation';

@Injectable({ providedIn: 'root' })
export class RouteLoaderService {
  private http = inject(HttpClient);

loadRoutes(): Observable<Routes> {
  return this.http.get<any[]>('http://localhost:3000/routes.json').pipe(
    map((routes) =>{
      return routes.map(route =>({
        path: route.path,
        loadComponent: () =>
          loadRemoteModule({
            type: route.type,
            remoteEntry: route.remoteEntry,
            exposedModule: route.exposedModule,
          }).then((m) => m.AppComponent),
      }));
    }
    )
  );
}
}

No app.component.ts foi adicionado a chamada ao serviço e atualização das rotas:

import { Component, OnInit } from '@angular/core';
import { Router, RouterOutlet } from '@angular/router';
import { RouteLoaderService } from './services/route-loader.service';
import { NavbarComponent } from './navbar/navbar.component';

@Component({
  selector: 'app-root',
  imports: [RouterOutlet, NavbarComponent],
  templateUrl: './app.component.html',
  styleUrl: './app.component.css'
})
export class AppComponent implements OnInit {
  title = 'host';

  constructor(private routeLoader: RouteLoaderService, private router: Router) {}

  ngOnInit() {
    this.routeLoader.loadRoutes().subscribe({
      next: (routes) => {
       this.router.config = [...this.router.config, ...routes];
      },
      error: (err) => {
        console.error('Failed to load routes:', err);
      },
    });
  }
}

5.2 - Provedora das apps

Nessa aplicação vai prover as aplicações, dentro da pasta public temos o arquivo routes.json com as rotas.

[
  {
    "path":"mfe-app-01",
    "type": "module",
    "remoteEntry": "http://localhost:3000/extensions/mfe-app-01/remoteEntry.js",
    "exposedModule":"./Component"
  },
  {
    "path":"mfe-app-02",
    "type": "module",
    "remoteEntry": "http://localhost:3000/extensions/mfe-app-02/remoteEntry.js",
    "exposedModule":"./Component"
  }
]

dentro de public/extensions/mfe-app-01 e public/extensions/mfe-app-02 temos as aplicações compiladas e são providas nas rotas:

http://localhost:3000/extensions/mfe-app-01/remoteEntry.js
http://localhost:3000/extensions/mfe-app-02/remoteEntry.js

O projeto completo https://github.com/wandealves/arquitetura-microfront-end-rotas-dinamicas

6 - Conclusão

O Module Federation é uma ferramenta poderosa que pode transformar a forma como desenvolvemos aplicações web complexas. Ao permitir a integração e compartilhamento de módulos entre diferentes aplicações, ele facilita a construção de sistemas escaláveis e modulares, alinhados com os princípios de micro front-end. No entanto, é essencial considerar os desafios e gerenciar cuidadosamente as dependências e a performance para tirar o máximo proveito dessa tecnologia.

Referências:

Module Federation

Testcontainers: Testes de integração em containers

Wanderson Alves Rodrigues — Mon, 09 Sep 2024 17:04:14 +0000

Nos dias atuais, onde a arquitetura de microsserviços e o uso de contêineres se tornaram comuns, a necessidade de realizar testes de integração confiáveis e reproduzíveis é crucial. É nesse cenário que o Testcontainers se destaca como uma ferramenta poderosa para desenvolvedores que buscam testar suas aplicações de maneira eficiente e isolada.

O que é Testcontainers?

Testcontainers é uma biblioteca de código aberto que permite aos desenvolvedores executar contêineres Docker em testes de integração. Originalmente desenvolvido para a JVM, ele agora oferece suporte para várias linguagens de programação, como Java, Python, .NET, NodeJs, entre outras. A principal função do Testcontainers é facilitar a criação de ambientes de teste realistas, usando contêineres que simulam dependências externas, como bancos de dados, filas de mensagens, navegadores web, entre outros.

Linguagens Suportadas

As linguagens podem ser acessadas Supported languages and prerequisites

Por que Usar Testcontainers?

Ambientes de Teste Isolados: Cada teste executado pelo Testcontainers é executado em um contêiner Docker isolado. Isso significa que as dependências e o estado dos testes não interferem uns com os outros, permitindo testes mais confiáveis e repetíveis.
Facilidade de Configuração: Testcontainers simplifica a configuração de ambientes complexos de teste. Em vez de configurar manualmente dependências como bancos de dados ou serviços externos, o Testcontainers permite que você defina essas dependências diretamente em seus testes, tornando o processo de configuração rápido e simples.
Reproduzibilidade: Com o Testcontainers, você pode garantir que seu ambiente de teste seja o mesmo em qualquer máquina ou pipeline CI/CD. Isso elimina problemas comuns de "funciona na minha máquina" que surgem devido a diferenças de configuração de ambiente.
Integração com Frameworks de Teste: O Testcontainers se integra facilmente com vários frameworks de teste populares, como JUnit para Java, PyTest para Python, e xUnit para .NET. Isso permite que os desenvolvedores utilizem suas ferramentas de teste preferidas enquanto aproveitam os benefícios do Testcontainers.

Como Funciona o Testcontainers?

O Testcontainers utiliza o Docker para iniciar e gerenciar contêineres que contêm as dependências necessárias para os testes. A biblioteca oferece uma API simples que permite configurar, iniciar e parar contêineres diretamente nos testes de integração. Por exemplo, ao testar uma aplicação que depende de um banco de dados MySQL, você pode configurar um contêiner MySQL diretamente no seu teste, popular o banco de dados com dados de teste e executar as verificações necessárias.

Testcontainers workflow

Um teste de integração típico baseado no Testcontainers funciona da seguinte forma:

Antes da execução do teste: Inicie os serviços necessários (bancos de dados, sistemas de mensageria, etc.) como contêineres Docker usando a API do Testcontainers. Assim que os contêineres necessários forem iniciados, configure ou atualize a configuração da sua aplicação para usar esses serviços containerizados e, opcionalmente, inicialize os dados necessários para o teste.
Durante a execução do teste: Seus testes são executados usando esses serviços containerizados.
Após a execução do teste: O Testcontainers cuida de destruir os contêineres, independentemente de os testes terem sido executados com sucesso ou se houveram falhas.

Vantagens e Desvantagens

1 - Vantagens

Ambientes Isolados: Cada teste é executado em um contêiner isolado, o que evita interferência entre testes.
Configuração Flexível: O Testcontainers permite configurar contêineres de maneira programática, facilitando a criação de ambientes complexos.
Reprodução de Bugs: Como os contêineres são idênticos em qualquer ambiente, os bugs são mais fáceis de reproduzir e resolver.
Suporte a Múltiplas Linguagens: Além de Java, o Testcontainers também suporta Python, .NET, Node.js, entre outras linguagens.

2 - Desvantagens

Dependência do Docker: Para usar o Testcontainers, você precisa ter o Docker instalado e funcionando corretamente em sua máquina ou no ambiente de CI/CD.
Tempo de Execução: Testes que utilizam Testcontainers podem demorar mais para serem executados devido ao tempo necessário para iniciar e configurar os contêineres.
Complexidade Adicional: Embora o Testcontainers simplifique a configuração de dependências, ele adiciona uma camada de complexidade ao processo de teste, que pode não ser necessária para testes simples.

Vamos colocar a mão na massa!

Vamos desenvolver uma API simples e realizar teste de integração. Será uma aplicação com a seguinte tecnologia: dotnet C#. A ideia não é focar na criação das APIs, mas sim no teste de integração da API usando para subir nossa infra o testcontainers.

Pré-requisitos:

dotnet
Docker

1 - API dotnet Csharp

using Endpoints.Dtos;
using Entities;
using Services;

namespace Endpoints;
public static class ProductEndpoints
{
  public static void MapProductEndpoints(this IEndpointRouteBuilder routes)
  {
    // GET: Retorna todos os produtos
    routes.MapGet("/api/products", async (IProductService service) =>
    {
      var products = await service.GetProductsAsync();
      return Results.Ok(products);
    });

    // GET: Retorna um produto pelo ID
    routes.MapGet("/api/products/{id:guid}", async (Guid id, IProductService service) =>
    {
      var product = await service.GetProductAsync(id);
      if (product == null)
        return Results.NotFound();

      return Results.Ok(product);
    });

    // POST: Cria um novo produto
    routes.MapPost("/api/products", async (ProductDto product, IProductService service) =>
    {
      var productCreated = await service.CreateProductAsync(new Product
      {
        Name = product.Name,
        Price = product.Price
      });
      return Results.Created($"/api/products/{productCreated.Id}", productCreated);
    });

    // PUT: Atualiza um produto existente
    routes.MapPut("/api/products/{id:guid}", async (Guid id, ProductDto updatedProduct, IProductService service) =>
    {
      var product = await service.GetProductAsync(id);
      if (product == null)
        return Results.NotFound();

      product.Name = updatedProduct.Name;
      product.Price = updatedProduct.Price;

      await service.UpdateProductAsync(product);

      return Results.NoContent();
    });

    // DELETE: Exclui um produto
    routes.MapDelete("/api/products/{id:guid}", async (Guid id, IProductService service) =>
    {
      var product = await service.GetProductAsync(id);
      if (product == null)
        return Results.NotFound();

      await service.DeleteProductAsync(product.Id);
      return Results.NoContent();
    });
  }
}

Esse trecho de código define uma série de endpoints para um sistema de gerenciamento de produtos utilizando a arquitetura de APIs RESTful no dotnet. Vamos detalhar cada parte:

Estrutura do Código

a - Namespaces e Usos:

Endpoints.Dtos, Entities, e Services são namespaces importados, indicando a organização do código em diferentes camadas e separação de responsabilidades. O Dto (Data Transfer Object) é usado para transferir dados entre camadas, e Entities refere-se aos objetos de domínio, enquanto Services contém a lógica de negócio.

b - MapProductEndpoints:
Esse método estático estende o IEndpointRouteBuilder, que é responsável por configurar as rotas da API. Ao chamar esse método, todas as rotas relacionadas a produtos são registradas.

c - GET: /api/products:

Esse endpoint retorna a lista de todos os produtos.
Ele chama o método GetProductsAsync de IProductService, que busca os produtos do banco de dados.
A resposta é enviada com o status HTTP 200 (OK) junto com a lista de produtos.

d - GET: /api/products/{id:guid}:

Busca um produto específico pelo seu id, que deve ser um GUID (Globally Unique Identifier).
Se o produto não for encontrado, o método retorna o status 404 (Not Found). Caso seja encontrado, retorna 200 (OK) com o produto.

e - POST: /api/products:

Cria um novo produto.
O ProductDto é o objeto recebido como entrada, que contém os dados necessários para criar o produto (por exemplo, Name e Price).
O serviço CreateProductAsync é chamado, que salva o novo produto no banco de dados.
Se bem-sucedido, retorna o status 201 (Created) com a URL do novo recurso criado.

f - PUT: /api/products/{id:guid}:

Atualiza um produto existente identificado pelo id.
O produto é primeiro buscado via GetProductAsync. Se não encontrado, retorna 404.
Caso contrário, atualiza as propriedades Name e Price com os valores do updatedProduct, e chama UpdateProductAsync para salvar as alterações.
Retorna o status 204 (No Content) para indicar sucesso sem conteúdo no corpo da resposta.

g - DELETE: /api/products/{id:guid}:

Exclui um produto específico.
O produto é primeiro buscado pelo id. Se não for encontrado, retorna 404.
Se encontrado, chama DeleteProductAsync para removê-lo e retorna 204 (No Content).

Padrões Utilizados

RESTful: As rotas seguem o padrão RESTful, onde cada ação (GET, POST, PUT, DELETE) corresponde a uma operação CRUD (Create, Read, Update, Delete).
Injeção de Dependência: Os serviços, como IProductService, são passados diretamente nos métodos de rota, utilizando a injeção de dependência do dotnet, o que facilita a troca de implementações e promove um código mais testável.
DTOs: O uso de ProductDto separa a camada de apresentação (dados enviados e recebidos pela API) da camada de domínio (os objetos reais de banco de dados), o que melhora a segurança e a manutenção do código.

2 - Serviço

Ela é responsável por fornecer a lógica de negócio para as operações CRUD (Create, Read, Update, Delete) relacionadas aos produtos, utilizando o Entity Framework Core para interagir com o banco de dados.

using Entities;
using Infra;
using Microsoft.EntityFrameworkCore;

namespace Services;

public class ProductService : IProductService
{
  private readonly AppDbContext _context;

  public ProductService(AppDbContext context)
  {
    _context = context;
  }

  public async Task<IEnumerable<Product>> GetProductsAsync()
  {
    return await _context.Products.ToListAsync();
  }

  public async Task<Product?> GetProductAsync(Guid id)
  {
    return await _context.Products.FirstOrDefaultAsync(x => x.Id == id);
  }

  public async Task<Product> CreateProductAsync(Product product)
  {
    product.CreatedOnUtc = DateTime.UtcNow;
    _context.Products.Add(product);
    await _context.SaveChangesAsync();
    return product;
  }

  public async Task UpdateProductAsync(Product product)
  {
    _context.Products.Update(product);
    await _context.SaveChangesAsync();
  }

  public async Task DeleteProductAsync(Guid id)
  {
    var product = await _context.Products.FirstOrDefaultAsync(x => x.Id == id);
    if (product != null)
    {
      _context.Products.Remove(product);
      await _context.SaveChangesAsync();
    }
  }
}

3 - Testes

Agota que temos a API, podemos realizar o teste de integração. Para nosso exemplo, um teste de integração verifica se diferentes partes de um sistema funcionam corretamente quando integradas. No contexto de uma API que utiliza banco de dados, um teste de integração comum envolve verificar se os serviços interagem corretamente com o banco de dados, confirmando que as operações CRUD (Create, Read, Update, Delete) funcionam conforme o esperado.
para esse exemplo vou usar xUnit como o framework de teste e também as libs:

Adicione a seguinte dependência ao seu arquivo de projeto:

dotnet add package Microsoft.AspNetCore.Mvc.Testing --version 8.0.8
dotnet add package Testcontainers.MsSql
dotnet add package FluentAssertions --version 6.12.1

Como para persistir dados vamos usar o Microsoft SQL Server, também conhecido como MSSQL, é um mecanismo de banco de dados relacional desenvolvido pela Microsoft e é uma escolha popular em sistemas empresariais.

O nosso código de teste segue:

3.1 - Classe IntegrationTestWebAppFactory

O código configura um ambiente de teste de integração para uma aplicação ASP.NET Core utilizando o Testcontainers para criar e gerenciar um banco de dados SQL Server em contêineres Docker

using DotNet.Testcontainers.Builders;
using Infra;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.AspNetCore.TestHost;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Testcontainers.MsSql;

namespace Tests;

public class IntegrationTestWebAppFactory : WebApplicationFactory<Program>, IAsyncLifetime
{
  private readonly MsSqlContainer _dbContainer = new MsSqlBuilder()
      .WithImage("mcr.microsoft.com/mssql/server:2022-latest")
      .WithPassword("1q2w3e4r@#$!")
      .WithWaitStrategy(Wait.ForUnixContainer().UntilPortIsAvailable(1433))
      .Build();

  protected override void ConfigureWebHost(IWebHostBuilder builder)
  {
    builder.UseEnvironment("Testing");
    builder.ConfigureTestServices(services =>
    {
      var descriptor = services.SingleOrDefault(
              d => d.ServiceType == typeof(DbContextOptions<AppDbContext>));
      if (descriptor is not null)
      {
        services.Remove(descriptor);
      }
      services.AddDbContext<AppDbContext>(options =>
            {
              var connectionString = _dbContainer.GetConnectionString();
              options.UseSqlServer(connectionString);
            });
    });
  }

  public async Task InitializeAsync()
  {
    await _dbContainer.StartAsync();
  }

  public async new Task DisposeAsync()
  {
    await _dbContainer.StopAsync();
  }
}

Estrutura do Código

a - Imports e Namespaces:

DotNet.Testcontainers.Builders: Biblioteca para construir e gerenciar contêineres Docker.
Infra: Namespace que provavelmente contém a classe AppDbContext.
Microsoft.AspNetCore.Hosting, Microsoft.AspNetCore.Mvc.Testing, Microsoft.AspNetCore.TestHost, Microsoft.EntityFrameworkCore, Microsoft.Extensions.DependencyInjection: Bibliotecas necessárias para a criação e configuração de testes de integração ASP.NET Core e acesso ao banco de dados.
Testcontainers.MsSql: Biblioteca específica para trabalhar com contêineres Docker do SQL Server.

b - Classe IntegrationTestWebAppFactory:

Herda de WebApplicationFactory, que é usada para configurar e criar uma instância do aplicativo para testes.
Implementa a interface IAsyncLifetime, que permite definir métodos assíncronos de inicialização e limpeza.

c - Propriedade _dbContainer:

MsSqlContainer: Configuração para criar e gerenciar um contêiner do SQL Server.
MsSqlBuilder: Construtor para criar a instância do contêiner.
.WithImage("mcr.microsoft.com/mssql/server:2022-latest"): Define a imagem do Docker para o SQL Server.
.WithPassword("1q2w3e4r@#$!"): Define a senha do administrador do banco de dados.
.WithWaitStrategy(Wait.ForUnixContainer().UntilPortIsAvailable(1433)): Configura a estratégia de espera para garantir que o contêiner esteja pronto antes de prosseguir. O SQL Server escuta na porta 1433.
.Build(): Constrói a instância do contêiner.

d - Método ConfigureWebHost:

UseEnvironment("Testing"): Configura o ambiente para "Testing", que pode alterar o comportamento da aplicação e as configurações de serviços.
ConfigureTestServices: Substitui a configuração de serviços padrão com uma configuração personalizada para testes.
Remove: Remove o registro existente do DbContextOptions, se existir.
AddDbContext: Adiciona e configura o contexto do banco de dados para usar a conexão do contêiner do SQL Server.

e - Método InitializeAsync:

Inicia o contêiner do SQL Server de forma assíncrona antes dos testes começarem.

f - Método DisposeAsync:

Para o contêiner do SQL Server de forma assíncrona após os testes serem concluídos, garantindo a limpeza dos recursos utilizados.

Explicação:

Testcontainers: A biblioteca Testcontainers permite a criação e gerenciamento de contêineres Docker durante os testes, o que é útil para criar ambientes de teste isolados e replicáveis. Aqui, ela é usada para criar um contêiner SQL Server que simula o ambiente de banco de dados real durante os testes.
WebApplicationFactory: Facilita a criação de uma instância do aplicativo ASP.NET Core para testes, configurando o ambiente de teste e injetando dependências conforme necessário.

Configuração do Banco de Dados para Testes:

Ao configurar o AppDbContext para usar o banco de dados dentro do contêiner, você garante que os testes não interfiram no banco de dados de produção ou desenvolvimento.

Gerenciamento de Ciclo de Vida do Contêiner:

Inicialização: Garante que o banco de dados esteja pronto antes dos testes começarem.
Limpeza: Para o banco de dados depois dos testes, liberando os recursos alocados.

3.2 - Classe BaseIntegrationTest

O código define uma classe abstrata chamada BaseIntegrationTest, que é projetada para fornecer uma base para testes de integração que envolvem a comunicação com uma API. A classe utiliza o xUnit para testes e configurações de integração. Vamos detalhar cada parte do código. A classe BaseIntegrationTest fornece métodos comuns para interagir com a API durante os testes de integração, incluindo a criação e recuperação de produtos. Utiliza o cliente HTTP configurado para enviar e receber dados da API e processa as respostas JSON para objetos C#. Isso facilita a escrita de testes de integração ao oferecer uma base reutilizável e configurada adequadamente para interagir com a API.

using Entities;
using Newtonsoft.Json;

namespace Tests;

public abstract class BaseIntegrationTest : IClassFixture<IntegrationTestWebAppFactory>
{
  public HttpClient _client = null!;
  public BaseIntegrationTest(IntegrationTestWebAppFactory factory)
  {
    _client = factory.CreateClient();
    _client.BaseAddress = new Uri("https://localhost");
  }

  public HttpClient GetClient()
  {
    return _client;
  }

  public async Task<Product> CreateProductAsync()
  {
    var product = new Product
    {
      Name = "Product 1",
      Price = 10
    };

    var client = GetClient();
    var response = await client.PostAsync("/api/products", product.ToStringContent());
    await response.Content.ReadAsStringAsync();
    var json = await response.Content.ReadAsStringAsync();
    var productCreated = JsonConvert.DeserializeObject<Product>(json);
    return productCreated ?? product;
  }

  public async Task<Product> GetProductAsync(HttpResponseMessage response)
  {
    var json = await response.Content.ReadAsStringAsync();
    var product = JsonConvert.DeserializeObject<Product>(json);
    return product ?? new Product();
  }

  public async Task<IEnumerable<Product>> GetProductsAsync(HttpResponseMessage response)
  {
    var json = await response.Content.ReadAsStringAsync();
    var products = JsonConvert.DeserializeObject<IEnumerable<Product>>(json);
    return products ?? Enumerable.Empty<Product>();
  }
}

Estrutura do Código

a - Namespaces e Imports:

Entities: Contém a definição da classe Product.
Newtonsoft.Json: Biblioteca para serialização e desserialização de JSON.

b - Classe BaseIntegrationTest:

Herança: Herda de IClassFixture, o que significa que a classe utiliza o IntegrationTestWebAppFactory para configurar a aplicação e criar uma instância do cliente HTTP para os testes.

c - Construtor BaseIntegrationTest:

IntegrationTestWebAppFactory factory: Recebe uma instância da fábrica de testes que configura o ambiente de teste.

_client: Cria um cliente HTTP usando a fábrica e define a base URL para https://localhost. Esse cliente é usado para fazer solicitações HTTP para a API durante os testes.

public BaseIntegrationTest(IntegrationTestWebAppFactory factory)
{
  _client = factory.CreateClient();
  _client.BaseAddress = new Uri("https://localhost");
}

d - Método GetClient:

Retorna o cliente HTTP configurado, que pode ser usado pelos métodos de teste para fazer solicitações.

public HttpClient GetClient()
{
  return _client;
}

3.3 - A classe de teste:

No arquivo ProductTests.cs que criamos os testes que ao ser executado vai levantar nosso infra de contêineres, no exemplo só temos o banco de dados SQL Server, porém poderia ser RabbitMQ, Redis e vários outros que podem ser visto em Modules.

using System.Net;
using Entities;
using FluentAssertions;

namespace Tests;

public class ProductTests : BaseIntegrationTest
{
  public ProductTests(IntegrationTestWebAppFactory factory) : base(factory)
  {

  }

  [Fact(DisplayName = "Obter todosprodutos")]
  [Trait("Categoria", "Produto")]
  public async Task GetAll_ShouldReturnProduct_WhenProductExists()
  {
    // Arrange
    var client = GetClient();
    // Act
    var response = await client.GetAsync("/api/products");
    await response.Content.ReadAsStringAsync();
    var products = await GetProductsAsync(response);
    // Assert
    products.Should().NotBeNullOrEmpty();
    response.StatusCode.Should().Be(HttpStatusCode.OK);
  }

  [Fact(DisplayName = "Obter produto pelo Id")]
  [Trait("Categoria", "Produto")]
  public async Task Get_ShouldReturnProduct_WhenProductExists()
  {
    // Arrange
    var product = await CreateProductAsync();
    var client = GetClient();
    // Act
    var response = await client.GetAsync($"/api/products/{product.Id}");
    await response.Content.ReadAsStringAsync();
    // Assert
    response.Content.Should().NotBeNull();
    response.StatusCode.Should().Be(HttpStatusCode.OK);
  }

  [Fact(DisplayName = "Criar novo produto")]
  [Trait("Categoria", "Produto")]
  public async Task Create_ShouldCreateProduct()
  {
    // Arrange
    var product = new Product
    {
      Name = "Product 1",
      Price = 10
    };
    var client = GetClient();
    // Act
    var response = await client.PostAsync("/api/products", product.ToStringContent());
    await response.Content.ReadAsStringAsync();
    // Assert
    response.Content.Should().NotBeNull();
    response.StatusCode.Should().Be(HttpStatusCode.Created);
  }

  [Fact(DisplayName = "Atualizar produto")]
  [Trait("Categoria", "Produto")]
  public async Task Update_ShouldThrow_WhenProductIsNull()
  {
    // Arrange
    var product = await CreateProductAsync();
    product.Name = "Product Updated";
    var client = GetClient();
    // Act
    var response = await client.PutAsync($"/api/products/{product.Id}", product.ToStringContent());
    await response.Content.ReadAsStringAsync();

    var responseGet = await client.GetAsync($"/api/products/{product.Id}");
    await responseGet.Content.ReadAsStringAsync();
    var productGet = await GetProductAsync(responseGet);
    // Assert
    response.Content.Should().NotBeNull();
    response.StatusCode.Should().Be(HttpStatusCode.NoContent);
    responseGet.Content.Should().NotBeNull();
    responseGet.StatusCode.Should().Be(HttpStatusCode.OK);
    productGet.Should().NotBeNull();
    product.Name.Should().Be(productGet.Name);
  }

  [Fact(DisplayName = "Deletar produto")]
  [Trait("Categoria", "Produto")]
  public async Task Delete_ShouldDeleteProduct_WhenProductExists()
  {
    // Arrange
    var product = await CreateProductAsync();
    var client = GetClient();
    // Act
    var response = await client.DeleteAsync($"/api/products/{product.Id}");
    await response.Content.ReadAsStringAsync();
    // Assert
    response.Content.Should().NotBeNull();
    response.StatusCode.Should().Be(HttpStatusCode.NoContent);
  }
}

Para executar os testes:

dotnet test

Saída:

Iniciando execução de teste, espere...
1 arquivos de teste no total corresponderam ao padrão especificado.

Aprovado!  – Com falha:     0, Aprovado:     5, Ignorado:     0, Total:     5, Duração: 46 ms - Tests.dll (net8.0)

Os contêineres criados para o teste:

CONTAINER ID   IMAGE                                        COMMAND                  CREATED        STATUS                  PORTS                     NAMES
6f98a2e38263   mcr.microsoft.com/mssql/server:2022-latest   "/opt/mssql/bin/perm…"   1 second ago   Up Less than a second   0.0.0.0:32781->1433/tcp   lucid_kilby
8ca5671ec0b4   testcontainers/ryuk:0.6.0                    "/bin/ryuk"              1 second ago   Up Less than a second   0.0.0.0:32780->8080/tcp   testcontainers-ryuk-74611f97-e6cd-4363-9b5f-7d63c17f1147

Testcontainers/Ryuk é um componente utilizado pela biblioteca Testcontainers para gerenciar o ciclo de vida de contêineres durante os testes. Ryuk é uma ferramenta auxiliar que se assegura de que todos os contêineres iniciados durante a execução de testes sejam parados e removidos quando os testes são concluídos, evitando que os contêineres deixem recursos "pendentes" no sistema.

Detalhes sobre Ryuk

Ryuk foi projetado para ser uma solução leve e eficaz para a limpeza automática dos contêineres Docker que são criados e usados durante os testes. Ele é especialmente útil em ambientes de CI/CD e desenvolvimento local, onde muitos testes podem iniciar e parar contêineres frequentemente.

Para quem gosta de anime vai lembra Ryuk é um personagem do anime e mangá Death Note. Ryuk é um shinigami ("deus da morte", em japonês).

O código completo pode ser acessado: Products Api dotnet Testcontainers

Conclusão

O Testcontainers é uma ferramenta valiosa para quem precisa realizar testes de integração confiáveis em ambientes complexos. Ele traz uma série de benefícios, como ambientes de teste isolados, facilidade de configuração e reprodução garantida de ambientes. Contudo, é importante estar ciente das suas limitações, como a dependência do Docker e o tempo de execução dos testes.

Para projetos que dependem de várias dependências externas ou precisam de ambientes de teste consistentes e reproduzíveis, o Testcontainers é uma excelente escolha que pode melhorar significativamente a qualidade e a confiabilidade dos seus testes de integração.

Referências:

Testcontainers

Ollama: Aproveitando o poder dos modelos de linguagem locais

Wanderson Alves Rodrigues — Wed, 24 Jul 2024 04:06:42 +0000

Os modelos de linguagem grandes (LLMs) como o GPT-4 revolucionaram a forma como interagimos com a inteligência artificial. No entanto, utilizar esses modelos geralmente requer acesso à nuvem, o que pode levantar preocupações com privacidade, latência e custos. É aqui que entra o Ollama, uma ferramenta poderosa que permite executar LLMs localmente no seu próprio hardware. Neste post, vamos explorar o que é o Ollama, seus benefícios e como você pode começar a usá-lo.

O que é o Ollama?

O Ollama é uma ferramenta de código aberto que possibilita a execução, criação e compartilhamento dos modelos de linguagem (LLMs) diretamente no seu próprio computador. Ele permite que você baixe, gerencie e execute modelos em seu próprio hardware, eliminando a necessidade de dependência da nuvem. Isso significa que você pode ter controle total sobre os seus dados, reduzir a latência das inferências e otimizar o uso dos recursos computacionais disponíveis e ter uma flexibilidade ao permitir a execução de modelos com diferentes configurações e tamanhos.

Benefícios de Usar o Ollama

Privacidade dos Dados: Ao executar modelos localmente, você garante que seus dados não saiam do seu ambiente controlado. Isso é crucial para empresas e indivíduos preocupados com a privacidade e segurança da informação.
Redução de Latência: A execução local dos modelos elimina a necessidade de comunicação com servidores remotos, resultando em respostas mais rápidas e eficientes.
Controle de Recursos: Com o Ollama, você pode otimizar o uso dos recursos de hardware disponíveis, como CPU e GPU, ajustando as configurações para atender às suas necessidades específicas.
Custo-Benefício: Evitar custos de serviços em nuvem pode ser uma vantagem significativa, especialmente para projetos de longo prazo ou com alta demanda de processamento.

Instalando o Ollama

Para instalar o Ollama, você pode baixar diretamente do site oficial ou utilizar uma imagem Docker disponível no Docker Hub. O comando abaixo vai instalar na sua maquina Ollama:



curl -fsSL https://ollama.com/install.sh | sh

Agora que já temos o Ollama instalado, vamos verificar se está tudo funcionando corretamente.



ollama --version

Se tudo estiver funcionando corretamente, você verá a versão do Ollama que está rodando na sua máquina:



ollama version is 0.2.8

Rodando um modelo de Machine Learning com o Ollama

Para nosso exemplo vamos usar o modelo llama3.1 de 8B de parâmetros.O Llama 3.1 criado pela Meta é o primeiro modelo disponível abertamente que rivaliza com os principais modelos de IA quando se trata de recursos de última geração em conhecimento geral, capacidade de direção, matemática, uso de ferramentas e tradução multilíngue.

Para rodar llama3.1, você pode utilizar o seguinte comando:



ollama run llama3.1

Na primeira vez que você rodar o comando, o Ollama irá baixar o modelo do llama3.1 e depois irá rodar o modelo.



pulling manifest 
pulling ff07ca852139... 100% ▕██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▏ 4.7 GB                         
pulling cdbcae7e69d5... 100% ▕██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▏  571 B                         
pulling f1cd752815fc... 100% ▕██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▏  12 KB                         
pulling 56bb8bd477a5... 100% ▕██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▏   96 B                         
pulling 7f5b37e43ea5... 100% ▕██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▏  485 B                         
verifying sha256 digest 
writing manifest 
removing any unused layers 
success

Quando você ver o prompt >>> Send a message (/? for help):, você poderá interagir com o modelo.



>>> 
Use Ctrl + d or /bye to exit.
>>> Olá, tudo bem?
Tudo! Quais são as suas dúvidas ou o que você precisa? Estou aqui para te ajudar.

>>> Send a message (/? for help)

Já estamos com o llama3.1 rodando na nossa máquina. Agora podemos interagir com o modelo e ver o que ele é capaz de fazer.
Para sair do modelo, você pode utilizar o comando Ctrl + d no terminal ou digitar /bye no prompt do modelo.
Para listar quais são os modelos disponíveis para rodar com o Ollama, execute o comando:



ollama list

A saída:



NAME            ID              SIZE    MODIFIED      
llama3.1:latest a23da2a80395    4.7 GB  9 minutes ago

Caso você queira remover um modelo que você baixou, você pode utilizar o seguinte comando:



ollama remove llama3.1

Instalando o Ollama via Docker

Vamos então efetuar o pull destas imagens:



docker pull ollama/ollama

Agora que já temos as imagens, vamos iniciar um container com o ollama e deixa-lo acessível, para isso iremos executar o comando:



docker run -d -p 11434:11434 --name myollama ollama/ollama

Para verificar se tudo realmente está disponível, vamos executar o comando para verificar a versão do ollama.



docker exec myollama ollama --version

Para rodar o modelo llama3.1:



docker exec -it myollama ollama run llama3.1

Para listar os modelos existentes:



docker exec myollama ollama list

Para remover modelo:



docker exec myollama ollama rm llama3.1

Instalando o Open WebUI

Para que possamos ter uma interface gráfica para a nossa IA, vamos usar a ferramenta é o Open WebUI.
Para instalar o Open WebUI, você pode utilizar o seguinte comando:



docker run -d --network=host -e OLLAMA_BASE_URL=http://127.0.0.1:11434 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

Onde:

--network=host é utilizado para que o container tenha acesso a rede da máquina host.
-v open-webui:/app/backend/data é utilizado para criar um volume para armazenar os dados do Open WebUI.
-e OLLAMA_BASE_URL é utilizado para informar a URL base do Ollama, que está rodando na sua máquina, se você estiver rodando o Ollama em outro lugar, você pode alterar o IP e a porta.
--name open-webui é utilizado para dar um nome ao container.
--restart always é utilizado para que o container seja reiniciado sempre que a máquina for reiniciada.
ghcr.io/open-webui/open-webui:main é a imagem do Open WebUI que será utilizada.

Para acessar o Open WebUI, acesse http://localhost:8080

Depois de criar o usuário, você poderá acessar a interface gráfica e interagir com a sua IA.

Referências:

Apresentando o Llama 3.1: nossos modelos mais capazes até o momento
Llama 3.1 - 405B, 70B & 8B with multilinguality and long context
Llama 3.1 - huggingface
Ollama
Open WebUI

Logs estruturados com Serilog e Seq: Melhorando a visibilidade e análise de dados em aplicações

Wanderson Alves Rodrigues — Fri, 10 May 2024 01:48:15 +0000

O registro de logs é uma prática fundamental no desenvolvimento de software, fornecendo informações valiosas sobre o comportamento, desempenho e erros de uma aplicação. No entanto, o simples armazenamento de mensagens de texto em arquivos ou consoles pode não ser suficiente para obter uma compreensão profunda e eficaz do funcionamento de uma aplicação. É aqui que os logs estruturados entram em jogo, oferecendo uma abordagem mais organizada, legível e analisável para o registro de eventos. Neste artigo, vamos explorar os conceitos de logs estruturados e como o Serilog em conjunto com o Seq pode melhorar significativamente a visibilidade e análise de dados em aplicações. O objetivo desse artigo é mostrar um aplicação usando Serilog com Seq, para isso vamos do início até a integração completa.

A Importância dos Logs

Os logs, registros detalhados de atividades e eventos em um sistema, assumem um papel crucial em diversos contextos, desde o desenvolvimento de software até a segurança de rede e a análise de negócios. Além disso, possibilitam uma atuação mais proativa do que reativa na resolução e identificação de problemas. Sua importância se manifesta em três pilares principais:

1 - Solução de Problemas e Depuração:

Rastreamento de Falhas: Logs facilitam a identificação de erros e falhas em sistemas, fornecendo informações sobre:

a - Origem do Erro: Localização específica no código ou componente onde o erro ocorreu.

b - Causa do Erro: Mensagens de erro e detalhes técnicos que auxiliam na compreensão da causa raiz do problema.

c - Contexto do Erro: Informações sobre o estado do sistema e as ações que antecederam o erro, facilitando a análise e a correção.

d - Análise de Desempenho: Logs permitem a análise do desempenho do sistema, identificando gargalos e áreas de otimização.

e - Tempo de Resposta: Monitoramento do tempo de resposta de operações e requisições, detectando lentidão e gargalos.

f - Detecção de Anomalias: Monitoramento de padrões de comportamento e identificação de anomalias que podem indicar problemas em potencial.

2 - Segurança e Conformidade:

Auditoria e Rastreamento: Logs fornecem um registro completo das atividades em um sistema, permitindo:

a - Investigação de Incidentes: Rastreamento de atividades suspeitas e investigação de incidentes de segurança.

b - Análise de Conformidade: Demonstração da conformidade com regulamentações e normas através da auditoria de logs.

c - Detecção de Fraude: Identificação de atividades fraudulentas e acesso não autorizado ao sistema.

d - Prevenção de Ataques: Logs podem ser usados para identificar e prevenir ataques cibernéticos.

3 - Análise de Negócios e Inteligência:

Melhoria da Experiência do Cliente: Análise de logs de aplicativos e websites para:

a - Identificar pontos de atrito: Compreender os desafios que os usuários enfrentam e identificar áreas de melhoria na experiência do cliente.

b - Compreender o comportamento do cliente: Analisar padrões de uso e preferências para personalizar a experiência do cliente e otimizar campanhas de marketing.

O que são Logs Estruturados?

Logs estruturados são registros de eventos que seguem um formato predefinido e organizado, geralmente em formato JSON, XML ou similar. Diferentes dos logs tradicionais, logs estruturados contém uma série informações e metadados adicionais, campos nomeados e valores associados usados para agrupamento e consultas,tornando-os mais legíveis, analisáveis e fáceis de correlacionar. Esta estruturação facilita a consulta, filtragem e visualização de logs, especialmente em ambientes de microserviços, contêineres e aplicações distribuídas. Logs estruturados devem conter informações relevantes ao negócio e ao desenvolvedor.

Um log comum de exceções, por exemplo, envia dados da exceção, como mensagem, stack trace, inner exceptions. Um log estruturado de exceções, poderia conter informações que diagnosticam o servidor no qual o log foi gerado, qual a operação estava sendo processada, qual o ID ou dados mais completos dos seus objetos de negócio durante a operação, além da comum severidade. E não para por aí, ainda seria possível informar qual o cliente da requisição, no caso de WebApps, qual o usuário logado, entre outras diversas informações de aplicação que poderiam ser passadas para o log, ajudando no troubleshooting e análise de problemas ou mesmo de fluxos de negócio. Para o artigo vamos usar Serilog para criar os logs estruturados.

Introdução ao Serilog

Serilog é uma biblioteca de logging para .NET e também outras linguagens que suporta a geração de logs estruturados de forma nativa. Ele permite que os desenvolvedores registrem facilmente eventos e erros em seus aplicativos, facilitando a depuração e a solução de problemas, além de oferece uma configuração flexível e extensível, permitindo que os desenvolvedores capturem e registrem informações detalhadas, contextuais e enriquecidas sobre o comportamento e o desempenho de suas aplicações. Ao contrário das estruturas de log tradicionais, o Serilog se concentra no log estruturado, o que significa que os logs são registrados em um formato estruturado que pode ser facilmente consultado e analisado.

Por que usar o Serilog?

O Serilog é uma biblioteca de logging que se destaca em muitos aspectos e oferece diversas vantagens sobre outras estruturas de log disponíveis no mercado. Abaixo estão algumas razões pelas quais muitos desenvolvedores optam por usar o Serilog em seus projetos em vez de outras bibliotecas de logging:

1 - Logs Estruturados

Uma das características mais distintivas do Serilog é o suporte nativo para logs estruturados. Em vez de simplesmente gravar mensagens de texto em arquivos ou consoles, o Serilog permite que os desenvolvedores gerem logs em formatos organizados, como JSON, XML ou outros, tornando-os mais fáceis de analisar, consultar e correlacionar. Logs estruturados são especialmente úteis em ambientes distribuídos e complexos, onde a capacidade de rastrear e analisar o fluxo de dados entre diferentes componentes é crucial.

2 - Flexibilidade e Extensibilidade

O Serilog é altamente flexível e extensível, permitindo que os desenvolvedores personalizem e configurem o sistema de logging de acordo com as necessidades específicas do projeto. Ele oferece uma variedade de sinks que representa qual o destino dos logs, existem também os enriquecedores de log, facilitando a integração com diferentes sistemas, serviços e plataformas de monitoramento e análise de logs.

O Serilog fornece Sinks que são os coletores para gravar eventos de log no armazenamento em vários formatos.

3 - Enriquecimento de Logs

O Serilog facilita o enriquecimento de logs com informações adicionais, como propriedades personalizadas, contexto da aplicação, dados do ambiente e muito mais. Isso ajuda a fornecer informações mais detalhados e contextuais sobre o comportamento e o desempenho da aplicação, melhorando a capacidade de monitoramento, diagnóstico e resolução de problemas em tempo real.

4 - Performance e Eficiência

O Serilog foi projetado com foco em performance e eficiência, minimizando o impacto no desempenho da aplicação durante a geração e gravação de logs. Ele utiliza técnicas avançadas de buffering, assincronia e otimização para garantir que o logging não se torne um gargalo ou afete negativamente a experiência do usuário final.

5 - Comunidade Ativa e Suporte

O Serilog possui uma comunidade ativa, engajada e colaborativa de desenvolvedores, mantenedores e contribuidores que continuamente trabalham juntos para melhorar, aprimorar e estender a biblioteca. Além disso, o Serilog é bem documentado, possui uma ampla gama de recursos, tutoriais e exemplos disponíveis, e oferece suporte através de fóruns, repositórios e plataformas de discussão, proporcionando uma base sólida e confiável para os desenvolvedores e organizações que escolhem adotá-lo em seus projetos.

Seq: Gerenciamento de Logs e Rastreamentos em Tempo Real

Seq é um servidor de pesquisa e análise em tempo real para logs e rastreamentos de aplicativos estruturados. Com sua interface intuitiva, armazenamento de eventos JSON, o que facilita a análise e a integração com outras ferramentas.

1 - Principais Recursos e Funcionalidades:

a - Interface de Usuário Amigável: A interface do Seq foi cuidadosamente projetada para facilitar a navegação e a análise de logs. Com recursos como busca rápida, filtros avançados e visualizações personalizadas, os usuários podem encontrar rapidamente as informações necessárias.

b - Armazenamento em Formato JSON: Os eventos de log no Seq são armazenados no formato JSON, o que permite uma estruturação flexível e facilita a integração com outras ferramentas e sistemas.

c - Busca e Análise em Tempo Real: Uma das principais vantagens do Seq é sua capacidade de buscar e analisar logs em tempo real. Isso permite que os usuários identifiquem e respondam rapidamente a problemas e anomalias em seus sistemas.

d - Integração com Plataformas e Ferramentas: O Seq oferece uma ampla gama de integrações com outras ferramentas e plataformas, incluindo sistemas de monitoramento, alerta e gerenciamento de incidentes. Isso permite uma integração perfeita em ambientes de desenvolvimento e operações.

Vamos colocar a mão na massa!

Vamos desenvolver uma API simples com integração ao Seq para armazenar nossos logs. Para isso, utilizaremos o Serilog. Serão duas aplicações com as seguintes tecnologias: C# e Node.js. A ideia não é focar na criação das APIs, mas sim na geração de logs e no monitoramento. Portanto, será uma API simples.

1 - API .NET Csharp

Será uma API simples para o cadastro de eventos. A ideia é utilizar logs e visualizá-los no Seq.

Pré-requisitos:

Para instalar o Serilog em nossa aplicação é bastante simples, os desenvolvedores podem usar o NuGet para instalar o pacote Serilog e, em seguida, configurá-lo usando uma variedade de abordagens, como JSON ou configuração baseada em código.



dotnet add package Serilog.Sinks.Seq --version 7.0.0
dotnet add package Serilog.Sinks.Dynatrace --version 1.0.7
dotnet add package Serilog.Enrichers.Thread --version 3.1.0
dotnet add package Serilog.Enrichers.Process --version 2.0.2
dotnet add package Serilog.Enrichers.Memory --version 1.0.4
dotnet add package Serilog.Enrichers.Environment --version 2.3.0
dotnet add package Serilog.Enrichers.CorrelationId --version 3.0.1

a - Serviço



using EventAPI.Models;

namespace EventAPI.Services;

public interface IEventService
{
    List<Event> GetAll();
    Event? GetById(int id);
    Event Create(Event newEvent);
    void Update(int id, Event updatedEvent);
    void Delete(int id);
    void BatchDelete();
}



using EventAPI.Models;

namespace EventAPI.Services;

public class EventService : IEventService
{
    private readonly ILogger<EventService> _logger;
    private List<Event> _events;

    public EventService(ILogger<EventService> logger)
    {
        _logger = logger;
        _events = new List<Event>();
    }

    public List<Event> GetAll()
    {
        return _events;
    }

    public Event? GetById(int id)
    {
        return _events.FirstOrDefault(e => e.Id == id);
    }

    public Event Create(Event newEvent)
    {
        _logger.LogInformation("Creating new event with title {title}", newEvent.Title);
        newEvent.Id = _events.Count > 0 ? _events.Max(e => e.Id) + 1 : 1;
        _events.Add(newEvent);
        return newEvent;
    }

    public void Update(int id, Event updatedEvent)
    {
        _logger.LogInformation("Updating event with id {id}", id);
        var existingEvent = _events.FirstOrDefault(e => e.Id == id);
        if (existingEvent is null) throw new InvalidOperationException("Event not found");
        existingEvent.Title = updatedEvent.Title;
        existingEvent.StartDateTime = updatedEvent.StartDateTime;
        existingEvent.EndDateTime = updatedEvent.EndDateTime;
    }

    public void Delete(int id)
    {
        _logger.LogInformation("Deleting event with id {id}", id);
        var existingEvent = _events.FirstOrDefault(e => e.Id == id);
        if (existingEvent is null) throw new InvalidOperationException("Event not found");
        _events.Remove(existingEvent);
    }

    public void BatchDelete()
    {
        if (_events.Count == 0)
        {
            throw new InvalidOperationException("No events to delete");
        }
        _events.Clear();
    }
}

Para algumas ações do serviço, foi disponibilizado o registro de log através da chamada logger.LogInformation, onde serão gravadas as informações passadas.

Os níveis de logs são:

O Serilog usa níveis como principal meio de atribuir importância aos eventos de log. Os níveis em ordem crescente de importância são:

Verbose: Este nível é usado para informações de rastreamento e detalhes de depuração extremamente minuciosos. Geralmente, esses logs são ativados apenas em situações incomuns ou durante a depuração intensiva. Eles fornecem uma quantidade muito detalhada de informações, úteis principalmente para desenvolvedores durante o diagnóstico de problemas complexos.
Debug: Logs neste nível são usados para informações relacionadas ao fluxo de controle interno e despejos de estado de diagnóstico para facilitar a identificação de problemas conhecidos. Eles fornecem detalhes úteis para os desenvolvedores entenderem a execução do código e identificarem possíveis problemas durante o desenvolvimento e a depuração.
Information: Este é o nível padrão mínimo de log ativado. Ele é usado para eventos de interesse ou relevância para observadores externos. Isso pode incluir eventos importantes para monitoramento ou rastreamento de atividades do sistema, sem sobrecarregar o registro com muitos detalhes desnecessários.
Warning: Logs neste nível indicam possíveis problemas ou degradação de serviço/funcionalidade. Eles sinalizam situações que podem precisar de atenção, mas que não causaram uma falha no sistema. Geralmente, são usados para alertar sobre condições anormais que podem precisar ser investigadas.
Error: Este nível indica falhas dentro da aplicação ou do sistema conectado. Esses logs registram erros que ocorreram durante a execução do programa e que podem exigir intervenção para corrigir ou mitigar. Eles são úteis para identificar e resolver problemas que podem impactar negativamente o funcionamento do sistema.
Fatal: Logs neste nível indicam erros críticos que causaram a falha completa da aplicação. Eles representam condições graves que exigem atenção imediata e intervenção para restaurar o funcionamento adequado do sistema. Esses logs geralmente são usados para registrar falhas catastróficas que impedem a continuidade da operação normal da aplicação.

Exemplo abaixo usa os níveis:



using Serilog;
using Serilog.Events;

class Program
{
    static void Main()
    {
        Log.Logger = new LoggerConfiguration()
            .MinimumLevel.Verbose() // Definindo o nível mínimo de log como Verbose
            .WriteTo.Console() // Escrevendo os logs no console
            .CreateLogger();

        Log.Verbose("Esta é uma mensagem de log Verbose."); // Este log será exibido
        Log.Debug("Esta é uma mensagem de log Debug."); // Este log será exibido
        Log.Information("Esta é uma mensagem de log Information."); // Este log será exibido
        Log.Warning("Esta é uma mensagem de log Warning."); // Este log será exibido
        Log.Error("Esta é uma mensagem de log Error."); // Este log será exibido
        Log.Fatal("Esta é uma mensagem de log Fatal."); // Este log será exibido

        Log.CloseAndFlush(); // Encerrando o logger
    }
}

b - Configuração Serilog



using Serilog;

namespace EventAPI.Extensions;

public static class LogSettings
{
  public static void AddLogSettings(this WebApplicationBuilder builder, string applicationName, ConfigurationManager configuration)
  {
    var seq = configuration["Settings:Seq"];
    if (string.IsNullOrWhiteSpace(seq)) throw new ArgumentNullException("Seq is required");
    Console.WriteLine($"Environment: {builder.Environment.EnvironmentName}");
    builder.Logging.ClearProviders();
    var logger = new LoggerConfiguration();
    logger.Enrich.WithProperty("ApplicationName", $"{applicationName} - {Environment.GetEnvironmentVariable("DOTNET_ENVIRONMENT")}")
    .MinimumLevel.Information()
    .Enrich.WithEnvironmentName()
    .Enrich.WithMachineName()
    .Enrich.WithProcessId()
    .Enrich.WithThreadId()
    .Enrich.WithMemoryUsage()
    .Enrich.FromLogContext()
    .Enrich.WithCorrelationId()
    .Enrich.WithCorrelationIdHeader();
    if (builder.Environment.EnvironmentName == "Development")
    {
      logger.WriteTo.Console(outputTemplate: "{Timestamp:yyy-MM-dd HH:mm:ss.fff} [{Level}] {Message}{NewLine}{Exception}");
    }
    logger.WriteTo.Seq(seq, restrictedToMinimumLevel: Serilog.Events.LogEventLevel.Information);
    builder.Logging.AddSerilog(logger.CreateLogger());
  }
}

No trecho de código abaixo, temos a obtenção da URL configurada para cada ambiente do Seq . Com isso, os logs gerados pela nossa aplicação são armazenados no Seq e podem ser acessados via: http://localhost:5341/.



using Serilog;

namespace EventAPI.Extensions;

public static class LogSettings
{
  public static void AddLogSettings(this WebApplicationBuilder builder, string applicationName, ConfigurationManager configuration)
  {
    var seq = configuration["Settings:Seq"];
    if (string.IsNullOrWhiteSpace(seq)) throw new ArgumentNullException("Seq is required");
    builder.Logging.ClearProviders();
    var logger = new LoggerConfiguration();
    ....
    logger.WriteTo.Seq(seq, restrictedToMinimumLevel: Serilog.Events.LogEventLevel.Information);
    builder.Logging.AddSerilog(logger.CreateLogger());
  }
}

Foi configurado alguns Enrichments permitem adicionar contexto adicional às suas mensagens de log, o que pode ser extremamente útil para depuração e solução de problemas.



Enrich.WithEnvironmentName()
Enrich.WithMachineName()
Enrich.WithProcessId()
Enrich.WithThreadId()
Enrich.WithMemoryUsage()
Enrich.FromLogContext()
Enrich.WithCorrelationId()
Enrich.WithCorrelationIdHeader();

Foi utilizado o Seq para registrar os logs, uma vez que a coleta de informações por console é apenas para o ambiente de desenvolvimento.



    if (builder.Environment.EnvironmentName == "Development")
    {
      logger.WriteTo.Console(outputTemplate: "{Timestamp:yyy-MM-dd HH:mm:ss.fff} [{Level}] {Message}{NewLine}{Exception}");
    }
    logger.WriteTo.Seq(seq, restrictedToMinimumLevel: Serilog.Events.LogEventLevel.Information);

c - API



using EventAPI.Models;
using EventAPI.Services;

namespace EventAPI.Endpoints;

public static class Events
{
  public static void RegisterEndpoints(this IEndpointRouteBuilder routes)
  {
    var events = routes.MapGroup("/api/v1/events")
    .WithName("Events")
    .WithOpenApi();
    events.MapGet("", (IEventService service) => service.GetAll())
    .WithName("GetAllEvents")
    .WithTags("Events");
    events.MapGet("/{id}", (int id, IEventService service) => service.GetById(id))
    .WithName("GetEventById")
    .WithTags("Events");
    events.MapPost("", (Event newEvent, IEventService service) => service.Create(newEvent))
    .WithName("CreateEvent")
    .WithTags("Events");
    events.MapPut("/{id}", (int id, Event updatedEvent, IEventService service) =>
    {
      service.Update(id, updatedEvent);
    })
    .WithName("UpdateEvent")
    .WithTags("Events");
    events.MapDelete("/{id}", (int id, IEventService service) =>
    {
      service.Delete(id);
    })
    .WithName("DeleteEvent")
    .WithTags("Events");
    events.MapDelete("/batch", (IEventService service) =>
    {
      service.BatchDelete();
    })
    .WithName("BatchDeleteEvents")
    .WithTags("Events");
  }
}

d - Global Exception



using Microsoft.AspNetCore.Diagnostics;

namespace EventAPI.ExceptionHandler;

public class GlobalException : IExceptionHandler
{
    private readonly ILogger<GlobalException> logger;
    public GlobalException(ILogger<GlobalException> logger)
    {
        this.logger = logger;
    }
    public ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        var exceptionMessage = exception.Message;
        logger.LogError(
            "Error Message: {exceptionMessage}, time of occurrence {time}",
            exceptionMessage, DateTime.UtcNow);
        return ValueTask.FromResult(false);
    }
}

Este código mostra como criar um manipulador de exceções global personalizado em um aplicativo ASP.NET Core para registrar mensagens de erro de exceção usando o *Serilog * ou outro mecanismo de registro. Este manipulador de exceções pode ser adicionado ao pipeline de middleware para lidar com exceções em todo o aplicativo.

Caso queira subir a API local siga os passos:

a - Crie um arquivo docker-compose.yml:



version: '3.4'

services:
  seq:
    image: datalust/seq:latest
    container_name: seq
    environment:
      - ACCEPT_EULA=Y
    ports:
      - 5341:5341
      - 8081:80

b - Depois execute o comando para subir o Seq:



docker-compose up

c - Acesse o Seq link:



 http://localhost:5341/

Caso queria testar como a aplicação e Seq compartilhando a mesma rede em containers:

Na raíz do projeto existe docker-compose.yml, execute os comandos:

a - Subir containers



docker-compose up -d --build

b - Descer containers



docker-compose down

Para acessar Seq o link local é:http://localhost:5341/

Para acessar o repositório com o código completo Serilog Seq Api

Dicas

1 - Uma melhoria que podemos fazer no código é usar Serilog.Sinks.Async para registar logs no console. Use esse coletor para reduzir a sobrecarga de registro de chamadas ,ficando o trabalho a cargo de uma Thread em segundo plano.

Instalando a partir do Nuget



dotnet add package Serilog.Sinks.Async



using Serilog;

class Program
{
  static async Task Main()
  {
    Log.Logger = new LoggerConfiguration()
        .MinimumLevel.Debug()
        .WriteTo.Async(wt => wt.Console())
        .WriteTo.File("logs/my-logs.txt", rollingInterval: RollingInterval.Day)
        .CreateLogger();

    Log.Information("Meu log!");

    int a = 10, b = 0;
    try
    {
      Log.Debug("Dividindo {A} by {B}", a, b);
      Console.WriteLine(a / b);
    }
    catch (Exception ex)
    {
      Log.Error(ex, "Algo deu errado");
    }
    finally
    {
      await Log.CloseAndFlushAsync();
    }
  }
}

2 - Não utilizar o Serilog.Sinks.Console em produção, O Console Sink é adequado para uso em desenvolvimento e depuração, por isso deve ser utilizado em ambiente local. Em produção é recomendado utilizar coletores como: Elasticsearch, Rabbitmq, Seq, Sentry, Splunk entre outros que podem ser visto em Provided Sinks

3 - Podemo formatar a saída para temos logs para estruturados. Os coletores baseados em console e em arquivo, geralmente aceitam modelos de saída para controlar como os dados de eventos de log são formatados.

a - Formato de Texto Simples:



  Log.Logger = new LoggerConfiguration()
            .WriteTo.Console()
        .CreateLogger();

b - Formato JSON:



   Log.Logger = new LoggerConfiguration()
      .WriteTo.Console(new JsonFormatter())
      .CreateLogger();

Saída



{"Timestamp":"2024-04-04T22:43:50.3868987-03:00","Level":"Information","MessageTemplate":"Meu log!"}
{"Timestamp":"2024-04-04T22:43:50.4401178-03:00","Level":"Error","MessageTemplate":"Algo deu errado","Exception":"System.DivideByZeroException: Attempted to divide by zero.\n   at Program.Main() in /home/wanderson/Developer/Repositorios/serilog_log_console/AppSerilogConsole/Program.cs:line 26"}

c - Formato Estruturado:

O formato logs gravados podem ser modificados usando o outputTemplateparâmetro.



Log.Logger = new LoggerConfiguration()
    .WriteTo.Console(outputTemplate:
        "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj}{NewLine}{Exception}")
    .CreateLogger();

Propriedades de saída:

Exception- A mensagem de exceção completa e o rastreamento de pilha, formatados em várias linhas. Vazio se nenhuma exceção estiver associada ao evento.
Level- O nível de evento de log, formatado como o nome completo do nível. Para nomes de níveis mais compactos, use um formato como {Level:u3}ou {Level:w3}para nomes de níveis com três caracteres maiúsculos ou minúsculos, respectivamente.
Message- A mensagem do evento de log, renderizada como texto simples. O :lespecificador de formato desativa a citação de strings e :jusa a renderização no estilo JSON para quaisquer dados estruturados incorporados.
NewLine- Uma propriedade com o valor de System.Environment.NewLine.
Properties- Todos os valores de propriedade de evento que não aparecem em nenhum outro lugar da saída. Use o :jformato para usar a renderização JSON.
Timestamp- O carimbo de data/hora do evento, como um arquivo DateTimeOffset.
TraceId- O ID do rastreamento que estava ativo quando o evento foi criado, se houver.
SpanId- O ID do período que estava ativo quando o evento foi criado, se houver.

2 - API com Node.js

Será uma API simples para o cadastro de eventos. A ideia é utilizar logs e visualizá-los no Seq."

Pré-requisitos:

Logs com Winston:

Winston é uma biblioteca de registro popular para node.js, com suporte para registro estruturado. Winston utiliza "transportes" para representar diferentes destinos de log, incluindo o console padrão e opções de arquivo. Winston-seq é um transporte para Winston, que possibilita o envio de logs para o Seq.

Pacotes:



npm install winston
npm install @datalust/winston-seq

Configuração:

import em sua aplicação Node.js:



const winston = require("winston");



const winston = require("winston");
const { combine, timestamp, json, printf } = winston.format;
const { SeqTransport } = require("@datalust/winston-seq");

const logLevels = {
  error: 0,
  warn: 1,
  info: 2,
  http: 3,
  verbose: 4,
  debug: 5,
  silly: 6
};

const customFormat = printf(({ level, message, label, timestamp }) => {
  return `${timestamp} [${label}] ${level}: ${message}`;
});

const setup = () => {
  const logger = winston.createLogger({
    levels: logLevels,
    level: process.env.LOG_LEVEL || "info",
    format: combine(
      timestamp({
        format: "YYYY-MM-DD hh:mm:ss.SSS A"
      }),
      json()
    ),
    transports: [
      new SeqTransport({
        serverUrl: process.env.SEQ_URL || "http://localhost:5341",
        onError: e => {
          console.error(e);
        }
      }),
      new winston.transports.Console()
    ]
  });
  return logger;
};

module.exports = { setup };

No código de configuração podemos ver os níveis do Log no Winston que são:



{
  error: 0,
  warn: 1,
  info: 2,
  http: 3,
  verbose: 4,
  debug: 5,
  silly: 6
}

Uso dos logs na API:



const { v4: uuidv4 } = require("uuid");
const logger = require("../configurations/logger").setup();

let events = [];

const list = (req, res) => {
  res.json(events);
};

const create = (req, res) => {
  const { code, title } = req.body;
  const newEvent = { id: uuidv4(), code, title };
  events.push(newEvent);
  res.status(201).json(newEvent);
};

const update = (req, res) => {
  const { id } = req.params;
  const { title } = req.body;
  const index = events.findIndex(event => event.id === id);
  if (index !== -1) {
    events[index].title = title;
    res.json(events[index]);
  } else {
    res.status(404).json({ mensagem: "Evento não encontrada" });
  }
};

const remove = (req, res) => {
  const { id } = req.params;
  const index = events.findIndex(event => event.id === id);
  if (index !== -1) {
    events.splice(index, 1);
    res.json({ mensagem: "Tarefa excluída com sucesso" });
  } else {
    logger.error("Tarefa não encontrada");
    res.status(404).json({ mensagem: "Tarefa não encontrada" });
  }
};

module.exports = { list, create, update, remove };

Os seis níveis de log acima de cada um correspondem a um método no criador de logs:



logger.error('error');
logger.warn('warn');
logger.info('info');
logger.verbose('verbose');
logger.debug('debug');
logger.silly('silly');

Caso queira subir a API local siga os passos:

a - Crie um arquivo docker-compose.yml:



version: '3.4'

services:
  seq:
    image: datalust/seq:latest
    container_name: seq
    environment:
      - ACCEPT_EULA=Y
    ports:
      - 5341:5341
      - 8081:80

b - Depois execute o comando para subir o Seq:



docker-compose up

c - Acesse o Seq link:



 http://localhost:5341/

Caso queria testar como docker-compose da aplicação:

Na raiz do projeto existe docker-compose.yml, execute os comandos:

a - Subir containers



docker-compose up -d --build

b - Descer containers



docker-compose down

Obs.: É necessário conceder permissão local ao arquivo wait-for-seq.sh com o comando:



chmod +x wait-for-seq.sh

Para acessar Seq o link local é:http://localhost:5341/

Para acessar o repositório com o código completo Serilog Seq API

Referências:

Seq
Serilog
Github - Serilog
Henrique Mauri - Melhores práticas de utilização do Serilog
Henrique Mauri -Coletando logs com o Serilog no .NET 6
Milan Jovanović - 5 Serilog Best Practices For Better Structured Logging
Logging from Node.js
Github - Winston
Github - Winston-seq
A Complete Guide to Winston Logging in Node.js
Node.js Logging with Winston
Automated Logging in Express.js
Best Practices for Logging in Node.js
Winston Logger - Full tutorial with a sample Nodejs application

Desvendando o poder do Docker, Nginx e dotnet 8: Configurando um proxy reverso com facilidade

Wanderson Alves Rodrigues — Wed, 14 Feb 2024 03:08:08 +0000

Você está pronto para levar suas aplicações .NET para o próximo nível? Nesta postagem, vamos explorar como configurar um proxy reverso usando Docker, Nginx e o .NET 8. Essa configuração poderosa não apenas otimiza o desempenho de suas aplicações, mas também oferece maior segurança e escalabilidade.
Antes de começar vamos entender o que é um proxy reverso, você sabe o que é um proxy?
Um proxy é um intermediário entre o usuário e o destino final na comunicação pela internet. Ele atua como um servidor que recebe solicitações de um cliente e as encaminha para o destino pretendido.

Existem vários tipos de proxies, cada um com suas próprias funcionalidades e finalidades:

Proxy de Encaminhamento (Forward Proxy): Neste tipo de proxy, o cliente envia suas solicitações para o proxy, que por sua vez as encaminha para o destino. É comumente usado para contornar restrições de rede ou acessar conteúdo bloqueado.
Proxy Reverso (Reverse Proxy): Ao contrário do forward proxy, o reverse proxy recebe solicitações de clientes em nome de um ou mais servidores de destino. Ele pode ser usado para equilibrar a carga entre servidores, ocultar a infraestrutura de servidores de destino ou fornecer cache e segurança adicional.
Proxy Transparente: Este tipo de proxy não requer configuração no cliente. Ele intercepta todas as solicitações de rede sem que o cliente tenha conhecimento disso. Geralmente usado em firewalls para aplicar políticas de segurança.
Proxy de Nível de Aplicativo: Este tipo de proxy opera no nível de aplicativo e é específico para um protocolo, como HTTP ou FTP. Ele pode modificar os dados transmitidos entre o cliente e o servidor de destino.

Os proxies desempenham um papel crucial na otimização de rede, segurança e gerenciamento de tráfego na internet. Eles são amplamente utilizados em ambientes corporativos, provedores de serviços de internet e aplicativos que exigem alto desempenho e segurança.

Proxy Reverso

Um Proxy Reverso é um tipo de servidor proxy que opera na frente de um ou mais servidores de destino. Ele recebe solicitações de clientes em nome desses servidores e, em seguida, encaminha essas solicitações para o servidor apropriado. O servidor de destino, por sua vez, envia a resposta de volta ao proxy reverso, que a encaminha de volta ao cliente.

Aqui está um exemplo para ilustrar o funcionamento de um proxy reverso:

Imagine que você tenha três servidores web em execução: Servidor A, Servidor B e Servidor C. Cada servidor executa uma parte diferente do seu site ou aplicação. O Proxy Reverso está configurado para lidar com todas as solicitações dos clientes.

1 - Um cliente faz uma solicitação para acessar o seu site.
2 - A solicitação do cliente chega ao Proxy Reverso.
3 - O Proxy Reverso, baseando-se em regras de roteamento definidas, encaminha a solicitação para o servidor apropriado. Por exemplo, se a solicitação for para uma página específica do seu site que está sendo servida pelo Servidor B, o Proxy Reverso encaminhará a solicitação para o Servidor B.
4 - O Servidor B processa a solicitação e envia a resposta de volta ao Proxy Reverso.
5 - O Proxy Reverso recebe a resposta do Servidor B e a envia de volta ao cliente.
Este é um cenário básico, mas as configurações do Proxy Reverso podem ser muito mais complexas. Ele pode ser configurado para balanceamento de carga entre os servidores, cache de conteúdo estático, SSL e filtragem de conteúdo, entre outras funcionalidades.

Em resumo, o Proxy Reverso atua como um intermediário entre os clientes e os servidores de destino, ajudando a melhorar o desempenho, a segurança e a confiabilidade de um sistema distribuído na web.

Minimal API

Para o exemplo, vamos usar uma simples API padrão do .NET. Como o mais importante será a configuração do Nginx e a criação do docker-compose, vou adotar a API criada por padrão.

Para criar uma API, execute o comando:

dotnet new webapi -n WeatherForecastApi

Após a execução do comando, será gerado o projeto WebAPI. No arquivo Program.cs, haverá um código inicial semelhante ao seguinte:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Entre no diretório do projeto e no terminal rode os comandos:

dotnet build

dotnet run

Se tudo estiver certo e nada errado, ao acessar a url http://localhost:5037/swagger/index.html será redirecionado para o swagger. Obs.: No meu caso a aplicação subiu na porta 5037, verifique o seu e mude caso necessário.

Dockerfile

Vamos criar a image da API que acabamos de desenvolver. Para isso, crie um arquivo Dockerfile no projeto com o seguinte conteúdo:

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build-env
WORKDIR /App

# Copy everything
COPY . ./
# Restore as distinct layers
RUN dotnet restore
# Build and publish a release
RUN dotnet publish -c Release -o out

# Build runtime image
FROM mcr.microsoft.com/dotnet/aspnet:8.0
RUN apt-get update && apt-get install -y wget
WORKDIR /App
COPY --from=build-env /App/out .
ENTRYPOINT ["dotnet", "WeatherForecastApi.dll"]

Vamos testar a criação da nossa image e do container. Para criar a imagem, execute o seguinte comando:

docker build -t wandersonalves/weather-forecast-api .

Para criar o container, execute:

docker run --rm -it -p 8080:8080 --name api wandersonalves/weather-forecast-api

Se estiver correto vamos conseguir acessar o Swagger via http://localhost:8080/swagger/index.html

Configurar Nginx

Para podemos fazer que o Nginx seja proxy reverso da nossa API, vamos ter que criar o arquivo nginx.conf. A configuração para esse exemplo será bem simples, porém podemos ter configurações mais complexa.

events {}

http {
    server {
        listen 80;

        location / {
            proxy_pass http://api:8080;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}

O trecho de código no qual realizamos o redirecionamento ao acessar o Nginx é a linha proxy_pass http://api:8080;. É nesta linha que seremos redirecionados para a nossa API, que está rodando na porta 8080. Uma observação bastante importante é a forma como acessamos nossa API, não é via IP direto e sim pelo nome. Quem fica responsável pela resolução de nome para IP é o Docker. Para isso, o Nginx e a API precisam estar na mesma rede.

Docker-compose

Agora vamos juntar tudo que fizemos até agora para podemos acessar nossa API através do proxy reverso Nginx. Nosso arquivo vai ficar igual o trecho abaixo:

version: "3"

services:
  nginx:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    networks:
      - mynet
    depends_on:
      api:
        condition: service_healthy

  api:
    build:
      context: .
    container_name: api
    tty: true
    ports:
      - "8080:8080"
    networks:
      - mynet
    healthcheck:
      test: wget --no-verbose --tries=1 --spider http://localhost:8080/healthz || exit 1
      interval: 30s
      retries: 5
      start_period: 20s
      timeout: 10s

networks:
  mynet:
    driver: bridge

O devemos saber:

Nossa rede é do tipo bridge e o nome dela será mynet, e a API e Nginx estão na mesma rede;
Como estão na mesma rede podemos usar o nome ao invés do IP, quem fica responsável pela resolução de nome para IP é o docker;
Para evitar que o container Nginx suba antes da nossa API, implementamos um healthcheck. Além disso, o Nginx tem uma dependência da nossa API usando depends_on. Para saber se nossa API subiu sem nenhum problema vamos criar uma chamada de API Health Checks, para isso adicione as linhas no arquivo Program.cs:

builder.Services.AddHealthChecks();
app.MapHealthChecks("/healthz");

Agora vamos subir nossa infra e ver se nosso proxy reverso vai funcionar, para isso execute o comando:

docker-compose up -d --build

Após subir os dois container, poderemos acessar nossa API na porta 80 do Nginx http://localhost/swagger/index.html

Nossos dois contêineres, a API e o Nginx, estão em execução, e o Nginx está atuando como um servidor de proxy reverso para a API.

Conclusão

A combinação de Docker, Nginx e o .NET 8 oferece uma solução poderosa para otimizar o desempenho, a segurança e a escalabilidade de suas aplicações. Configurando um proxy reverso, podemos direcionar o tráfego de entrada de maneira eficiente para nossas aplicações .NET, garantindo uma experiência de usuário confiável e responsiva.

Ao seguir os passos delineados nesta postagem, você aprendeu como preparar seu ambiente, criar uma aplicação .NET, configurar o Dockerfile e o Nginx como um proxy reverso, e executar o ambiente usando o Docker Compose. Essa abordagem simplifica o processo de implantação e gerenciamento de suas aplicações, permitindo que você se concentre no desenvolvimento de recursos essenciais.

Sinta-se à vontade para explorar e personalizar ainda mais essa configuração de acordo com suas necessidades específicas. E lembre-se, se surgirem dúvidas ou questões adicionais, estou aqui para ajudar!

O código completo pode ser acessado: Github

Referências

Create a minimal API with ASP.NET Core

Criando um proxy de encaminhamento usando o roteamento de solicitação de aplicativo

Health checks in ASP.NET Core

Host ASP.NET Core no Linux com Nginx

Compreendendo a notação Big O: Medindo a eficiência dos algoritmos

Wanderson Alves Rodrigues — Sat, 01 Jul 2023 14:02:57 +0000

Hoje, vamos falar sobre um conceito fundamental em ciência da computação e análise de algoritmos: a notação Big O. Se você já teve contato com programação ou estudos relacionados, provavelmente já ouviu falar sobre esse termo. Mas o que exatamente ele significa e por que é tão importante? Vamos descobrir juntos!

A notação Big O é uma forma de descrever a complexidade de um algoritmo, ou seja, a medida de quanta memória ou tempo computacional ele requer à medida que o tamanho da entrada aumenta. É uma ferramenta essencial para analisar e comparar algoritmos, permitindo-nos escolher a melhor solução para um determinado problema.

"A notação Big O é uma notação matemática que descreve o comportamento limitante de uma função quando o argumento tende a um valor específico ou ao infinito. Ela pertence a uma família de notações inventadas por Paul Bachmann, Edmund Landau e outros, coletivamente chamadas de notação Bachmann–Landau ou de notação assintótica." — Definição da Wikipédia de notação Big O

Ao utilizar a notação Big O, expressamos a eficiência de um algoritmo em termos de seu crescimento assintótico. Em outras palavras, estamos interessados no comportamento do algoritmo quando a quantidade de dados aumenta consideravelmente. A notação Big O nos permite identificar o crescimento mais significativo em relação ao tamanho da entrada e descrevê-lo de forma simplificada.

Você pode perguntar: mas quem liga para isso?. Bem, acontece que você frequentemente utilizará o algoritmo feitos por outras pessoas, e quando faz isso, é bom entender o quão rápido ou lento o algoritmo é.

Para exemplificar o que é a notação Big O, vamos dar uma olhada em um caso típico, O(n²), que geralmente é chamada também de "Big O quadrática". A letra n representa o tamanho da entrada, enquanto a função "g(n) = n²" interna ao "O()" nos dá a ideia da complexidade do algoritmo em relação ao tamanho da entrada.

Outro exemplo é da pesquisa binária, que precisa de log n operações para verificar uma lista de tamanho n. A complexidade desse algoritmo é da ordem de O(log2 n), em que n é o tamanho do vetor de busca.

Vamos examinar alguns exemplos comuns de notações Big O:

O(1): Tempo de execução constante: Independentemente do tamanho da entrada, o algoritmo sempre leva o mesmo tempo para ser executado. É o cenário ideal, onde a eficiência não é afetada pelo aumento dos dados.
O(log n): Tempo de execução logarítmico: O tempo de execução aumenta de forma logarítmica à medida que o tamanho da entrada aumenta. Algoritmos com essa complexidade são geralmente muito eficientes, como é o caso de árvores balanceadas e algoritmos de busca binária.
O(n): Tempo de execução linear: O tempo de execução cresce proporcionalmente ao tamanho da entrada. Algoritmos lineares percorrem cada elemento da entrada uma vez. Exemplos incluem busca linear e algumas formas de ordenação.
O(n * log n): Exemplo: um algoritmo rápido de ordenação, como a ordenação quicksort.
O(n^2): Tempo de execução quadrático: O tempo de execução é o quadrado do tamanho da entrada. Algoritmos com essa complexidade são menos eficientes e podem levar muito tempo para processar grandes conjuntos de dados. Exemplos comuns são algoritmos de ordenação como o Bubble Sort e o Insertion Sort.
O(n!): Exemplo: um algoritmo bastante lento, como o do caixeiro-viajante.

Esses são apenas alguns exemplos das muitas possibilidades da notação Big O. Existem notações mais complexas, como O(n log n) e O(2^n), que descrevem algoritmos com diferentes níveis de eficiência. É importante lembrar que a notação Big O descreve o pior caso possível de um algoritmo e nos dá uma visão geral de sua eficiência relativa.

Ao analisar algoritmos e escolher a melhor abordagem para um problema, é fundamental considerar a complexidade temporal e espacial. Um algoritmo com complexidade O(n) pode ser mais eficiente do que um algoritmo com complexidade O(log n), dependendo do contexto e dos requisitos do problema.

Algoritmos e suas respectivas notações Big O:

1 - Busca linear: Este algoritmo percorre todos os elementos de uma lista até encontrar o elemento desejado ou chegar ao final da lista.

Tempo de execução: O(n)
Descrição: O tempo de execução aumenta linearmente com o tamanho da entrada, pois cada elemento precisa ser verificado.

2 - Busca binária: Este algoritmo é aplicável apenas a listas ordenadas. Ele divide repetidamente a lista ao meio e verifica se o elemento desejado está na metade esquerda ou direita.

Tempo de execução: O(log n)
Descrição: O tempo de execução cresce logaritmicamente com o tamanho da entrada, pois a lista é dividida pela metade a cada iteração.

3 - Ordenação por Bubble Sort: Neste algoritmo de ordenação, os elementos são comparados em pares e trocados se estiverem fora de ordem. O processo se repete até que a lista esteja ordenada.

Tempo de execução: O(n^2)
Descrição: O tempo de execução é quadrático em relação ao tamanho da entrada, pois são necessárias iterações múltiplas e cada elemento pode precisar ser comparado com todos os outros.

4 - Ordenação por Merge Sort: Este é um algoritmo de ordenação baseado em dividir para conquistar. A lista é dividida em sublistas menores, ordenadas separadamente e, em seguida, mescladas para obter a lista final ordenada.

Tempo de execução: O(n log n)
Descrição: O tempo de execução cresce em uma taxa logarítmica com o tamanho da entrada para dividir as sublistas e, em seguida, linearmente com o tamanho da entrada para mesclá-las.

5 - Cálculo da soma de uma lista de números: Este algoritmo simples percorre uma lista de números e calcula a soma total.

Tempo de execução: O(n)
Descrição: O tempo de execução é linear em relação ao tamanho da entrada, pois cada elemento da lista precisa ser visitado uma vez.

6 - Busca em uma tabela de dispersão (hash table): Ao procurar um elemento em uma tabela de dispersão, a função hash é aplicada para determinar sua posição na tabela.

Tempo de execução médio (em caso ideal): O(1)
Descrição: O tempo de execução é constante, independentemente do tamanho da entrada, desde que não ocorram muitas colisões.

Problema do caixeiro viajante

O problema do caixeiro viajante é um desafio clássico de otimização combinatória, em que o objetivo é encontrar o menor caminho possível que passe por todas as cidades (ou pontos) visitando cada uma delas exatamente uma vez e retornando à cidade de origem.

A complexidade do problema do caixeiro viajante depende da abordagem utilizada para resolver o problema. Existem diferentes algoritmos para isso, e vou apresentar dois exemplos com suas respectivas notações Big O:

1 - Força bruta (Brute Force):

Tempo de execução: O(n!)
Descrição: O tempo de execução cresce fatorialmente com o número de cidades. Esse algoritmo testa todas as permutações possíveis das cidades para encontrar o caminho mais curto.

2 - Algoritmo heurístico (Algoritmo do vizinho mais próximo):

Tempo de execução: O(n^2)
Descrição: Neste algoritmo, cada cidade é visitada a partir da cidade atual escolhendo a cidade vizinha mais próxima que ainda não foi visitada. O tempo de execução é quadrático em relação ao número de cidades, pois em cada iteração é necessário encontrar a cidade mais próxima.

A Big O estabelece o pior caso para o tempo de execução

Vamos imaginar que você queira encontrar um nome em um lista ordenada e para isso vamos usar uma busca simples para percorrer. Um busca simples tem uma complexidade de O(n) vezes para ser executada, isso quer dizer que, no pior caso, terá que examinar cada registro até um determinado nome. Vamos supor que temos que buscar o nome Adriano se ele for o primeiro da lista então levará O(1) agora se o nome for o _Zairro _sendo o ultimo da lista temos O(n) sendo o pior caso.

Neste caso, O(1) é o melhor cenário, teve a sorte de achar Adriano no começo da lista. Mas a notação Big O leva em conta o pior dos casos, que é O(n) então a complexidade do algoritmo de busca simples é de O(n). É uma reafirmação de que a busca simples nunca será mais lenta que O(n).

Conclusão

Em resumo, a notação Big O é uma ferramenta poderosa para medir a eficiência dos algoritmos, permitindo-nos comparar e selecionar a melhor solução para um determinado problema. Compreender e utilizar corretamente a notação Big O é essencial para os desenvolvedores de software, pois nos ajuda a escrever algoritmos eficientes e otimizados.

Espero que esta postagem tenha sido útil para vocês! Se tiverem mais dúvidas sobre a notação Big O ou qualquer outro tópico relacionado à ciência da computação, fiquem à vontade para perguntar.

Fontes:

Grande-O - wikipedia
Notação Big-O
Quantum Computing in Complexity Theory and Theory of Computation
Know Thy Complexities!
Definição da notação "Big O"
Pesquisa binária
A Busca Binária
Busca Linear
Problema do Caixeiro Viajante
Problema do caixeiro-viajante - wikipedia

Entendendo a injeção de dependência: Uma abordagem para um código mais flexível e testável

Wanderson Alves Rodrigues — Sat, 27 May 2023 16:04:55 +0000

Hoje vamos falar sobre um conceito importante na programação: a injeção de dependência. Se você é um desenvolvedor ou está aprendendo a programar, certamente já ouviu falar sobre esse termo. Mas você sabe o que é e por que é tão importante? Vamos explorar um pouco mais esse assunto.

A injeção de dependência é um padrão de projeto utilizado para diminuir o acoplamento entre as classes de um sistema. Em outras palavras, é uma forma de estruturar o código para que as classes dependam de abstrações, em vez de dependerem diretamente de outras classes concretas.

Mas o que isso significa na prática? Vamos supor que você esteja desenvolvendo um aplicativo que precisa se conectar a um banco de dados. Em vez de criar uma classe que faça a conexão diretamente, você cria uma interface que define os métodos que essa classe deve ter, como "conectar", "desconectar" e "executar consulta".

Em seguida, você implementa uma classe concreta que implementa essa interface e realiza a conexão com um banco de dados específico, como o MySQL. Agora, ao invés de outras classes do seu sistema dependerem diretamente da classe de conexão com o MySQL, elas dependem da interface genérica que você definiu.

E é aí que a injeção de dependência entra em ação. Em vez de instanciar diretamente a classe de conexão dentro das classes dependentes, você assegura que essa dependência seja "injetada" por meio de construtores, métodos ou até mesmo configurações externas.

Isso traz uma série de benefícios para o seu código. Primeiramente, torna o sistema mais flexível, pois você pode facilmente substituir a implementação da interface por outra que se conecte a um banco de dados diferente, como o PostgreSQL, sem precisar alterar as classes dependentes. Basta trocar a implementação da interface no momento da injeção.

Além disso, a injeção de dependência facilita muito os testes automatizados. Você pode criar implementações "falsas" ou "mocks" da interface para simular o comportamento do banco de dados durante os testes, o que ajuda a isolar e testar partes específicas do seu sistema de forma mais eficiente.

Outro ponto importante é que a injeção de dependência promove uma melhor organização e modularidade do código, tornando-o mais fácil de entender, dar manutenção e estender no futuro.

Existem várias formas de implementar a injeção de dependência em diferentes linguagens de programação, seja manualmente ou utilizando frameworks dedicados. Algumas linguagens, como o Java, possuem frameworks como o Spring, que facilitam a configuração e gerenciamento das dependências.

Injeção de Dependência com Interface (C#)

Em linguagens como C#, é comum utilizar interfaces para definir contratos e aplicar injeção de dependência. Vejamos um exemplo:

public interface IEmailSender {
    void SendEmail(string recipient, string message);
}

public class EmailSender : IEmailSender {
    public void SendEmail(string recipient, string message) {
        // Lógica para enviar o e-mail
    }
}

public class NotificationService {
    private IEmailSender emailSender;

    public NotificationService(IEmailSender emailSender) {
        this.emailSender = emailSender;
    }

    public void SendNotification(string recipient, string message) {
        // Lógica para enviar notificação
        emailSender.SendEmail(recipient, message);
    }
}

No contexto do desenvolvimento .NET, a injeção de dependência pode ser gerenciada através de um contêiner de injeção de dependência, como o padrão Dependency Injection (DI) do ASP.NET Core. Ao usar um contêiner de DI, você tem controle sobre o ciclo de vida das dependências injetadas. O ciclo de vida refere-se ao tempo de vida das instâncias das dependências e como elas são gerenciadas pelo contêiner. Existem três principais ciclos de vida comumente usados em aplicações .NET: Transient, Scoped e Singleton.

a. Transient:

Uma nova instância é criada a cada solicitação.
É ideal para objetos leves, sem estado e de curta duração.
Uma nova instância será fornecida a cada injeção.
O contêiner não rastreia nem reutiliza instâncias anteriores.
Pode haver múltiplas instâncias para diferentes partes do aplicativo.

b. Scoped:

Uma instância é criada e usada dentro de um escopo específico.
Geralmente, o escopo está relacionado a uma solicitação HTTP em aplicativos da web.
A mesma instância é retornada para todas as classes dentro do mesmo escopo.
Uma nova instância é criada para um novo escopo.
Útil para compartilhar a mesma instância dentro do escopo de uma solicitação.

c. Singleton:

Uma única instância é criada e compartilhada durante toda a vida do aplicativo.
É adequado para objetos pesados, carregamento demorado ou que precisam ser compartilhados globalmente.
A mesma instância é retornada para todas as classes em todas as solicitações.
A instância é criada na primeira solicitação e usada em todas as solicitações subsequentes.
Útil para dados imutáveis e serviços globais.

O ciclo de vida adequado a ser utilizado depende das necessidades do seu aplicativo e das características da dependência em questão. É importante escolher o ciclo de vida apropriado para garantir que as instâncias sejam gerenciadas corretamente, evitando problemas como vazamento de recursos ou compartilhamento inadequado de estado.

Ao configurar a injeção de dependência no ASP.NET Core, você pode especificar o ciclo de vida das dependências usando métodos como AddTransient, AddScoped e AddSingleton no contêiner de DI. A escolha do ciclo de vida certo contribui para a eficiência, escalabilidade e correta utilização dos recursos no seu aplicativo .NET.

Em resumo, a injeção de dependência é uma técnica poderosa para melhorar a qualidade do código, tornando-o mais flexível, testável e organizado. Ela ajuda a reduzir o acoplamento entre as classes e permite que você substitua facilmente as implementações das dependências, trazendo uma série de benefícios tanto para o desenvolvimento quanto para a manutenção do seu sistema.

Espero que essa explicação tenha sido útil!

Fontes:
Inversion of Control Containers and the Dependency Injection pattern

Dependency Injection

O que é injeção de dependência?

Injeção de dependência