How to Build a transaction monitoring Agent Using CrewAI in TypeScript for payments

A transaction monitoring agent watches payment events, scores them for risk, and routes suspicious activity for review before money moves or gets settled. For payments teams, that matters because you need fast decisions without losing auditability, compliance coverage, or control over false positives.

Architecture

• •

  Event ingestion layer

  • •Pulls transactions from Kafka, SQS, webhooks, or a payments API.
  • •Normalizes fields like amount, currency, merchant category, card-present flag, country, and customer history.
• •

  Risk enrichment layer

  • •Adds context from internal systems: customer profile, velocity checks, device fingerprint, chargeback history, sanctions hits.
  • •Keeps the agent from making decisions on raw transaction data alone.
• •

  CrewAI agent layer

  • •Uses a Crew with specialized Agent roles:
    • •transaction_monitor
    • •compliance_reviewer
    • •case_summarizer
  • •Each agent handles one job instead of one giant prompt doing everything.
• •

  Tooling layer

  • •Exposes tools for lookup and action:
    • •transaction history lookup
    • •sanctions screening
    • •rule engine evaluation
    • •case creation in your fraud queue
  • •In CrewAI TypeScript, these are implemented as tools the agent can call during task execution.
• •

  Decision and audit layer

  • •Produces a structured output: approve, hold, or escalate.
  • •Stores the rationale, inputs used, model version, and timestamps for audit trails.

Implementation

1) Install CrewAI and define your transaction schema

Start with a strict transaction shape. Payments systems break when agents infer missing fields or accept loose JSON.

npm install @crew-ai/crewai zod

import { z } from "zod";

export const TransactionSchema = z.object({
  transactionId: z.string(),
  accountId: z.string(),
  amount: z.number().positive(),
  currency: z.string().length(3),
  country: z.string().length(2),
  merchantCategory: z.string(),
  cardPresent: z.boolean(),
  timestamp: z.string(),
  deviceId: z.string().optional(),
});

export type Transaction = z.infer<typeof TransactionSchema>;

This schema is your first guardrail. If the event is malformed, reject it before the agent sees it.

2) Build tools for enrichment and case creation

CrewAI agents should not guess at compliance facts. Give them tools that query your systems of record.

import { Tool } from "@crew-ai/crewai";

export const getCustomerVelocityTool = new Tool({
  name: "get_customer_velocity",
  description: "Fetch recent transaction velocity for an account",
  func: async ({ accountId }: { accountId: string }) => {
    // Replace with real DB/API call
    return {
      txCount24h: 18,
      totalAmount24h: 12400,
      countries24h: ["US", "GB"],
    };
  },
});

export const screenSanctionsTool = new Tool({
  name: "screen_sanctions",
  description: "Check whether the merchant or customer matches sanctions lists",
  func: async ({ accountId }: { accountId: string }) => {
    return {
      hit: false,
      listNames: [],
      screenedAt: new Date().toISOString(),
    };
  },
});

export const createCaseTool = new Tool({
  name: "create_case",
  description: "Create an AML/fraud review case in the investigation system",
  func: async (input: { transactionId: string; reason: string }) => {
    return {
      caseId: `CASE-${input.transactionId}`,
      status: "open",
      reason: input.reason,
    };
  },
});

Keep these tools deterministic. The agent can interpret data; your tools should fetch facts.

3) Define agents and tasks with explicit outputs

Use separate agents for risk analysis and compliance review. That keeps the prompt narrow and makes audits easier.

import { Agent, Task, Crew } from "@crew-ai/crewai";
import { getCustomerVelocityTool, screenSanctionsTool, createCaseTool } from "./tools";

const monitorAgent = new Agent({
  role: "Transaction Monitor",
  goal:
    "Assess payment transactions for fraud and AML risk using provided tools and return a structured decision.",
  backstory:
    "You monitor card and bank payment flows for unusual patterns, policy breaches, and compliance triggers.",
});

const complianceAgent = new Agent({
  role: "Compliance Reviewer",
  goal:
    "Validate whether a transaction should be escalated based on sanctions, jurisdictional rules, and audit requirements.",
});

monitorAgent.tools = [getCustomerVelocityTool];
complianceAgent.tools = [screenSanctionsTool, createCaseTool];

const assessTask = new Task({
  description:
    "Analyze this payment transaction and decide approve, hold, or escalate. Return JSON with decision, reason codes, and required actions.",
});

const reviewTask = new Task({
  description:
    "Review the monitoring result for compliance impact. If needed create a case and return final disposition.",
});

const crew = new Crew({
  agents: [monitorAgent, complianceAgent],
  tasks: [assessTask, reviewTask],
});

The key pattern here is separation of concerns. Monitoring finds anomalies; compliance decides whether those anomalies require escalation under policy.

4) Run the crew on validated events and persist an audit trail

Wrap execution in a service that validates input first and stores every decision after execution.

import { TransactionSchema } from "./schema";
import { crew } from "./crew";

export async function processTransaction(eventPayload: unknown) {
  const tx = TransactionSchema.parse(eventPayload);

  
 
 

  
  

  
  

  
  
  

  
  

  
  
  

  
  
  

  
  
  

  
  
  

  
  
  

  
  
  

  
  
  
 

  
  

  
  
  

  

  
  

  

  

  

  

  

  

  

  
  

  

  

  
  

  

  

  

  

  

  

  

  
  

  



  

  
  

  
  



 
 



 



const result = await crew.kickoff({
    inputs: {
      transactionId: tx.transactionId,
      accountId: tx.accountId,
      amount: tx.amount,
      currencyCodeTypeCurrencyCodeCurrencyCodeCurrencyCodeCurrencyCodeCurrencyCodeCurrencyCodeCurrencyCodeCurrencyCodeCurrencyCodeCurrencyCodeCurrencyCodeCurrencyCodeCurrencyCodeCurrencyCodeCurrencyCodeCountryCountryCountryCountryCountryCountryCountryCountryCountryCountryCountryCountryCountryCountryCountryCountryMerchantCategoryMerchantCategoryMerchantCategoryMerchantCategoryMerchantCategoryMerchantCategoryMerchantCategoryMerchantCategoryCardPresentCardPresentCardPresentCardPresentCardPresentCardPresentCardPresentCardPresentTimestampTimestampTimestampTimestampTimestampTimestampTimestampTimestampDeviceDeviceDeviceDeviceDeviceDeviceDeviceDeviceDeviceDevice?: tx.deviceId,
      countryNameNameNameNameNameNameNameNameNameNameNameNameNameNameNameNameNameName?: tx.country,
      
      
      
      
      
      
      
      
      
      
      
      
      
      

      
      

    
    

    
    

    
    

    
    

    
    

    
    

    
    

    
    
    
    
    
    

    
    
    
    
    
      

    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
}
});
}

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.