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

A claims processing agent for lending takes in borrower-submitted claims, pulls the relevant loan, collateral, payment, and policy documents, and helps a human or downstream workflow decide what happens next. In lending, that matters because claim handling is tied to compliance, auditability, customer impact, and money movement — if the agent gets facts wrong or cannot explain its reasoning, you inherit operational and regulatory risk.

Architecture

• •

  Document ingestion layer

  • •Loads claim forms, loan agreements, insurance certificates, payoff statements, and internal policy docs.
  • •Keep sources separated by tenant and jurisdiction for data residency controls.
• •

  Indexing layer

  • •Uses VectorStoreIndex for semantic retrieval over policies and historical claims.
  • •Uses metadata filters for product type, region, borrower segment, and document version.
• •

  Claim orchestration layer

  • •A workflow or service endpoint that receives a claim ID and routes it through retrieval, extraction, validation, and decision support.
• •

  LLM reasoning layer

  • •A QueryEngine or RetrieverQueryEngine built on top of LlamaIndex to answer structured questions from the retrieved evidence.
  • •Outputs a recommendation plus cited sources.
• •

  Guardrail and audit layer

  • •Stores every prompt, retrieved chunk, model response, and final decision payload.
  • •Enforces “human review required” for low-confidence or policy-sensitive cases.
• •

  Case management integration

  • •Writes results into your lending system of record via API: approved, rejected, needs more docs, or escalated.

Implementation

1. •

   Load lending documents with metadata

   Start by loading only the document types your claims process actually uses. In lending, metadata is not optional; it is how you keep jurisdictional boundaries intact and make audit queries possible later.

from llama_index.core import SimpleDirectoryReader
from llama_index.core.schema import Document

docs = SimpleDirectoryReader(
    input_dir="./lending_docs",
    recursive=True,
).load_data()

# Add lending-specific metadata for filtering and audit
enriched_docs = []
for d in docs:
    d.metadata = {
        **(d.metadata or {}),
        "tenant_id": "bank_001",
        "jurisdiction": "us",
        "product": "auto_loan",
        "doc_type": d.metadata.get("file_name", "").split(".")[0],
        "source_system": "claims_portal",
    }
    enriched_docs.append(d)

2. •

   Build a vector index over the claim evidence

   For production claims work, VectorStoreIndex is the base pattern. It gives you semantic retrieval over policies and case history while keeping the implementation simple enough to instrument.

from llama_index.core import VectorStoreIndex
from llama_index.core.node_parser import SentenceSplitter

splitter = SentenceSplitter(chunk_size=512, chunk_overlap=64)
index = VectorStoreIndex.from_documents(
    enriched_docs,
    transformations=[splitter],
)

retriever = index.as_retriever(similarity_top_k=5)

3. •

   Create a query engine that returns evidence-backed answers

   The agent should not freewheel. It should answer only from retrieved context and return citations so an analyst can verify the result before any lending action is taken.

from llama_index.core import Settings
from llama_index.llms.openai import OpenAI
from llama_index.core.query_engine import RetrieverQueryEngine
from llama_index.core.response_synthesizers import get_response_synthesizer

Settings.llm = OpenAI(model="gpt-4o-mini", temperature=0)

response_synthesizer = get_response_synthesizer(
    response_mode="compact"
)

query_engine = RetrieverQueryEngine(
    retriever=retriever,
    response_synthesizer=response_synthesizer,
)

question = """
Given the claim documents and policy files,
does this borrower qualify for payment deferment under hardship rules?
Return the decision criteria used and cite supporting sources.
"""

response = query_engine.query(question)
print(response.response)
for source in response.source_nodes:
    print(source.node.metadata.get("file_name"), source.score)

4. •

   Wrap it in a claim-review function with structured output

   Your application should convert model output into a case record. Keep the final step deterministic: parse fields into your workflow state rather than letting free-form text drive business logic.

from dataclasses import dataclass

@dataclass
class ClaimDecision:
    status: str
    reason: str
    requires_human_review: bool

def review_claim(claim_id: str) -> ClaimDecision:
    prompt = f"""
    Review claim {claim_id}.
    Determine whether it meets deferment policy.
    If evidence is incomplete or conflicting, require human review.
    """
    result = query_engine.query(prompt)

    text = str(result.response).lower()
    if "insufficient" in text or "unclear" in text:
        return ClaimDecision(
            status="needs_more_review",
            reason=str(result.response),
            requires_human_review=True,
        )

    return ClaimDecision(
        status="recommended",
        reason=str(result.response),
        requires_human_review=True,
    )

Production Considerations

• •

  Enforce data residency at ingestion

  • •Keep EU borrower records in EU-hosted storage and indexes.
  • •Use separate indexes per jurisdiction instead of one global corpus with filters layered on top.
• •

  Log every retrieval path

  • •Store query text, retrieved node IDs, source document hashes, model version, and final recommendation.
  • •That gives you an audit trail when operations or compliance asks why a claim was escalated or approved.
• •

  Add confidence-based escalation

  • •If retrieval scores are low or policy conflicts appear across documents, route to manual review.
  • •Never let the agent auto-close claims that affect repayment terms without a human approval step.
• •

  Monitor drift in policy documents

  • •Claims agents fail when policy PDFs change but indexes do not get rebuilt.
  • •Track document freshness by product line and invalidate stale embeddings on version updates.

Common Pitfalls

• •

  Using unstructured prompts as business logic

  • •Mistake: letting the LLM decide “approved” vs “rejected” from raw text alone.
  • •Fix: require retrieved evidence plus deterministic post-processing rules before any workflow action.
• •

  Ignoring metadata during indexing

  • •Mistake: mixing all borrower documents into one index with no tenant or region tags.
  • •Fix: attach tenant_id, jurisdiction, product, and doc_type to every document and use them in retrieval strategy.
• •

  Skipping citation capture

  • •Mistake: returning only a natural language answer with no source references.
  • •Fix: always persist response.source_nodes so compliance can trace each recommendation back to policy language or case records.

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.