agentpg CLAUDE.md

AgentPG - Event-Driven AI Agent Framework

Event-driven Go framework for building async AI agents using PostgreSQL for state management and distribution. Provides stateful, distributed, and transaction-safe agent execution with Claude Batch API integration.

Architecture Overview

AgentPG Architecture

Layer 1: HTTP Server Layer (Optional)

• ui.UIHandler() - /ui/* (HTMX + SSR)
• Components: Dashboard, Sessions/Runs, Chat Interface, Monitoring

Layer 2: Workers

• Client 1 (Worker), Client 2 (Worker), Client N (Worker)
• Deployed as k8s pods

Layer 3: PostgreSQL Database

• Tables: Sessions, Runs, Iterations, Tools, Messages, Instances, Agents
• LISTEN/NOTIFY channels:
  • agentpg_run_created
  • agentpg_tool_pending
  • agentpg_run_state
  • agentpg_tools_complete

Layer 4: Claude Batch API

• 24h processing window
• Async submission/polling

Key Design Principles

1. PostgreSQL as Single Source of Truth: All state stored in PostgreSQL. No in-memory state that could be lost.
2. Event-Driven with Polling Fallback: Uses LISTEN/NOTIFY for real-time events, with polling as fallback.
3. Race-Safe Distribution: Uses SELECT FOR UPDATE SKIP LOCKED for safe work claiming across workers.
4. Transaction-First: RunTx() accepts user transactions for atomic operations.
5. Database-Driven Agents: Agents are database entities with UUID primary keys, not per-client registrations. Tools are registered per-client.
6. Multi-Level Agent Hierarchies: Agents can be tools for other agents (PM → Lead → Worker pattern).

---

Core Concepts

Client

A Client represents a single worker instance. Multiple clients can run across different processes/pods, sharing work from the same database.

client, err := agentpg.NewClient(driver, &agentpg.ClientConfig{
    APIKey: os.Getenv("ANTHROPIC_API_KEY"),
    Name:   "worker-1",
})

Agent

An Agent is a Claude-powered AI with a specific role, model, and system prompt. Agents are database entities identified by UUID, created via CreateAgent() after the client starts.

agent, err := client.CreateAgent(ctx, &agentpg.AgentDefinition{
    Name:         "assistant",
    Model:        "claude-sonnet-4-5-20250929",
    SystemPrompt: "You are a helpful assistant.",
})
// Use agent.ID (uuid.UUID) when running