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

A claims processing agent for pension funds reads incoming benefit or death-claim cases, extracts the required facts, checks them against scheme rules and policy documents, and prepares a decision packet for a human reviewer. It matters because pension operations are document-heavy, time-sensitive, and heavily regulated; the agent reduces manual triage while preserving auditability, compliance, and control.

Architecture

• •

  Ingress layer

  • •Receives claim packets from email, SFTP, or case-management APIs.
  • •Normalizes PDFs, scans, forms, and supporting documents into text.
• •

  Document extraction toolchain

  • •OCR for scanned forms.
  • •Structured extraction for identity data, dates, membership numbers, nominee details, and supporting evidence.
• •

  Policy and rules retrieval

  • •Pulls scheme rules, trust deed excerpts, KYC/AML requirements, and jurisdiction-specific pension regulations.
  • •Keeps retrieval scoped to the correct fund and region.
• •

  CrewAI workflow

  • •One agent for intake validation.
  • •One agent for rules interpretation.
  • •One agent for exception handling and escalation.
  • •A final human-review handoff step.
• •

  Audit log store

  • •Persists prompts, retrieved sources, tool calls, outputs, and decision reasons.
  • •Required for disputes, regulator queries, and internal controls.
• •

  Secure deployment boundary

  • •Keeps data residency inside approved regions.
  • •Uses private model endpoints or approved vendors only.

Implementation

1) Install the TypeScript stack

Use the CrewAI JS/TS package plus your document and storage dependencies. The exact package layout can vary by version, but the pattern below is what you want in a Node.js service.

npm install @crewai/core zod dotenv
npm install pdf-parse
npm install -D typescript tsx @types/node

Set your environment variables so the runtime knows which model endpoint to use and where to keep logs.

CREWAI_API_KEY=your_key
OPENAI_API_KEY=your_key
PENSION_FUND_ID=fund_uk_001
DATA_REGION=eu-west-2

2) Define tools for claim intake and policy lookup

In production you do not want an agent guessing from raw text alone. Give it narrow tools that return structured data from trusted sources.

import "dotenv/config";
import { z } from "zod";
import { Agent, Crew } from "@crewai/core";

type ClaimPacket = {
  claimantName: string;
  memberId: string;
  claimType: "retirement" | "death" | "ill-health";
  jurisdiction: string;
  documents: string[];
};

const claimSchema = z.object({
  claimantName: z.string().min(1),
  memberId: z.string().min(1),
  claimType: z.enum(["retirement", "death", "ill-health"]),
  jurisdiction: z.string().min(2),
});

const extractClaimTool = {
  name: "extract_claim_packet",
  description: "Extract structured claim fields from the submitted documents.",
  schema: claimSchema,
  execute: async (input: unknown): Promise<ClaimPacket> => {
    const parsed = claimSchema.parse(input);
    return {
      ...parsed,
      documents: ["application.pdf", "id-proof.pdf", "beneficiary-form.pdf"],
    };
  },
};

const getSchemeRulesTool = {
  name: "get_scheme_rules",
  description: "Fetch the applicable pension scheme rules for a given jurisdiction.",
  schema: z.object({
    jurisdiction: z.string(),
    claimType: z.enum(["retirement", "death", "ill-health"]),
    fundId: z.string(),
  }),
  execute: async ({ jurisdiction, claimType }: any) => {
    return `Rules for ${jurisdiction} / ${claimType}: verify identity, validate entitlement date,
    check nomination status where applicable, confirm tax treatment with local policy,
    escalate if missing mandatory evidence.`;
  },
};

3) Create specialized agents and wire them into a crew

Keep each agent narrow. Pension workflows fail when one general-purpose agent tries to do extraction, legal interpretation, fraud screening, and customer messaging in one pass.

const intakeAgent = new Agent({
  role: "Claims Intake Analyst",
  goal: "Validate incoming pension claims and structure the case file.",
  backstory:
    "You process pension claims with strict attention to completeness, identity checks, and missing evidence.",
});

const rulesAgent = new Agent({
  role: "Pension Rules Analyst",
  goal: "Assess the claim against scheme rules and identify compliance gaps.",
});

const escalationAgent = new Agent({
  role: "Exception Handler",
  goal:
    "Flag ambiguous or high-risk cases for human review with a concise reasoned summary.",
});

const crew = new Crew({
  agents: [intakeAgent as any, rulesAgent as any, escalationAgent as any],
});

4) Run the workflow and produce an auditable output

The output should be a decision packet, not an automated approval. For pension funds you need traceable reasoning plus source references that can be reviewed later.

async function processClaim(rawInput: unknown) {
  const structuredClaim = await extractClaimTool.execute(rawInput);

  
 const rulesText = await getSchemeRulesTool.execute({
    jurisdiction: structuredClaim.jurisdiction,
    claimType: structuredClaim.claimType,
    fundId: process.env.PENSION_FUND_ID!,
 });

 const task = {
    description:
      `Review this pension claim:\n` +
      `Member ID: ${structuredClaim.memberId}\n` +
      `Claimant Name: ${structuredClaim.claimantName}\n` +
      `Claim Type: ${structuredClaim.claimType}\n` +
      `Jurisdiction: ${structuredClaim.jurisdiction}\n\n` +
      `Applicable Rules:\n${rulesText}\n\n` +
      `Return:\n` +
      `1. completeness_status\n2. compliance_risks\n3. required_missing_documents\n4. recommend_human_action`,
    expectedOutput:
      "A concise decision packet suitable for operations review.",
    agent: rulesAgent as any,
   };

 const result = await crew.kickoff({
   tasks: [task as any],
 });

 return {
   caseId: crypto.randomUUID(),
   structuredClaim,
   result,
   auditTrail: {
     fundId: process.env.PENSION_FUND_ID!,
     region: process.env.DATA_REGION!,
     timestampUtc: new Date().toISOString(),
   },
 };
}

processClaim({
 claimantName:"Jane Doe",
 memberId:"M123456",
 claimType:"death",
 jurisdiction:"UK",
}).then(console.log);

Production Considerations

• •Data residency

Keep all PII inside the approved region. If your fund operates in the UK or EU, pin storage, vector indexes, logs, and model endpoints to those regions only.

• •Auditability

Persist every input document hash, extracted field set, retrieved rule snippet, tool call result, and final recommendation. Pension administrators need a full chain of evidence when a beneficiary disputes a decision.

• •Guardrails

Do not allow direct auto-approval on first pass. Require human sign-off for death benefits, ill-health claims, tax-sensitive outcomes, missing nominee data, or any case with conflicting identity signals.

• •Monitoring

Track extraction accuracy by document type, escalation rate by scheme segment, average review latency, and false-positive compliance flags. A spike in exceptions often means your source docs changed or your retrieval scope drifted.

Common Pitfalls

• •Using one generic agent for everything

This creates sloppy reasoning and weak controls. Split intake validation from rules interpretation so each step has a clear responsibility.

• •Letting the model infer missing facts

If a birth date or beneficiary relationship is absent from source documents, treat it as missing evidence. Never let the agent “fill in” pension data from context or prior cases.

• •Ignoring jurisdiction-specific policy

A retirement claim in one country can have different tax treatment or documentary requirements in another. Always scope retrieval by fund ID plus jurisdiction before asking the agent to reason.

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.