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

A claims processing agent for pension funds takes a member’s claim, gathers the required evidence, checks eligibility against plan rules, flags missing documents, and prepares a decision packet for human review. It matters because pension operations are document-heavy, rule-bound, and audit-sensitive; a bad automation layer can create compliance risk, delay payouts, or produce decisions that cannot be defended later.

Architecture

• •

  Intake layer

  • •Receives claim forms, emails, scanned PDFs, and supporting documents.
  • •Normalizes them into a structured case object with member ID, claim type, dates, and attachments.
• •

  Policy retrieval layer

  • •Pulls the relevant pension plan rules, benefit definitions, vesting rules, and jurisdiction-specific requirements.
  • •Keeps policy text versioned so every decision can be traced back to the exact rule set in force.
• •

  Validation and extraction layer

  • •Extracts entities from documents: member details, employment dates, beneficiary names, medical evidence, death certificates.
  • •Checks completeness against a checklist specific to the claim type.
• •

  Decision support layer

  • •Applies deterministic business rules first.
  • •Uses the agent only for summarization, gap detection, and drafting recommendations for human approval.
• •

  Audit and case management layer

  • •Stores prompts, tool calls, retrieved policy snippets, outputs, timestamps, and reviewer actions.
  • •Produces an immutable trail for compliance and internal audit.

Implementation

1. •

   Install CrewAI and define your case schema

   Keep the agent narrow. For pension claims you do not want a general-purpose assistant; you want a constrained workflow that extracts facts and drafts recommendations.

   pip install crewai
   

   from dataclasses import dataclass
   from typing import List
   
   @dataclass
   class ClaimCase:
       claim_id: str
       member_id: str
       claim_type: str
       jurisdiction: str
       documents: List[str]
       policy_version: str
   

2. •

   Create focused agents with explicit roles

   Use separate agents for extraction and review. In CrewAI terms that means Agent, Task, and Crew, with each agent responsible for one step only.

   from crewai import Agent
   
   extractor = Agent(
       role="Claims Document Extractor",
       goal="Extract structured facts from pension claim documents without making eligibility decisions",
       backstory=(
           "You work on pension administration. "
           "You extract dates, names, identifiers, and missing document signals."
       ),
       verbose=True,
       allow_delegation=False,
   )
   
   reviewer = Agent(
       role="Claims Policy Reviewer",
       goal="Compare extracted facts against plan rules and draft a human-review recommendation",
       backstory=(
           "You assess pension claims using supplied policy text only. "
           "You never invent missing facts."
       ),
       verbose=True,
       allow_delegation=False,
   )
   

3. •

   Define tasks that force traceability

   The key pattern is to make the extractor produce structured output first, then pass that output into the reviewer. That keeps the workflow auditable and reduces hallucination risk.

   from crewai import Task
   
   extract_task = Task(
       description=(
           "Review the attached claim documents for {claim_id}. "
           "Extract member name, member ID if present, claim type indicators, "
           "employment dates, beneficiary details if applicable, and missing documents."
       ),
       expected_output=(
           "A JSON-like summary with fields: member_name, member_id_found,"
           " claim_type_signals, key_dates, missing_documents."
       ),
       agent=extractor,
   )
   
   review_task = Task(
       description=(
           "Using the extracted facts and policy version {policy_version}, "
           "check whether the claim appears complete and identify any rule-based concerns. "
           "Do not decide approval or denial; produce a recommendation for human review."
       ),
       expected_output=(
           "A concise review memo with eligibility flags, missing evidence,"
           " cited policy points, and next action."
       ),
       agent=reviewer,
       context=[extract_task],
   )
   

4. •

   Run the crew and store outputs for audit

   For production use you should persist inputs/outputs outside the agent runtime. The snippet below shows the core orchestration pattern using Process.sequential.

   from crewai import Crew, Process
   
   def process_claim(case: ClaimCase):
       crew = Crew(
           agents=[extractor, reviewer],
           tasks=[extract_task, review_task],
           process=Process.sequential,
           verbose=True,
       )
   
       result = crew.kickoff(inputs={
           "claim_id": case.claim_id,
           "policy_version": case.policy_version,
           "jurisdiction": case.jurisdiction,
           "documents": "\n".join(case.documents),
       })
   
       return result
   
   
   if __name__ == "__main__":
       case = ClaimCase(
           claim_id="CLM-10042",
           member_id="M-77821",
           claim_type="death_benefit",
           jurisdiction="ZA",
           documents=[
               "Death certificate attached.",
               "Beneficiary form dated 2021-08-14.",
               "Member employment record from HR system.",
           ],
           policy_version="PEN-PLAN-2024-R3",
       )
   
       output = process_claim(case)
       print(output)
   

Production Considerations

• •

  Compliance first

  • •Keep the agent out of final adjudication unless your legal team has signed off.
  • •Use it for triage, extraction, completeness checks, and draft recommendations only.
  • •Every recommendation should include cited policy version and source document references.
• •

  Data residency

  • •Pension data often falls under strict residency requirements.
  • •Run model inference in-region and avoid sending raw member data to external services unless your data processing agreement explicitly allows it.
• •

  Auditability

  • •Log prompt inputs, retrieved policy snippets, task outputs, model version, timestamps, and reviewer overrides.
  • •Store these records in immutable storage so you can reconstruct why a claim moved forward or was escalated.
• •

  Guardrails

  • •Add deterministic checks before agent output is accepted: identity match thresholds, date consistency checks, benefit eligibility windows.
  • •If any high-risk field is missing or contradictory—beneficiary mismatch or invalid service dates—force human review.

Common Pitfalls

1. •

   Letting the agent make final decisions

   • •This is the fastest way to create compliance exposure.
   • •Fix it by limiting CrewAI tasks to extraction and recommendation only; keep approval/denial in a rules engine plus human sign-off.
2. •

   Feeding unversioned policy text

   • •If you do not pin plan rules to a version number you cannot defend decisions later.
   • •Fix it by storing policy_version on every case and retrieving only that exact rule set during processing.
3. •

   Skipping structured outputs

   • •Free-form summaries are hard to validate downstream.
   • •Fix it by forcing task outputs into predictable fields like missing_documents, key_dates, policy_flags`, so your workflow can branch reliably.
4. •

   Ignoring sensitive-data handling

   • •Claims files contain national IDs, medical evidence, banking details, and beneficiary information.
   • •Fix it by redacting where possible before prompts are built and by restricting logs to metadata plus hashed references when full content is not needed.

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.