How to Build a fraud detection Agent Using LlamaIndex in TypeScript for retail banking

A fraud detection agent for retail banking triages suspicious activity, pulls the right account and transaction context, and produces a defensible recommendation for analysts or downstream automation. It matters because fraud teams need speed without losing auditability: every alert needs traceable evidence, policy-aware reasoning, and strict handling of customer data.

Architecture

• •

  Transaction ingestion layer

  • •Receives card swipes, ACH transfers, wire events, login anomalies, and device signals.
  • •Normalizes them into a consistent event schema before the agent sees them.
• •

  Retrieval layer

  • •Uses LlamaIndex to fetch relevant account history, prior alerts, KYC notes, merchant metadata, and policy documents.
  • •Keeps the model grounded in bank-owned data instead of guessing.
• •

  Fraud reasoning agent

  • •Uses an LLM through LlamaIndex’s OpenAI integration and ReActAgent.
  • •Produces a risk assessment, rationale, and next action.
• •

  Tooling layer

  • •Exposes functions like getAccountHistory, getCustomerProfile, createCase, and freezeCard.
  • •Lets the agent call bank systems instead of hallucinating actions.
• •

  Audit and compliance log

  • •Stores inputs, retrieved context IDs, tool calls, outputs, timestamps, and model version.
  • •Supports review under model risk management and regulatory audit.
• •

  Policy guardrail layer

  • •Enforces residency rules, PII redaction, threshold-based escalation, and human approval for high-risk actions.
  • •Prevents autonomous actions on sensitive cases.

Implementation

1. •Install dependencies and configure the LLM

Use the TypeScript package for LlamaIndex and wire up an OpenAI model. In banking environments, keep secrets in your vault and pin model versions in config.

import {
  OpenAI,
  ReActAgent,
  tool,
} from "llamaindex";

const llm = new OpenAI({
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY,
});

2. •Define bank tools with explicit contracts

Your agent should not “infer” account status. Give it narrow tools that hit approved services only.

type Transaction = {
  id: string;
  accountId: string;
  amount: number;
  merchant: string;
  country: string;
  timestamp: string;
};

const getAccountHistory = tool({
  name: "get_account_history",
  description: "Fetch recent transactions for a retail banking account",
  parameters: {
    type: "object",
    properties: {
      accountId: { type: "string" },
      limit: { type: "number" }
    },
    required: ["accountId"]
  },
  execute: async ({ accountId, limit }) => {
    const rows: Transaction[] = await fetchBankTransactions(accountId, limit ?? 20);
    return JSON.stringify(rows);
  }
});

const getCustomerProfile = tool({
  name: "get_customer_profile",
  description: "Fetch KYC and profile risk indicators",
  parameters: {
    type: "object",
    properties: {
      customerId: { type: "string" }
    },
    required: ["customerId"]
  },
  execute: async ({ customerId }) => {
    const profile = await fetchCustomerProfile(customerId);
    return JSON.stringify(profile);
  }
});

const createCase = tool({
  name: "create_case",
  description: "Create a fraud review case in the case management system",
  parameters: {
    type: "object",
    properties: {
      accountId: { type: "string" },
      reasonCode: { type: "string" },
      severity: { type: "string", enum: ["low", "medium", "high"] }
    },
    required: ["accountId", "reasonCode", "severity"]
  },
  execute: async (args) => {
    const caseId = await openFraudCase(args);
    return JSON.stringify({ caseId });
  }
});

3. •Build the fraud agent with ReAct

ReActAgent works well here because you want tool use plus reasoning traceability. Keep the prompt tight so the model scores risk from evidence rather than inventing narratives.

const agent = new ReActAgent({
  llm,
  tools: [getAccountHistory, getCustomerProfile, createCase],
});

async function triageFraudAlert(alertText: string) {
  const response = await agent.chat(
    `You are a retail banking fraud triage assistant.
Assess this alert using only provided tools and returned evidence.
Return:
1) risk level
2) key reasons
3) recommended action
4) whether to escalate to human review

Alert:
${alertText}`
  );

  return response.toString();
}

4. •Add retrieval for policy and historical context

For real deployments, connect policy docs and prior playbooks through LlamaIndex retrieval. This keeps decisions aligned with internal controls like card-not-present rules or wire transfer escalation thresholds.

import { VectorStoreIndex } from "llamaindex";

async function buildPolicyRetriever() {
  const index = await VectorStoreIndex.fromDocuments([
    // load docs from approved internal sources
    // e.g. fraud playbook PDFs converted to Document objects
]);
}

In practice you’ll expose a retriever-backed tool to fetch relevant policy snippets during triage. That gives analysts a citation trail for why a case was escalated.

Production Considerations

• •

  Data residency

  • •Keep customer PII inside approved regions.
  • •If your LLM endpoint is outside your residency boundary, send only redacted or tokenized fields.
• •

  Auditability

  • •Log prompt inputs, retrieved document IDs, tool invocations, output text, model version, and decision thresholds.
  • •Store immutable records so compliance can reconstruct why an alert was escalated or closed.
• •

  Human-in-the-loop controls

  • •Auto-create cases for medium-risk events.
  • •Require analyst approval before freezing cards, blocking transfers, or filing regulatory reports.
• •

  Monitoring

Common Pitfalls

• •Letting the model decide without tools

If the agent answers from memory instead of retrieving transaction history or KYC data, you’ll get confident nonsense. Force evidence-based triage with strict tools and retrieval.

• •Sending raw PII to the model

Names alone are usually fine; full account numbers, SSNs, and card PANs are not. Redact sensitive fields before prompt construction and keep reversible tokens only in internal systems.

• •Autonomous action on high-risk events

Do not let the agent freeze accounts or block wires without policy checks. Gate those actions behind deterministic rules plus analyst approval for anything above your defined severity threshold.

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.