@cuylabs/agent-storage-postgres

PostgreSQL-backed SessionStorage for @cuylabs/agent-core.

Use this backend when agents need durable session state across restarts or scale-out instances, including Azure App Service with Azure Database for PostgreSQL Flexible Server.

import { SessionManager } from "@cuylabs/agent-core";
import { PostgresSessionStorage } from "@cuylabs/agent-storage-postgres";

const sessionManager = new SessionManager(
  new PostgresSessionStorage({
    connectionString: process.env.AGENT_SESSION_POSTGRES_URL,
    poolOptions: {
      ssl: { rejectUnauthorized: true },
    },
  }),
);

For scaled Azure App Service deployments, also pass the Postgres-backed turn lock to createAgent() so multiple app instances cannot run turns for the same session concurrently:

import { createAgent, SessionManager } from "@cuylabs/agent-core";
import {
  PostgresSessionStorage,
  PostgresSessionTurnLock,
} from "@cuylabs/agent-storage-postgres";

const connectionString = process.env.AGENT_SESSION_POSTGRES_URL;

const agent = createAgent({
  model,
  sessionManager: new SessionManager(
    new PostgresSessionStorage({ connectionString }),
  ),
  sessionTurnLock: new PostgresSessionTurnLock({ connectionString }),
});

The storage is append-only and stores each session entry as jsonb. By default it creates the public.agent_session_entries table on first use.

The turn lock uses PostgreSQL advisory locks and holds a dedicated database connection only while the agent turn is running. It does not hold a database transaction open during LLM/tool execution.

Azure PostgreSQL

For Azure Database for PostgreSQL Flexible Server, configure an App Service application setting such as:

AGENT_SESSION_POSTGRES_URL=postgresql://user:[email protected]:5432/database?sslmode=require

If your deployment uses an Azure-managed CA bundle, pass the CA through poolOptions.ssl. For private networks and managed identity, create the pg.Pool in the host app and pass it as pool.