Increment 3 of .scratch/solution-architect-agent/spec.md, test-first. - app/execution/deliverables.py: four Phases, nine Deliverables and their Dependencies declared once, plus per-kind contracts (required headings, attachments) checked by check_submission. - app/execution/ledger.py: pure Ledger enforcing both acceptance thresholds, Phase Approvals (including pre-approved mode and change requests), Revision cascade with withdrawn Approvals, the revision cap with escalation and user override, attempt numbers that reject stale submissions, an ordered event log, and dict round-tripping. - 37 new tests; full suite 102 passed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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-architectureskill 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.adkclasses below are local compatibility stubs. The realgoogle-adkpackage 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 usinggoogle.adk.tools.FunctionTool.PackagingAgent(Phase 3): Compiles the final comprehensivesolution-architecture-guide.mdwith 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 ormax_iterationsis 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:FunctionToolwrappers for static artifact and diagram validators, plus Google Developer Knowledge MCP tools (developerknowledge:*).google.adk.artifacts:ArtifactRepositorysynchronized with disk and PostgreSQL.google.adk.sessions:PostgresSessionServicefor durable session memory.google.adk.runners:Runnerfor managing execution workflows.google.adk.workflows:Workflowcomposition primitives.google.adk.evaluation:Evaluatorfor 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 (includingdocs/source-architecture.mdandsource-architecture.mmd).orchestrator_review_logs: Detailed iteration review logs from theOrchestratorLoopAgent.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