Overview
Agent-TS is the TypeScript implementation of the SmartPay conversational agent, powered by OpenAI's Assistant API with function calling capabilities.
Purpose
The agent provides an automated conversational interface for SmartPay mobile-money users, enabling self-service operations through natural language:
WhatsApp Integration
Handles user messages from WhatsApp Business API and external clients
Wallet Operations
Check balance, send money, view transactions, manage linked cards
KYC Processing
Upload and validate identity documents with OCR and fraud detection
Natural Language
OpenAI-powered intent recognition and response generation
Key Features
OpenAI Function Calling
The agent leverages OpenAI's function calling to execute wallet operations:
// Example: User asks "What is my balance?"
// OpenAI recognizes intent and calls check_balance function
const tools = [
{
type: "function",
function: {
name: "check_balance",
description: "Get the user's current wallet balance",
parameters: {
type: "object",
properties: {
currency: { type: "string", enum: ["SLE", "USD"] }
}
}
}
}
];
Available Operations
| Operation | Description |
|---|---|
check_balance | Get current wallet balance |
get_transactions | View transaction history |
initiate_transfer | Send money to another user or card |
get_account_limits | Check spending and transaction limits |
get_user_cards | List linked NFC cards |
link_card | Activate and link a new card |
block_card | Freeze a card |
unblock_card | Reactivate a blocked card |
upload_kyc_image | Submit KYC document for verification |
upgrade_kyc | Complete KYC upgrade with front/back images |
KYC Fraud Detection
Multi-layer validation for Sierra Leone National ID cards:
- OpenAI Vision API - Document authenticity validation
- Tesseract OCR - Text extraction and tampering detection
- Cross-Validation - Data consistency between front and back images
Architecture
User Flow
Quick Start
Prerequisites
- Node.js 18+
- OpenAI API key
- Gateway API key
- AWS credentials (for KYC document storage)
Installation
cd agent-ts
npm install
cp .env.example .env
# Edit .env with your configuration
npm run dev
Docker
docker compose up -d --build agent
Project Structure
agent-ts/
├── src/
│ ├── index.ts # Express server & webhooks
│ ├── smartpay-agent.ts # OpenAI Agent implementation
│ ├── gateway-client.ts # Gateway API client
│ ├── tools/
│ │ ├── wallet.ts # Balance, transfers
│ │ ├── cards.ts # Card operations
│ │ ├── kyc.ts # KYC upload & validation
│ │ └── registration.ts # User registration
│ ├── ocr-service.ts # Tesseract OCR
│ ├── id-card-validator.ts # Vision AI validation
│ └── s3-uploader.ts # KYC document storage
├── Dockerfile
└── package.json