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 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, 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.
• 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; decisions are recorded in 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

pip install -r requirements.txt
pip install -r requirements-dev.txt

Run Tests & Validation

# 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

python3 app/agent.py --host 0.0.0.0 --port 8080

🐳 Run with Podman

1. Build the Podman Container Image

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:

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

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

# 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