agentpg

AgentPG

Event-driven Go framework for async AI agents using PostgreSQL for state management. Source at /home/youssef/projects/agentpg.

Workflow Decision Tree

1. New project setup? -> See "Quick Start" below
2. Adding tools? -> See references/tools.md
3. MCP server tools? -> See references/mcp.md
4. Agent hierarchies? -> See references/agents.md
5. Cancel or regenerate runs? -> See "Cancel and Regenerate" below
6. Tool call visibility / callbacks? -> See "Tool Call Visibility" below
7. Distributed workers / transactions / compaction / UI? -> See references/advanced.md

Quick Start

Prerequisites

go get github.com/youssefsiam38/agentpg
go get github.com/youssefsiam38/agentpg/driver/pgxv5   # or driver/databasesql
# Optional: go get github.com/youssefsiam38/agentpg/mcp  # MCP server tools
psql $DATABASE_URL -f storage/migrations/001_agentpg_migration.up.sql

Minimal Application

package main

import (
    "context"
    "fmt"
    "log"
    "os"

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

func main() {
    ctx := context.Background()
    pool, _ := pgxpool.New(ctx, os.Getenv("DATABASE_URL"))
    defer pool.Close()

    client, _ := agentpg.NewClient(pgxv5.New(pool), &agentpg.ClientConfig{
        APIKey: os.Getenv("ANTHROPIC_API_KEY"),
    })
    client.Start(ctx)
    defer client.Stop(context.Background())

    agent, _ := client.GetOrCreateAgent(ctx, &agentpg.AgentDefinition{
        Name:         "assistant",
        Model:        "claude-sonnet-4-5-20250929",
        SystemPrompt: "You are a helpful assistant.",
    })

    sessionID, _ := client.NewSession(ctx, nil, nil)
    response, _ := client.RunFastSync(ctx, sessionID, agent.ID, "Hello!", nil)
    fmt.Println(response.Text)
}

Lifecycle Order

1. RegisterTool() - before Start
2. agentmcp.RegisterServer() - MCP tools, before Start (optional)
3. client.Start(ctx) - starts background services
4. CreateAgent() / GetOrCreateAgent() - after Start (agents are DB entities)
5. NewSession() -> Run*() / RunFast*() - execute work
6. client.Stop(ctx) - graceful shutdown