Laboratório: Agente de IA para Geração e Análise de Campanhas de Marketing com Claude Agent SDK, ElevenLabs e HeyGen

Roteiro para estudo em ambiente de laboratório ou de teste. Execute apenas em equipamentos, redes e contas que você tenha autorização para usar, com backup e homologação próprios. Comandos podem causar indisponibilidade ou perda de dados. Software e marcas citados pertencem aos seus titulares. Termos de Uso.

Duração estimada

120 min

Passos

12

Validações

5

Versões da documentação consultada

Python 3.10 ou superior · Claude Agent SDK (Python) a versão estável atual · Requests a versão estável atual

Topologia

O agente Python roda localmente e conecta-se à API Claude (Anthropic) para geração de texto, à API ElevenLabs para síntese de voz e à API HeyGen para criação de vídeo. O usuário interage via terminal. As APIs externas são acessadas via Internet, com endereços de exemplo na faixa 192.168.56.0/24 para a máquina local.

Usuário
   |
[Terminal local]
   |
[Agente Python]
  /   |    \
Claude  ElevenLabs  HeyGen
(API)    (API)       (API)

Equipamentos e software

Roteiro

1. Preparar ambiente Python

   Crie um ambiente virtual para isolar as dependências e evitar conflitos.

   python3 -m venv venv
   source venv/bin/activateCopiar

   O que você deve ver: Prompt do terminal indica ambiente virtual ativo.

2. Instalar dependências

   Instale Claude Agent SDK, requests e dependências necessárias.

   pip install claude-agent-sdk-python requestsCopiar

   O que você deve ver: Pacotes instalados sem erros.

3. Configurar variáveis de ambiente

   Defina as chaves de API das três plataformas em variáveis de ambiente para segurança.

   export ANTHROPIC_API_KEY='SUA_CHAVE_CLAUDE'
   export ELEVENLABS_API_KEY='SUA_CHAVE_ELEVENLABS'
   export HEYGEN_API_KEY='SUA_CHAVE_HEYGEN'Copiar

   O que você deve ver: Variáveis disponíveis na sessão atual.

4. Criar prompt de sistema versionado

   Implemente um arquivo de prompt de sistema para o agente, em português, com instruções claras e data de versão.

   echo 'Versão: 2024-06-10
   Você é um agente de marketing. Gere um texto de campanha para o produto X, converta para voz e crie um vídeo curto. Analise resultados simulados e proponha melhorias.' > prompt.txtCopiar

   O que você deve ver: Arquivo prompt.txt criado com o conteúdo especificado.

5. Definir ferramentas do agente

   Implemente funções Python para: gerar texto (Claude), sintetizar voz (ElevenLabs) e criar vídeo (HeyGen), cada uma com contrato claro (parâmetros e retorno).

   # Exemplo de função para Claude
   import os
   from claude_agent_sdk import Agent
   import requests
   
   def gerar_texto_campanha(prompt):
       agent = Agent(name='AgenteMarketing', instructions=prompt)
       resposta = agent.run_sync('Gere um texto de campanha para o produto X.')
       return resposta['output']
   
   # Função ElevenLabs
   def sintetizar_voz(texto):
       url = 'https://api.elevenlabs.io/v1/text-to-speech/EXEMPLO_VOICE_ID'
       headers = {'xi-api-key': os.environ['ELEVENLABS_API_KEY']}
       data = {'text': texto}
       r = requests.post(url, headers=headers, json=data)
       with open('campanha.mp3', 'wb') as f:
           f.write(r.content)
       return 'campanha.mp3'
   
   # Função HeyGen
   def criar_video(audio_path):
       url = 'https://api.heygen.com/v3/videos'
       headers = {'x-api-key': os.environ['HEYGEN_API_KEY']}
       data = {'type': 'avatar', 'avatar_id': 'EXEMPLO_AVATAR_ID', 'audio_url': 'EXEMPLO_URL_AUDIO'}
       r = requests.post(url, headers=headers, json=data)
       return r.json()['data']['video_id']Copiar

   O que você deve ver: Funções Python criadas e salvas em um arquivo, sem erros de sintaxe.

6. Implementar avaliação automática

   Implemente casos de teste com entrada e saída esperada para o texto gerado, voz e vídeo.

   # Exemplo de teste
   entrada = 'Campanha para lançamento de fibra óptica.'
   esperado = 'Conheça a nova fibra óptica da Upnetix...'
   resultado = gerar_texto_campanha(entrada)
   assert esperado.split()[0] in resultadoCopiar

   O que você deve ver: Testes executados sem falhas (AssertionError).

7. Adicionar guardrails de entrada/saída

   Implemente validações para garantir que o texto não contenha termos proibidos e que o áudio/vídeo sejam gerados.

   # Exemplo de guardrail
   PROIBIDOS = ['EXEMPLO_PROIBIDO']
   def validar_texto(texto):
       for termo in PROIBIDOS:
           if termo in texto:
               raise ValueError('Termo proibido detectado.')Copiar

   O que você deve ver: Função de validação impede uso de termos proibidos.

8. Registrar execuções (tracing)

   Implemente registro de cada execução em arquivo local, incluindo entradas, saídas e status.

   import json
   def registrar_execucao(entrada, saida, status):
       with open('execucoes.log', 'a') as f:
           f.write(json.dumps({'entrada': entrada, 'saida': saida, 'status': status}) + '\n')Copiar

   O que você deve ver: Arquivo execucoes.log criado e atualizado a cada execução.

9. Executar agente ponta a ponta

   Rode o script principal: leia prompt, gere texto, sintetize voz, crie vídeo e registre tudo.

   python agente_marketing.pyCopiar

   O que você deve ver: Texto de campanha exibido, arquivo campanha.mp3 salvo, ID do vídeo retornado.

10. Revisão humana para ação irreversível

    Inclua etapa manual para aprovar envio do vídeo antes de qualquer publicação ou uso externo.

    # Exemplo: input('Aprovar envio do vídeo? (s/n): ')Copiar

    O que você deve ver: Execução aguarda aprovação manual antes de prosseguir.

11. Simular análise de resultados

    Implemente função que recebe dados simulados de campanha e gera análise textual.

    def analisar_resultados(dados):
        if dados['cliques'] > 100:
            return 'Campanha com bom desempenho.'
        else:
            return 'Resultados abaixo do esperado.'Copiar

    O que você deve ver: Análise textual exibida conforme dados simulados.

12. Testar casos de falha

    Altere entradas para provocar erros e valide se guardrails, logs e mensagens de erro funcionam.

    try:
        validar_texto('EXEMPLO_PROIBIDO na campanha')
    except ValueError as e:
        print(e)Copiar

    O que você deve ver: Erro detectado e registrado, sem execução indevida.

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca inclua chaves de API em arquivos de código ou logs
• Restrinja permissões do arquivo execucoes.log para acesso apenas do usuário
• Garanta que dados pessoais só sejam processados com base legal e minimização
• Valide todas as entradas do usuário antes de enviar a APIs externas
• Revise manualmente qualquer conteúdo gerado antes de publicação

Checklist final

• Ambiente Python virtual criado e ativado
• Dependências instaladas sem erro
• Chaves de API configuradas em variáveis de ambiente
• Prompt de sistema versionado criado
• Funções de agente implementadas e testadas
• Guardrails e avaliação automática funcionando
• Execuções registradas em log
• Aprovação manual exigida antes de ações irreversíveis