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

A claims processing agent for pension funds takes in member requests, supporting documents, and policy rules, then routes each claim through validation, retrieval, review, and decision support. It matters because pension operations are document-heavy, compliance-sensitive, and expensive to handle manually; the agent reduces turnaround time without turning the fund into a black box.

Architecture

• •

  Claim intake layer

  • •Accepts PDFs, scanned forms, emails, and structured claim payloads.
  • •Normalizes everything into a single claim object with member ID, claim type, dates, and attachments.
• •

  Document ingestion and indexing

  • •Uses LlamaIndex to parse policy manuals, benefit rules, scheme trust deeds, and historical claim decisions.
  • •Stores chunked text in a vector index for retrieval during review.
• •

  Policy retrieval engine

  • •Pulls the exact clauses relevant to a claim.
  • •Grounds every recommendation in source documents so compliance teams can audit the reasoning.
• •

  Decision support workflow

  • •Checks eligibility, missing documents, exceptions, and escalation thresholds.
  • •Produces a structured recommendation: approve, reject, or escalate.
• •

  Audit logging layer

  • •Records inputs, retrieved sources, model output, and final human action.
  • •Required for pension fund governance and post-incident review.
• •

  Human-in-the-loop review

  • •Sends borderline claims to an operations officer or compliance reviewer.
  • •Prevents the agent from making final decisions on high-risk cases.

Implementation

1. Install dependencies and load policy documents

Use LlamaIndex for document loading and indexing. For production claims systems, keep policy files in a controlled repository or object store with versioning so you can prove which rule set was used for each decision.

pip install llama-index llama-index-llms-openai pydantic

from llama_index.core import SimpleDirectoryReader, VectorStoreIndex
from llama_index.core.settings import Settings
from llama_index.llms.openai import OpenAI

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

# Load pension scheme rules, claims SOPs, and benefit manuals
documents = SimpleDirectoryReader(
    input_dir="./pension_policy_docs",
    required_exts=[".pdf", ".txt", ".md"]
).load_data()

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

2. Define a structured claim schema

Claims need structure before you ask an LLM to reason over them. Use Pydantic so your upstream API rejects incomplete requests before they hit retrieval or generation.

from pydantic import BaseModel
from typing import List, Optional

class ClaimRequest(BaseModel):
    claim_id: str
    member_id: str
    claim_type: str  # e.g. "retirement", "death_benefit", "disability"
    scheme_name: str
    submission_date: str
    supporting_docs: List[str]
    notes: Optional[str] = None

3. Build the agent workflow with retrieval + grounded output

This pattern uses QueryEngine for policy lookup and as_query_engine() for grounded answers. In practice you wrap this in your service layer so each request is logged with retrieved sources and timestamps.

from datetime import datetime

def process_claim(claim: ClaimRequest) -> dict:
    prompt = f"""
You are assisting with a pension fund claims review.

Claim details:
- Claim ID: {claim.claim_id}
- Member ID: {claim.member_id}
- Claim type: {claim.claim_type}
- Scheme: {claim.scheme_name}
- Submission date: {claim.submission_date}
- Supporting docs: {', '.join(claim.supporting_docs)}
- Notes: {claim.notes or 'None'}

Task:
1. Check eligibility criteria.
2. Identify missing documents.
3. Flag compliance or exception risks.
4. Return one of: APPROVE_FOR_REVIEW, ESCALATE, REJECT_PRELIMINARY.
5. Cite the policy basis from retrieved documents.
"""

    response = query_engine.query(prompt)

    return {
        "claim_id": claim.claim_id,
        "processed_at": datetime.utcnow().isoformat(),
        "recommendation": str(response),
        "policy_sources": [node.node.metadata.get("file_name") for node in response.source_nodes],
    }

4. Add human review thresholds

Do not let the model finalize payouts or denials for edge cases. Use deterministic rules to escalate claims involving deceased members, disability exceptions, disputed service history, or missing identity verification.

HIGH_RISK_CLAIM_TYPES = {"death_benefit", "disability"}
REQUIRED_DOCS = {
    "retirement": {"id_document", "bank_proof"},
    "death_benefit": {"death_certificate", "beneficiary_id"},
}

def needs_human_review(claim: ClaimRequest) -> bool:
    docs = set(claim.supporting_docs)
    missing = REQUIRED_DOCS.get(claim.claim_type, set()) - docs

    return (
        claim.claim_type in HIGH_RISK_CLAIM_TYPES
        or len(missing) > 0
        or claim.notes is not None and "dispute" in claim.notes.lower()
    )

Production Considerations

• •

  Deployment isolation

  • •Run the agent inside the fund’s approved cloud region or on-prem environment.
  • •Pension data often has residency constraints; do not ship member records to unmanaged third-party endpoints.
• •

  Monitoring and auditability

  • •Log every prompt, retrieved chunk IDs, source filenames, model version, and final action.
  • •Keep immutable audit trails so compliance can reconstruct why a recommendation was made.
• •

  Guardrails

  • •Enforce schema validation before inference.
  • •Block unsupported actions like “approve payment” unless a human reviewer signs off.
• •

  Access control

  • •Restrict retrieval indexes by scheme or business unit.
  • •Claims officers should only see documents they are authorized to access.

Common Pitfalls

1. •

   Using unstructured prompts without schema validation

   • •This leads to malformed claims data and inconsistent outputs.
   • •Fix it by validating every request with Pydantic before calling LlamaIndex.
2. •

   Retrieving from all pension documents at once

   • •That creates noisy context and increases the chance of wrong citations.
   • •Fix it by separating indexes per scheme type or document class.
3. •

   Letting the agent make final decisions on sensitive claims

   • •Pension claims often involve legal exceptions and beneficiary disputes.
   • •Fix it by routing high-risk cases to human review with explicit escalation rules.
4. •

   Ignoring source traceability

   • •If you cannot show which rule informed the recommendation, compliance will reject the system.
   • •Fix it by storing source_nodes, document versions, and timestamps with every case record.

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.