Developer Guide

Prerequisites

• Python 3.12+
• pip / venv

Local Setup

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp config.yaml.example config.yaml
make run

Project Architecture

The service follows a core + interfaces pattern:

• src/core/agent.py — Central Claude agent logic. All interfaces delegate here.
• src/core/config.py — Loads config.yaml + environment variables.
• src/core/tools/ — Custom tools available to the agent.
• src/interfaces/api.py — FastAPI REST API (main entrypoint).
• src/interfaces/mcp_server.py — MCP Server for tool/resource exposure.
• src/interfaces/a2a_server.py — Agent-to-Agent protocol.
• src/interfaces/cli.py — Command-line interface.
• src/interfaces/webhook.py — Incoming webhook handler.

Adding a New Tool

Create a module in src/core/tools/ and register it in the agent. The tool will automatically be available across all interfaces.

Testing

make test          # Run all tests
make lint          # Check code style
make lint-fix      # Auto-fix issues

CI Pipeline

Bitbucket Pipelines runs on every push:

• Step 1: Lint (ruff check + format)
• Step 2: Test (pytest)
• Step 3: Deploy to stage (main branch only)