Pular para o conteúdo principal
JC
PT | EN
← Voltar aos projetos HEROw Marketing Agent

HEROw Marketing Agent

Python LangChain/LangGraph

Visão Geral

O HEROw Marketing Agent nasceu de uma dor direta de operação: gerar conteúdo de marketing para várias plataformas e vários clientes consumia facilmente dezenas de horas por semana só em configuração manual. Cada projeto exigia tom de voz próprio, regras por plataforma e agentes especializados diferentes - algo que ferramentas no-code genéricas não cobriam com precisão suficiente.

Para resolver isso, construí uma CLI em Python que orquestra múltiplos agentes LLM especializados usando LangGraph. Toda a configuração de projetos, agentes e plataformas é feita via arquivos Markdown com YAML frontmatter, versionados em git. A ferramenta lê esse “cérebro” em Markdown, decide quais agentes devem atuar, executa tools em paralelo e devolve conteúdo pronto por plataforma em uma única sessão de CLI.

Foi um projeto solo: desenhei a arquitetura, implementei o orchestrator em LangGraph, criei a abstração de providers (Anthropic, Gemini, OpenAI), integrei ferramentas externas (web search, MCP) e modelei a experiência de linha de comando com questionary e Rich. O resultado foi uma redução consistente de ~20 horas/semana no esforço de criação de conteúdo interno da HEROw, atendendo múltiplos projetos e até 9 plataformas distintas sem reconfiguração manual.

Diferencial Principal

O diferencial do HEROw Marketing Agent não é “mais uma automação de conteúdo”, mas a combinação de três decisões de engenharia:

  1. Providers totalmente abstraídos por Protocol: o orchestrator nunca fala diretamente com o SDK de Anthropic, Gemini ou OpenAI. Toda resposta passa por um LLMProvider único e uma função coerce_content_blocks() que normaliza blocos de conteúdo e tool calls para um formato interno estável. Isso permite trocar ou adicionar providers sem tocar na lógica de orquestração.
  2. Configuração como Markdown + YAML: em vez de painéis no-code, cada projeto e sub-agente é um arquivo .md com frontmatter YAML (contexto, tom de voz, especialidades). Ajustar comportamento passa a ser editar texto versionado em git, não cliques em UI. Essa escolha torna o sistema mais rastreável, auditável e fácil de manter em times de engenharia.
  3. LangGraph para loops de ferramenta: no lugar de um loop manual com while e variáveis espalhadas, toda a execução é um StateGraph tipado, com nós específicos (call_model, execute_tools, ask_user_interactive) e edges condicionais. Ferramentas são executadas em paralelo com asyncio.gather, e o estado é um TypedDict imutável — fácil de testar, depurar e estender.

Arquitetura

  • CLI (questionary + Rich): interface interativa em terminal; seleção de projeto e plataformas com histórico de recência, spinner de progresso e exibição formatada do conteúdo gerado.
  • Orchestrator (LangGraph StateGraph): grafo de execução com nós call_model, execute_tools, ask_user_interactive e função condicional should_continue que decide entre encerrar, chamar tools ou perguntar ao usuário.
  • Roteador de agentes: módulo que calcula um score lexical entre briefing e descrições de agentes usando tokenização + stemming leve; seleciona candidatos e injeta “routing hints” no system prompt.
  • Prefetch paralelo de sub-agentes: camada assíncrona que executa sub-agentes preferenciais com asyncio.gather antes do primeiro passo do grafo, trazendo contexto pronto para o orchestrator.
  • Camada de Providers (****LLMProvider Protocol): implementação específica para Anthropic, Gemini e OpenAI, todas expondo create_message, get_model_capabilities, format_tools e integradas via coerce_content_blocks() para normalizar blocos {type, ...}.
  • Ferramentas (Tools Layer): wrappers para httpx + lxml (fetch de páginas), pesquisa DuckDuckGo via ddgs e suporte a MCP, todos integrados como tools LangGraph com execução paralela.
  • Config Engine (Markdown + python-frontmatter****): parser de arquivos .md de projeto e agentes, extraindo YAML frontmatter (metadados) e corpo (contexto de sistema) para compor prompts.
  • Testes e Qualidade: suíte de testes com Pytest cobrindo orchestrator, providers, sub-agents, CLI e tools; linting com Ruff e formatação com Black.

Destaques Técnicos

  • Abstraí três SDKs diferentes (Anthropic, Gemini, OpenAI) atrás de um Protocol único com função coerce_content_blocks(), eliminando condicionais por provider no orchestrator.
  • Reescrevi um loop manual de tool calls em um StateGraph do LangGraph com estado tipado e edges condicionais, permitindo tool use paralelo e interações com usuário sem acoplamento.
  • Modelei roteamento de agentes com scoring lexical leve (stemmer + pesos por campo) para pré-selecionar sub-agentes e reduzir latência, injetando “routing hints” no prompt.
  • Estruturei a configuração de projetos e agentes via Markdown + YAML frontmatter com parsing por python-frontmatter, permitindo controlar comportamento do sistema via git.
  • Criei uma CLI em Python 3.11 com questionary + Rich, incluindo seleção com recência, feedback visual e fluxo guiado em 5 etapas (projeto → plataformas → briefing → revisão → follow-up).
  • Integrei ferramentas HTTP, scraping básico e pesquisa DuckDuckGo (ddgs), além de drivers MCP, unificados como tools LangGraph com execução concorrente via asyncio.gather.
  • Alcancei economia operacional estimada em ~20 horas/semana na geração de conteúdo multi-plataforma dentro da HEROw, atendendo múltiplos projetos com contextos isolados.