Construindo um agente de sinistros de seguros: o plano e a camada de dados | Parte 1

#ia #agentes #rag #postgresql

Por que comecei este projeto

A IA está tomando conta de tudo, e rápido. Já trabalho em um sistema baseado em IA para os analistas de sinistros no meu emprego, mas esse trabalho não cobre tudo o que envolve IA. Eu preciso de mais. Por isso decidi construir esta PoC, que tem relação com o meu trabalho e me dá a oportunidade de estudar IA agêntica e ganhar experiência prática construindo uma.

Dividi o projeto em partes menores, porque o objetivo nunca foi construir a PoC o mais rápido possível, mas entender cada parte dela.

Do que se trata o projeto?

A ideia é construir um assistente de IA com LangGraph que consulta as tabelas de apólices e sinistros via MCP, busca documentos com RAG e coloca um humano no circuito antes de recomendar um pagamento.

Infraestrutura e ferramentas

Neste projeto, estou usando:

  • Docker
  • PostgreSQL 18
  • Python 3.14
  • Outras ferramentas (a confirmar)

Fonte

Todos os dados são sintéticos e baseados no mercado irlandês: valores em euro, condados irlandeses e nomes irlandeses.

Há três produtos de seguro residencial. Cada um cobre um conjunto de riscos, e cada risco tem seu próprio limite e sua própria franquia:

Risco HOME-BASIC HOME-STD HOME-PLUS
fire €150.000 / €500 €300.000 / €350 €500.000 / €250
theft €10.000 / €250 €25.000 / €250 €50.000 / €150
storm €50.000 / €500 €100.000 / €350 €200.000 / €250
water_damage sem cobertura €30.000 / €350 €60.000 / €250
accidental_damage sem cobertura sem cobertura €15.000 / €150

Os valores são limite / franquia. Os riscos são incêndio (fire), roubo (theft), tempestade (storm), danos por água (water_damage) e danos acidentais (accidental_damage).

O limite é o máximo que a seguradora paga por um único sinistro, e a franquia é a parte de cada sinistro que o próprio cliente paga. Juntando os dois, a regra de pagamento é:

amount_paid = max(min(loss_amount, limit_amount) - deductible, 0)

Por exemplo, um cliente HOME-STD com um prejuízo de €6.400 por tempestade tem um limite de €100.000 e uma franquia de €350, então o pagamento é de €6.050.

O LLM nunca faz esse cálculo; o Python faz. LLMs podem errar em aritmética, e um pagamento precisa estar certo todas as vezes.

O plano

Dividi o trabalho em sete etapas:

  1. Preparar a camada de dados: o banco de dados, o schema e os dados sintéticos.
  2. Tornar o banco de dados seguro para o agente.
  3. Escrever os documentos-fonte do RAG: as condições gerais da apólice e o guia de regulação de sinistros.
  4. Construir o pipeline de RAG com pgvector.
  5. Construir um servidor MCP que dá ao agente suas ferramentas de SQL.
  6. Construir o agente com LangGraph, incluindo uma etapa de aprovação humana.
  7. Construir um executor de avaliação que compara as decisões do agente com as esperadas.

As etapas 1 e 2 estão prontas, e as próximas seções explicam cada uma.

Etapa 1: a camada de dados

A infraestrutura

O Docker Compose sobe dois serviços: o PostgreSQL 18 com a extensão pgvector, e o Adminer, uma interface web para navegar pelo banco de dados. O agente ainda não precisa do pgvector, mas o pipeline de RAG da etapa 4 vai precisar.

Na primeira vez que o banco de dados sobe, três scripts SQL rodam: um cria o schema, outro carrega os dados dos arquivos CSV, e o último cria os papéis (roles) do banco de dados.

O schema

Todas as tabelas ficam no schema insurance:

Tabela Chave Conteúdo
customers customer_id Os segurados.
policies policy_id Uma apólice anual por cliente: produto, status, datas, prêmio e importância segurada.
coverages (policy_id, peril) Uma linha por risco coberto, com seu limite e sua franquia.
claims_history claim_id Sinistros anteriores: data do prejuízo, risco, valor do prejuízo, valor pago e resultado.

Os dados sintéticos

Um script Python usa o Faker para criar 1.000 clientes, cada um com uma apólice. Como ele usa uma semente fixa e uma data de referência fixa, gera exatamente os mesmos arquivos em toda execução.

Para deixar os dados realistas, segui algumas regras:

  • As datas combinam com o status. O script escolhe o status primeiro (85% ativas, 10% vencidas e 5% canceladas) e depois escolhe datas que fazem sentido para ele. Um sinistro nunca acontece fora do período de cobertura ou depois de um cancelamento.
  • Os prêmios combinam com o produto. Cada prêmio é a importância segurada multiplicada por uma taxa específica do produto.
  • Os sinistros combinam com o risco. Cada risco tem sua própria frequência de sinistros. A maioria dos prejuízos é pequena, com só alguns grandes, e a sinistralidade (sinistros pagos divididos pelos prêmios) fica entre 0,6 e 0,8.

Etapa 2: tornar o banco de dados seguro

Um papel somente leitura

O agente se conecta ao banco de dados com um papel próprio, que só pode ler as tabelas. Ele não pode inserir, atualizar nem apagar linhas, e não pode criar tabelas. Há testes que comprovam isso.

Isso importa. Se um prompt algum dia mandar o agente apagar uma tabela, o banco de dados recusa. A segurança está no banco de dados, não no prompt.

Credenciais em um arquivo .env

As credenciais ficam em um arquivo .env que o git ignora. Se o arquivo não existir, o Docker Compose falha na hora com um erro, o que é muito melhor do que um banco de dados que sobe silenciosamente com as credenciais erradas.

Restrições

O schema também tem restrições CHECK que garantem que:

  • O status e o resultado só assumem valores permitidos.
  • A data de término de uma apólice vem depois da data de início.
  • O valor pago nunca é maior que o valor do prejuízo.

Além disso, uma chave estrangeira composta liga claims_history (policy_id, peril) a coverages, então todo sinistro anterior precisa ser de um risco que a apólice de fato cobre.

Com essas restrições, um bug no gerador faz a carga dos dados falhar, em vez de deixar dados ruins entrarem no banco de dados sem ninguém perceber.

O conjunto de avaliação

Um agente sem avaliação é só uma demo, então construí o conjunto de avaliação antes de escrever uma única linha do agente.

O conjunto tem 12 cenários. Cada um insere linhas no banco de dados com um marcador SCN (por exemplo, POL-SCN-LAPSED), além de um novo sinistro e o resultado esperado:

Cenário Decisão esperada O que testa
SCN-01-CLEAN approve Um risco coberto, abaixo do limite.
SCN-02-BURST-PIPE approve Danos súbitos por água têm cobertura.
SCN-03-GRADUAL-LEAK deny Uma exclusão que só aparece nas condições gerais da apólice.
SCN-04-NOT-COVERED deny Um risco que o produto não inclui.
SCN-05-OVER-LIMIT partial Um prejuízo acima do limite.
SCN-06-BELOW-DEDUCTIBLE deny Um prejuízo menor que a franquia.
SCN-07-LAPSED deny Um prejuízo depois do fim da apólice.
SCN-08-CANCELLED deny Um prejuízo depois do cancelamento.
SCN-09-EARLY-CLAIM escalate Um sinistro nos primeiros 30 dias da apólice (sinal de fraude).
SCN-10-FREQUENT escalate Três ou mais sinistros em 12 meses (sinal de fraude).
SCN-11-MISSING-INFO request_info Um sinistro sem data do prejuízo ou sem valor.
SCN-12-UNKNOWN-POLICY request_info Um número de apólice que não existe.

Aqui está um cenário do arquivo, com alguns campos removidos para ficar mais curto:

{
  "scenario_id": "SCN-01-CLEAN",
  "input": {
    "policy_id": "POL-SCN-CLEAN",
    "loss_date": "2026-11-05",
    "reported_peril": "storm",
    "claimed_amount": 6400,
    "description": "Storm Bram blew several slates off the roof and rain came into the attic."
  },
  "expected": {
    "decision": "approve",
    "payout": 6050,
    "reason": "covered_within_limit",
    "required_tools": ["get_policy", "get_coverage"],
    "required_docs": []
  }
}

Os resultados esperados ficam só em um arquivo JSONL e nunca entram no banco de dados, então o agente não consegue encontrar a resposta via SQL.

Cada cenário também lista as ferramentas e os documentos que o agente precisa usar. Assim, a avaliação verifica não só a decisão, mas também como o agente chegou a ela.

O projeto tem 46 testes até agora. Eles verificam as datas, a regra de pagamento, as chaves primárias e estrangeiras, e a reprodutibilidade dos dados. Eles também garantem que cada decisão esperada realmente decorre dos dados do seu cenário.

O que vem a seguir

A próxima etapa é escrever os documentos-fonte do RAG. Sem eles, o agente não consegue decidir corretamente quatro dos cenários. Por exemplo, a única diferença entre um cano estourado (SCN-02) e um vazamento gradual (SCN-03) está nas condições gerais da apólice.

Ainda há algumas decisões a tomar:

  • Qual modelo de embedding usar, e qual o tamanho de cada chunk.
  • Se o servidor MCP usa stdio ou HTTP.
  • Qual provedor e qual modelo de LLM usar.
  • Onde guardar os checkpoints da etapa de aprovação humana: PostgreSQL ou SQLite.

Vou escrever um post sobre cada etapa à medida que for terminando.

mathTosetto/python-postgresql-rag-insurance-ai-agenticSynthetic claims agent built with LangGraph. It retrieves documents via RAG, queries a SQL policy table through a tool (exposed via MCP), and requests human approval before recommending payment. - ...GitHub