AgentPG Documentation

AgentPG is a fully event-driven Go framework for building async AI agents using PostgreSQL for state management and distribution. It provides stateful, distributed, and transaction-safe agent execution with Claude API integration.

Key Features

• Event-Driven Architecture: PostgreSQL LISTEN/NOTIFY for real-time coordination with polling fallback
• Distributed Workers: Race-safe work claiming with SELECT FOR UPDATE SKIP LOCKED
• Transaction-First API: Atomic operations with user transaction support
• Multi-Agent Hierarchies: Agent-as-tool pattern for complex workflows
• Dual API Modes: Batch API (50% cost savings) and Streaming API (real-time)
• Context Compaction: Automatic context window management for long conversations
• Embedded Admin UI: HTMX-powered dashboard for monitoring and chat

Documentation Index

Getting Started

Document	Description
Getting Started	Quick start guide with installation and first agent
Configuration	All configuration options with defaults
Tools Guide	Building custom tools for agents

Core Concepts

Document	Description
Architecture	System design, components, and data flow
Distributed Workers	Multi-instance coordination and leader election
Context Compaction	Managing long conversations and token limits

API Reference

Document	Description
Go API Reference	Complete Go package documentation

Operations

Document	Description
Deployment	Production deployment, Docker, and scaling
Admin UI	Web interface setup and customization
Hooks	Extension points and customization

Development

Document	Description
Contributing	Development setup and contribution guidelines

Quick Links

• Examples: See the /examples directory for working code samples
• Migrations: Database schema in /storage/migrations
• Main Reference: Comprehensive guide in /CLAUDE.md

Installation

go get github.com/youssefsiam38/agentpg

Minimal Example

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/jackc/pgx/v5/pgxpool"
    "github.com/youssefsiam38/agentpg"
    "github.com/youssefsiam38/agentpg/driver/pgxv5"
)

func main() {
    ctx := context.Background()

    // Connect to PostgreSQL
    pool, _ := pgxpool.New(ctx, os.Getenv("DATABASE_URL"))
    defer pool.Close()

    // Create driver and client
    drv := pgxv5.New(pool)
    client, _ := agentpg.NewClient(drv, &agentpg.ClientConfig{
        APIKey: os.Getenv("ANTHROPIC_API_KEY"),
    })

    // Start client
    client.Start(ctx)
    defer client.Stop(context.Background())

    // Create or get agent (idempotent - safe to call on every startup)
    agent, _ := client.GetOrCreateAgent(ctx, &agentpg.AgentDefinition{
        Name:         "assistant",
        Model:        "claude-sonnet-4-5-20250929",
        SystemPrompt: "You are a helpful assistant.",
    })

    // Create session and run (uses agent UUID, nil for no variables)
    sessionID, _ := client.NewSession(ctx, nil, nil)
    response, _ := client.RunSync(ctx, sessionID, agent.ID, "Hello!", nil)
    fmt.Println(response.Text)
}

License

Mozilla Public License 2.0 - see LICENSE for details.