# 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 (design):** `product-selector`, `design-advisor` (which consults one `pillar-advisor` per architecture-framework pillar), `target-architect`. - **Solution implementation:** `describer`, `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. The design Phase ends with the **Target architecture**: one explicit graph of Elements, Relationships and Checks ([ADR-0005](docs/adr/0005-the-target-architecture-is-an-explicit-graph.md)). The user approves it before any infrastructure code is written. The diagram is drawn from it by code, the Terraform must account for every Check, and validation gives a verdict per Check. Requirements, components, products and recommendations each carry ids in a data file, so every requirement can be traced through to its verdict; a submission with a missing link is refused. ### 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/`, `skills/iac-validation/` and `skills/requirements-chain/`: our own Skills for the tooling and the data files. - `skills/google-cloud-iac-patterns/`: Terraform patterns for Google Cloud products, each validated by a test against the provider version `providers/gcp.yaml` pins. `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. Pass `customer_case` to group it with the case's other Executions; over A2A, send `customer_case` in the message metadata. 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 ``` ### 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 outputs (`deliverables/cases/{customer_case}/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_ENTERPRISE=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", "customer_case": "acme-webhooks"}' ``` --- ## 📁 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/ │ └── cases/ # Everything generated, grouped by Customer case │ └── / │ ├── intent/ # What the customer asked for, and how it has changed │ │ ├── 001.md, 002.md # Each request as the customer stated it, in order │ │ └── history.json # Every request, the Execution it started and how it ended │ └── executions// │ ├── execution.json # Request, status and files of this Execution │ ├── solution-architecture-guide.md │ ├── deliverables/.md # One per Deliverable │ ├── requirements.json, components.json, products.json, recommendations.json │ ├── target-architecture.json # Elements, Relationships and Checks │ ├── architecture.mmd # Drawn from the graph │ ├── terraform/, implementation.json # The code, and which part meets each Check │ └── verdicts.json # Validation's verdict on each Check ├── lessons/candidates// # Lesson candidates per Execution (gitignored) ├── docs/ # ADRs, agent-skill conventions and operations notes ├── scripts/ # Vendored-Skill sync, MCP tool listing └── tests/ # Unit & integration test suite ```