Skip to content

AI Agent Module

Overview

The AI Agent is a conversational assistant for the banking platform. It helps staff with:

  • Customer KYC: Look up customer profile and KYC details by customer/identity ID.
  • Transactions: Look up transaction history or a specific transaction by ID or reference.
  • Customer onboarding: Step-by-step guidance for onboarding new customers (registration, staging, approval).

The agent uses an LLM (OpenAI-compatible API) with function calling (tools) so that it can call existing platform APIs (customer, transaction) on behalf of the user. All actions run with the current user’s permissions; the agent does not bypass access control.

Configuration

Environment variable Description Default
OPENAI_API_KEY OpenAI API key (required for LLM) ""
OPENAI_MODEL Model name (e.g. gpt-4o, gpt-4o-mini) gpt-4o-mini

If OPENAI_API_KEY is not set, the agent responds with a message that it is not configured; no LLM calls are made.

Permission

  • ai_agent: Required to call the chat endpoint. Assign this permission to roles that should use the AI agent.

API

POST /api/v1/ai-agent/chat

Sends a message to the AI agent and returns the assistant’s reply.

Note: this endpoint is still supported but the UI now uses a WebSocket connection for chat. See WebSocket Support below.

Request body

{
  "messages": [
    { "role": "user", "content": "What is the KYC status for customer 123?" }
  ]
}

For multi-turn conversations, include previous messages:

{
  "messages": [
    { "role": "user", "content": "List customers named John" },
    { "role": "assistant", "content": "Here are the customers..." },
    { "role": "user", "content": "Show me full details for the first one" }
  ]
}

Response

{
  "message": "Assistant reply text...",
  "tool_calls_used": ["get_customer_kyc"]
}

Tools (capabilities)

The agent can call these tools automatically when the user asks for data or guidance:

Customer & Transactions

Tool Description
get_customer_kyc Full customer KYC/profile by identity_id (customer id).
list_customers Search or list customers with optional search_string, page_size, page_number.
get_transactions Transaction list with optional filters (pagination, reference_id, status, etc.).
get_transaction_by_id Single transaction by numeric id or reference_id.

Loan Products & Applications

Tool Description
get_loan Full loan details by loan_id.
list_loans Search or list loans with filters (status, borrower, product).
get_loan_application Loan application details by application_id.
list_loan_applications Search or list loan applications with filters.
get_loan_product Loan product details by product_id.
list_loan_products Search or list loan products.

Loan Management & Details (NEW)

Tool Description
get_loan_repayments Get repayment history for a specific loan.
get_loan_installments Get installment schedule for a specific loan with payment dates and amounts.
get_loan_balance Get current loan balance, outstanding amount, and repayment status.
list_collection_cases Get collection cases and actions for a specific loan.
get_loan_score_history Get loan scoring history for a specific customer (borrower).
get_blacklist_status Check if a customer is blacklisted for loans and get blacklist details.

Staff & Organization

Tool Description
get_agent_info Full agent details by agent_id (identity id).
list_agents Search or list agents with optional filters.
get_store_info Store details by store_id.
list_stores Search or list stores with optional filters.
get_operator_info Operator details by operator_id (identity id).
list_operators Search or list operators with optional filters.

Transaction Insights

Tool Description
get_failed_transactions Fetch failed transactions with optional pagination.
get_suspicious_transactions Fetch suspicious transactions with risk score filtering.
get_reconciliation_reports Fetch daily reconciliation reports.

Onboarding

Tool Description
customer_onboarding_guide Step-by-step guidance for customer onboarding.

WebSocket Support

The chat UI opens a WebSocket connection to /ws using the same JWT token used for REST calls. Once connected the following event types are supported:

  • Client → Server 

    {
  "event_type": "chat_message",
  "data": { "message": "Hello", "conversation_id": "123" }
}
    conversation_id is optional; if omitted a new conversation is created.

  • Server → Client 

    {
  "event_type": "chat_response",
  "data": { "message": "...assistant text...", "conversation_id": 123 }
}
    In case of errors the server will emit chat_error with an { error: "..."} payload.

The websocket supports two additional request/response patterns for conversation management:

  • Client → Server (fetch list) 
    { "event_type": "fetch_conversations", "data": { "offset": 0, "limit": 20 } }

  • Server → Client 

    {
  "event_type": "conversations_list",
  "data": { "total": 5, "conversations": [ /* items */ ], "offset": 0, "limit": 20 }
}
    On failure the server sends conversations_error with an { error: "..." } payload.

  • Client → Server (get single conversation) 

    { "event_type": "get_conversation", "data": { "conversation_id": 123, "limit": 50 } }

  • Server → Client 
    {
  "event_type": "conversation_details",
  "data": { /* full conversation object with messages */ }
}
    Errors are returned using conversation_error.

The WebSocket handler resides in routers/socket.py alongside other real‑time events. This mechanism allows low‑latency chat without additional HTTP round trips.

Loan Scoring Workflow (NEW)

Tool Description
start_loan_scoring_workflow Interactive multi-step workflow for loan scoring evaluation. Takes customer through: customer search/validation, product selection, amount entry, and final score calculation.

Example prompts

  • “What is the KYC status for customer 123?”
  • “List the last 10 transactions.”
  • “Show me transaction with reference REF-001.”
  • “Search for customers named Mary.”
  • "How do I onboard a new customer?"
  • "Show me the repayment history for loan 456." (NEW)
  • "What is the outstanding balance for loan 789?" (NEW)
  • "List all collection cases for customer 123's loans." (NEW)
  • "Is customer 456 blacklisted?" (NEW)
  • "Get the loan score history for customer 789." (NEW)
  • "I want to do a loan scoring for customer 123." (NEW - initiates workflow)
  • "Let me check if customer 456 qualifies for a loan." (NEW - initiates workflow)
  • "Start a loan scoring process for customer 789 with product 5 and amount 50000." (NEW - complete workflow in one call)

Implementation notes

  • Controller: controller/ai_agent.py — system prompt, tool definitions, execute_tool / execute_tool_async, chat_with_tools.
  • Router: routers/ai_agent.py — POST /chat with permission ai_agent.
  • Schemas: db/schemas.py — AgentChatMessage, AgentChatRequest, AgentChatResponse.

The agent reuses existing business logic (e.g. get_both_customer_by_id_response, fetch_customer, fetch_transactions, get_transaction_by_id) so that results and permissions stay consistent with the rest of the platform.