Skip to main content

​
Agent-TS Overview

Agent-TS is the TypeScript implementation of the OLIVE conversational agent, powered by OpenAI’s Assistant API with function calling capabilities.

​
Purpose

The agent provides an automated conversational interface for OLIVE 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

OperationDescription
check_balanceGet current wallet balance
get_transactionsView transaction history
initiate_transferSend money to another user or card
get_account_limitsCheck spending and transaction limits
get_user_cardsList linked NFC cards
link_cardActivate and link a new card
block_cardFreeze a card
unblock_cardReactivate a blocked card
upload_kyc_imageSubmit KYC document for verification
upgrade_kycComplete KYC upgrade with front/back images

​
KYC Fraud Detection

Multi-layer validation for Sierra Leone National ID cards:
  1. OpenAI Vision API - Document authenticity validation
  2. Tesseract OCR - Text extraction and tampering detection
  3. 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
│   ├── olive-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

​
Next Steps

Configuration

Environment variables and setup

Tools Reference

Complete tool documentation

KYC Validation

OCR and fraud detection details

Webhooks

WhatsApp integration setup