How to Build a claims processing Agent Using LlamaIndex in TypeScript for wealth management

A claims processing agent for wealth management takes incoming client claims, extracts the relevant facts, checks them against policy and portfolio records, and prepares a decision package for human review or straight-through processing. It matters because claims in this domain are not just operational events; they affect client trust, compliance exposure, and the integrity of managed assets.

Architecture

• •

  Ingestion layer

  • •Pulls claim emails, PDFs, scanned forms, and CRM notes into a normalized text pipeline.
  • •In wealth management, this often means handling beneficiary claims, account transfer disputes, fee reversals, or insurance-linked investment claims.
• •

  Document parsing and indexing

  • •Uses LlamaIndex loaders to convert source documents into Document objects.
  • •Builds an index over policy docs, client agreements, KYC records, and claims playbooks.
• •

  Retrieval layer

  • •Retrieves only the relevant clauses, historical cases, and account metadata.
  • •This is where you enforce data minimization for compliance and residency boundaries.
• •

  Reasoning / decision agent

  • •Uses an LLM-backed query engine to classify claim type, extract fields, and draft a recommendation.
  • •Keeps the model grounded in source documents instead of free-form guessing.
• •

  Audit trail

  • •Persists retrieved chunks, prompts, outputs, and final decisions.
  • •Mandatory for regulated workflows where every recommendation needs traceability.
• •

  Human review handoff

  • •Routes low-confidence or high-risk claims to an operations analyst.
  • •Required when legal interpretation or exception handling is involved.

Implementation

1) Install dependencies and load your documents

Use the TypeScript package from LlamaIndex and a real OpenAI-backed LLM. Keep your claim policy docs separate from client-specific case files so you can control access later.

npm install llamaindex dotenv

import "dotenv/config";
import { Document } from "llamaindex";

const claimPolicyDocs = [
  new Document({
    text: `
      Claim approval rules:
      - Verify claimant identity against KYC record.
      - Check if the asset transfer date is within the dispute window.
      - Escalate any claim involving fraud indicators or sanctions hits.
      - Claims over $250,000 require compliance review.
    `,
    metadata: { source: "claims-playbook", jurisdiction: "US" },
  }),
];

const clientCaseDocs = [
  new Document({
    text: `
      Client requested reversal of advisory fee charged on 2024-11-15.
      Account holder: M. Patel
      Case notes mention duplicate billing after portfolio migration.
    `,
    metadata: { source: "case-file", clientId: "C12345" },
  }),
];

2) Build a vector index over the claims knowledge base

For this pattern, use VectorStoreIndex.fromDocuments. That gives you retrieval grounded in your policies and prior cases. In production, swap the default storage for your approved vector backend if you need residency control.

import {
  VectorStoreIndex,
  Settings,
  OpenAI,
} from "llamaindex";

Settings.llm = new OpenAI({
  model: "gpt-4o-mini",
});

async function buildIndex() {
  const allDocs = [...claimPolicyDocs, ...clientCaseDocs];
  const index = await VectorStoreIndex.fromDocuments(allDocs);
  return index;
}

3) Create a query engine that extracts structured claim facts

The key pattern is to ask for a constrained output format while grounding answers in retrieved context. Use asQueryEngine() on the index and pass a focused prompt that forces classification plus rationale.

async function analyzeClaim() {
  const index = await buildIndex();
  const queryEngine = index.asQueryEngine();

  const response = await queryEngine.query({
    query: `
      Review this wealth management claim:
      Client alleges duplicate advisory fee billing after portfolio migration.

      Return:
      - claim_type
      - likely_disposition
      - required_next_step
      - compliance_risk
      - supporting_evidence
    `,
  });

  console.log(String(response));
}

analyzeClaim();

4) Wrap it with decision logic for human review

Do not let the model auto-close regulated claims without thresholds. Use its output as a recommendation layer, then apply deterministic rules for escalation.

type ClaimDecision =
  | { disposition: "approve"; reason: string }
  | { disposition: "reject"; reason: string }
  | { disposition: "review"; reason: string };

function routeClaim(modelText: string): ClaimDecision {
  const lower = modelText.toLowerCase();

  if (lower.includes("fraud") || lower.includes("sanctions")) {
    return { disposition: "review", reason: "Compliance-sensitive indicators detected" };
    }

  if (lower.includes("duplicate billing") || lower.includes("fee reversal")) {
    return { disposition: "review", reason: "Financial remediation requires analyst validation" };
  }

  return { disposition: "review", reason: "Default to human review for regulated workflow" };
}

Production Considerations

• •

  Data residency

  • •Keep client case files inside approved regions.
  • •If your firm operates across jurisdictions, partition indexes by region instead of mixing all documents into one global store.
• •

  Audit logging

  • •Persist raw input, retrieved chunks, model response, final routing decision, timestamp, and operator override.
  • •You need this when compliance asks why a claim was approved or escalated.
• •

  Guardrails

  • •Block direct auto-decisioning on fraud flags, sanctions-related cases, large-value claims, and legal disputes.
  • •Force human review when confidence is low or when retrieved evidence conflicts with user input.
• •

  Monitoring

  • •Track retrieval quality, escalation rate, hallucination rate, and time-to-resolution.
  • •In wealth management workflows, also monitor false approvals because they create regulatory and fiduciary risk.

Common Pitfalls

1. •

   Mixing policy docs with unrestricted client data

   • •This breaks least-privilege access and makes audit trails messy.
   • •Keep reference knowledge separate from case-specific records and filter retrieval by tenant or jurisdiction.
2. •

   Letting the model decide without deterministic controls

   • •A model can summarize well but still miss legal thresholds.
   • •Use explicit rules for high-value claims, sanctions checks, fraud markers, and exceptions.
3. •

   Ignoring provenance in outputs

   • •If you cannot show which clause or note supported the recommendation, compliance will reject it.
   • •Always store retrieved sources alongside the final answer so analysts can verify the reasoning path.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.