How to Build a underwriting Agent Using LlamaIndex in TypeScript for healthcare

An underwriting agent for healthcare takes patient, provider, plan, and policy data, then turns it into a structured coverage recommendation with traceable evidence. It matters because healthcare underwriting is full of rules: eligibility, exclusions, prior auth requirements, medical necessity checks, and compliance constraints that need to be applied consistently and audited later.

Architecture

• •

  Document ingestion layer

  • •Pulls in policy PDFs, benefit summaries, clinical guidelines, prior authorization rules, and internal underwriting playbooks.
  • •Normalizes them into text chunks with metadata like policyId, jurisdiction, effectiveDate, and sourceType.
• •

  Vector index

  • •Stores embeddings for semantic retrieval across policy language and clinical criteria.
  • •Keeps the agent grounded in approved documents instead of free-form reasoning.
• •

  Retrieval + synthesis layer

  • •Uses LlamaIndex retrieval to fetch the most relevant passages for a case.
  • •Produces an answer with citations so underwriters can verify every recommendation.
• •

  Workflow/orchestration layer

  • •Accepts a case payload: age, diagnosis codes, procedure codes, member plan, location, requested service.
  • •Routes the request through retrieval, rule checks, and response formatting.
• •

  Compliance guardrails

  • •Redacts or minimizes PHI where possible.
  • •Enforces allowed document scopes by region and line of business.
• •

  Audit logging

  • •Records query text, retrieved sources, model output, timestamps, and reviewer actions.
  • •Needed for healthcare audits, disputes, and internal QA.

Implementation

1) Install dependencies and prepare your document set

Use LlamaIndex’s TypeScript packages and keep your source documents in a controlled location. In healthcare, your first job is not prompting; it is making sure only approved policy content enters the index.

npm install llamaindex dotenv

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

const docs = [
  new Document({
    text: `
      Prior authorization is required for elective inpatient admissions,
      advanced imaging over $1,500, and any experimental treatment not listed
      in the approved medical policy. Coverage decisions must reference the
      active policy version and effective date.
    `,
    metadata: {
      policyId: "UW-2025-001",
      sourceType: "policy",
      jurisdiction: "US-NY",
      effectiveDate: "2025-01-01",
    },
  }),
  new Document({
    text: `
      For oncology-related requests, use NCCN-aligned criteria when available.
      If clinical documentation is insufficient, return a request for additional
      information rather than a denial.
    `,
    metadata: {
      policyId: "UW-2025-002",
      sourceType: "clinical_guideline",
      jurisdiction: "US-NY",
      effectiveDate: "2025-01-01",
    },
  }),
];

2) Build the index with metadata-aware chunking

For underwriting you want retrieval that respects jurisdiction and policy version. LlamaIndex’s VectorStoreIndex works well here because you can attach metadata at ingestion time and filter later.

import { VectorStoreIndex } from "llamaindex";

async function buildIndex() {
  const index = await VectorStoreIndex.fromDocuments(docs);
  return index;
}

If your corpus is larger than memory or you need persistence across deployments, back this with a real vector store. The pattern stays the same; only the storage layer changes.

3) Query with a case-specific prompt and citations

The actual underwriting agent should not “decide” from thin air. It should retrieve evidence first, then synthesize a recommendation tied to source material.

import { OpenAI } from "llamaindex";

type UnderwritingCase = {
  memberId: string;
  state: string;
  diagnosisCodes: string[];
  procedureCodes: string[];
  requestedService: string;
};

async function underwriteCase(caseData: UnderwritingCase) {
  const index = await buildIndex();
  const queryEngine = index.asQueryEngine({
    similarityTopK: 3,
    llm: new OpenAI({ model: "gpt-4o-mini" }),
  });

  const prompt = `
You are a healthcare underwriting assistant.
Use only the retrieved policy content.
Return:
1. Recommendation: approve | deny | request_more_info
2. Reasoning
3. Citations
4. Missing information if any

Case:
- State: ${caseData.state}
- Diagnosis codes: ${caseData.diagnosisCodes.join(", ")}
- Procedure codes: ${caseData.procedureCodes.join(", ")}
- Requested service: ${caseData.requestedService}
`;

  const response = await queryEngine.query({ queryStr: prompt });

  console.log(response.response);
}

underwriteCase({
  memberId: "M12345",
  state: "NY",
  diagnosisCodes: ["C50.911"],
  procedureCodes: ["77067"],
  requestedService: "Advanced imaging prior authorization review",
});

This gives you an auditable path from request to answer. In production you should also persist response.sourceNodes so reviewers can inspect which passages influenced the result.

4) Add a simple audit trail around every decision

Healthcare underwriting needs traceability. Store inputs, retrieved sources, model output, and final human decision in an append-only log or database table.

type AuditRecord = {
  memberId: string;
  timestamp: string;
  inputHash?: string;
  recommendation?: string;
};

async function writeAudit(record: AuditRecord) {
  // Replace with your DB or event stream.
  console.log(JSON.stringify(record));
}

Pair this with redaction before logging raw case payloads. Keep PHI out of general application logs unless your retention policy explicitly allows it.

Production Considerations

• •

  Deployment isolation

  • •Run the agent in a private network segment with restricted egress.
  • •Keep PHI-bearing workloads inside your compliant cloud region to satisfy data residency requirements.
• •

  Monitoring

  • •Track retrieval quality metrics like top-k hit rate and citation coverage.
  • •Alert on empty retrievals, low-confidence outputs, or cases where the model returns a decision without citations.
• •

  Guardrails

  • •Enforce document scoping by jurisdiction and line of business before retrieval.
  • •Block unsupported recommendations such as diagnosis changes or clinical advice outside underwriting scope.
• •

  Auditability

  • •Store prompt versions alongside model versions and retrieved source IDs.
  • •Make every decision reproducible for internal QA and external review.

Common Pitfalls

1. •

   Indexing uncontrolled documents

   • •If you ingest drafts, emails, or outdated policies, the agent will surface bad guidance.
   • •Fix it by allowing only approved source systems and tagging every document with effectiveDate plus status=active.
2. •

   Letting the model decide without evidence

   • •A naked LLM response is not an underwriting decision; it is an unverified opinion.
   • •Fix it by requiring citations from response.sourceNodes before any recommendation is accepted.
3. •

   Ignoring PHI handling

   • •Logging full case payloads to standard app logs creates compliance risk fast.
   • •Fix it by redacting identifiers early and sending sensitive fields only to controlled storage with access controls and retention rules.

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.