Agent Development

The agent services are Go applications in agent/. They require Go 1.25+.

Directory structure

agent/
  cmd/
    buck/main.go       # Buck entry point
  internal/
    platform/          # Shared infrastructure
      bedrock/         # AWS Bedrock Converse API wrapper
      webhook/         # HTTP server, event handlers
      nats/            # NATS JetStream publisher/subscriber
      k8s/             # EKS pod orchestrator
      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
    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

Commands

cd agent

# Build
make build              # build Buck (bin/buck)

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

# Run locally
make run                # build + run Buck

# Docker
make docker-build       # Docker build Buck

# 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 the agent:

make run          # runs Buck

Without DATABASE_HOST, the agent uses 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 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/buck/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. Create the tool function in internal/buck/agent/ (e.g., my_tool.go)
2. Define typed args and result structs
3. Register with functiontool.New("tool_name", "description", handler)
4. Add the tool to the agent’s tool list in internal/buck/agent/agent.go
5. Update the system prompt in internal/buck/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

Buck is deployed to ECS via FSD. Deployment config is at agent/ad-tools-agent.yml.

When adding or changing environment variables:

1. Update internal/buck/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