Agent Service Architecture

The agent service is a Go application built on Google ADK (Agent Development Kit). Buck imports a common platform layer and implements 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"]
    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

    Platform --> BuckMod

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

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

LLM integration

Buck uses 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

Buck’s default model is configurable:

Agent	Default Model	Config Variable
Buck	Claude Sonnet (configurable)	`BEDROCK_MODEL_ID`

Async processing

Webhook handlers return 200 OK immediately. Events are published to NATS JetStream and processed by Buck’s consumer:

Buck runs a NATS consumer with a webhooks.buck.* 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:

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