Construindo um agente de sinistros de seguros: o plano e a camada de dados | Parte 1
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:
- Preparar a camada de dados: o banco de dados, o schema e os dados sintéticos.
- Tornar o banco de dados seguro para o agente.
- Escrever os documentos-fonte do RAG: as condições gerais da apólice e o guia de regulação de sinistros.
- Construir o pipeline de RAG com pgvector.
- Construir um servidor MCP que dá ao agente suas ferramentas de SQL.
- Construir o agente com LangGraph, incluindo uma etapa de aprovação humana.
- 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