# GCP Solution Architecture Agent (`gcp_solution_architecture_agent`)

A production-ready Google Cloud Solution Architecture Agent built using **Google ADK (Agent Development Kit)**, **LangChain**, and **LangGraph**, featuring a multi-agent orchestration graph with iterative review loops, dynamic local skill loading, PostgreSQL database persistence, a Starlette REST API server, and an offline evaluation harness.

> **Direction and current state (2026-09-15).** This agent is being built to replace the [`google-cloud-solution-architecture`](https://github.com/google/skills/blob/main/skills/cloud/google-cloud-solution-architecture/SKILL.md) skill with something that runs on any agent framework and, later, targets any Cloud provider. Google Cloud is the first provider.
> - **Target:** behaviour lives in [Agent Skills](https://agentskills.io/specification), loaded by a framework's own skill runtime (Google ADK `SkillToolset`, or LangChain Deep Agents skills). This repo supplies the tooling those Skills call. See [ADR-0002](docs/adr/0002-skills-are-the-portable-unit-of-behaviour.md).
> - **Today:** the `google.adk` classes below are local compatibility stubs. The real `google-adk` package isn't used, and Phase outputs are fixed templates, not model-generated.
>
> Vocabulary is defined in [CONTEXT.md](CONTEXT.md); decisions are recorded in [docs/adr/](docs/adr/).

---

## 🌟 Architecture & Features

### 1. Multi-Agent Orchestration & `google.adk.agents.LoopAgent`
The agent uses an end-to-end multi-agent graph managed by an `OrchestratorLoopAgent` (`google.adk.agents.LoopAgent`):
- **`SourceDiscoveryAgent`** (Phase 0a): Pre-emptively audits and documents the existing pre-migration source environment (As-Is Architecture) and pain points.
- **`DiscoveryAgent`** (Phase 0): Discovers functional & non-functional requirements while explicitly deferring product selection.
- **`ArchitectureDesignAgent`** (Phase 1): Resolves product selections (Cloud Run, Pub/Sub, Cloud Storage, Firestore, IAM, KMS), grounds guidance with **Google Developer Knowledge MCP**, generates Mermaid diagrams (`architecture.mmd`), and builds Terraform IaC (`terraform/main.tf`).
- **`ValidationReviewAgent`** (Phase 2): Evaluates Mermaid syntax, Terraform structural integrity, and artifact completeness using `google.adk.tools.FunctionTool`.
- **`PackagingAgent`** (Phase 3): Compiles the final comprehensive `solution-architecture-guide.md` with **Before (Source) vs After (Target)** architecture comparison.
- **`OrchestratorLoopAgent`**: Repeatedly loops through the multi-agent pipeline, reviewing and validating content in a feedback loop until production quality criteria pass or `max_iterations` is reached.

### 2. Google ADK Integration (`google.adk`)
Built directly on Google ADK framework primitives (with offline compatibility stubs):
- **`google.adk.agents`**: `LlmAgent`, `SequentialAgent`, `ParallelAgent`, `LoopAgent`.
- **`google.adk.tools`**: `FunctionTool` wrappers for static artifact and diagram validators, plus Google Developer Knowledge MCP tools (`developerknowledge:*`).
- **`google.adk.artifacts`**: `ArtifactRepository` synchronized with disk and PostgreSQL.
- **`google.adk.sessions`**: `PostgresSessionService` for durable session memory.
- **`google.adk.runners`**: `Runner` for managing execution workflows.
- **`google.adk.workflows`**: `Workflow` composition primitives.
- **`google.adk.evaluation`**: `Evaluator` for scoring benchmark suites.

### 3. PostgreSQL Database Persistence (`app/database.py`)
State, sessions, workflow executions, review iteration logs, and evaluation metrics are written to an external PostgreSQL database (with an automatic SQLite fallback for offline development):
- `adk_sessions`: Durable session memory and state data.
- `workflow_executions`: Workflow execution status, phase, and iteration metrics.
- `adk_artifacts`: Generated solution architecture artifacts (including `docs/source-architecture.md` and `source-architecture.mmd`).
- `orchestrator_review_logs`: Detailed iteration review logs from the `OrchestratorLoopAgent`.
- `adk_evaluations`: Benchmark evaluation scores and pass rates.

### 4. Dynamic Local Skill Loading (`app/skills/`)
Domain knowledge is stored as self-contained markdown instruction templates under `app/skills/`:
- `source_discovery/SKILL.md` (Phase 0a - Pre-emptive Source Environment Discovery)
- `requirements_discovery/SKILL.md` (Phase 0 - Requirements Discovery & Deferral)
- `architecture_design/SKILL.md` (Phase 1 - Product Selection & Terraform IaC)
- `validation_rules/SKILL.md` (Phase 2 - Pre-deployment Validation Rules)
- `packaging_guide/SKILL.md` (Phase 3 - Solution Guide Packaging)

The `SkillLoader` (`app/skills/loader.py`) dynamically parses frontmatter and injects instructions into phase system prompts.

### 5. Starlette REST API Server (`app/agent.py`)
Production HTTP REST endpoints exposed via Starlette and Uvicorn:
- `GET /health`: Operational health signal & database connection status.
- `GET /card`: Agent capability card metadata.
- `POST /generate`: Trigger the ADK multi-agent workflow execution.
- `POST /validate`: Execute pre-deployment artifact validation.
- `GET /sessions/{session_id}`: Query session state from the PostgreSQL database.

---

## 🚀 Quick Start & Commands

### Install Dependencies
```bash
pip install -r requirements.txt
pip install -r requirements-dev.txt
```

### Run Tests & Validation
```bash
# Run pytest test suite (100% pass rate)
pytest -v

# Run offline benchmark evaluation harness
python3 -m eval.eval_harness

# Run static artifact validation
python3 scripts/validate_artifacts.py
```

### Start Starlette REST Server
```bash
python3 app/agent.py --host 0.0.0.0 --port 8080
```

### 🐳 Run with Podman

#### 1. Build the Podman Container Image
```bash
podman build -t gcp-solution-architecture-agent:latest .
```

#### 2. Run Container with Host Deliverables Volume Mount
To ensure execution deliverables (`deliverables/executions/{execution_id}/*`) are written directly to your host machine's workspace:

```bash
podman run -d --name gcp-agent \
  -p 8080:8080 \
  -v $(pwd)/deliverables:/app/deliverables:Z \
  -v ~/.config/gcloud/application_default_credentials.json:/app/credentials/adc.json:ro \
  -e GOOGLE_APPLICATION_CREDENTIALS=/app/credentials/adc.json \
  -e GCP_PROJECT_ID=your-project-id \
  localhost/gcp-solution-architecture-agent:latest
```

#### 3. Run Connected to External PostgreSQL Container
```bash
podman run -d --name gcp-agent \
  -p 8080:8080 \
  -e POSTGRES_HOST=postgres-container-name \
  -e POSTGRES_PORT=5432 \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=gcp_agent_db \
  localhost/gcp-solution-architecture-agent:latest
```

#### 4. Test API Endpoints
```bash
# Health Signal
curl http://localhost:8080/health

# Agent Capability Card
curl http://localhost:8080/card

# Run Multi-Agent ADK Workflow
curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{"request": "Event-driven regional HTTP application in Podman"}'
```

---

## 📁 Repository Structure
```
gcp_solution_architecture_agent/
├── app/
│   ├── adk/                     # Google ADK framework primitives & fallbacks
│   │   ├── agents.py            # Multi-agents & OrchestratorLoopAgent
│   │   ├── artifacts.py         # PostgresArtifactRepository
│   │   ├── compat.py            # ADK compatibility layer
│   │   ├── evaluation.py        # ADKEvaluator
│   │   ├── runners.py           # ADKAgentRunner
│   │   ├── sessions.py          # PostgresSessionService
│   │   ├── tools.py             # ADK FunctionTools
│   │   └── workflows.py         # ADK Workflow composition
│   ├── agent.py                 # Starlette REST server entrypoint
│   ├── card.py                  # AgentCard & capability metadata
│   ├── config.py                # Typed settings (Pydantic BaseSettings)
│   ├── database.py              # PostgreSQL database persistence manager
│   ├── nodes/                   # Phase execution node handlers
│   ├── skills/                  # Local SKILL.md instruction templates & SkillLoader
│   ├── states/                  # GCPArchitectureState schema definition
│   ├── tools/                   # LangChain & ADK validation tools
│   └── workflows/               # LangGraph StateGraph & Starlette REST routes
├── eval/                        # ADK Evaluation & Optimization Harness
│   ├── datasets/                # Benchmark test cases (JSON)
│   ├── eval_harness.py          # Benchmark runner CLI
│   ├── metrics.py               # Scoring rubrics & evaluation logic
│   ├── optimizer.py             # Prompt tuning optimizer
│   └── test_eval_harness.py     # Evaluation unit tests
├── deliverables/                 # Scalable deliverable repository (categorized & versioned)
│   ├── as-is/                   # Pre-emptive Source Environment Deliverables (Before State)
│   │   ├── source-architecture.md
│   │   └── source-architecture.mmd
│   ├── target/                  # Target Architecture Deliverables (After State)
│   │   ├── requirements.md
│   │   ├── architecture.md
│   │   └── architecture.mmd
│   ├── validation/              # Pre-deployment Validation Reports
│   │   └── validation-results.md
│   ├── guides/                  # Consolidate Solution Architecture Guides
│   │   └── solution-architecture-guide.md
│   └── executions/              # Per-Execution Versioned Snapshots ({execution_id}/*)
├── docs/                        # Specifications, audit notes & verification records
├── terraform/                   # Deployable GCP Terraform IaC blueprint
├── scripts/
│   └── validate_artifacts.py    # Static artifact validation script
└── tests/                       # Unit & integration test suite
```