Agent Service Architecture

The agent services are Go applications built on Google ADK (Agent Development Kit). Three agents — Buck, Dolly, and Pearl — share a common platform layer and each implement agent-specific modules with custom tools and prompts. Events arrive via NATS JetStream, are processed by Claude (via AWS Bedrock), and responses are routed back to the originating platform.

Architecture

graph TD
    subgraph Platform["Platform Layer (shared)"]
        Webhook["Webhook handlers"]
        Bedrock["Bedrock LLM"]
        K8s["K8s orchestrator"]
        NATS["NATS client"]
        JiraClient["Jira client"]
        SlackClient["Slack client"]
        Storage["Storage (S3/CloudFront)"]
        SessionIdx["Session Index"]
        GitHubClient["GitHub client"]
        Celestials["Celestials"]
        ConfluenceClient["Confluence client"]
        GDriveClient["Google Drive client"]
        FigmaClient["Figma client"]
    end

    subgraph BuckMod["Buck Modules"]
        BuckConfig["Config"]
        BuckAgent["Agent (ADK + tools)"]
        BuckDash["Dashboard (Connect RPC, GORM, runner API, terminal tunnel)"]
        BuckMetrics["Metrics"]
        BuckProm["Prometheus"]
    end

    subgraph DollyMod["Dolly Modules"]
        DollyConfig["Config"]
        DollyAgent["Agent (ADK + tools)"]
        DollyDash["Dashboard (sessions, team settings, user memory, decompositions)"]
    end

    subgraph PearlMod["Pearl Modules"]
        PearlConfig["Config"]
        PearlAgent["Agent (ADK + tools)"]
        PearlDash["Dashboard (sessions, snippets, components, design languages)"]
        PearlFigma["Figma client"]
    end

    Platform --> BuckMod
    Platform --> DollyMod
    Platform --> PearlMod

Key modules

Platform modules (shared)

Module	Path	Purpose
Webhook	`internal/platform/webhook/`	HTTP server, event handlers, NATS publishing
Bedrock	`internal/platform/bedrock/`	Custom `model.LLM` for AWS Bedrock Converse API
K8s	`internal/platform/k8s/`	EKS pod orchestrator, pod-bound JWT auth, exec streaming
NATS	`internal/platform/nats/`	JetStream client, stream/consumer management, publish/subscribe
Jira	`internal/platform/jira/`	Jira REST API v3 client
Slack	`internal/platform/slack/`	Slack Web API client with image downloading, Block Kit support
Storage	`internal/platform/storage/`	Image store (S3 + CloudFront)
Session Index	`internal/platform/sessionindex/`	Platform identifier to session UUID mapping
GitHub	`internal/platform/github/`	GitHub API client via App installation tokens
Celestials	`internal/platform/celestials/`	Team/Pack lookup via celestials service
Confluence	`internal/platform/confluence/`	Confluence REST API client
Google Drive	`internal/platform/gdrive/`	Google Drive client via service account
Figma	`internal/platform/figma/`	Figma REST API client via personal access token

Buck modules

Module	Path	Purpose
Config	`internal/buck/config/`	Environment variable loading with validation and defaults
Agent	`internal/buck/agent/`	ADK agent factory, custom tools, prompt management
Dashboard	`internal/buck/dashboard/`	Connect RPC API, GORM models, runner API, terminal tunnel
Metrics	`internal/buck/metrics/`	OTel custom metrics (`bucky.*` prefix)
Prometheus	`internal/buck/prometheus/`	Prometheus HTTP API client, PromQL query catalog

Dolly modules

Module	Path	Purpose
Config	`internal/dolly/config/`	Environment variable loading with validation and defaults
Agent	`internal/dolly/agent/`	ADK agent factory, custom tools (Jira, Confluence, Drive, decomposition)
Dashboard	`internal/dolly/dashboard/`	Sessions, team settings, user memory, decompositions

Pearl modules

Module	Path	Purpose
Config	`internal/pearl/config/`	Environment variable loading with validation and defaults
Agent	`internal/pearl/agent/`	ADK agent factory, custom tools (design, Figma, snippets, components)
Dashboard	`internal/pearl/dashboard/`	Sessions, snippets, components, design languages
Figma client	`internal/pearl/figma/`	Figma file/node/component/style/variable access

LLM integration

The agents use AWS Bedrock’s Converse API to call Claude. The custom model.LLM implementation in internal/platform/bedrock/:

Translates between ADK’s genai types and Bedrock’s message/content block types
Handles message role mapping and consecutive same-role merging
Converts tool use/result blocks between ADK and Bedrock formats
Supports multimodal input (images from Slack threads to Bedrock ImageBlock)
Uses the ECS task role for AWS credentials

Each agent can specify a different default model:

Agent	Default Model	Config Variable
Buck	Claude Sonnet (configurable)	`BEDROCK_MODEL_ID`
Dolly	Claude Opus	`DOLLY_BEDROCK_MODEL_ID`
Pearl	Claude Opus	`PEARL_BEDROCK_MODEL_ID`

Async processing

Webhook handlers return 200 OK immediately. Events are published to NATS JetStream and processed by per-agent consumers:

Each agent runs its own NATS consumer with a webhooks.{agent}.* subject filter
256-slot sharded mutex (FNV32a hash) ensures per-session ordering — events for the same session execute sequentially
Deduplication for Slack events (by event ID) and GitHub webhooks (by comment ID)
Backoff retry schedule: 0s, 5s, 30s, 2m, 10m — terminates after 5 attempts

Observability

When POSTHOG_PROJECT_API_KEY is set (applies to all agents):

LLM analytics: $ai_generation events captured via ADK callbacks with token counts, latency, and input/output for every LLM call
Error tracking: $exception events captured automatically via slog.Error() calls with stack traces
Tracing: Each runner.Run() invocation maps to a PostHog trace; each LLM call within is a generation span