How to Integrate LlamaIndex for wealth management with Supabase for multi-agent systems

Wealth management workflows are full of structured data, long-running conversations, and agent handoffs. LlamaIndex gives you retrieval and orchestration over financial documents, while Supabase gives you Postgres-backed state, auth, and event storage for multi-agent systems.

Put them together and you can build agents that read client portfolios, persist memory across sessions, route tasks between specialist agents, and keep an auditable trail of every decision.

Prerequisites

• •Python 3.10+
• •A Supabase project with:
  • •SUPABASE_URL
  • •SUPABASE_SERVICE_ROLE_KEY
• •A LlamaIndex setup with:
  • •llama-index
  • •a wealth-management knowledge source such as portfolio PDFs, policy docs, or market commentary
• •Optional but useful:
  • •llama-index-vector-stores-supabase
  • •llama-index-embeddings-openai or another embedding package
• •A local .env file or secret manager for credentials
• •A Supabase table for agent state and message logs

Install the packages:

pip install llama-index supabase python-dotenv
pip install llama-index-vector-stores-supabase llama-index-embeddings-openai

Integration Steps

1. •Set up Supabase connection and schema

For multi-agent systems, keep state in Postgres instead of in-memory objects. You want each agent run to be replayable, queryable, and tied to a client or household.

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

load_dotenv()

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

supabase: Client = create_client(SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY)

# Example schema assumptions:
# agent_sessions(id uuid, client_id text, agent_name text, status text, created_at timestamptz)
# agent_messages(id uuid, session_id uuid, role text, content text, created_at timestamptz)

If you want to create tables quickly:

create table if not exists agent_sessions (
  id uuid primary key default gen_random_uuid(),
  client_id text not null,
  agent_name text not null,
  status text not null default 'active',
  created_at timestamptz default now()
);

create table if not exists agent_messages (
  id uuid primary key default gen_random_uuid(),
  session_id uuid references agent_sessions(id),
  role text not null,
  content text not null,
  created_at timestamptz default now()
);

2. •Build a LlamaIndex index over wealth management documents

Use LlamaIndex to ingest client-facing documents: IPS statements, research notes, fee schedules, suitability policies, and portfolio commentary.

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.core.settings import Settings
from llama_index.embeddings.openai import OpenAIEmbedding

Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")

documents = SimpleDirectoryReader("./wealth_docs").load_data()
index = VectorStoreIndex.from_documents(documents)

query_engine = index.as_query_engine(similarity_top_k=3)
response = query_engine.query(
    "What is the firm's policy on rebalancing threshold for discretionary portfolios?"
)

print(response)

This gives your agents a retrieval layer they can call before making recommendations. In wealth management systems, that matters because the answer often lives in a policy PDF rather than a hardcoded rule.

3. •Persist agent memory in Supabase after each retrieval step

A multi-agent system needs shared memory. Store the query context and response so another agent can pick up the thread later.

from datetime import datetime

def save_agent_message(session_id: str, role: str, content: str):
    payload = {
        "session_id": session_id,
        "role": role,
        "content": content,
        "created_at": datetime.utcnow().isoformat()
    }
    return supabase.table("agent_messages").insert(payload).execute()

session = supabase.table("agent_sessions").insert({
    "client_id": "client_123",
    "agent_name": "policy-researcher",
    "status": "active"
}).execute()

session_id = session.data[0]["id"]

user_question = "Can we recommend a higher equity allocation for this retiree?"
save_agent_message(session_id, "user", user_question)

answer = query_engine.query(user_question)
save_agent_message(session_id, "assistant", str(answer))

Now the system has durable context. That is what lets one agent research policy while another drafts a client-ready summary.

4. •Use Supabase as shared state between specialist agents

A practical pattern is one orchestrator plus specialist agents: research, compliance, portfolio construction. Store task status in Supabase so any worker can claim work without stepping on another worker.

def create_task(client_id: str, task_type: str, payload: dict):
    return supabase.table("agent_sessions").insert({
        "client_id": client_id,
        "agent_name": task_type,
        "status": "queued"
    }).execute()

task = create_task("client_123", "compliance-review", {"question": user_question})
task_session_id = task.data[0]["id"]

pending = supabase.table("agent_sessions") \
    .select("*") \
    .eq("status", "queued") \
    .execute()

for row in pending.data:
    supabase.table("agent_sessions") \
        .update({"status": "processing"}) \
        .eq("id", row["id"]) \
        .execute()

This is enough to build a simple distributed queue without introducing extra infrastructure. For many internal advisory tools, that is the right tradeoff.

5. •Connect LlamaIndex retrieval results to downstream agents

Once the research agent retrieves relevant policy text from LlamaIndex, pass it to another agent through Supabase records. That second agent can generate a recommendation or check suitability constraints.

research_result = query_engine.query(
    "Summarize the firm's guidance on concentration risk for taxable accounts."
)

supabase.table("agent_messages").insert({
    "session_id": session_id,
    "role": "researcher",
    "content": str(research_result)
}).execute()

compliance_prompt = f"""
Review this guidance and flag any issues for a client proposal:

{research_result}
"""

compliance_result = query_engine.query(compliance_prompt)

supabase.table("agent_messages").insert({
    "session_id": session_id,
    "role": "compliance",
    "content": str(compliance_result)
}).execute()

That pattern keeps each agent narrow in scope while still sharing evidence through the database.

Testing the Integration

Run a simple end-to-end check: write a session to Supabase, query LlamaIndex for a wealth-management rule, then store the answer back into Postgres.

test_session = supabase.table("agent_sessions").insert({
    "client_id": "test_client",
    "agent_name": "integration-test",
    "status": "active"
}).execute()

test_session_id = test_session.data[0]["id"]

result = query_engine.query("What does the IPS say about annual portfolio review frequency?")

supabase.table("agent_messages").insert({
    "session_id": test_session_id,
    "role": "assistant",
    "content": str(result)
}).execute()

rows = supabase.table("agent_messages") \
    .select("*") \
    .eq("session_id", test_session_id) \
    .execute()

print(rows.data[-1]["content"])

Expected output:

The IPS requires an annual portfolio review...

If you get a row back from Supabase and a grounded answer from LlamaIndex over your document set, the integration is working.

Real-World Use Cases

• •

  Client portfolio review assistant

  • •One agent retrieves policy and portfolio notes from LlamaIndex.
  • •Another writes meeting prep into Supabase so advisors can review history before calls.
• •

  Compliance triage pipeline

  • •Research agents pull relevant rules from investment policy docs.
  • •Compliance agents store approvals or escalations in Supabase for auditability.
• •

  Household-level multi-agent memory

  • •A planning agent tracks goals and constraints per client household.
  • •Specialist agents reuse that state across tax planning, rebalancing, and reporting 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.