A pillar's checklist item the request gives no information about was marked "not addressed", which reads as a fault in the design. It is missing information. The checklist review gains a fourth outcome, to confirm with the customer, which must carry the question to ask. The questions are written into the design recommendations and the guide, and to customer-questions.md; the evaluation's judged check counts such an item as accounted for. Records the owner's decisions of 2026-10-10 and the vendor's answers on Jev's retention, training, context and rate limits (iteration 5 step 1), and the owner's labels, which showed the judged question was wrong, not the judges. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
GCP Solution Architecture Agent (gcp_solution_architecture_agent)
A hierarchical 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 is a router (ADR-0007): code reads the Execution's state, a decision model (Jev) answers the closed questions that need judgement, and a playbook in code picks the action. A language model only writes what the user reads. 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.
A Change request (ADR-0006) starts from a completed Execution in the same Customer case, its Baseline, and delivers the full updated Deliverables with changes.json: what changed, what was only reworded, and anything changed that nobody asked for.
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 (ADR-0004). SetLESSONS_ENABLED=falseto run without them.skills/overlays/: overlay Skills, each an organisation's standards or one engagement's constraints. An Execution names the ones it wants;DEFAULT_OVERLAY_SKILLSnames the ones every Execution loads. The one here is an example, not anyone's policy.skills/google-cloud-iac-patterns/: Terraform patterns for Google Cloud products, each validated by a test against the provider versionproviders/gcp.yamlpins.skills/google-cloud-iac-modules/: published modules fromterraform-google-modulesthat work with that provider version, and the rule for when one fits better than plain resources. Generated code is plain resources by default. An Execution opts in withterraform_modules: true, and may then take a module only from the registry namespacesproviders/gcp.yamllists, at one exact version.
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. Decisions by Jev (app/tools/jev.py)
Jev is a hosted decision model that answers typed, closed questions with a probability. It is optional: without TYPESAFE_API_KEY every decision takes its fallback in code. Beyond routing the Orchestrator it is used to:
- read a message that starts something: a new request, a Change request, or a question (
app/nodes/intake.py); - choose which pillar advisors a change needs consulting again, and which Skill references a Specialist should read first;
- withhold a remote MCP server's reply that reads as instructions to the agent, and flag the same in the user's text;
- tell a rewording from a real change in a Change request;
- score each Execution's design recommendations when it ends, kept in
execution.jsonunderassessment.
Every setting, with its threshold, is described in .env.example. What each use measured against the live service is in .agents/plans/iter-05-jev-decisions/.
6. 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,baseline(an Execution id in that case) to make it a Change request,overlay_skills(a list of names) to apply overlay Skills, andterraform_modules: trueto allow published Terraform modules from the approved sources. Over A2A, send the same fields 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
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
Copy .env.example to .env for local settings. The server and the evaluation read it at start-up, and export its model credentials (GOOGLE_*) to the process.
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 own, lessons, overlays
├── 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)
│ ├── baseline.py # Loading the Execution a Change request starts from
│ ├── card.py # A2A agent card
│ ├── states/ # ExecutionState and the Ledger
│ ├── nodes/ # Execution graph nodes, the router and message intake
│ ├── workflows/ # Execution graph wiring, the Deliverable dependency graph,
│ │ # the Requirements chain and change summaries
│ ├── adk/ # Agent-runtime interface, ADK runtime, role loader
│ ├── skills/ # Agent Skills discovery and validation
│ ├── tools/ # Execution tools, local tools, remote MCP, pillar fan-out,
│ │ # the Jev client and each decision that uses it
│ ├── learning/ # The lessons loop: evidence, proposals, publishing, proof
│ ├── 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
│ ├── judge.py # The judges for the judged checks (Jev, or a model)
│ ├── calibrate_judge.py # Judges against a person's labels, and against each other
│ ├── curate_lessons.py # propose, publish, prove and retire lessons
│ └── datasets/ # Benchmark cases (JSON) and the judge's labelled set
├── 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, Baseline, overlay Skills,
│ │ # risks, assessment 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
│ ├── working.json # What a Change request carries forward
│ └── changes.json # In a Change request: what changed and why
├── 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