Iteration 4: - Overlay Skills (step 12): an Execution names an organisation's standards Skill from the folders the deployment configures; recorded with its version. An example standards Skill and an evaluation case that uses it. - Lessons (step 10): a prove command that compares a run with lessons against one without, and triage of evidence an existing lesson already covers. Iteration 5: - Step 8: the references of a Specialist's Skills its task needs are named in its context as read_first. - Step 14: a remote MCP server's reply that instructs the agent is withheld; the user's own text is flagged as a risk and nothing more. - Step 15: in a Change request, items only reworded are listed apart from real changes. - Step 19: each Execution's design recommendations are judged when it ends and the scores kept in its record. The evaluation takes its rubric from the same place. Each question was calibrated against live Jev; none has run in a case. Steps 6, 7, 9, 13 and 18 stay planned, with the reasons in the plan map. 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