Building Stateful, Persistent AI Agents with LangGraph & Supabase Postgres

Architecture & Overview

LangGraph enables complex cyclic state graphs for LLM agents, while Supabase provides enterprise Postgres storage with built-in pgvector support for semantic retrieval. By connecting LangGraph's PostgresSaver checkpointer directly to Supabase, your AI agents maintain deterministic state persistence across server restarts and long-running human-in-the-loop workflows.

Implementation Example

from langgraph.checkpoint.postgres import PostgresSaver
from langgraph.graph import StateGraph, END
import psycopg

# Connect directly to Supabase Postgres pooler connection string
DB_URI = "postgresql://postgres:[PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres"

def run_agent_workflow(user_input: str, thread_id: str):
    with psycopg.connect(DB_URI) as conn:
        checkpointer = PostgresSaver(conn)
        checkpointer.setup() # Prepares checkpoint tables

        builder = StateGraph(State)
        # Define agent nodes and conditional routing
        builder.add_node("agent", agent_node)
        builder.add_node("tools", tool_execution_node)
        builder.set_entry_point("agent")

        graph = builder.compile(checkpointer=checkpointer)

        config = {"configurable": {"thread_id": thread_id}}
        return graph.invoke({"messages": [("user", user_input)]}, config)

Key Architectural Takeaways

• Persist agent state across multi-day async workflows without losing context.
• Leverage Supabase pgvector for vector retrieval directly inside LangGraph tool calls.
• Enforce Row Level Security (RLS) so multi-tenant users only query their own agent checkpoints.

Common Production Pitfalls

• Avoid pooling connection exhaustion by using Supabase Transaction Pooler (Port 6543) for serverless environments.
• Ensure thread IDs are sanitized to prevent unauthorized state manipulation across multi-tenant agents.

Frequently Asked Questions