​
High Availability Setup

This guide explains how to configure ACP Server for high availability (HA) deployments using centralized storage to share server state across multiple server replicas.

​
Overview

ACP Server supports high availability through centralized storage backends that enable multiple replicas to share server state. This allows you to:
  • Run multiple ACP Server replicas behind a load balancer
  • Ensure resilience across server restarts
  • Scale horizontally for increased throughput
  • Maintain state consistency across nodes

​
Supported Storage Backends

ACP Server provides three storage options:

​
1. Memory Store (Default)

  • Use case: Single-instance deployments, development
  • Limitations: No HA support, data lost on restart, TTL expiration
  • Configuration: Used by default, no setup required

​
2. Redis Store

  • Use case: Production HA deployments with fast access
  • Features: Pub/Sub notifications, automatic expiration
  • Requirements: Redis server accessible by all ACP replicas

​
3. PostgreSQL Store

  • Use case: Production HA deployments with persistence
  • Features: ACID compliance, notifications via LISTEN/NOTIFY
  • Requirements: PostgreSQL database accessible by all ACP replicas

​
Configuration Examples

​
Redis Store Setup

from acp_sdk.server import RedisStore, Server
from redis.asyncio import Redis

# Configure Redis connection
redis = Redis(
    host="your-redis-host",
    port=6379,
    password="your-redis-password",
)

server = Server()

# Create your agent
@server.agent()
async def my_agent(input):
    # Your agent implementation
    pass

# Run server with Redis store
server.run(store=RedisStore(redis=redis))

​
PostgreSQL Store Setup

from acp_sdk.server import PostgreSQLStore, Server
from psycopg import AsyncConnection

# Configure PostgreSQL connection
aconn = await AsyncConnection.connect(
    "postgresql://user:password@host:5432/database",
)

server = Server()

# Create your agent
@server.agent()
async def my_agent(input):
    # Your agent implementation
    pass

# Run server with PostgreSQL store
server.run(
    store=PostgreSQLStore(
        aconn=aconn,
        table="acp_store",      # Optional: custom table name
        channel="acp_update"    # Optional: custom notification channel
    )
)

​
ACP-Specific Deployment Considerations

​
Storage Backend Requirements

Redis Requirements:
  • Redis 6.0+
  • ACP will automatically configure keyspace notifications: CONFIG SET notify-keyspace-events KEA
PostgreSQL Requirements:
  • PostgreSQL 12+ with LISTEN/NOTIFY support
  • Database with JSONB support
  • ACP will automatically create the required acp_store table

​
Load Balancer Considerations

  • Session affinity: Not required for ACP (sessions are centralized)
  • Health checks: Configure to check /ping endpoint
  • Graceful shutdown: ACP handles session persistence during restarts

​
Environment Variables

ACP supports configuration through environment variables for storage backends:

​
Redis Configuration

export REDIS_HOST=your-redis-host
export REDIS_PORT=6379
export REDIS_PASSWORD=your-redis-password
export REDIS_DB=0

​
PostgreSQL Configuration

export POSTGRES_HOST=your-postgres-host
export POSTGRES_PORT=5432
export POSTGRES_USER=your-username
export POSTGRES_PASSWORD=your-password
export POSTGRES_DATABASE=your-database

​
Troubleshooting

​
ACP-Specific Issues

Session not found errors
  • Verify all instances use the same storage configuration
  • Check that session data exists in the centralized store
  • Ensure proper authentication credentials for storage backend
Agent state inconsistencies
  • Check storage backend connectivity from all instances
  • Verify notification channels are working (Redis pub/sub, PostgreSQL LISTEN/NOTIFY)
  • Review storage backend logs for connection issues
Performance issues with centralized storage
  • Monitor storage backend performance and connection pools
  • Check network latency between ACP instances and storage
  • Consider storage backend-specific optimizations

​
Infrastructure Issues

For Redis setup, see the official Redis documentation.
For PostgreSQL setup, see the official PostgreSQL documentation.
For Kubernetes deployment patterns, see the official Kubernetes documentation. For additional support, see the production deployment guide or visit our GitHub discussions.