How to Integrate LlamaIndex for insurance with Supabase for AI agents

Combining LlamaIndex for insurance with Supabase gives you a practical pattern for building AI agents that can retrieve policy data, claims history, and underwriting notes from indexed insurance content while persisting state, chat history, and workflow metadata in a Postgres-backed store. That means your agent can answer policy questions with grounded context and remember what happened across sessions without bolting on a separate database layer.

Prerequisites

• •Python 3.10+
• •A Supabase project with:
  • •SUPABASE_URL
  • •SUPABASE_SERVICE_ROLE_KEY or anon key for read-only access
• •A Postgres database in Supabase with tables for:
  • •documents or chunks
  • •agent sessions
  • •messages or events
• •An LLM provider configured for LlamaIndex, such as OpenAI
• •Install the required packages:

pip install llama-index supabase python-dotenv psycopg2-binary

• •Environment variables set in .env:

OPENAI_API_KEY=your_openai_key
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

Integration Steps

1. •Set up the Supabase client and connection config.

Use Supabase as the persistence layer for agent state and optionally as the source of truth for insurance records.

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

load_dotenv()

supabase_url = os.getenv("SUPABASE_URL")
supabase_key = os.getenv("SUPABASE_SERVICE_ROLE_KEY")

supabase: Client = create_client(supabase_url, supabase_key)

# quick sanity check: fetch one row from an insurance policies table
response = supabase.table("insurance_policies").select("*").limit(1).execute()
print(response.data)

2. •Build a LlamaIndex index over insurance content.

If your insurance documents live in files, ingest them into a vector index first. For production, you usually split by policy section, endorsement, claim note, or FAQ entry.

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.core.settings import Settings
from llama_index.llms.openai import OpenAI

Settings.llm = OpenAI(model="gpt-4o-mini")

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

query_engine = index.as_query_engine(similarity_top_k=3)
answer = query_engine.query("What is covered under accidental damage for home policies?")
print(answer)

3. •Persist agent memory and session metadata in Supabase.

This is the part most teams skip. Store session IDs, user IDs, last message timestamps, and summaries so your agent can resume context across channels.

from datetime import datetime

session_id = "session_123"
user_id = "user_456"

supabase.table("agent_sessions").upsert({
    "session_id": session_id,
    "user_id": user_id,
    "last_seen_at": datetime.utcnow().isoformat()
}).execute()

supabase.table("agent_messages").insert({
    "session_id": session_id,
    "role": "user",
    "content": "Does my policy cover storm damage?",
    "created_at": datetime.utcnow().isoformat()
}).execute()

4. •Combine retrieval from LlamaIndex with structured lookup from Supabase.

Use LlamaIndex for unstructured policy language and Supabase for structured fields like policy number, deductible, coverage limits, or claim status.

policy_number = "POL-100245"

policy_row = (
    supabase.table("insurance_policies")
    .select("policy_number, product_type, deductible, coverage_limit")
    .eq("policy_number", policy_number)
    .single()
    .execute()
)

retrieval_answer = query_engine.query(
    f"Explain storm damage coverage for {policy_row.data['product_type']} policies."
)

final_response = {
    "policy": policy_row.data,
    "answer": str(retrieval_answer),
}

print(final_response)

5. •Wire both into an agent-style request handler.

This gives you a clean pattern: fetch structured data from Supabase, retrieve supporting context from LlamaIndex, then return a grounded response.

def handle_insurance_question(session_id: str, policy_number: str, question: str):
    policy = (
        supabase.table("insurance_policies")
        .select("*")
        .eq("policy_number", policy_number)
        .single()
        .execute()
    ).data

    context = query_engine.query(
        f"Given this policy type: {policy['product_type']}, answer: {question}"
    )

    supabase.table("agent_messages").insert({
        "session_id": session_id,
        "role": "assistant",
        "content": str(context),
        "created_at": datetime.utcnow().isoformat()
    }).execute()

    return {
        "policy_number": policy_number,
        "response": str(context)
    }

result = handle_insurance_question(
    session_id="session_123",
    policy_number="POL-100245",
    question="Am I covered if a tree falls on my roof during a storm?"
)

print(result)

Testing the Integration

Run a simple end-to-end check that reads from Supabase and queries the index.

test_policy_number = "POL-100245"

row = (
    supabase.table("insurance_policies")
    .select("policy_number, product_type")
    .eq("policy_number", test_policy_number)
    .single()
    .execute()
).data

test_query = query_engine.query(
    f"For a {row['product_type']} policy, what does storm damage usually exclude?"
)

print("Policy:", row["policy_number"])
print("Type:", row["product_type"])
print("Answer:", test_query)

Expected output:

Policy: POL-100245
Type: homeowners
Answer: Storm damage exclusions typically include...

If that works, your integration is doing two things correctly:

• •Supabase is returning structured insurance data.
• •LlamaIndex is retrieving grounded context from indexed documents.

Real-World Use Cases

• •

  Claims triage assistant
  Pull claim status and claimant details from Supabase while using LlamaIndex to explain relevant coverage clauses and next steps.

• •

  Underwriting copilot
  Store applicant attributes in Supabase and retrieve underwriting guidelines from indexed manuals to help agents assess risk consistently.

• •

  Customer support bot for policies
  Use Supabase for account lookup and conversation history, then use LlamaIndex to answer questions about endorsements, exclusions, deductibles, and renewal terms.

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.