AgentPG Agents Reference

Table of Contents

• Agent CRUD
• AgentDefinition Fields
• Agent-as-Tool Pattern
• Multi-Level Hierarchies
• Best Practices

Agent CRUD

Agents are database entities with UUID primary keys. Manage after client.Start().

// Create
agent, err := client.CreateAgent(ctx, &agentpg.AgentDefinition{
    Name:         "assistant",
    Model:        "claude-sonnet-4-5-20250929",
    SystemPrompt: "You are a helpful assistant.",
    Tools:        []string{"calculator"},
    Metadata:     map[string]any{"tenant_id": "t1"},
})

// Idempotent create (safe for every startup)
agent, err := client.GetOrCreateAgent(ctx, &agentpg.AgentDefinition{
    Name:  "assistant",
    Model: "claude-sonnet-4-5-20250929",
})

// Query
agent, err := client.GetAgentByID(ctx, agentID)
agent, err := client.GetAgentByName(ctx, "assistant", nil)                              // No metadata filter
agent, err := client.GetAgentByName(ctx, "assistant", map[string]any{"tenant_id": "t1"}) // With metadata
agents, total, err := client.ListAgents(ctx, nil, 100, 0)                               // All, limit 100
agents, total, err := client.ListAgents(ctx, map[string]any{"tenant_id": "t1"}, 100, 0) // Filtered

// Update
agent.SystemPrompt = "Updated prompt."
err := client.UpdateAgent(ctx, agent)

// Delete
err := client.DeleteAgent(ctx, agentID)

AgentDefinition Fields

type AgentDefinition struct {
    ID           uuid.UUID          // Auto-generated
    Name         string             // Required, unique display name
    Description  string             // Required when used as tool (shown to parent agent)
    Model        string             // Required: Claude model ID
    SystemPrompt string
    Tools        []string           // Tool names this agent can use
    AgentIDs     []uuid.UUID        // Agent UUIDs for delegation (agent-as-tool)
    MaxTokens    *int               // Max response tokens
    Temperature  *float64
    TopK         *int
    TopP         *float64
    Metadata     map[string]any     // App-specific (tenant_id, tags, etc.)
    Config       map[string]any     // Additional settings
}

Agent-as-Tool Pattern

One agent delegates work to another. The child agent appears as a callable tool to the parent.

// 1. Create child agent (specialist)
researcher, _ := client.CreateAgent(ctx, &agentpg.AgentDefinition{
    Name:         "researcher",
    Description:  "Research specialist for gathering and analyzing information",  // Shown to parent
    Model:        "claude-sonnet-4-5-20250929",
    SystemPrompt: "You are a research specialist. Provide thorough analysis.",
})

// 2. Create parent with delegation via AgentIDs
manager, _ := client.CreateAgent(ctx, &agentpg.AgentDefinition{
    Name:         "manager",
    Model:        "claude-sonnet-4-5-20250929",
    SystemPrompt: "Delegate research tasks to your researcher tool.",
    AgentIDs:     []uuid.UUID{researcher.ID},  // researcher becomes a tool
})

// 3. Run parent - it can invoke researcher as a tool
response, _ := client.RunSync(ctx, sessionID, manager.ID, "Research quantum computing", nil)

When manager calls the researcher "tool", AgentPG creates a child run for the researcher agent. The child run gets its own session (child of the parent's session).

Multi-Level Hierarchies

// Level 3: Workers with specialized tools
frontendDev, _ := client.CreateAgent(ctx, &agentpg.AgentDefinition{
    Name:        "frontend-dev",
    Description: "Frontend developer - implements UI components",
    Model:       "claude-sonnet-4-5-20250929",
    Tools:       []string{"lint", "format_code"},
})

backendDev, _ := client.CreateAgent(ctx, &agentpg.AgentDefinition{
    Name:        "backend-dev",
    Description: "Backend developer - implements APIs and services",
    Model:       "claude-sonnet-4-5-20250929",
    Tools:       []string{"run_tests", "query_db"},
})

// Level 2: Team lead delegates to workers
techLead, _ := client.CreateAgent(ctx, &agentpg.AgentDefinition{
    Name:        "tech-lead",
    Description: "Technical lead - coordinates development work",
    Model:       "claude-sonnet-4-5-20250929",
    AgentIDs:    []uuid.UUID{frontendDev.ID, backendDev.ID},
})

// Level 1: PM delegates to tech lead
pm, _ := client.CreateAgent(ctx, &agentpg.AgentDefinition{
    Name:     "project-manager",
    Model:    "claude-opus-4-5-20251101",  // More capable model for orchestration
    AgentIDs: []uuid.UUID{techLead.ID},
})

An agent can have BOTH Tools (regular tools) and AgentIDs (agent delegation) simultaneously.

Best Practices

• Single responsibility: Each agent should have one clear role
• Clear descriptions: Required for child agents - the parent sees this to decide when to delegate
• Model selection: Use cheaper models (haiku) for simple specialist tasks, capable models (opus) for orchestrators
• Limit depth: Each delegation level = additional API call. Keep hierarchies shallow (2-3 levels max)
• Idempotent creation: Use GetOrCreateAgent() in startup code for safety
• Variable propagation: Run variables automatically flow from parent to child runs. Instruction overrides (OverrideInstructions, AppendInstructions) do NOT propagate — each child agent uses its own system prompt.