Laboratório: Agente Claude para Revisão de Contratos com Ferramentas Customizadas e Avaliação Automática

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 · pip a versão estável atual

Topologia

O agente Claude roda em um servidor local (192.168.56.10), acessando arquivos de contratos em uma pasta compartilhada. O agente usa o Claude Agent SDK para processar os contratos e salvar relatórios em outra pasta local. O operador interage via terminal SSH. Não há conexão externa obrigatória para a execução do agente, exceto para baixar dependências.

+-------------------+
| Operador (SSH)    |
+--------+----------+
         |
         v
+--------+----------+
| VM/Servidor Local |
| IP: 192.168.56.10 |
+--------+----------+
         |
         v
+-------------------+
| Claude Agent SDK  |
| Contratos: /dados |
| Relatórios: /out  |
+-------------------+

Equipamentos e software

Roteiro

1. Preparar o ambiente Python

   Garanta um ambiente limpo para evitar conflitos de dependências.

   sudo apt update && sudo apt install -y python3 python3-venv python3-pip
   python3 -m venv venv
   source venv/bin/activateCopiar

   O que você deve ver: Prompt alterado para indicar ambiente virtual ativo.

2. Instalar o Claude Agent SDK

   O SDK oficial é necessário para criar e rodar o agente localmente.

   pip install claude-agent-sdkCopiar

   O que você deve ver: Mensagem de instalação bem-sucedida do pacote claude-agent-sdk.

3. Criar diretórios de trabalho

   Organize os arquivos de contratos e relatórios para facilitar o acesso e versionamento.

   mkdir -p ~/contratos_lab/dados ~/contratos_lab/outCopiar

   O que você deve ver: Pastas ~/contratos_lab/dados e ~/contratos_lab/out criadas.

4. Adicionar contratos fictícios para teste

   Inclua contratos de EXEMPLO para o agente analisar.

   echo 'CONTRATO DE PRESTAÇÃO DE SERVIÇOS
   Cláusula 1: O contratado deverá...
   Cláusula 2: O contratante poderá rescindir sem aviso prévio...' > ~/contratos_lab/dados/contrato1.txtCopiar

   O que você deve ver: Arquivo contrato1.txt criado em ~/contratos_lab/dados.

5. Definir prompt de sistema versionado

   O prompt orienta o agente sobre o objetivo e limitações da tarefa.

   cat <<EOF > ~/contratos_lab/prompt_v1.txt
   Você é um agente jurídico especializado em revisão de contratos. Seu objetivo é identificar cláusulas de risco, inconsistências e pontos que exigem atenção do advogado responsável. Não tome decisões legais. Liste as cláusulas de risco e explique o motivo. Use linguagem clara e objetiva. Versão do prompt: v1.
   EOFCopiar

   O que você deve ver: Arquivo prompt_v1.txt salvo com o texto do sistema.

6. Implementar ferramenta customizada de análise de cláusulas

   Ferramentas customizadas permitem que o agente execute funções específicas, como identificar padrões de risco.

   cat <<EOF > ~/contratos_lab/analisador.py
   import re
   def analisar_clausulas(texto):
       riscos = []
       padroes = [r'rescindir sem aviso prévio', r'indenização ilimitada']
       for padrao in padroes:
           if re.search(padrao, texto, re.IGNORECASE):
               riscos.append(padrao)
       return riscos
   EOFCopiar

   O que você deve ver: Arquivo analisador.py criado com função de identificação de padrões de risco.

7. Integrar ferramenta ao agente Claude

   O SDK permite registrar funções Python como ferramentas acessíveis ao agente.

   cat <<EOF > ~/contratos_lab/agente_lab.py
   from claude_agent_sdk import Agent, Tool
   from analisador import analisar_clausulas
   
   with open('prompt_v1.txt') as f:
       prompt = f.read()
   
   def ferramenta_analisar(texto: str):
       riscos = analisar_clausulas(texto)
       return {'riscos': riscos}
   
   analisar_tool = Tool(
       name='analisar_clausulas',
       description='Identifica cláusulas de risco em contratos',
       parameters={'texto': str},
       func=ferramenta_analisar
   )
   
   agent = Agent(
       name='AgenteRevisor',
       instructions=prompt,
       tools=[analisar_tool]
   )
   
   if __name__ == '__main__':
       with open('dados/contrato1.txt') as f:
           contrato = f.read()
       resultado = agent.run_sync({'texto': contrato})
       with open('out/relatorio1.txt', 'w') as f:
           f.write(str(resultado))
   EOFCopiar

   O que você deve ver: Arquivo agente_lab.py criado com integração do prompt e ferramenta customizada.

8. Executar o agente e gerar relatório

   Rode o agente para processar o contrato de teste e salvar o relatório.

   cd ~/contratos_lab
   python agente_lab.pyCopiar

   O que você deve ver: Arquivo out/relatorio1.txt criado com os riscos identificados.

9. Criar casos de teste e avaliação automática

   Teste automatizado garante que o agente identifica corretamente cláusulas de risco.

   cat <<EOF > ~/contratos_lab/teste_agente.py
   from agente_lab import ferramenta_analisar
   
   def test_risco_rescisao():
       texto = 'O contratante poderá rescindir sem aviso prévio.'
       resultado = ferramenta_analisar(texto)
       assert 'rescindir sem aviso prévio' in resultado['riscos']
   
   def test_sem_risco():
       texto = 'Cláusula padrão.'
       resultado = ferramenta_analisar(texto)
       assert resultado['riscos'] == []
   
   if __name__ == '__main__':
       test_risco_rescisao()
       test_sem_risco()
       print('Todos os testes passaram.')
   EOFCopiar

   O que você deve ver: Arquivo teste_agente.py criado com dois testes automatizados.

10. Rodar avaliação automática

    Execute os testes para validar o comportamento da ferramenta.

    python teste_agente.pyCopiar

    O que você deve ver: Mensagem 'Todos os testes passaram.' exibida.

11. Registrar logs de execução

    O registro é essencial para auditoria e revisão humana.

    cat <<EOF > ~/contratos_lab/logger.py
    import datetime
    def registrar_log(acao, detalhes):
        with open('out/log_execucao.txt', 'a') as f:
            f.write(f"{datetime.datetime.now()} | {acao} | {detalhes}\n")
    EOFCopiar

    O que você deve ver: Arquivo logger.py criado para registrar logs.

12. Adicionar logging ao agente

    Inclua o registro de cada execução no fluxo principal.

    cat <<EOF >> ~/contratos_lab/agente_lab.py
    from logger import registrar_log
    # ...
    if __name__ == '__main__':
        with open('dados/contrato1.txt') as f:
            contrato = f.read()
        resultado = agent.run_sync({'texto': contrato})
        with open('out/relatorio1.txt', 'w') as f:
            f.write(str(resultado))
        registrar_log('analise_contrato', f'contrato1.txt: {resultado}')
    EOFCopiar

    O que você deve ver: Código do agente atualizado para registrar logs de execução.

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca inclua dados pessoais reais nos contratos de teste.
• Armazene segredos (como chaves de API) apenas em variáveis de ambiente, nunca em arquivos de código.
• Restrinja permissões das pastas ~/contratos_lab/dados e ~/contratos_lab/out para o usuário do laboratório.
• Revise periodicamente os logs para identificar acessos indevidos.
• Desative o ambiente virtual ao finalizar para evitar uso indevido.

Checklist final

• Ambiente virtual Python criado e ativado
• Claude Agent SDK instalado
• Diretórios de dados e saída criados
• Contrato de teste salvo
• Prompt de sistema versionado criado
• Ferramenta customizada implementada
• Agente integrado e executado
• Relatório gerado
• Testes automatizados passaram
• Logs de execução registrados