Agent Development

The agent service is a Go application in agent/. It requires Go 1.25+.

Commands

cd agent
make build       # build binary to bin/ad-tools-agent
make test        # run all tests
make lint        # golangci-lint run
make run         # build + run locally

Local development setup

1. Copy the env template and fill in values:

cd agent
cp .env.example .env

2. (Optional) Start PostgreSQL for persistent sessions:

docker compose up -d

3. Run the agent:

make run

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 processed via goroutine worker pool (buffered channel, 10 workers) with panic recovery
• Interfaces: API clients (SlackClient, GitHubClient, JiraClient) defined as interfaces for testability
• Prompts: Large LLM prompts live in internal/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/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/agent/agent.go
5. Update the system prompt in internal/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

The agent is deployed to ECS via FSD. The deployment config is at agent/ad-tools-agent.yml.

When adding or changing environment variables:

1. Update internal/config/config.go
2. Update agent/.env.example
3. Update agent/ad-tools-agent.yml (add to environment_variables or secrets)
4. Update the Agent Configuration docs page