How to Integrate LlamaIndex for retail banking with Supabase for startups

Retail banking agents need two things: grounded answers and durable state. LlamaIndex gives you the retrieval layer for policies, product docs, and customer context; Supabase gives you Postgres-backed storage for conversations, audit trails, and workflow state.

For startups building bank-facing AI agents, this combo is the difference between a demo and something you can actually ship.

Prerequisites

• •Python 3.10+
• •A Supabase project with:
  • •SUPABASE_URL
  • •SUPABASE_SERVICE_ROLE_KEY or anon key for limited access
• •A LlamaIndex setup with:
  • •llama-index
  • •an embedding model configured
  • •a chat LLM configured
• •Retail banking documents to index:
  • •FAQs
  • •fee schedules
  • •KYC/AML policy docs
  • •product terms
• •Basic knowledge of:
  • •SQL tables in Supabase
  • •Python async/sync clients

Install the packages:

pip install llama-index supabase python-dotenv

Integration Steps

1) Connect to Supabase and create a storage table

Use Supabase as the system of record for agent sessions, retrieved passages, and traceability.

import os
from dotenv import load_dotenv
from supabase import create_client, Client

load_dotenv()

SUPABASE_URL = os.environ["SUPABASE_URL"]
SUPABASE_KEY = os.environ["SUPABASE_SERVICE_ROLE_KEY"]

supabase: Client = create_client(SUPABASE_URL, SUPABASE_KEY)

# Example table schema expected:
# agent_sessions(id uuid primary key, user_id text, query text, response text, created_at timestamptz default now())
print("Supabase client ready")

Create the table once in Supabase SQL editor:

create table if not exists agent_sessions (
  id uuid primary key default gen_random_uuid(),
  user_id text not null,
  query text not null,
  response text not null,
  created_at timestamptz default now()
);

2) Load retail banking documents into LlamaIndex

This example indexes local policy files. In production, swap this for a document pipeline from S3, SharePoint, or your CMS.

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

docs = SimpleDirectoryReader("./retail_banking_docs").load_data()
index = VectorStoreIndex.from_documents(docs)

query_engine = index.as_query_engine(similarity_top_k=3)
print("LlamaIndex vector index built")

If you are using OpenAI-backed models, configure them explicitly:

from llama_index.core import Settings
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding

Settings.llm = OpenAI(model="gpt-4o-mini")
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")

3) Build an agent function that queries LlamaIndex and writes to Supabase

This is the core integration pattern. Retrieve context from banking docs first, then persist the interaction in Supabase.

import uuid

def answer_banking_question(user_id: str, question: str) -> str:
    # Retrieve grounded context from indexed banking docs
    result = query_engine.query(question)
    answer = str(result)

    # Persist request/response for auditability and follow-up workflows
    supabase.table("agent_sessions").insert({
        "id": str(uuid.uuid4()),
        "user_id": user_id,
        "query": question,
        "response": answer,
    }).execute()

    return answer

response = answer_banking_question(
    user_id="cust_123",
    question="What is the overdraft fee on the checking account?"
)

print(response)

This pattern works well because retrieval stays in LlamaIndex while persistence stays in Postgres. Don’t mix those responsibilities unless you want a brittle agent.

4) Add metadata filtering for banking-specific routing

Retail banking usually has multiple product lines. Use metadata filters so your agent answers from the right corpus instead of blending credit card terms with deposit account terms.

from llama_index.core.schema import MetadataMode

# If your documents include metadata like {"product": "checking"}
# build a filtered retriever for a specific line of business.
retriever = index.as_retriever(similarity_top_k=5)

nodes = retriever.retrieve("How do I dispute an ACH transfer?")
for node in nodes:
    print(node.node.get_content(metadata_mode=MetadataMode.LLMS))

If you want stricter routing, store product tags in your source docs before indexing. That lets you build separate indexes for deposits, lending, cards, or support scripts.

5) Store structured outputs for downstream workflows

For startup teams building agents that trigger ops tasks, keep structured fields in Supabase instead of only raw text.

def save_structured_case(user_id: str, question: str):
    result = query_engine.query(question)

    payload = {
        "user_id": user_id,
        "query": question,
        "response": str(result),
        "case_type": "banking_support",
        "status": "open",
    }

    supabase.table("agent_sessions").insert(payload).execute()
    return payload

case = save_structured_case("cust_456", "How do I increase my daily debit card limit?")
print(case["status"])

That makes it easy to build dashboards, escalation queues, and human review flows on top of the same data.

Testing the Integration

Run a simple end-to-end check: retrieve from indexed docs and confirm the row lands in Supabase.

test_question = "What documents are required to open a business checking account?"
answer = answer_banking_question("test_user_001", test_question)

rows = supabase.table("agent_sessions").select("*").eq("user_id", "test_user_001").limit(1).execute()

print("Answer:", answer[:200])
print("Rows returned:", len(rows.data))
print("Stored query:", rows.data[0]["query"])

Expected output:

Answer: ...grounded response from your retail banking documents...
Rows returned: 1
Stored query: What documents are required to open a business checking account?

If rows.data is empty, check:

• •table name spelling
• •service role key permissions
• •whether .execute() is being called on the insert/select chain

Real-World Use Cases

• •

  Retail banking support agent

  • •Answer fee questions, card replacement steps, branch hours, and account opening requirements from approved docs.
  • •Store every interaction in Supabase for audit logs and escalation review.
• •

  KYC/AML assistant

  • •Retrieve policy snippets for onboarding checks.
  • •Persist case notes and reviewer decisions in Supabase tables.
• •

  Ops copilot for startup banking teams

  • •Let internal staff ask questions like “Which accounts require manual verification?”
  • •Track unresolved cases in Supabase and route them into human workflows.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.