Agentic AI · Retail Banking

System Architecture

A personal finance advisor built on an orchestrator + specialists pattern. Mock-first and swap-ready — the same topology accepts a real LLM or LangGraph with no restructure.

4 agents Star topology Typed contracts FastAPI + vanilla JS

Topology

Web UI
chat · HTML / JS
POST /chat {message, session_id}
FastAPI backend
Planner — Orchestrator
parse → plan → route → branch → merge
Spending
anomaly >20% MoM
Recommendation
profile-scaled ₹
Alerting
budget ≥90%
Tool layer — mock APIs
get_transactions · get_categories · get_budgets · get_balance
Mock data store
JSON transactions
Memory (session)Planner read/write — conversation history · result cache · user profile

Components

ComponentRole
PlannerSpine. Classify intent → build plan → sequence specialists → branch on results → merge FinalResponse.
Spending AnalysisCategorize transactions, compute month-over-month trend, flag anomaly (>20% MoM). The in-depth agent.
RecommendationTarget high categories, estimate ₹ saved. Aggressiveness scales to profile.risk_pref.
AlertingScan every category against budget. Flag breach / near-breach (≥90%).
Tool layerTyped mock APIs. Agents never touch the store directly. Shaped like LLM function-calls.
MemorySession history + result cache + user profile. In-memory.

Control flow

  1. UI POSTs the message → FastAPI → Planner.
  2. Planner classifies intent → candidate plan.
  3. Spending runs first — run(query, profile).
  4. Planner branches on the result: Alerting runs only on anomaly / near-breach; Recommendation is skipped if nothing is reducible.
  5. Specialists return typed contracts → Planner merges → FinalResponse.
  6. Planner saves the turn to memory. UI renders cards + agent trace.

Routing

IntentExecution plan
IMPROVE_SAVINGSspending → recommend → alert
SPENDING_SUMMARYspending
BUDGET_STATUSalert (+ spending for context)
WHY_OVERSPENTspending → alert → recommend
GENERAL_ADVICEspending → recommend
GREETING / UNKNOWNdirect reply, no agents

First-match-wins keyword routing. The same interface accepts an LLM classifier later.

Why this architecture

Orchestrator owns control flow

Specialists never call each other → acyclic, debuggable star topology.

Typed contracts

Dataclasses, not free text → testable and predictable.

Mock-first, swap-ready

Rule-based reason() now; maps 1:1 to LangGraph nodes/edges. A real model drops in with zero restructure.

Data-dependent autonomy

Executed steps depend on the agent's own output → reasoned, not a fixed pipeline.

One file per agent

Parallel build seams; fully modular.

Rejected alternatives: monolith (fails the multi-agent requirement, no visible orchestration) · peer-to-peer agents (cycles, coordination tax) · real LLM now (no key, 1-hour budget).

Extensibility

LLM
Replace reason() / classify_intent() with a Claude tool-calling loop.
LangGraph
Planner = graph · agents = nodes · routing table = conditional edges.
Persistence
Swap in-memory state + JSON store for a database.