# Validação de relatórios de despesas com IA usando saídas estruturadas e regras de negócio ## **Visão geral** Este guia mostra como criar um sistema automatizado de validação de relatórios de despesas que usa IA para extrair dados de arquivos PDF e aplicar regras de negócio para decidir como cada relatório é aprovado. Ao final, você terá um pipeline que: * Recebe um documento via API. * Extrai dados estruturados usando IA. * Aplica regras de negócio determinísticas. * Encaminha relatórios com base em limites predefinidos. ## **Padrões relacionados** Essa extração com IA se aplica a diversos cenários de processamento de documentos: * **Processamento de faturas**: Extrai o fornecedor, o valor e a data de vencimento, e encaminha as informações para o time financeiro. * **Revisão de contratos**: Extrai os principais termos, datas relevantes e as partes envolvidas, e envia para revisão jurídica. * **Triagem de currículos**: Extrai competências, experiência profissional e formação acadêmica, e encaminha o perfil para o gestor responsável pela contratação. * **Sinistros de seguros**: Extrai o número da apólice e os detalhes do incidente, e encaminha a solicitação para o analista responsável. O princípio central é sempre o mesmo: **a IA extrai dados estruturados e as regras de negócio determinam o que acontece em seguida.** {% stepper %} {% step %} ## **Configuração do pipeline**
### **Configurando o trigger** O pipeline começa com um [**HTTP File Trigger**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/triggers/web-protocols/http-file) que aceita uploads de PDFs. Quando um arquivo é enviado, ele fica disponível no pipeline por meio do array `files[]`. ### **Validando a requisição** Valide a requisição antes da etapa de IA. Isso garante que tokens sejam utilizados apenas quando o arquivo obrigatório estiver presente. Você pode validar o payload de diferentes formas. Para este cenário, use o [**conector Validator v2**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/validator-v2). Configure o Validator v2 com um JSON Schema que exija um nome de arquivo compatível com o padrão `^.+\\.(pdf)$`. * Se a validação falhar, use um [**conector Choice**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/logic/choice) para direcionar para o fluxo de erro. * Se a validação for bem-sucedida, prossiga para a extração com IA. {% endstep %} {% step %} ## **Extração com IA** ### **Entendendo saídas estruturadas** Sem saídas estruturadas, a IA pode retornar um texto livre difícil de processar: {% code overflow="wrap" %} ``` O funcionário John Smith (ID: EMP001) do departamento de Sales enviou um relatório de despesas em 15 de novembro de 2024 para uma viagem no valor total de US$ 1.250,00... ``` {% endcode %} Esse formato é difícil de trabalhar. Seria necessário implementar lógica de parsing complexa, lidar com muitas variações e tratar erros. **Com saídas estruturadas**, você define um JSON Schema e a IA retorna: ```json { "employee_id": "EMP001", "employee_name": "John Smith", "department": "Sales", "total": 1250.00 } ``` Esse resultado pode ser usado imediatamente para roteamento, validação e armazenamento. Não há necessidade de parsing. ### **Configurando o Agent Component** Ao configurar o [**Agent Component**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/ai-tools/llm), concentre-se nas seguintes configurações: #### **Seleção do modelo** * **Modelo**: Selecione o modelo que deseja utilizar. * **Conta:** Escolha a conta a ser usada pelo LLM. * **Temperatura:** `0.3` (Uma temperatura baixa ajuda a garantir extrações consistentes e previsíveis.) * **Máximo de Tokens de Saída**: `1024` (Suficiente para a maioria dos relatórios de despesas. Ajuste se estiver processando relatórios muito detalhados.) * **Outros parâmetros**: Mantenha Top-P, Top-K e penalidades com os valores padrão. #### **Arquivos** * **Arquivos**: `{{ message.fileName }}` (Este campo aceita [Double Braces](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/double-braces/overview), permitindo referenciar o arquivo de forma dinâmica.) * **Guardrails:** * **Habilite a proteção de PII (Informações de Identificação Pessoal):** Detecta e mascara dados pessoais sensíveis. * **Habilite JSON Schema:** Força o LLM a retornar dados estruturados no formato esperado (altamente recomendado). * **Habilite padrões Regex:** Valida formatos específicos de campos. Para este caso de uso de extração de despesas, habilitaremos o **JSON Schema** para garantir uma saída estruturada que possa ser usada diretamente nas decisões de roteamento. A definição do schema é apresentada na próxima seção. #### **Mensagens** **Mensagem do Sistema** (define o papel da IA): ``` Você é um agente de extração de relatórios de despesas. Sua tarefa é extrair dados estruturados do documento fornecido. Não tome decisões. Não aplique regras de negócio. Retorne apenas os dados extraídos, seguindo o JSON Schema fornecido. ``` **Mensagem do Usuário** (a solicitação específica): ``` Extraia os dados do relatório de despesas do PDF anexado. ``` ### **Definindo o JSON Schema** As saídas estruturadas agregam valor porque mantêm os dados consistentes. Aqui, use o Agent como um normalizador de dados, não como uma ferramenta de raciocínio. **JSON Schema**: {% code overflow="wrap" expandable="true" %} ```json { "type": "object", "required": ["employee_name", "department", "total", "trip_type", "itemized_expenses"], "properties": { "employee_name": { "type": "string", "description": "Nome completo do funcionário" }, "department": { "type": "string", "description": "Nome do departamento" }, "total": { "type": "number", "description": "Valor total da despesa" }, "trip_type": { "type": "string", "enum": ["Domestic", "International"], "description": "Tipo de viagem" }, "itemized_expenses": { "type": "array", "items": { "type": "object", "required": ["date", "description", "category", "amount"], "properties": { "date": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "amount": { "type": "number" } } } } } } ``` {% endcode %} **Exemplo de saída**: {% code overflow="wrap" expandable="true" %} ```json { "employee_name": "John Smith", "department": "Sales", "total": 1250.00, "trip_type": "Domestic", "itemized_expenses": [ { "date": "11/05/2024", "description": "Hotel - Centro (3 noites)", "category": "Hospedagem", "amount": 600.00 }, { "date": "11/05/2024", "description": "Jantar da equipe", "category": "Refeições", "amount": 150.00 } ] } ``` {% endcode %} {% hint style="success" %} **Guia de início rápido relacionado**: [Transforme respostas de IA em uma saída JSON estruturada](https://docs.google.com/document/u/0/d/1G5qDIiSpR3M_b30RCD9MA18vLGC3Elofm7Hj_u2yEfg/edit) {% endhint %} Os dados extraídos agora estão disponíveis em `message.body` e prontos para roteamento. ### **Monitorando o uso de tokens (Opcional)** Monitorar o uso de IA é uma boa prática para controle de custos. Neste exemplo, um [**Event Publisher**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/queues-and-messaging/event-publisher) foi adicionado após o Agent para acompanhar o consumo: {% code overflow="wrap" expandable="true" %} ```json { "timestamp": {{ NOW() }}, "step_name": "expense-extraction", "model": "gpt-4o", "tokens": { "input": {{ message.tokenUsage.inputTokenCount }}, "output": {{ message.tokenUsage.outputTokenCount }}, "total": {{ message.tokenUsage.totalTokenCount }} }, "cost_calc": {{ COST_CALCULATION }} } ``` {% endcode %} Isso publica o uso de tokens em um pipeline de eventos para análise de custos. {% endstep %} {% step %} ## **Lógica de negócio** Agora que você tem dados estruturados vindos da IA, é possível encaminhar os relatórios com base em regras de negócio. ### **Roteamento simples por valor total** Na maioria dos casos, o roteamento depende do valor total da despesa: * Abaixo de US$ 500: Aprovação automática * Entre US$ 500 e US$ 2.000: Aprovação do gestor * Acima de US$ 2.000: Aprovação da diretoria Para este exercício, usaremos um [**conector Choice**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/logic/choice), já que o roteamento é feito com base no campo `total`, sem necessidade de cálculos ou agregações. {% code overflow="wrap" expandable="true" %} ```json { "when": [ { "path": "auto-approve", "jsonPath": "$.[?(@.body.total < 500)]" }, { "path": "manager-approval", "jsonPath": "$.[?(@.body.total >= 500 && @.body.total < 2000)]" }, { "path": "director-approval", "jsonPath": "$.[?(@.body.total >= 2000)]" } ], "otherwise": "error" } ``` {% endcode %} Após o roteamento, cada fluxo gera uma resposta apropriada. ### **Exemplo: Resposta de aprovação automática** **JSON**: {% code overflow="wrap" expandable="true" %} ```json { "status": 200, "decision": "APPROVED", "employee": {{ message.body.employee_name }}, "department": {{ message.body.department }}, "total": {{ message.body.total }}, "message": "Relatório de despesas aprovado automaticamente, abaixo do limite de US$ 500" } ``` {% endcode %} {% endstep %} {% endstepper %} ## **Extensões** Você pode estender esta solução de várias formas: * **Notificações por email:** Enviar emails para o aprovador correto após o roteamento. * **Limites por departamento:** Aplicar regras de aprovação diferentes para cada departamento. * **Armazenamento em banco de dados:** Adicionar um conector de banco de dados após a resposta para registrar as decisões de despesas. Isso cria uma trilha de auditoria e permite análises sobre padrões de despesas. ## **Principais aprendizados** * **Saídas estruturadas são essenciais**: O JSON Schema garante que a IA retorne dados confiáveis e previsíveis, e não texto livre. * **Monitore os custos**: Sempre acompanhe o uso de tokens ao utilizar LLMs. Mesmo PDFs pequenos podem consumir centenas de tokens em escala. * **Falhe rápido**: Valide as entradas (existência e tipo do arquivo) o quanto antes para evitar desperdício de tokens de IA. O conector Validator é sua primeira linha de defesa. * **Combine IA e regras**: Use a IA para extrair dados (não estruturados para estruturados) e aplique lógica de negócio determinística para tomar decisões. Isso garante flexibilidade e controle.