# GCP Solution Architecture Agent (`gcp_solution_architecture_agent`) A hierarchical ReAct agent that turns a request for a cloud workload into a reviewed solution architecture: requirements, a target design with diagram and infrastructure-as-code, validation results, and a packaged guide. It replaces the [`google-cloud-solution-architecture`](https://github.com/google/skills/blob/main/skills/cloud/google-cloud-solution-architecture/SKILL.md) skill with an agent that runs anywhere. Google Cloud is the first Cloud provider. Vocabulary is defined in [CONTEXT.md](CONTEXT.md), decisions in [docs/adr/](docs/adr/), and the plan and history of each iteration in [.agents/plans/](.agents/plans/README.md). --- ## 🌟 Architecture & Features ### 1. Orchestrator and Specialists (`agents/`) One Orchestrator coordinates an Execution and is the only agent that talks to the user. It delegates each Deliverable to one Specialist, and independent Deliverables run in parallel: - **Requirements discovery:** `requirements-analyst`, `decomposer`. - **Solution architecture:** `product-selector`, `diagrammer`, `describer`, `design-advisor` (which consults one `pillar-advisor` per architecture-framework pillar), `iac-author`. - **Solution validation:** `validator`. - **Packaging:** `packager`. Each Phase needs the user's explicit Approval before work that depends on it starts. A pre-approved mode serves batch and evaluation runs. ### 2. LangGraph state, ADK agents (`app/`) Per [ADR-0003](docs/adr/0003-langgraph-holds-state-adk-agents-reason.md): - A LangGraph `StateGraph` holds the Execution: the dependency graph of Deliverables (`app/workflows/deliverables.py`), the Ledger of their states (`app/states/ledger.py`), checkpoints, and `interrupt()` whenever the user must answer or approve. - Every agent is a Google ADK `LlmAgent` running its own ReAct loop behind one runtime interface (`app/adk/runtime.py`). `app/adk/adk_runtime.py` is the only module that imports `google.adk`. - Tools are tiered: local checks and public documentation run freely, reading the user's cloud needs permission once per Execution, and nothing can change cloud resources. ### 3. Persistence (`app/database.py`, `app/checkpointing.py`) Execution records (status, Ledger events, submitted Deliverables) go to PostgreSQL, with an automatic SQLite fallback for local development. Checkpoints use `CHECKPOINTER=memory | sqlite | postgres`. ### 4. Agent Skills (`skills/`, loaded by `app/skills/`) Behaviour lives in Agent Skills (agentskills.io format) at the repository root, per ADR-0002: - `skills/vendor/google/`: the upstream solution-architecture Skill and six Well-Architected Framework pillar Skills, vendored unmodified. - `skills/cloud-discovery/` and `skills/iac-validation/`: our own Skills for the tooling. `app/skills/agent_skills.py` discovers and validates them; the ADK runtime (`app/adk/adk_runtime.py`) loads them on demand. `providers/gcp.yaml` assigns Skills, tools, MCP servers and models to each role in `agents/`. ### 5. A2A Server (`app/main.py`) The container starts the hierarchical Execution engine (ADR-0003) behind an A2A server: - `POST /a2a`: A2A JSON-RPC for interactive, multi-turn Executions with Approvals. - `GET /.well-known/agent-card.json`: A2A agent card. - `GET /health`: Health signal, the Cloud provider and any MCP discovery gaps. - `POST /generate`: One-shot, pre-approved Execution for batch and evaluation callers. The original linear pipeline and its REST routes (`/card`, `/validate`, `/sessions/{session_id}`) were removed on 2026-10-06; see `.agents/plans/iter-03-kab-layout/`. --- ## 🚀 Quick Start & Commands ### Install Dependencies ```bash pip install -r requirements.txt pip install -r requirements-dev.txt ``` ### Run Tests & Validation ```bash # Run the deterministic test suite (no model or network calls) pytest -q # Real-model evaluation of the engine (costs model usage; see eval/solution_eval.py) python3 -m eval.solution_eval # Run static artifact validation python3 scripts/validate_artifacts.py ``` ### Start the A2A Server ```bash python3 -m app.main --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 GOOGLE_GENAI_USE_VERTEXAI=true \ -e GOOGLE_CLOUD_PROJECT=your-project-id \ -e GOOGLE_CLOUD_LOCATION=global \ -e A2A_PUBLIC_URL=http://localhost:8080 \ 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 # A2A Agent Card curl http://localhost:8080/.well-known/agent-card.json # Run a pre-approved Execution 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/ ├── agents/ # Framework-neutral role files, one per agent ├── providers/ # Cloud provider bundles (gcp.yaml) ├── skills/ # Agent Skills: vendored upstream + our tooling Skills ├── app/ # KAB workflow-agent layout │ ├── main.py # A2A server entrypoint (python -m app.main) │ ├── a2a_server.py # Maps A2A tasks to Executions and their prompts │ ├── agent.py # ExecutionEngine and its assembly (composition root) │ ├── card.py # A2A agent card │ ├── states/ # ExecutionState and the Ledger │ ├── nodes/ # Execution graph nodes (orchestrator, specialist, user) │ ├── workflows/ # Execution graph wiring and the Deliverable dependency graph │ ├── adk/ # Agent-runtime interface, ADK runtime, role loader │ ├── skills/ # Agent Skills discovery and validation │ ├── tools/ # Execution tools, local tools, remote MCP, pillar fan-out │ ├── providers.py # Provider bundle loader │ ├── recorder.py # Execution recording │ ├── checkpointing.py # LangGraph checkpointer selection │ ├── presentation.py # Prompts and /generate responses │ ├── config.py # Typed settings (Pydantic BaseSettings) │ └── database.py # Database persistence manager ├── eval/ # Evaluation │ ├── solution_eval.py # Real-model evaluation of the Execution engine │ ├── scoring.py # Checks applied to a finished Execution │ └── datasets/ # Benchmark cases (JSON) ├── 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 ```