Laboratório: Agente Claude para Triagem de E-mails Administrativos com Ferramentas Customizadas e Avaliação Automatizada

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

Topologia

Uma máquina local (192.168.56.10) executa o agente Claude via Agent SDK Python, com um diretório de trabalho contendo prompts, ferramentas e casos de teste. O agente lê e-mails fictícios de um arquivo, classifica segundo critérios definidos e registra o resultado em outro arquivo. Não há conexão externa obrigatória: a API da Anthropic é chamada via chave de API local (demo).

+-------------------+
|  Máquina Local    |
| 192.168.56.10     |
|                   |
| +-------------+   |
| | Claude      |   |
| | Agent SDK   |   |
| +-------------+   |
|    |               |
|    v               |
| Ferramentas        |
| (classificação)    |
|    |               |
|    v               |
| Arquivos de teste  |
+-------------------+

Equipamentos e software

Roteiro

1. Preparar ambiente Python isolado

   Isolar dependências evita conflitos e facilita a limpeza após o laboratório.

   python3 -m venv agente_claude_lab
   source agente_claude_lab/bin/activateCopiar

   O que você deve ver: Prompt do terminal com (agente_claude_lab) à esquerda

2. Instalar Claude Agent SDK Python

   O SDK oficial permite rodar o laço de agente localmente, com ferramentas customizadas.

   pip install claude-agent-sdk-pythonCopiar

   O que você deve ver: Mensagem de sucesso do pip, sem erros

3. Criar diretório de trabalho do agente

   Organizar arquivos do agente facilita versionamento e testes.

   mkdir agente_claude
   cd agente_claude
   mkdir .claudeCopiar

   O que você deve ver: Diretório .claude criado dentro de agente_claude

4. Definir prompt de sistema versionado

   O prompt de sistema orienta o agente e precisa ser claro, objetivo e versionado.

   echo 'Você é um agente administrativo. Sua tarefa é ler e-mails recebidos e classificá-los em: "Protocolo", "Compras", "Contratos", "Atas", "Fornecedores" ou "Outros". Não tome decisões legais ou financeiras: apenas classifique e registre. Use apenas as ferramentas autorizadas. Versão: 2024-06-01.' > .claude/system_prompt_v20240601.txtCopiar

   O que você deve ver: Arquivo .claude/system_prompt_v20240601.txt criado com o texto do prompt

5. Implementar ferramenta de classificação

   Ferramentas customizadas permitem que o agente execute ações controladas e auditáveis.

   cat > .claude/tools.py <<EOF
   from typing import Literal
   
   def classificar_email(conteudo: str) -> Literal['Protocolo', 'Compras', 'Contratos', 'Atas', 'Fornecedores', 'Outros']:
       """Classifica um e-mail administrativo em uma das categorias."""
       # EXEMPLO: lógica simplificada para laboratório
       if 'compra' in conteudo.lower():
           return 'Compras'
       if 'contrato' in conteudo.lower():
           return 'Contratos'
       if 'ata' in conteudo.lower():
           return 'Atas'
       if 'fornecedor' in conteudo.lower():
           return 'Fornecedores'
       if 'protocolo' in conteudo.lower():
           return 'Protocolo'
       return 'Outros'
   EOFCopiar

   O que você deve ver: Arquivo .claude/tools.py criado com a função classificar_email

6. Criar casos de teste automatizados

   Testes garantem que o agente e as ferramentas funcionam como esperado antes de operar em produção.

   cat > .claude/test_cases.json <<EOF
   [
     {"input": "Solicito abertura de protocolo para novo contrato.", "expected": "Protocolo"},
     {"input": "Favor enviar ata da última reunião.", "expected": "Atas"},
     {"input": "Pedido de compra de material de escritório.", "expected": "Compras"},
     {"input": "Atualização cadastral do fornecedor XPTO.", "expected": "Fornecedores"},
     {"input": "Dúvida sobre férias.", "expected": "Outros"}
   ]
   EOFCopiar

   O que você deve ver: Arquivo .claude/test_cases.json criado com 5 casos de teste

7. Implementar guardrails de entrada e saída

   Guardrails protegem contra entradas inválidas e saídas fora do esperado, reduzindo riscos.

   cat > .claude/guardrails.py <<EOF
   def validar_entrada(email):
       if not isinstance(email, str) or len(email) < 10:
           raise ValueError('Entrada inválida: e-mail muito curto ou não é texto')
   
   def validar_saida(categoria):
       categorias = ['Protocolo', 'Compras', 'Contratos', 'Atas', 'Fornecedores', 'Outros']
       if categoria not in categorias:
           raise ValueError('Saída inválida: categoria desconhecida')
   EOFCopiar

   O que você deve ver: Arquivo .claude/guardrails.py criado com funções de validação

8. Configurar tracing para auditoria

   Registrar cada execução do agente permite rastrear decisões e facilitar revisões.

   cat > .claude/tracing.py <<EOF
   import datetime
   
   def registrar_tracing(email, categoria):
       with open('tracing.log', 'a') as f:
           f.write(f"{datetime.datetime.now().isoformat()} | Entrada: {email} | Saída: {categoria}\n")
   EOFCopiar

   O que você deve ver: Arquivo .claude/tracing.py criado para logging

9. Rodar agente Claude localmente com as ferramentas

   Executar o laço do agente com prompt, ferramentas e guardrails integrados.

   cat > rodar_agente.py <<EOF
   import os
   from claude_agent_sdk.agent import Agent, Tool
   from claude_agent_sdk.runner import AgentRunner
   from .claude.tools import classificar_email
   from .claude.guardrails import validar_entrada, validar_saida
   from .claude.tracing import registrar_tracing
   
   with open('.claude/system_prompt_v20240601.txt') as f:
       system_prompt = f.read()
   
   def main():
       agent = Agent(
           name='Agente Administrativo',
           instructions=system_prompt,
           tools=[
               Tool(
                   name='classificar_email',
                   function=classificar_email,
                   description='Classifica um e-mail administrativo.'
               )
           ]
       )
       runner = AgentRunner(agent)
       import json
       with open('.claude/test_cases.json') as f:
           casos = json.load(f)
       for caso in casos:
           email = caso['input']
           validar_entrada(email)
           categoria = classificar_email(email)
           validar_saida(categoria)
           registrar_tracing(email, categoria)
           print(f"E-mail: {email}\nClassificação: {categoria}\n---")
   
   if __name__ == '__main__':
       main()
   EOFCopiar

   O que você deve ver: Arquivo rodar_agente.py criado; pronto para execução

10. Executar o agente e observar resultados

    Rodar o agente para processar os casos de teste e verificar o funcionamento ponta a ponta.

    python rodar_agente.pyCopiar

    O que você deve ver: Saída no terminal com cada e-mail e sua classificação; arquivo tracing.log preenchido

11. Implementar revisão manual para decisões sensíveis

    Garantir que decisões com efeito legal, fiscal ou financeiro passem por aprovação humana.

    cat > revisar.py <<EOF
    with open('tracing.log') as f:
        linhas = f.readlines()
    for linha in linhas:
        if any(cat in linha for cat in ['Contratos', 'Compras']):
            print(f'Revisão obrigatória: {linha.strip()}')
    EOFCopiar

    O que você deve ver: Arquivo revisar.py criado para revisão manual

12. Rodar revisão manual

    Executar o script de revisão para identificar decisões que exigem validação humana.

    python revisar.pyCopiar

    O que você deve ver: Linhas do tracing.log com categorias sensíveis exibidas para revisão

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca inclua segredos (chaves de API) em arquivos de código ou prompts; use variáveis de ambiente
• Não processe dados pessoais reais sem base legal e minimização (LGPD, Lei 13.709/2018)
• Restrinja permissões de escrita/leitura dos arquivos .claude e tracing.log
• Revisão manual obrigatória para decisões sensíveis

Checklist final

• Ambiente virtual Python criado e ativado
• Claude Agent SDK instalado sem erros
• Prompt de sistema versionado criado
• Ferramenta de classificação implementada
• Casos de teste automatizados criados
• Guardrails de entrada e saída funcionando
• Tracing registrando execuções
• Revisão manual identificando decisões sensíveis