How to Build a customer support Agent Using LlamaIndex in TypeScript for insurance

A customer support agent for insurance answers policy questions, explains coverage, helps with claims status, and routes sensitive cases to the right human team. It matters because most insurance support failures are not “AI problems” — they are compliance problems, bad retrieval problems, or bad escalation handling.

Architecture

• •

  Channel adapter

  • •Takes input from web chat, WhatsApp, email, or a CRM widget.
  • •Normalizes messages into a single request shape.
• •

  Policy knowledge base

  • •Contains policy wordings, FAQs, claim procedures, underwriting rules, and product disclosures.
  • •Usually indexed from PDFs, HTML pages, and internal docs.
• •

  Retriever + response synthesizer

  • •Uses LlamaIndex to find relevant policy snippets.
  • •Produces grounded answers with citations instead of free-form guesses.
• •

  Conversation state

  • •Tracks the customer’s intent, policy type, claim number, and prior turns.
  • •Needed for multi-turn support flows like “check claim status” or “explain excess”.
• •

  Guardrails and escalation layer

  • •Blocks unsupported advice like legal interpretation or claims approval promises.
  • •Escalates to a human when confidence is low or the user asks about complaints, fraud, litigation, or regulated disclosures.
• •

  Audit logging

  • •Stores prompts, retrieved sources, final answers, and escalation decisions.
  • •Required for traceability in regulated environments.

Implementation

1) Install dependencies and load insurance documents

Use LlamaIndex’s TypeScript packages plus a PDF reader. Keep your documents in a controlled bucket or internal file store if you have residency requirements.

npm install llamaindex dotenv

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

async function loadDocs() {
  const reader = new SimpleDirectoryReader();
  const documents = await reader.loadData({
    directoryPath: "./insurance-docs",
  });

  console.log(`Loaded ${documents.length} documents`);
  return documents;
}

loadDocs().catch(console.error);

For insurance support, your source set should include:

• •Policy wording PDFs
• •Claims FAQ pages
• •Product disclosure statements
• •Internal support macros approved by legal/compliance

2) Build an index and query engine

For a support agent, start with VectorStoreIndex. It gives you grounded retrieval without needing a full agent framework on day one. Use asQueryEngine() so every answer comes from retrieved context.

import "dotenv/config";
import {
  Document,
  Settings,
  OpenAI,
  VectorStoreIndex,
} from "llamaindex";
import { SimpleDirectoryReader } from "llamaindex";

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

async function buildQueryEngine() {
  const reader = new SimpleDirectoryReader();
  const documents = await reader.loadData({
    directoryPath: "./insurance-docs",
  });

  const index = await VectorStoreIndex.fromDocuments(documents);

  return index.asQueryEngine({
    similarityTopK: 4,
    responseMode: "compact",
    preFilters: {
      filters: [
        {
          key: "documentType",
          value: "policy",
          operator: "==",
        },
      ],
    },
  });
}

async function ask(question: string) {
  const queryEngine = await buildQueryEngine();
  const response = await queryEngine.query({ query: question });

  console.log(response.toString());
}

ask("Does this home policy cover accidental water damage?");

A few things matter here:

• •Settings.llm sets the model globally for LlamaIndex.
• •VectorStoreIndex.fromDocuments() builds the retrieval layer.
• •asQueryEngine() keeps the system grounded in your source docs.
• •similarityTopK should stay small for support use cases to reduce irrelevant context.

3) Add a support-specific guardrail before answering

Insurance agents should not invent coverage decisions. If the question is about claims approval, legal interpretation, complaints handling, or policy exceptions, route it out of the model path.

const escalationKeywords = [
  "approve my claim",
  "deny my claim",
  "legal advice",
  "lawsuit",
  "complaint",
];

function shouldEscalate(question: string): boolean {
  const q = question.toLowerCase();
  return escalationKeywords.some((k) => q.includes(k));
}

async function handleSupportQuestion(question: string) {
    if (shouldEscalate(question)) {
      return {
        answer:
          "I can connect you to a licensed support specialist for that request.",
        escalated: true,
      };
    }

    const queryEngine = await buildQueryEngine();
    const response = await queryEngine.query({ query: question });

    return {
      answer: response.toString(),
      escalated: false,
      sources: response.sourceNodes?.map((node) => node.node.getContent()),
    };
}

handleSupportQuestion("Can you approve my claim today?").then(console.log);

This pattern is simple but effective. In production you can replace keyword checks with an intent classifier or rules engine tied to your compliance policy.

4) Return citations and log every interaction

Insurance teams need auditability. Keep the original question, retrieved sources, model output, and escalation flag in your logs or case system.

type AuditRecord = {
  timestamp: string;
  question: string;
};

async function answerWithAudit(question: string) {
    const startedAt = new Date().toISOString();
    const result = await handleSupportQuestion(question);

    const record: AuditRecord & {
      escalated?: boolean;
      answer?: string;
      sources?: string[];
    } = {
      timestamp: startedAt,
      question,
      escalated: result.escalated,
      answer: result.answer,
      sources: result.sources,
    };

    console.log(JSON.stringify(record, null, 2));
    return result;
}

If you need stronger controls later:

• •Store logs in an immutable audit store
• •Redact PII before persistence
• •Tag records by jurisdiction for retention policies

Production Considerations

• •

  Deployment

  • •Keep document ingestion separate from runtime chat handling.
  • •Run indexing in a controlled job so policy updates are versioned and reviewable.
  • •If residency matters, keep embeddings and vector storage inside the required region.
• •

  Monitoring

  • •Track retrieval hit rate, escalation rate, hallucination reports, and latency.
  • •Log which source nodes were used for each answer.
• •

  Guardrails

  • •Block unsupported outputs around claims decisions, coverage guarantees, legal advice, and complaint handling.
• •

  Compliance

Common Pitfalls

1. •

   Using general web data instead of approved policy content

   • •Avoid this by indexing only approved internal documents.
   • •For insurance support, source quality matters more than model size.
2. •

   Letting the model answer without citations

   • •Avoid free-form responses for coverage questions.
   • •Always return source nodes or quoted snippets from the policy text.
3. •

   Skipping escalation paths

   • •Don’t force the agent to handle complaints, fraud allegations, or disputed claims end-to-end.
   • •Route those cases to licensed staff with full conversation context attached.

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.