Laboratório: Agente Claude para Conferência Automatizada de Folha de Pagamento com Guardrails e Avaliação

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

Uma máquina local (192.168.56.10) executa o Claude Agent SDK em Python, com scripts de ferramenta e arquivos de teste. O agente recebe comandos via terminal, processa dados simulados de folha e registra logs localmente. Não há comunicação externa: tudo ocorre em localhost.

+-----------------------+
|  VM/PC Local (192.168.56.10) |
|-----------------------|
| Claude Agent SDK      |
| Ferramentas Python    |
| Casos de Teste        |
| Prompt Versionado     |
| Logging               |
+-----------------------+

Equipamentos e software

Roteiro

1. Preparar o ambiente Python

   Isolar dependências evita conflitos. Crie um ambiente virtual.

   python3 -m venv venv
   source venv/bin/activateCopiar

   O que você deve ver: (venv) aparece no prompt

2. Instalar o Claude Agent SDK

   O SDK conecta seu código ao laço de agente Claude local.

   pip install claude-agent-sdkCopiar

   O que você deve ver: Successfully installed claude-agent-sdk

3. Configurar variável de ambiente da API Key

   A chave de API protege seu acesso ao Claude. Nunca coloque no código.

   export ANTHROPIC_API_KEY="SUA_CHAVE_AQUI"Copiar

   O que você deve ver: Nenhuma saída (variável setada na sessão)

4. Criar prompt de sistema versionado

   O prompt define o comportamento do agente. Use um arquivo para versionar.

   echo 'Você é um agente de RH. Sua tarefa é conferir folhas de pagamento simuladas e sinalizar valores fora do padrão EXEMPLO. Nunca aprove pagamentos: apenas registre e peça revisão humana.' > prompt_v1.txtCopiar

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

5. Definir ferramenta Python para conferência de folha

   Ferramentas permitem ao agente executar lógica customizada. Crie uma função que verifica salários acima de um teto EXEMPLO.

   cat > folha_tools.py <<EOF
   def conferir_folha(folha):
       teto = 10000  # EXEMPLO
       alertas = []
       for item in folha:
           if item['salario'] > teto:
               alertas.append(f"Colaborador {item['nome']} com salário acima do teto: {item['salario']}")
       return {'alertas': alertas}
   EOFCopiar

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

6. Criar dados de teste de folha de pagamento

   Casos de teste automatizam a validação. Use dados fictícios.

   cat > folha_teste.json <<EOF
   [
     {"nome": "Ana", "salario": 9500},
     {"nome": "Carlos", "salario": 12000},
     {"nome": "Beatriz", "salario": 8000}
   ]
   EOFCopiar

   O que você deve ver: Arquivo folha_teste.json criado

7. Implementar guardrail de entrada

   O guardrail impede dados fora do formato esperado. Valide o tipo e campos.

   cat > guardrails.py <<EOF
   def validar_entrada(folha):
       if not isinstance(folha, list):
           raise ValueError('Folha deve ser lista')
       for item in folha:
           if not all(k in item for k in ('nome', 'salario')):
               raise ValueError('Cada item deve ter nome e salario')
   EOFCopiar

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

8. Construir script principal do agente

   Integre prompt, ferramenta, guardrail e logging. O agente lê o prompt, valida entrada, executa a ferramenta e registra resultado.

   cat > agente_folha.py <<EOF
   import os, json
   from folha_tools import conferir_folha
   from guardrails import validar_entrada
   
   with open('prompt_v1.txt') as f:
       prompt = f.read()
   
   with open('folha_teste.json') as f:
       folha = json.load(f)
   
   try:
       validar_entrada(folha)
   except Exception as e:
       print(f'Guardrail falhou: {e}')
       exit(1)
   
   resultado = conferir_folha(folha)
   with open('log_execucao.txt', 'w') as f:
       f.write(json.dumps(resultado, indent=2))
   print('Conferência concluída. Veja log_execucao.txt')
   EOFCopiar

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

9. Executar o agente localmente

   Rode o script e observe o resultado.

   python agente_folha.pyCopiar

   O que você deve ver: Conferência concluída. Veja log_execucao.txt

10. Verificar o log de execução

    Confirme que o agente registrou alertas corretos.

    cat log_execucao.txtCopiar

    O que você deve ver: Colaborador Carlos com salário acima do teto: 12000

11. Adicionar caso de teste automatizado

    Automatize a validação: crie um teste que espera um alerta específico.

    cat > teste_agente.py <<EOF
    import json
    with open('log_execucao.txt') as f:
        resultado = json.load(f)
    assert any('Carlos' in alerta for alerta in resultado['alertas']), 'Alerta esperado não encontrado'
    print('Teste passou')
    EOFCopiar

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

12. Rodar o teste automatizado

    Execute o teste para validar o comportamento do agente.

    python teste_agente.pyCopiar

    O que você deve ver: Teste passou

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca registre ou exponha dados pessoais reais nos arquivos de teste ou log
• API Key deve ser mantida em variável de ambiente, nunca em arquivos ou código
• Restrinja permissões dos arquivos de log para evitar acesso não autorizado
• Revise o código para evitar execução de comandos externos não controlados

Checklist final

• Ambiente virtual Python criado e ativado
• Claude Agent SDK instalado
• Prompt de sistema versionado criado
• Ferramenta de conferência implementada
• Guardrail de entrada funcionando
• Agente executa e gera log
• Teste automatizado passa