Laboratório: Agente Fiscal Multiagente com Claude Agent SDK, OpenAI Agents 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

4

Versões da documentação consultada

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

Topologia

Uma máquina (VM ou física) roda todos os componentes: scripts Python com Claude Agent SDK, OpenAI Agents SDK, integração MCP local, ElevenLabs TTS e chamadas à API HeyGen. O agente lê arquivos XML de notas fiscais, valida campos, consulta obrigações simuladas e produz alertas em voz (arquivo MP3) e vídeo (avatar). Não há conexão direta entre Claude/OpenAI e ElevenLabs/HeyGen: a orquestração é feita pelo script Python local. Endereços de exemplo: 192.168.56.10 para a máquina de testes.

+------------------------+
|   Máquina de Bancada   |
| 192.168.56.10          |
|                        |
| [Python Script]        |
|  |                    |
|  |-- Claude Agent SDK |
|  |-- OpenAI Agents SDK|
|  |-- ElevenLabs TTS   |
|  |-- HeyGen API       |
+------------------------+

Equipamentos e software

Roteiro

1. Preparar ambiente Python isolado

   Use um ambiente virtual para evitar conflitos de dependências. Isso garante reprodutibilidade e limpeza.

   python3 -m venv fiscal-lab
   source fiscal-lab/bin/activateCopiar

   O que você deve ver: Prompt do terminal com (fiscal-lab) à esquerda

2. Instalar dependências

   Instale Claude Agent SDK, OpenAI Agents SDK, ElevenLabs SDK e Requests para chamadas HTTP.

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

   O que você deve ver: Mensagens de instalação concluída para cada pacote

3. Configurar variáveis de ambiente para segredos

   Coloque as chaves de API em variáveis de ambiente para não expor segredos no código.

   export CLAUDE_API_KEY='SUA_CHAVE_CLAUDE'
   export OPENAI_API_KEY='SUA_CHAVE_OPENAI'
   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 (use 'echo $CLAUDE_API_KEY' para conferir)

4. Criar diretório de trabalho e dados de teste

   Organize o workspace e inclua um XML fictício de nota fiscal para testes.

   mkdir -p ~/fiscal-lab/notas
   cat > ~/fiscal-lab/notas/nfe-exemplo.xml <<EOF
   <?xml version="1.0"?>
   <NFe>
     <infNFe>
       <ide><cNF>12345678</cNF><dhEmi>2024-06-10T10:00:00-03:00</dhEmi></ide>
       <emit><CNPJ>12345678000199</CNPJ></emit>
       <dest><CNPJ>98765432000188</CNPJ></dest>
       <total><vNF>1000.00</vNF></total>
     </infNFe>
   </NFe>
   EOFCopiar

   O que você deve ver: Arquivo nfe-exemplo.xml criado em ~/fiscal-lab/notas/

5. Definir prompt de sistema versionado para agente fiscal

   Crie um arquivo com o prompt de sistema em português, orientando o agente a validar notas fiscais, simular obrigações e gerar alertas.

   cat > ~/fiscal-lab/prompt_fiscal_v1.txt <<EOF
   Você é um agente fiscal automatizado. Sua tarefa é:
   - Ler e validar campos obrigatórios de notas fiscais eletrônicas (XML)
   - Simular calendário de obrigações fiscais (valores EXEMPLO)
   - Gerar alerta se houver campos ausentes, valores inconsistentes ou obrigação próxima
   - Não tomar decisões finais: apenas preparar e registrar para revisão humana
   EOFCopiar

   O que você deve ver: Arquivo prompt_fiscal_v1.txt salvo

6. Implementar ferramenta de validação de NFe (Python)

   Implemente uma função Python para ler e validar o XML da nota fiscal, retornando inconsistências encontradas.

   cat > ~/fiscal-lab/validador_nfe.py <<EOF
   import xml.etree.ElementTree as ET
   
   def validar_nfe(xml_path):
       tree = ET.parse(xml_path)
       root = tree.getroot()
       erros = []
       cnpj_emit = root.find('.//emit/CNPJ')
       cnpj_dest = root.find('.//dest/CNPJ')
       vnf = root.find('.//total/vNF')
       if cnpj_emit is None or len(cnpj_emit.text) != 14:
           erros.append('CNPJ do emitente inválido')
       if cnpj_dest is None or len(cnpj_dest.text) != 14:
           erros.append('CNPJ do destinatário inválido')
       if vnf is None or float(vnf.text) <= 0:
           erros.append('Valor da nota inválido')
       return erros
   EOFCopiar

   O que você deve ver: Arquivo validador_nfe.py criado

7. Integrar Claude Agent SDK com ferramenta local

   Monte um agente Claude com prompt do passo anterior e a ferramenta de validação como função Python.

   cat > ~/fiscal-lab/agente_claude.py <<EOF
   import os
   from claude_agent_sdk import Agent, Tool
   from validador_nfe import validar_nfe
   
   class ValidadorNFETool(Tool):
       name = "validador_nfe"
       description = "Valida campos obrigatórios de uma nota fiscal eletrônica XML."
       def run(self, xml_path):
           return validar_nfe(xml_path)
   
   agent = Agent(
       name="Agente Fiscal Claude",
       instructions=open('prompt_fiscal_v1.txt').read(),
       tools=[ValidadorNFETool()]
   )
   EOFCopiar

   O que você deve ver: Arquivo agente_claude.py criado

8. Integrar OpenAI Agents SDK com ferramenta local

   Monte um agente OpenAI com o mesmo prompt e ferramenta de validação.

   cat > ~/fiscal-lab/agente_openai.py <<EOF
   import os
   from openai_agents import Agent, Tool, Runner
   from validador_nfe import validar_nfe
   
   class ValidadorNFETool(Tool):
       name = "validador_nfe"
       description = "Valida campos obrigatórios de uma nota fiscal eletrônica XML."
       def run(self, xml_path):
           return validar_nfe(xml_path)
   
   agent = Agent(
       name="Agente Fiscal OpenAI",
       instructions=open('prompt_fiscal_v1.txt').read(),
       tools=[ValidadorNFETool()]
   )
   EOFCopiar

   O que você deve ver: Arquivo agente_openai.py criado

9. Executar validação de nota fiscal com ambos agentes

   Rode cada agente para processar o XML de teste e registrar o resultado.

   python3 -c 'from agente_claude import agent; print(agent.run({"xml_path": "notas/nfe-exemplo.xml"}))'
   python3 -c 'from agente_openai import agent; from openai_agents import Runner; print(Runner.run_sync(agent, {"xml_path": "notas/nfe-exemplo.xml"}))'Copiar

   O que você deve ver: Saída com lista vazia (sem erros) ou lista de inconsistências

10. Gerar alerta de voz com ElevenLabs

    Use o SDK ElevenLabs para transformar um alerta textual em arquivo MP3.

    cat > ~/fiscal-lab/alerta_voz.py <<EOF
    import os
    from elevenlabs import ElevenLabs
    
    def gerar_alerta_voz(texto, saida):
        el = ElevenLabs(api_key=os.environ['ELEVENLABS_API_KEY'])
        audio = el.text_to_speech(text=texto, voice_id='EXEMPLO_VOICE_ID')
        with open(saida, 'wb') as f:
            f.write(audio)
    EOF
    python3 -c 'from alerta_voz import gerar_alerta_voz; gerar_alerta_voz("Alerta: obrigação fiscal próxima do vencimento.", "alerta.mp3")'Copiar

    O que você deve ver: Arquivo alerta.mp3 criado com áudio do alerta

11. Gerar vídeo de conferência com HeyGen

    Faça uma chamada à API HeyGen para criar um vídeo de avatar lendo o alerta.

    cat > ~/fiscal-lab/alerta_video.py <<EOF
    import os, requests
    headers = {
        'x-api-key': os.environ['HEYGEN_API_KEY'],
        'Content-Type': 'application/json'
    }
    data = {
        "type": "avatar",
        "avatar_id": "EXEMPLO_AVATAR_ID",
        "script": "Alerta: obrigação fiscal próxima do vencimento.",
        "voice_id": "EXEMPLO_VOICE_ID",
        "output_format": "mp4"
    }
    resp = requests.post('https://api.heygen.com/v3/videos', headers=headers, json=data)
    print(resp.json())
    EOF
    python3 alerta_video.pyCopiar

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

12. Registrar e avaliar execuções (tracing e testes)

    Implemente logging simples para registrar entradas, saídas e status de cada agente. Execute casos de teste com nota fiscal válida e inválida.

    cat > ~/fiscal-lab/testes.py <<EOF
    from validador_nfe import validar_nfe
    print('Teste válido:', validar_nfe('notas/nfe-exemplo.xml'))
    with open('notas/nfe-invalida.xml', 'w') as f:
        f.write('<?xml version="1.0"?><NFe><infNFe><emit><CNPJ>123</CNPJ></emit></infNFe></NFe>')
    print('Teste inválido:', validar_nfe('notas/nfe-invalida.xml'))
    EOF
    python3 testes.pyCopiar

    O que você deve ver: Saída: Teste válido: [] Teste inválido: ['CNPJ do emitente inválido', 'CNPJ do destinatário inválido', 'Valor da nota inválido']

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca exponha chaves de API em arquivos de código ou logs
• Restrinja permissões dos arquivos de configuração e segredos
• Não use dados reais de clientes ou notas fiscais em ambiente de testes
• Garanta que os arquivos de áudio e vídeo não contenham informações sensíveis
• Desative e revogue chaves de API não utilizadas após o laboratório

Checklist final

• Ambiente Python isolado criado
• Dependências instaladas sem erro
• Variáveis de ambiente configuradas
• Nota fiscal de teste criada
• Prompt de sistema salvo e versionado
• Ferramenta de validação funcionando
• Agentes Claude e OpenAI executando
• Alerta de voz gerado e reproduzido
• Vídeo de alerta criado na HeyGen
• Casos de teste com resultado esperado registrados