How to Build a claims processing Agent Using LlamaIndex in Python for insurance

A claims processing agent takes a first notice of loss, pulls the right policy and claim context, extracts the key facts from unstructured documents, and routes the case to the right next action. For insurance teams, that matters because most delays come from manual document triage, inconsistent intake, and poor visibility into why a claim was classified a certain way.

Architecture

• •

  Document ingestion layer

  • •Loads FNOL forms, adjuster notes, emails, PDFs, photos metadata, and policy docs.
  • •Use SimpleDirectoryReader or your own loader for S3, SharePoint, or a claims platform.
• •

  Indexing layer

  • •Builds a searchable knowledge base over policies, coverage rules, claims procedures, and historical claim examples.
  • •In LlamaIndex this is typically VectorStoreIndex.
• •

  Retrieval and reasoning layer

  • •Pulls relevant policy clauses and prior claim context for each incoming claim.
  • •Uses index.as_query_engine() or an RetrieverQueryEngine.
• •

  Extraction and normalization layer

  • •Converts free-text claim narratives into structured fields like loss date, peril type, location, estimated severity, and missing documents.
  • •Use LlamaIndex structured outputs with Pydantic models.
• •

  Decision support layer

  • •Produces next-step recommendations: request more docs, route to auto-approval queue, escalate to SIU, or assign to human adjuster.
  • •Keep this as decision support, not final adjudication.
• •

  Audit and governance layer

  • •Stores prompt inputs, retrieved context, outputs, model version, and timestamps for compliance review.
  • •Required for explainability, dispute handling, and regulator audits.

Implementation

1) Load policy and claims knowledge into an index

Start by indexing only the content you want the agent to cite. For insurance workflows that means policy wordings, claims handling playbooks, coverage matrices, and approved SOPs.

from llama_index.core import VectorStoreIndex
from llama_index.core import SimpleDirectoryReader

# Example local corpus:
# ./data/policies/
# ./data/claims_playbooks/

documents = SimpleDirectoryReader(
    input_dir="./data",
    recursive=True
).load_data()

index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine(similarity_top_k=4)

This gives you a retrieval layer that can answer questions like:

• •“Does this water damage claim require proof of sudden discharge?”
• •“What documents are missing for commercial property loss?”

2) Extract structured claim data with a Pydantic model

For claims processing you want deterministic fields back from the model. LlamaIndex supports structured prediction through as_structured_llm() on an LLM object.

from pydantic import BaseModel
from typing import Optional
from llama_index.llms.openai import OpenAI

class ClaimIntake(BaseModel):
    claimant_name: Optional[str]
    policy_number: Optional[str]
    loss_date: Optional[str]
    loss_type: Optional[str]
    location: Optional[str]
    description: str
    missing_documents: list[str]

llm = OpenAI(model="gpt-4o-mini")
structured_llm = llm.as_structured_llm(ClaimIntake)

intake_text = """
Policy number: POL-88321
Claimant: Jordan Lee
Loss date: 2026-03-14
Reported issue: kitchen fire after grease flare-up.
Address: 18 Cedar Ave
Missing docs: photos of damage, repair estimate
"""

claim = structured_llm.complete(
    f"Extract structured insurance claim intake data from this text:\n\n{intake_text}"
)

print(claim)

This is the pattern you want when downstream systems need clean fields for routing rules or workflow automation.

3) Build a retrieval-backed decision step

Now combine extracted intake with retrieved policy context. This lets the agent explain why it recommended a path instead of guessing from the raw narrative alone.

from llama_index.core.prompts import PromptTemplate

prompt = PromptTemplate(
    """
You are a claims triage assistant for an insurance carrier.

Claim intake:
{claim_intake}

Relevant policy / claims guidance:
{context}

Task:
1. Determine whether more information is needed.
2. Recommend one of: request_docs, route_to_adjuster, escalate_siu_review.
3. Explain the reason in one paragraph.
4. Cite only the provided context.

Return concise output.
"""
)

claim_text = """
Policy number POL-88321. Kitchen fire after grease flare-up. Address 18 Cedar Ave.
Photos and repair estimate are missing.
"""

context_response = query_engine.query("Commercial property fire documentation requirements")
response = llm.complete(
    prompt.format(
        claim_intake=claim_text,
        context=str(context_response)
    )
)

print(response.text)

In production you would usually replace llm.complete(...) with a chat workflow or agent loop. The important part is that retrieval grounds the recommendation in approved internal guidance.

4) Add guardrails before anything reaches production workflows

Insurance needs hard controls around sensitive data and unsafe decisions. Use pre-processing filters before sending content to the model and keep humans in the approval loop for adverse outcomes.

def redact_sensitive(text: str) -> str:
    # Replace this with your DLP / PII service.
    return text.replace("SSN", "[REDACTED]").replace("DOB", "[REDACTED]")

safe_claim_text = redact_sensitive(claim_text)

guardrail_prompt = PromptTemplate(
    "Classify whether this claim should be escalated to human review.\n"
    "Return only YES or NO.\n\nClaim:\n{claim}"
)

decision = llm.complete(guardrail_prompt.format(claim=safe_claim_text))
print(decision.text.strip())

The real production version should integrate with your identity controls, DLP pipeline, and case management system before any automated action is taken.

Production Considerations

• •

  Keep PHI/PII out of unmanaged logs

  • •Claims data often includes names, addresses, medical details, vehicle VINs, bank info, and sometimes regulated health data.
  • •Log prompt metadata and document IDs; do not log raw payloads unless they are encrypted and access-controlled.
• •

  Respect data residency

  • •If your insurer operates across regions, pin storage and inference to approved jurisdictions.
  • •Your vector store should live in-region too; otherwise you can accidentally move regulated content across borders during retrieval.
• •

  Build audit trails

  • •Persist the exact retrieved chunks used for each recommendation.
  • •Store model name/version, prompt template version, timestamp, user ID/service account ID, and final action taken.
• •

  Use human-in-the-loop thresholds

  • •Auto-route low-risk completeness checks if confidence is high.
  • •Send coverage interpretation disputes, fraud indicators, bodily injury claims, or large-loss cases to adjusters/SIU reviewers.

Common Pitfalls

1. •

   Using the model as the source of truth for coverage decisions

   • •Don’t ask the LLM to interpret policy language without retrieval from approved documents.
   • •Avoid this by grounding every response in VectorStoreIndex results from controlled policy content.
2. •

   Skipping structured extraction

   • •Free-form summaries are hard to validate in downstream systems.
   • •Use Pydantic-backed extraction so fields like loss date and missing documents are machine-checkable.
3. •

   Ignoring compliance boundaries

   • •A claims agent that processes customer data without redaction or retention controls becomes a legal problem fast.
   • •Put DLP redaction in front of inference, restrict who can query what content through RBAC/ABAC policies, and keep immutable audit logs.
4. •

   Letting the agent make final adjudication calls

   • •The agent should triage and recommend actions.
   • •Final coverage denial or SIU escalation should remain under explicit business rules or human approval until your governance team signs off on automation levels.

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.