Laboratório: Agente de Prospecção Comercial 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

13

Validações

4

Versões da documentação consultada

Python a versão estável atual · Claude Agent SDK Python a versão estável atual · openai-agents-python a versão estável atual · ElevenLabs Python SDK a versão estável atual · requests a versão estável atual

Topologia

Um notebook ou VM local executa o agente Python com Claude Agent SDK. O agente se conecta via internet às APIs do Claude (Anthropic), ElevenLabs (voz) e HeyGen (vídeo). Não há servidores externos próprios. Os dados de leads e catálogo são mockados localmente. Endereço de exemplo: 192.168.56.10.

┌─────────────┐
│   Usuário   │
└─────┬───────┘
      │
┌─────▼─────┐
│  Python   │
│(Agente IA)│
└─┬────┬────┘
  │    │
  │    ├─────────────┐
  │    │             │
Claude API   ElevenLabs API   HeyGen API
  │    │             │

Equipamentos e software

Roteiro

1. Preparar ambiente Python isolado

   Crie e ative um ambiente virtual para evitar conflitos de dependências.

   python3 -m venv venv
   source venv/bin/activateCopiar

   O que você deve ver: Prompt do terminal mostra (venv) indicando ambiente ativo.

2. Instalar dependências

   Instale os SDKs necessários para Claude Agent, ElevenLabs, requests e OpenAI Agents.

   pip install claude-agent-sdk-python elevenlabs openai-agents-python requestsCopiar

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

3. Configurar variáveis de ambiente para segredos

   Defina as chaves de API como variáveis de ambiente para proteger os segredos.

   export CLAUDE_API_KEY='SUA_CHAVE_CLAUDE'
   export ELEVEN_API_KEY='SUA_CHAVE_ELEVENLABS'
   export HEYGEN_API_KEY='SUA_CHAVE_HEYGEN'Copiar

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

4. Criar arquivo de leads fictícios

   Monte um arquivo JSON com leads para simular a pesquisa.

   cat > leads.json <<EOF
   [
     {"nome": "Empresa Exemplo", "segmento": "TI", "tamanho": 50, "email": "contato@exemplo.com"},
     {"nome": "Comércio Fictício", "segmento": "Varejo", "tamanho": 12, "email": "vendas@ficticio.com"}
   ]
   EOFCopiar

   O que você deve ver: Arquivo leads.json criado com dois leads de exemplo.

5. Definir prompt de sistema versionado para o agente

   Crie um arquivo system_prompt_v1.txt com instruções claras: pesquisar leads, qualificar por segmento e tamanho, gerar proposta objetiva.

   cat > system_prompt_v1.txt <<EOF
   Você é um agente comercial. Sua tarefa é:
   1. Pesquisar leads no arquivo leads.json.
   2. Qualificar leads do segmento 'TI' com mais de 20 funcionários.
   3. Gerar uma proposta de serviço baseada no catálogo fictício.
   4. A proposta deve ser objetiva e personalizada.
   EOFCopiar

   O que você deve ver: Arquivo system_prompt_v1.txt criado.

6. Implementar ferramenta de pesquisa de leads

   Implemente uma função Python que lê o leads.json e retorna os leads qualificados.

   def pesquisar_leads():
       import json
       with open('leads.json') as f:
           leads = json.load(f)
       return [lead for lead in leads if lead['segmento'] == 'TI' and lead['tamanho'] > 20]Copiar

   O que você deve ver: Função retorna apenas leads do segmento TI com mais de 20 funcionários.

7. Implementar ferramenta de geração de proposta

   Implemente uma função Python que recebe um lead e gera uma proposta textual baseada em catálogo fictício.

   def gerar_proposta(lead):
       return f"Olá {lead['nome']},\n\nOferecemos conectividade dedicada de fibra óptica e suporte especializado para empresas de TI. Proposta EXEMPLO: 500 Mbps, instalação em até 10 dias úteis. Consulte condições vigentes.\n\nAtenciosamente,\nEquipe Comercial"Copiar

   O que você deve ver: Função retorna texto objetivo e personalizado para o lead.

8. Integrar Claude Agent SDK com as ferramentas

   Monte o agente Claude com prompt de sistema, ferramentas e guardrails simples (ex: não gerar proposta para leads não qualificados).

   from claude_agent_sdk_python import Agent
   agent = Agent(
       name='AgenteComercial',
       system_prompt=open('system_prompt_v1.txt').read(),
       tools={'pesquisar_leads': pesquisar_leads, 'gerar_proposta': gerar_proposta},
       guardrails={'output': lambda x: 'Proposta' in x}
   )Copiar

   O que você deve ver: Agente criado sem erros, pronto para orquestrar o fluxo.

9. Executar fluxo de prospecção e geração de proposta

   Rode o agente para pesquisar, qualificar e gerar proposta para o primeiro lead elegível.

   leads = pesquisar_leads()
   if leads:
       proposta = gerar_proposta(leads[0])
       print(proposta)Copiar

   O que você deve ver: Texto da proposta aparece no terminal.

10. Converter proposta em áudio com ElevenLabs

    Use o SDK ElevenLabs para sintetizar a proposta em voz.

    from elevenlabs import ElevenLabs, Voice
    el = ElevenLabs(api_key=os.environ['ELEVEN_API_KEY'])
    audio = el.text_to_speech(text=proposta, voice_id='EXEMPLO_VOICE_ID')
    with open('proposta.mp3', 'wb') as f:
        f.write(audio)Copiar

    O que você deve ver: Arquivo proposta.mp3 criado com a proposta falada.

11. Gerar vídeo personalizado com HeyGen

    Envie o áudio e o texto para a API HeyGen para criar um vídeo de proposta com avatar.

    import requests
    headers = {'x-api-key': os.environ['HEYGEN_API_KEY']}
    payload = {
        'type': 'avatar',
        'avatar_id': 'EXEMPLO_AVATAR_ID',
        'script': proposta,
        'audio_url': 'file://proposta.mp3',
        'voice_id': 'EXEMPLO_VOICE_ID',
        'output_format': 'mp4'
    }
    r = requests.post('https://api.heygen.com/v3/videos', headers=headers, json=payload)
    print(r.json())Copiar

    O que você deve ver: Resposta JSON com video_id e status 'waiting' ou 'processing'.

12. Consultar status do vídeo e baixar resultado

    Verifique o status do vídeo até estar 'completed' e faça download do arquivo.

    video_id = r.json()['data']['video_id']
    while True:
        resp = requests.get(f'https://api.heygen.com/v3/videos/{video_id}', headers=headers)
        status = resp.json()['data']['status']
        if status == 'completed':
            video_url = resp.json()['data']['video_url']
            break
        elif status == 'failed':
            raise Exception('Falha na geração do vídeo')
        time.sleep(10)
    # Download
    video = requests.get(video_url)
    with open('proposta_video.mp4', 'wb') as f:
        f.write(video.content)Copiar

    O que você deve ver: Arquivo proposta_video.mp4 salvo localmente.

13. Registrar execução e avaliar resultado

    Implemente registro simples em log.txt e defina critérios de aprovação: lead correto, proposta personalizada, áudio e vídeo gerados.

    with open('log.txt', 'a') as log:
        log.write(f'Lead: {leads[0]['nome']}, Status: OK\n')Copiar

    O que você deve ver: Linha registrada em log.txt; todos os artefatos gerados.

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca inclua chaves de API em código ou logs
• Minimize dados pessoais nos exemplos e artefatos
• Garanta que arquivos de áudio e vídeo não exponham informações sensíveis
• Restrinja permissões de leitura e gravação dos arquivos de segredos
• Apague artefatos sensíveis após o uso

Checklist final

• Ambiente Python isolado criado
• SDKs instalados sem erro
• Chaves de API protegidas em variáveis de ambiente
• Arquivo leads.json criado e lido corretamente
• Prompt de sistema versionado salvo
• Agente Claude funcional com ferramentas integradas
• Proposta gerada e personalizada
• Áudio da proposta sintetizado
• Vídeo de proposta gerado e baixado
• Registro da execução salvo em log.txt