Pipeline CrewAI para Leads 🚀

Este repositório contém a automação de ponta a ponta desenvolvida em Python com o ecossistema CrewAI, projetada para ler dados brutos de leads a partir de uma planilha do Google Sheets, acionar agentes inteligentes para realizar auditorias estruturadas de mercado/SEO e devolver as informações consolidadas.

Esta documentação serve como o marco regulatório e arquitetural da Versão 1.0 (Agente Reativo) antes da migração planejada para a Versão 2.0 (Buscador Proativo por Cidade, Bairro e Ramo de Atuação).

📌 1. Visão Geral do Sistema e Decisões Positivas

O ecossistema foi estruturado sob o conceito de Agentes de IA (Role-Based Autonomous Agents). Durante as interações de desenvolvimento, formulei uma arquitetura orientada e revisada com o GEMINI para estabilizar a aplicação e filtrar os dados brutos:

• Abstração do LLM (Gemini 1.5 Flash): Substituição de chamadas diretas de API puras por uma camada gerenciada via langchain-google-genai. resolevndo os erros de mapeamento de endpoints (404 NOT_FOUND em chamadas v1beta).
• Mecanismo de Retentativa e Tolerância a Falhas: Configuração de tratamento de exceções no fluxo do CrewAI. Se um lead falha por instabilidade na extração da URL, o pipeline registra o erro em log, respeita a pausa de segurança e avança de forma resiliente para o próximo item, evitando o travamento completo do script.
• Pausa de Segurança Contra Rate-Limiting: Implementação de um delay estrito de segurança (time.sleep(5)) entre as iterações dos leads, mitigando bloqueios por excesso de requisições por segundo (QPS) na cota do Google Gemini API Tiers.
• Controle de Estado da Planilha: O script executa uma varredura inicial lógica. Se nenhum lead novo estiver marcado como pendente, ele encerra de forma limpa, protegendo a planilha contra sobrescritas acidentais ("Sua planilha está atualizada!").

📊 2. Mapeamento de Células e Campos (Google Sheets)

A integração com o Google Sheets atua como a interface de entrada (Input) e persistência de dados (Output). O mapeamento lógico estruturado na planilha segue o modelo abaixo:

| Nome do Campo | Tipo de Dado | Origem/Destino | Descrição / Exemplo | | :--- | :--- | :--- | :--- | | Corporate Entity | Texto (String) | Input (Planilha) | Nome fantasia da empresa alvo (Ex: Follow Me Idiomas SBC). | | District/Neighborhood| Texto (String) | Input (Planilha) | Bairro de localização para delimitação geo-comercial (Ex: Assunção, Baeta Neves). | | Site URL | URL (String) | Input (Planilha) | Endereço web oficial para análise e extração (Ex: https://...). | | Phone | Texto (String) | Input (Planilha) | Telefone de contato formatado com código de país (Ex: +55 11 98975-0302). | | Status Processamento| Enum / Flag | Input/Output | Controla o fluxo (Pendente, Em Processamento, Concluído, Erro). | | Lead Profile (SEO) | Markdown/Texto | Output (Planilha) | Campo preenchido pelo agente contendo o relatório estruturado final. |

🤖 3. Arquitetura de Agentes e Tarefas

O ecossistema CrewAI foi configurado com um agente especialista altamente focado, garantindo que o prompt do sistema não sofra com dispersão de contexto.

Agente: Expert Market Miner

• Papel (Role): Especialista em Mineração de Mercado e Auditoria de Presença Digital.
• Objetivo (Goal): Formatar e estruturar campos de dados de entidades corporativas recebidos como entrada bruta e gerar perfis otimizados de inteligência de mercado para o auditor de SEO.
• Características: Alta precisão de extração, análise e foco em dados B2B reais.

Tarefa Associada: Format & Profile Lead

• Descrição: Ler os campos brutos recebidos da planilha (Empresa, Estado,Bairro, Site URL, Telefone), acessar/analisar a estrutura digital da URL fornecida e construir um perfil consolidado.
• Output Esperado: Um documento estruturado detalhando a qualidade do site, validação dos canais de contato e pontos imediatos de atenção em SEO técnico local para apoiar a abordagem de vendas.

🔌 4. APIs e Ferramentas Utilizadas

A stack tecnológica atual utiliza três pilares principais de integração:

1. Google Gemini API (gemini-1.5-flash):
   • Uso: Orquestração cognitiva dos agentes, inferência, análise do contexto das páginas web e estruturação do output textual em Markdown.
   • Endpoint/SDK: Utilizado através de ChatGoogleGenerativeAI dentro de langchain_google-genai.
2. Google Sheets API & Drive API:
   • Uso: Conexão via conta de serviço (service_account) para leitura dinâmica das linhas e escrita das atualizações em tempo real no final de cada execução de agente.
3. CrewAI Framework:
   • Uso: Engine de gerenciamento do ciclo de vida dos agentes, injeção de variáveis de tarefas em lote (batch processing) e controle de telemetria nativo.

🚀 5. Próximo Passo: Roadmap para a Versão 2.0 (O Buscador Ativo)

O objetivo da próxima iteração do projeto é transformar este fluxo de Reativo (onde você precisa preencher os leads previamente) para Proativo (onde o sistema descobre os leads).

[Parâmetros de Entrada] 
  (Cidade, Bairro, Ramo)
        │
        ▼
[Agente Pesquisador] ──► Utiliza SerpApi / Google Maps API ──► Coleta Leads Automaticamente
                                                                        │
                                                                        ▼
                                                       [Planilha Google Sheets] (Popula linhas)
                                                                        │
                                                                        ▼
                                                       [Agente Expert Market Miner] (Executa Auditoria)

Alterações de Infraestrutura Necessárias:

• Nova API de Prospecção: Integração de SerperDevTool do CrewAI ou chaves da SerpApi / Google Places API.
• Novo Agente (Lead Discovery Specialist): Focado puramente em gerar buscas sintáticas inteligentes (ex: "escolas de inglês em são bernardo do campo bairro assunção") e extrair os metadados brutos (Maps, reviews, sites) para povoar a planilha de forma autônoma antes da auditoria de SEO.