Infrastructure code is plain resources by default. An Execution may opt in with terraform_modules; the deployment default is TERRAFORM_MODULES, off. - A module is accepted only from the registry namespaces the provider bundle lists (terraform-google-modules), at one exact version. Any other source is refused before Terraform runs; until now nothing stopped generated code naming any source for terraform init to download. - terraform_module looks up a module's inputs, outputs and submodules from the registry and says when it cannot be used with the pinned provider. - skills/google-cloud-iac-modules: when a module fits, and four modules with examples a test validates against hashicorp/google 8.6.0. - Opted in, the IaC author and validator get the Skill and the lookup. Not opted in, they get neither and a module block is refused in code. - A Change request follows its Baseline. execution.json records the choice. - case-07 runs case 03's request with modules opted into. Azure (aztfm) and AWS (terraform-aws-modules) sources are recorded in the plan for when those Cloud providers are added. No case has run with this. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
199 lines
14 KiB
Markdown
199 lines
14 KiB
Markdown
# 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`](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 is a router ([ADR-0007](docs/adr/0007-jev-is-the-orchestrators-decision-point.md)): 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 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.
|
|
|
|
A **Change request** ([ADR-0006](docs/adr/0006-a-change-request-starts-from-a-baseline-execution.md)) 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](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-lessons/`: lessons learned from earlier Executions, written by the lessons loop (`app/learning/`, `eval/curate_lessons.py`) from proposals a person approved ([ADR-0004](docs/adr/0004-lessons-and-overlays-arrive-as-skills.md)). Set `LESSONS_ENABLED=false` to 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_SKILLS` names 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 version `providers/gcp.yaml` pins.
|
|
- `skills/google-cloud-iac-modules/`: published modules from `terraform-google-modules` that 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 with `terraform_modules: true`, and may then take a module only from the registry namespaces `providers/gcp.yaml` lists, 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.json` under `assessment`.
|
|
|
|
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. Pass `customer_case` to 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, and `terraform_modules: true` to 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
|
|
```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
|
|
```
|
|
|
|
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
|
|
```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 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
|
|
```
|
|
|