Laboratório: Agente de Síntese Executiva com Claude Agent SDK, OpenAI Agents SDK e ElevenLabs TTS

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 · OpenAI Agents SDK (Python) a versão estável atual · ElevenLabs Python SDK a versão estável atual

Topologia

O agente Python central conecta-se à Claude API (via Agent SDK), à API da OpenAI (via Agents SDK) e à ElevenLabs TTS. Dados simulados são lidos de arquivos locais. O agente orquestra prompts, ferramentas e testes, e salva logs localmente. Endereços de exemplo: 192.168.56.10 (host), 127.0.0.1 (localhost para scripts), APIs externas via internet.

+-------------------+
|   Usuário local   |
+-------------------+
          |
          v
+-------------------+
|  Agente Python    |
| (Claude/OpenAI/   |
|  ElevenLabs SDKs) |
+-------------------+
   |     |      |
   v     v      v
Claude  OpenAI  ElevenLabs
API     API     TTS API

Equipamentos e software

Roteiro

1. Preparar ambiente Python isolado

   Isolar dependências e evitar conflitos criando um ambiente virtual.

   python3 -m venv ia_lab_env
   source ia_lab_env/bin/activateCopiar

   O que você deve ver: Prompt do terminal indica ambiente ativado (ia_lab_env).

2. Instalar SDKs necessários

   Instalar Claude Agent SDK, OpenAI Agents SDK e ElevenLabs SDK para acesso às APIs.

   pip install claude-agent-sdk-python openai-agents elevenlabsCopiar

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

3. Configurar variáveis de ambiente para segredos

   Evitar exposição de chaves de API. Use variáveis de ambiente para Claude, OpenAI e ElevenLabs.

   export CLAUDE_API_KEY='SUA_CHAVE_CLAUDE'
   export OPENAI_API_KEY='SUA_CHAVE_OPENAI'
   export ELEVEN_API_KEY='SUA_CHAVE_ELEVENLABS'Copiar

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

4. Criar arquivos de dados simulados

   Gerar arquivos CSV de EXEMPLO para simular fontes de dados (financeiro, vendas, produção).

   echo 'mes,receita,despesa
   2024-01,10000,7000
   2024-02,12000,8000' > dados_financeiros.csv
   echo 'produto,vendas
   A,500
   B,300' > dados_vendas.csvCopiar

   O que você deve ver: Arquivos dados_financeiros.csv e dados_vendas.csv criados no diretório.

5. Definir prompt de sistema versionado

   Criar arquivo prompt_v1.txt com instruções claras: sintetizar dados, explicitar premissas, recomendar ação e declarar incerteza.

   echo 'Você é um agente de decisão executiva. Leia os dados fornecidos, sintetize os pontos-chave, explicite premissas, recomende uma ação e declare o grau de incerteza. Responda apenas com texto estruturado.' > prompt_v1.txtCopiar

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

6. Implementar ferramenta customizada de leitura de CSV

   Criar função Python para ler e resumir arquivos CSV. Expor como ferramenta para o agente.

   cat <<EOF > ferramentas.py
   import csv
   def resumo_csv(path):
       with open(path, newline='') as f:
           reader = csv.DictReader(f)
           linhas = list(reader)
           return f'{len(linhas)} linhas, colunas: {reader.fieldnames}'
   EOFCopiar

   O que você deve ver: Arquivo ferramentas.py criado com função resumo_csv.

7. Configurar agente Claude com ferramenta e prompt

   Criar script Python que inicializa Claude Agent com prompt_v1.txt e ferramenta resumo_csv.

   cat <<EOF > agente_claude.py
   import os
   from claude_agent_sdk import Agent, Tool
   from ferramentas import resumo_csv
   with open('prompt_v1.txt') as f:
       prompt = f.read()
   agent = Agent(
       name='AgenteExecutivo',
       instructions=prompt,
       tools=[Tool('resumo_csv', resumo_csv, {'path': str}, str)]
   )
   EOFCopiar

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

8. Configurar agente OpenAI com ferramenta e prompt

   Criar script Python que inicializa Agent do OpenAI Agents SDK com mesmo prompt e ferramenta.

   cat <<EOF > agente_openai.py
   import os
   from openai_agents import Agent, Tool
   from ferramentas import resumo_csv
   with open('prompt_v1.txt') as f:
       prompt = f.read()
   agent = Agent(
       name='AgenteExecutivo',
       instructions=prompt,
       tools=[Tool('resumo_csv', resumo_csv, {'path': str}, str)]
   )
   EOFCopiar

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

9. Implementar avaliação automatizada (casos de teste)

   Criar script test_lab.py que executa o agente com dados de teste e compara a saída com o esperado.

   cat <<EOF > test_lab.py
   from agente_claude import agent as agente_c
   entrada = {'path': 'dados_financeiros.csv'}
   resposta = agente_c.run('resumo_csv', entrada)
   assert '2 linhas' in resposta, 'Falha no resumo do CSV'
   print('Teste OK')
   EOFCopiar

   O que você deve ver: Arquivo test_lab.py criado para testar ferramenta.

10. Adicionar guardrails de entrada e saída

    No agente, valide que o caminho do arquivo termina com .csv e que a saída não contenha dados pessoais.

    cat <<EOF >> ferramentas.py
    def guardrail_entrada(path):
        if not path.endswith('.csv'):
            raise ValueError('Arquivo deve ser CSV')
    def guardrail_saida(saida):
        if 'cpf' in saida.lower():
            raise ValueError('Dados pessoais detectados')
    EOFCopiar

    O que você deve ver: Guardrails adicionados ao arquivo ferramentas.py.

11. Integrar ElevenLabs TTS para leitura da recomendação

    Criar script Python que recebe texto do agente e gera áudio usando ElevenLabs.

    cat <<EOF > tts_lab.py
    import os
    from elevenlabs import ElevenLabs
    api = ElevenLabs(api_key=os.environ['ELEVEN_API_KEY'])
    texto = 'Recomendação: aumentar vendas do produto A.'
    voz = api.text_to_speech(text=texto, voice_id='EXEMPLO_VOICE_ID')
    with open('output.mp3', 'wb') as f:
        f.write(voz)
    EOFCopiar

    O que você deve ver: Arquivo output.mp3 gerado com áudio da recomendação.

12. Executar agente de ponta a ponta

    Rodar script principal que integra leitura dos dados, síntese pelo agente e leitura em voz.

    python agente_claude.py
    python tts_lab.pyCopiar

    O que você deve ver: Recomendação impressa e arquivo de áudio gerado.

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca inclua chaves de API em arquivos de código ou prompts
• Use variáveis de ambiente para segredos
• Não armazene dados pessoais nos arquivos de teste
• Restrinja permissões de leitura/gravação dos arquivos de dados
• Revise logs para evitar vazamento de informações sensíveis

Checklist final

• Ambiente Python isolado criado
• SDKs instalados sem erro
• Variáveis de ambiente configuradas
• Arquivos de dados simulados criados
• Prompt versionado salvo
• Ferramenta resumo_csv funcional
• Agente Claude e OpenAI configurados
• Casos de teste automatizados passam
• Guardrails de entrada e saída ativos
• Integração com ElevenLabs TTS gera áudio
• Execução ponta a ponta concluída