- Schema review: a dotted path is judged only when it starts at a name the resource type has, so a database flag or a service name is no longer read as a missing setting. Lesson L-04, which worked around that, is retired. - Skill routing: in a Change request the question says what changed. - Evaluation: a case may list code_standards the infrastructure code must meet; case 06 checks its overlay's regions, naming and labels. - Model tiers (iteration 5 step 6): a lighter model for a role's first attempt, named in the provider bundle. Measured on case 03 and left off: Flash saved five cents on the IaC author and took twice the requests. - Steps 7 and 9 decided against on the numbers, recorded in the plans. - Plans: the runs of cases 05 and 06, and the first proof of the lessons on case 03 (no Revision, 22 minutes against 28, quality held). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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 skill with an agent that runs anywhere. Google Cloud is the first Cloud provider.
Vocabulary is defined in CONTEXT.md, decisions in docs/adr/, and the plan and history of each iteration in .agents/plans/.
🌟 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 onepillar-advisorper 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). 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:
- A LangGraph
StateGraphholds the Execution: the dependency graph of Deliverables (app/workflows/deliverables.py), the Ledger of their states (app/states/ledger.py), checkpoints, andinterrupt()whenever the user must answer or approve. - Every agent is a Google ADK
LlmAgentrunning its own ReAct loop behind one runtime interface (app/adk/runtime.py).app/adk/adk_runtime.pyis the only module that importsgoogle.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/andskills/requirements-chain/: our own Skills for the tooling and the data files.skills/google-cloud-lessons/: lessons learned from earlier Executions, written by the lessons loop (app/learning/,eval/curate_lessons.py) from proposals a person approved. Empty until one is.skills/google-cloud-iac-patterns/: Terraform patterns for Google Cloud products, each validated by a test against the provider versionproviders/gcp.yamlpins.
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. Passcustomer_caseto group it with the case's other Executions; over A2A, sendcustomer_casein 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
pip install -r requirements.txt
pip install -r requirements-dev.txt
Run Tests & Validation
# 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
python3 -m app.main --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 outputs (deliverables/cases/{customer_case}/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 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
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
# 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
│ └── <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_id>/
│ ├── execution.json # Request, status and files of this Execution
│ ├── solution-architecture-guide.md
│ ├── deliverables/<kind>.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/<customer_case>/ # 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