Agent Development

The agent services are Go applications in agent/. They require Go 1.25+. There are three agents — Buck, Dolly, and Pearl — sharing a common platform layer.

Directory structure

agent/
  cmd/
    buck/main.go       # Buck entry point
    dolly/main.go      # Dolly entry point
    pearl/main.go      # Pearl entry point
  internal/
    platform/          # Shared infrastructure (all agents)
      bedrock/         # AWS Bedrock Converse API wrapper
      webhook/         # HTTP server, event handlers
      nats/            # NATS JetStream publisher/subscriber
      k8s/             # EKS pod orchestrator (Buck)
      jira/            # Jira REST API client
      slack/           # Slack API client
      github/          # GitHub App client
      storage/         # S3 + CloudFront image store
      sessionindex/    # Platform → session UUID mapping
      celestials/      # Team/Pack lookups
      confluence/      # Confluence REST API client (Dolly)
      googledrive/     # Google Drive client (Dolly)
      figmaclient/     # Figma API client (Pearl)
    buck/              # Buck-specific code
      config/          # Environment config
      agent/           # ADK agent, tools, prompts
      dashboard/       # Connect RPC API, models, runner API
      metrics/         # OTel custom metrics
      prometheus/      # PromQL query catalog
    dolly/             # Dolly-specific code
      config/          # Environment config
      agent/           # ADK agent, tools, prompts
      dashboard/       # Sessions, team settings, user memory, decompositions
    pearl/             # Pearl-specific code
      config/          # Environment config
      agent/           # ADK agent, tools, prompts
      dashboard/       # Sessions, snippets, components, design languages

Commands

cd agent

# Build
make build              # default: build Buck (bin/buck)
make build-buck         # explicit: build Buck
make build-dolly        # build Dolly (bin/dolly)
make build-pearl        # build Pearl (bin/pearl)

# Test & lint
make test               # run all tests
make lint               # golangci-lint run

# Run locally
make run                # build + run Buck

# Docker
make docker-build       # default: Docker build Buck
make docker-build-buck  # explicit: Docker build Buck
make docker-build-dolly # Docker build Dolly
make docker-build-pearl # Docker build Pearl

# Proto
make proto-lint         # buf lint
make proto-format       # buf format
make proto-breaking     # buf breaking change detection

Local development setup

1. Copy the env template and fill in values:

cd agent
cp .env.example .env

2. Start the local dev stack:

docker compose up -d

This starts PostgreSQL (:5432), Prometheus (:9090), OTel Collector (:4317/:4318), Grafana (:3001), and NATS JetStream (:4222/:8222).

Caution

NATS is required for all agents. Set NATS_URL=nats://localhost:4222 in your .env file.

3. Run an agent:

make run          # runs Buck

Without DATABASE_HOST, agents use in-memory sessions (lost on restart).

Key patterns

• Error handling: Fail fast on startup errors (os.Exit(1)); async processing errors logged and surfaced to Slack when possible
• Async webhooks: Handlers return 200 immediately; work is published to NATS JetStream and consumed by per-agent workers with per-session ordering (256-slot sharded mutex)
• Interfaces: API clients (SlackClient, GitHubClient, JiraClient) defined as interfaces for testability
• Prompts: Large LLM prompts live in internal/{agent}/agent/prompts/*.md, embedded at compile time via //go:embed
• ADK integration: Bedrock Claude model + MCP toolsets + custom function tools registered via functiontool.New
• Logging: Structured JSON logging via log/slog

Adding a new tool

1. Decide which agent gets the tool (Buck, Dolly, or Pearl)
2. Create the tool function in internal/{agent}/agent/ (e.g., my_tool.go)
3. Define typed args and result structs
4. Register with functiontool.New("tool_name", "description", handler)
5. Add the tool to the agent’s tool list in internal/{agent}/agent/agent.go
6. Update the system prompt in internal/{agent}/agent/prompts/system.md if the agent needs guidance on when to use it

Testing

Tests use interface mocks for external dependencies:

type mockSlackClient struct {
    // implement SlackClient interface
}

Run all tests:

cd agent && make test

Deployment

Each agent is deployed to ECS via FSD. Buck’s deployment config is at agent/ad-tools-agent.yml.

When adding or changing environment variables:

1. Update internal/{agent}/config/config.go
2. Update agent/.env.example
3. Update the FSD deployment config (add to environment_variables or secrets)
4. Update the Agent Configuration docs page