Getting Started: Platform Engineers

Getting Started: Platform Engineers

This guide helps platform engineers and AI developers get started with ADEPT development.

---

Prerequisites

• Python 3.11+
• Docker Engine 24+ with Compose v2
• 32GB RAM recommended
• Git + GitHub CLI (gh)
• Claude Code (recommended for SDLC automation)

---

Development Setup

# Clone
git clone https://github.com/pnnl/adept-agentic.git
cd adept-agentic

# Configure
cp .env.example .env
# Edit .env with LLM API keys

# Start full stack (25 services)
make start

# Verify
make validate-service-health

---

Key Development References

Document	Purpose
CLAUDE.md	Architecture, port mappings, validation commands
docs/development/FEATURE_DEVELOPMENT_WORKFLOW.md	10-phase canonical lifecycle
docs/development/CODE_HYGIENE.md	Branch naming, commit format, testing tiers
config/model_catalog.yaml	LLM purpose routing configuration

---

Architecture Quick Reference

Tier 1: Agent Gateway (port 8083)    -- Auth proxy (Keycloak JWT)
Tier 2: Orchestration Service (8084) -- Core brain (LangGraph + PostgreSQL)
Tier 3: MCP Servers                  -- Stateless tool executors
  - mcp_server (scientific tools)
  - hpc_mcp_server (HPC pipelines, port 8081)
  - sandbox_mcp_server (code execution)
Supporting: Gateway Registry (8086), Keycloak, Redis, ChromaDB, PostgreSQL

---

Building MCP Tools

Create a New MCP Server

# Use the canonical template
cp -r examples/mcp_server_template/ examples/my_new_server/

# Or use Claude Code skill
> /mcp-scaffold

Add a Tool to Existing Server

# In tools/my_tool.py
from pydantic import BaseModel, Field

class MyToolInput(BaseModel):
    query: str = Field(description="Search query")
    limit: int = Field(default=10, description="Max results")

def register(mcp):
    @mcp.tool()
    async def my_tool(query: str, limit: int = 10) -> str:
        """Search for something useful."""
        # Implementation here
        return result

Test Tiers (4-tier strategy)

# Unit tests (tool logic in isolation)
make validate-unit-<server>

# Integration tests (tool + real dependencies)
make validate-integration-<server>

# Registration tests (tool appears in discovery)
make validate-mcp-tools-discovery

# E2E tests (tool called via chat API)
make validate-response-api-tool-calls

---

Multi-Agent Development

Router Mode (Supervisor + Workers)

CreateMultiAgentSession(
    roles=["chemist", "data_scientist"],
    mode="router"  # Supervisor decomposes and delegates
)

Graph Mode (DAG Execution)

CreateMultiAgentSession(
    roles=[
        RolePersona(name="coder", llm_purpose="coding_agent"),
        RolePersona(name="reviewer", llm_purpose="coding_agent")
    ],
    mode="graph"  # Structured plan with parallel steps
)

YAML Model Catalog

Add new LLM purposes without code changes:

# config/model_catalog.yaml
purposes:
  my_purpose:
    env_var: MY_PURPOSE_DEFAULT_MODEL
    description: "My custom LLM purpose"
    
aliases:
  my_role: my_purpose

---

Validation Commands

make validate                  # Full E2E suite
make validate-unit-all         # All unit tests
make validate-data             # Data-plane auth flow
make validate-multi-agent      # Multi-agent orchestration
make validate-service-health   # Credentials + tool discovery
make validate-response-api-tool-calls  # Response API

---

Service Rebuilds

After code changes:

make rebuild-gateway           # Tier 1
make rebuild-orchestrator      # Tier 2
make rebuild-registry          # Gateway Registry

---

Deployment Targets

Target	Tooling	Command
Local	Docker Compose	make start
AWS	CDK + Ansible + EKS Helm	/deploy-cloud skill
Azure	Pulumi + AKS Helm	/deploy-cloud skill
GCP	Terraform + GKE	Planned
Bare metal	Ansible	deployment/ansible/

---

Further Reading

• Architecture Overview
• MCP Server Blueprint
• Claude Code Skills
• CI/CD GitHub Actions