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

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
│   ├── 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

Getting Started

Agent-TS

Gateway

Wallet-Core

Concepts

Overview

Agent-TS Overview

Purpose

WhatsApp Integration

Wallet Operations

KYC Processing

Natural Language

Key Features

OpenAI Function Calling

Available Operations

KYC Fraud Detection

Architecture

User Flow

Quick Start

Prerequisites

Installation

Docker

Project Structure

Next Steps

Configuration

Tools Reference

KYC Validation

Webhooks

​Agent-TS Overview

​Purpose

WhatsApp Integration

Wallet Operations

KYC Processing

Natural Language

​Key Features

​OpenAI Function Calling

​Available Operations

​KYC Fraud Detection

​Architecture

​User Flow

​Quick Start

​Prerequisites

​Installation

​Docker

​Project Structure

​Next Steps

Configuration

Tools Reference

KYC Validation

Webhooks

Agent-TS Overview

Purpose

Key Features

OpenAI Function Calling

Available Operations

KYC Fraud Detection

Architecture

User Flow

Quick Start

Prerequisites

Installation

Docker

Project Structure

Next Steps