Sistema Multiagente de IA para Suporte à Decisão em Marketing Digital

Este repositório contém o código-fonte e os artefatos do projeto de Trabalho de Conclusão de Curso (TCC) que propõe um sistema multiagente de Inteligência Artificial para auxiliar na tomada de decisões estratégicas em campanhas de Marketing Digital.

O sistema é composto por agentes especializados que orquestram a coleta de dados (SEO e anúncios), a análise estratégica e a geração de relatórios acionáveis, utilizando um modelo de LLM e uma base de conhecimento para fundamentar as recomendações.

1. Estrutura do Repositório

O projeto está organizado nas seguintes pastas e arquivos principais:

Pasta/Arquivo	Descrição
agente_*.py	Arquivos que contêm a lógica de cada agente especializado (Analista, Arquiteto, Coletor Meta, Estrategista, Intérprete, Tradutor).
orquestrador_principal.py	O agente central que coordena o fluxo de trabalho entre todos os agentes.
requirements.txt	Lista de dependências Python necessárias para o projeto.
.env	Arquivo de configuração essencial. Deve ser criado para armazenar a chave de API do serviço de LLM (OpenRouter).
Artigo/	Contém o artigo acadêmico completo do TCC.
Artigo/artigo.pdf	O documento final do TCC.
RAG/	Base de Conhecimento Bruta. Contém os documentos originais (PDFs, Markdown, etc.) que alimentam o sistema RAG (Retrieval-Augmented Generation).
storage/	Índice Vetorial Persistido. Diretório criado após a primeira execução do sistema, contendo os embeddings e o índice vetorial dos documentos da pasta RAG, otimizando consultas futuras.
Harmonie_exemplo/	Exemplo de execução para o caso de uso "Harmonie".
Prolaje_exemplo/	Exemplo de execução para o caso de uso "Prolaje".

1.1. Detalhes dos Exemplos

As pastas de exemplo (Harmonie_exemplo e Prolaje_exemplo) demonstram o resultado de uma execução completa do sistema.

Arquivo de Exemplo	Descrição
*_log.txt ou *_completo.txt	O resultado completo da execução do terminal, mostrando o fluxo de trabalho do orquestrador e as interações entre os agentes.
prompt.txt	O prompt de entrada fornecido pelo usuário ao sistema para iniciar a análise.
relatorio_final.md	O relatório final de análise e estratégia gerado pelo Agente Tradutor, em formato Markdown.
relatorio_final.pdf	O relatório final de análise e estratégia gerado pelo Agente Tradutor, em formato PDF.

2. Agentes e Componentes do Sistema

O sistema opera com uma arquitetura de agentes especializados, cada um com uma função clara no fluxo de trabalho:

Agente	Função Principal
Agente Intérprete	Analisa o prompt do usuário, extrai a URL e o termo de busca, e define as diretivas de análise.
Agente Arquiteto	Realiza a coleta de dados de SEO (Search Engine Optimization) da URL fornecida, utilizando o Playwright para simular a navegação de um usuário.
Agente Coletor Meta	Coleta dados de anúncios de plataformas como o Meta (Facebook/Instagram) com base no termo de busca.
Agente Estrategista	Gerencia a base de conhecimento (RAG). É responsável por construir e consultar o índice vetorial (storage/) a partir dos documentos brutos (RAG/).
Agente Analista	Recebe os dados brutos (SEO e Anúncios), identifica problemas e oportunidades, e formula perguntas estratégicas para o Agente Estrategista (RAG).
Agente Tradutor	É responsável por transformar os resultados técnicos e as recomendações do LLM em um relatório final formatado e legível para o usuário.
Orquestrador Principal	É o main do sistema. Coordena a sequência de execução dos agentes, gerencia a passagem de dados entre eles e consolida o resultado final.

3. Configuração e Instalação

Para executar o projeto, siga os passos abaixo. É fundamental configurar um ambiente virtual para isolar as dependências.

3.1. Pré-requisitos

Você precisará ter instalado em seu sistema:

1. Python 3.10+: O projeto é desenvolvido em Python.

2. Git: Para clonar o repositório do GitHub.

3.2. Clonando o Repositório

Abra o terminal (ou Prompt de Comando/PowerShell no Windows) e execute o comando git clone, substituindo [URL_DO_SEU_REPOSITORIO] pelo endereço real do seu projeto no GitHub:

git clone [https://github.com/DATA-UFMS/multi-agent-system/tree/main](https://github.com/DATA-UFMS/multi-agent-system/tree/main )

3.3. Configuração do Ambiente Virtual

O uso de um ambiente virtual garante que as bibliotecas instaladas para este projeto não interfiram em outros projetos Python em sua máquina.

3.3.1. Windows (PowerShell)

1. Criação do Ambiente Virtual:

   python -m venv .venv
   

2. Ativação do Ambiente Virtual:

   .\.venv\Scripts\Activate.ps1
   

   Nota: Se encontrar um erro de política de execução, pode ser necessário executar Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass antes da ativação.

3.3.2. Linux/macOS (Bash/Zsh)

1. Criação do Ambiente Virtual:

   python3 -m venv .venv

2. Ativação do Ambiente Virtual:

   source .venv/bin/activate

3.4. Instalação de Dependências

Com o ambiente virtual ativado, instale todas as bibliotecas listadas no arquivo requirements.txt:

pip install -r requirements.txt

Instalação do Playwright:

O Agente Arquiteto utiliza a biblioteca playwright para web scraping. Após a instalação via pip, é necessário instalar os browsers binários:

playwright install

3.5. Configuração das Variáveis de Ambiente

O sistema utiliza a chave de API do serviço de LLM (OpenRouter) para comunicação entre os agentes.

1. Crie um arquivo chamado .env na raiz do projeto.

2. Adicione sua chave de API no formato:

   OPENROUTER_API_KEY="CHAVE_DE_API_AQUI"
   

4. Execução do Sistema

O sistema é executado através do orquestrador_principal.py, que requer três argumentos obrigatórios:

1. --url: A URL do site a ser analisado (ex: https://exemplo.com ).

2. --termo: O termo de busca para a coleta de anúncios (ex: "treinamento em vendas").

3. --prompt: (Opcional) Um prompt do usuário com diretivas ou contexto adicional.

Exemplo de Execução:

python orquestrador_principal.py \
    --url "[https://www.prolaje.com.br](https://www.prolaje.com.br)" \
    --termo "lajes pré-moldadas" \
    --prompt "Querem um direcionamento do que melhorar no marketing digital para aumentar branding e conseguir mais clientes."

O resultado da execução será impresso no terminal e pode ser redirecionado para um arquivo de log, como feito nos exemplos:

python orquestrador_principal.py --url "..." --termo "..." --prompt "..." > insider_resultado.txt

5. Geração do Relatório Final (Agente Tradutor)

O Agente Tradutor é responsável por processar o arquivo de log gerado pelo Orquestrador Principal e transformá-lo em um relatório final formatado (Markdown ou PDF), aplicando correções de codificação e refinamento via LLM.

5.1. Execução do Agente Tradutor

O agente_tradutor.py recebe o nome do arquivo de log como argumento e uma flag opcional para o formato de saída.

Sintaxe:

python agente_tradutor.py [ARQUIVO_DE_LOG] [--md]

Regra de Formato:

• Se a flag --md for utilizada, o relatório será salvo em formato Markdown (.md).

• Caso contrário (sem a flag --md), o relatório será salvo em formato PDF (.pdf).

Exemplos:

1. Gerar Relatório em PDF (Padrão):

   python agente_tradutor.py insider_resultado.txt
   # Saída: relatorio_final.pdf

2. Gerar Relatório em Markdown:

   python agente_tradutor.py insider_resultado.txt --md
   # Saída: relatorio_final.md

6. Manutenção da Base de Conhecimento (RAG)

O sistema utiliza a técnica RAG para fornecer recomendações estratégicas fundamentadas.

• Adicionar Conhecimento: Para adicionar novos documentos à base de conhecimento, basta colocar os arquivos (PDF, DOCX, MD, TXT) na pasta RAG/.

• Reconstrução do Índice: Na próxima execução do orquestrador_principal.py, o Agente Estrategista detectará os novos arquivos e reconstruirá o índice vetorial na pasta Storage/. Se a pasta Storage/ já existir, ele tentará recarregar o índice existente para otimizar o tempo de inicialização. Para forçar uma reconstrução completa, basta deletar a pasta Storage/.

---