Marketeiro 📣

O Marketeiro é um sistema orquestrado de IA projetado para criar comerciais publicitários de alta qualidade de ponta a ponta. Ele implementa uma arquitetura baseada no protocolo A2A (Agent-to-Agent), onde um agente diretor coordena quatro agentes especialistas remotos e um especialista de garantia de qualidade para gerar roteiros, áudios (voz e música), imagens em HD/4K (Imagen 4) e vídeos cinematográficos (Veo 3.1) integrados fisicamente.

O pipeline é composto por 6 agentes cooperativos que trocam informações estruturadas de forma determinística:

graph TD
    User([Usuário]) --> Orchestrator[Diretor de Marketing <br/> marketing_director]
    Orchestrator --> R1[1. Roteirista <br/> redator_specialist]
    Orchestrator --> R2[2. Produtor de Áudio <br/> audio_producer]
    Orchestrator --> R3[3. Diretor CGI <br/> visual_director]
    Orchestrator --> R4[4. Editor de Vídeo <br/> video_compiler]
    Orchestrator --> R5[5. Validador QA <br/> qa_specialist]
    
    R1 -- Retorna CommercialScript <br/> SSML, Trilha, Imagem, Vídeo --> Orchestrator
    R2 -- Retorna WAV Mixado --> Orchestrator
    R3 -- Retorna Keyframes HD/4K --> Orchestrator
    R4 -- Retorna Comercial MP4 --> Orchestrator
    R5 -- Retorna Relatório de Validação --> Orchestrator

    %% Estilos Elegantes e Cores Vivas
    classDef userStyle fill:#ec4899,stroke:#db2777,stroke-width:2px,color:#fff,font-weight:bold;
    classDef orchestratorStyle fill:#8b5cf6,stroke:#6d28d9,stroke-width:2px,color:#fff,font-weight:bold;
    classDef specialistStyle fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff;
    classDef qaStyle fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff,font-weight:bold;

    class User userStyle;
    class Orchestrator orchestratorStyle;
    class R1,R2,R3,R4 specialistStyle;
    class R5 qaStyle;

1. Diretor de Marketing (marketing_director) (Orquestrador)

   • Engine: gemini-3.5-flash + BuiltInPlanner (Thinking Mode).
   • Papel: Briefa a campanha, cria o Guia de Estilo Estético Master (paleta de cores, câmera, iluminação) e orquestra a chamada sequencial dos especialistas.

2. Copywriter / Roteirista (redator_specialist)

   • Engine: gemini-3.5-flash + Structured Output (output_schema).
   • Papel: Gera o blueprint estruturado da campanha (CommercialScript) contendo:
     • O roteiro SSML completo consolidado e blocos individuais por cena.
     • Prompts acústicos detalhados para composição de trilha sonora sem voz.
     • Prompts visuais estáticos para a geração de imagens de produto.
     • Prompts de cinematografia e movimentos de câmera para geração de vídeo.

3. Sound Studio (audio_producer)

   • Engines: gemini-3.1-flash-tts-preview + lyria-3-pro-preview.
   • Papel: Recebe o roteiro e os prompts acústicos para:
     • Sintetizar vozes profissionais a partir de SSML (com controle de entonação).
     • Compor trilhas musicais instrumentais e efeitos sonoros (SFX) com o Lyria.
     • Mixar vozes e música aplicando ducking sidechain (música em -12dB) e normalização de volume (-14 LUFS para vertical 9:16 ou -23 LUFS para 16:9).

4. Diretor CGI (visual_director)

   • Engines: imagen-3.0-generate-002 (Imagen 4) + gemini-3.1-flash-image-preview.
   • Papel: Lida dinamicamente com a geração de keyframes estáticos:
     • Se houver imagens brutas de produto: realiza a fusão realista de plano de fundo (edit_product_background).
     • Se não houver imagens: gera cenários e mockups publicitários do zero (generate_marketing_image).
     • Suporta aspect ratios dinâmicos (16:9, 9:16, 1:1, 4:3) e qualidades (SD, HD, 4K).

5. Editor de Vídeo (video_compiler)

   • Engines: veo-3.1-generate-001 + FFmpeg físico.
   • Papel: Recebe as imagens em alta resolução e o áudio masterizado para:
     • Animar imagens estáticas em clipes dinâmicos de 6s com o Veo 3.1 respeitando o aspect ratio.
     • Concatenar os clipes (incluindo introdução intro.mp4).
     • Realiza medição dinâmica de tempo do canal de áudio com ffmpeg.probe.
     • Se a duração física somada dos clipes de vídeo for menor que o tempo de áudio, aplica o filtro nativo do FFmpeg tpad em modo clone para congelar o último frame mantendo a tela estática enquanto o áudio finaliza e esmaece suavemente.
     • Trunca e renderiza o arquivo final na duração exata do áudio.

6. Garantia de Qualidade (qa_specialist)

   • Engine: gemini-3.5-flash.
   • Papel: Roda após a compilação do vídeo. Valida se a entrega final atende às especificações do briefing original (paleta de cores, aspect ratio, presença do produto, duração do vídeo, tom de áudio). Fornece um relatório detalhado de conformidade técnico-criativa.

A jornada do usuário no Marketeiro foi projetada para ser fluida, transparente e altamente visual. Abaixo está a jornada ponta a ponta:

sequenceDiagram
    actor User as Usuário
    participant Director as Diretor (marketing_director)
    participant Copywriter as Roteirista (redator_specialist)
    participant Audio as Áudio (audio_producer)
    participant Visual as CGI (visual_director)
    participant Video as Vídeo (video_compiler)
    participant QA as Garantia de Qualidade (qa_specialist)

    User->>Director: 1. Envia Briefing (Produto, Estilo, Assets)
    activate Director
    Director->>Director: Define Paleta, Lentes, Tom da Campanha
    Director->>Copywriter: 2. Solicita Roteiro Estruturado (CommercialScript)
    activate Copywriter
    Copywriter-->>Director: Retorna cenas, SSML, Prompts acústicos/visuais
    deactivate Copywriter

    Note over Director, Audio: Processamento Paralelo de Mídia
    Director->>Audio: 3. Solicita Mixagem de Áudio (SSML + Trilha Lyria)
    activate Audio
    Audio-->>Director: Retorna Áudio Masterizado (WAV)
    deactivate Audio

    Director->>Visual: 4. Solicita Keyframes (Fusão com Produto ou Imagem Nova)
    activate Visual
    Visual-->>Director: Retorna Imagens Estáticas em HD
    deactivate Visual

    Director->>Video: 5. Solicita Vídeo Comercial (Imagens + Áudio Masterizado)
    activate Video
    Video->>Video: Gera animações Veo 3.1 por cena
    Video->>Video: Mede áudio com ffmpeg.probe
    Video->>Video: Aplica tpad (clone) se vídeo for curto
    Video-->>Director: Retorna MP4 Completo
    deactivate Video

    Director->>QA: 6. Solicita Auditoria de Conformidade (Briefing vs Entregáveis)
    activate QA
    QA-->>Director: Retorna Relatório de QA (Aprovado / Reprovado com correções)
    deactivate QA

    Director-->>User: 7. Apresenta o Comercial + Relatório de QA + Artefatos (MIME-types salvos)
    deactivate Director

1. Definição de Briefing Simplificada: O usuário preenche um formulário estruturado de briefing direto no chat da interface do ADK. Se possuir uma imagem física do produto (ex. no GCS), ele simplesmente envia a URI no prompt.
2. Visualização em Tempo Real (Interface Web do ADK):
   • A interface web reage dinamicamente graças ao armazenamento e registro de artefatos efetuados pelas ferramentas personalizadas dos agentes.
   • Todos os artefatos gerados intermediários (imagem de fundo gerada pelo Imagen, áudio mixado, música crua) e finais (vídeo compilado) são catalogados e renderizados na aba Artifacts com seus respectivos mime_types (ex: image/png, audio/mpeg, video/mp4), permitindo que o usuário escute o áudio e assista ao vídeo no navegador sem precisar baixá-los para testar.
3. Auditoria de Qualidade: O usuário recebe um feedback final transparente do agente de QA que elenca detalhadamente o nível de aderência ao briefing original, dando segurança de que a IA de fato respeitou todos os constraints criativos informados.

• Core Framework: Google ADK (Agent Development Kit) v2.2.0+.
• SDK: google-genai Python SDK (compatível com Vertex AI e Gemini API).
• Mídia: pydub (processamento de áudio) + ffmpeg-python (concatenação e render de vídeo).
• Dependency & Environment: Managed by Astral uv.

Certifique-se de possuir instalado:

• uv: curl -LsSf https://astral.sh/uv/install.sh | sh
• agents-cli: uv tool install google-agents-cli
• FFmpeg: Necessário para a renderização de mídia (brew install ffmpeg no macOS).

Instale as dependências e registre as ferramentas locais:

agents-cli install

Para validar a integridade sintática e de comunicação de todo o pipeline:

uv run pytest

Abra a interface interativa local para testar a comunicação A2A e as chamadas de agentes:

agents-cli playground

Para agilizar o processamento e obter o menor tempo de resposta (evitando rodadas adicionais de perguntas e respostas com o orquestrador), o briefing enviado na primeira interação do usuário deve preencher todas as 7 variáveis essenciais.

Você pode preencher e enviar o bloco a seguir diretamente no chat do orquestrador (marketing_director):

1. Produto/Campanha: [Nome do Produto e descrição detalhada/especificações técnicas]
2. Assets Iniciais: [SIM, gs://meu-bucket/imagens/produto.png] ou [NÃO - gerar do zero]
3. Guia de Estilo Estético (Aesthetic Style Guide):
   - Paleta de Cores: [Ex: Tons terrosos, dourado e preto]
   - Iluminação: [Ex: Luz dramática lateral, chiaroscuro]
   - Estilo de Câmera/Lente: [Ex: Macro, lentes anamórficas de cinema]
   - Texturas/Mood: [Ex: Rústico, premium, aconchegante]
4. Objetivo de Conversão: [Awareness, Venda Direta ou Retenção]
5. Formato e Target: [30 Segundos / 9:16 (Shorts/Reels)] ou [90 Segundos / 16:9 (YouTube/TV)]
6. Volume de Cenas (Clip Count): [Número de cenas desejado, ex: 8 cenas]
7. Domínio Visual: [Live-Action, Faceless / UGC POV, Animação 3D, Mockup publicitário]

Para acionamentos via API ou chamadas estruturadas:

{
  "produto_campanha": "Café Gourmet Rústico - Grãos selecionados da Mogiana Paulista, torra média, notas de chocolate.",
  "assets_iniciais": {
    "fornecido": true,
    "uris": ["gs://brand-bucket/coffee_roasting.png"]
  },
  "guia_estilo_estetico": {
    "paleta_cores": ["#3E2723", "#FFF8E1", "#FFD54F"],
    "iluminacao": "Luz solar natural da manhã filtrada, sombras suaves",
    "estilo_camera": "Lente macro com pouca profundidade de campo (bokeh acentuado)",
    "mood_textura": "Conforto matinal, rústico, orgânico e premium"
  },
  "objetivo_conversao": "Venda Direta",
  "formato_target": "30 Segundos / 9:16",
  "volume_cenas": 8,
  "dominio_visual": "Live-Action"
}

Na arquitetura de processo único (single process), todos os agentes especialistas e a lógica de orquestração rodam de forma unificada no mesmo container. O deploy da aplicação é realizado diretamente no Google Cloud Run e, em seguida, o agente A2A é publicado no Gemini Enterprise.

Para compilar a imagem via Dockerfile e fazer o deploy no Cloud Run, execute o comando:

agents-cli deploy --project <PROJECT_ID> --update-env-vars GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=false

Exemplo prático:

agents-cli deploy --project <PROJECT_ID> --update-env-vars GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=false

Isso publicará a imagem e retornará a URL de serviço do Cloud Run (ex: https://<SERVICE_NAME>-<RANDOM_CHARS>-uc.a.run.app).

Se sua organização possuir políticas restritivas de compartilhamento de domínio (Domain Restricted Sharing) que impeçam expor o Cloud Run publicamente para allUsers, conceda permissão de invocação (roles/run.invoker) diretamente para a Service Account padrão do Gemini Enterprise (Discovery Engine):

gcloud run services add-iam-policy-binding marketeiro \
  --member="serviceAccount:service-<PROJECT_NUMBER>@gcp-sa-discoveryengine.iam.gserviceaccount.com" \
  --role="roles/run.invoker" \
  --project=<PROJECT_ID> \
  --region=<REGION>

Exemplo:

gcloud run services add-iam-policy-binding marketeiro \
  --member="serviceAccount:service-<PROJECT_NUMBER>@gcp-sa-discoveryengine.iam.gserviceaccount.com" \
  --role="roles/run.invoker" \
  --project=<PROJECT_ID> \
  --region=us-central1

Com o app servindo no Cloud Run, registre-o como um agente A2A no Gemini Enterprise:

agents-cli publish gemini-enterprise \
  --deployment-target cloud_run \
  --registration-type a2a \
  --agent-card-url https://<SERVICE_URL>/a2a/app/.well-known/agent-card.json \
  --gemini-enterprise-app-id <ENTERPRISE_APP_ID_OR_NAME> \
  --project-id <PROJECT_ID> \
  --display-name "<DISPLAY_NAME>" \
  --description "<DESCRIPTION>"

Exemplo prático de publicação na instância:

agents-cli publish gemini-enterprise \
  --deployment-target cloud_run \
  --registration-type a2a \
  --agent-card-url https://<SERVICE_URL>/a2a/app/.well-known/agent-card.json \
  --gemini-enterprise-app-id projects/<PROJECT_NUMBER>/locations/global/collections/default_collection/engines/<ENTERPRISE_APP_ID> \
  --project-id <PROJECT_ID> \
  --display-name "Marketeiro\n GenMedia Studio" \
  --description "Assistente de Criação Publicitária\n\n 1) Planeja o conceito visual\n\n 2) Orchestra a produção comercial"