Files
gcp_solution_architecture_a…/README.md
Jonathan Boniface 7ee49ab352
Some checks failed
validation / verify (push) Failing after 10s
latest refactoring
2026-10-06 20:22:37 +01:00

170 lines
8.6 KiB
Markdown

# 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:** `product-selector`, `diagrammer`, `describer`, `design-advisor` (which consults one `pillar-advisor` per architecture-framework pillar), `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.
### 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/` and `skills/iac-validation/`: our own Skills for the tooling.
`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.
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
# Run static artifact validation
python3 scripts/validate_artifacts.py
```
### 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 deliverables (`deliverables/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_VERTEXAI=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"}'
```
---
## 📁 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/ # Scalable deliverable repository (categorized & versioned)
│ ├── as-is/ # Pre-emptive Source Environment Deliverables (Before State)
│ │ ├── source-architecture.md
│ │ └── source-architecture.mmd
│ ├── target/ # Target Architecture Deliverables (After State)
│ │ ├── requirements.md
│ │ ├── architecture.md
│ │ └── architecture.mmd
│ ├── validation/ # Pre-deployment Validation Reports
│ │ └── validation-results.md
│ ├── guides/ # Consolidate Solution Architecture Guides
│ │ └── solution-architecture-guide.md
│ └── executions/ # Per-Execution Versioned Snapshots ({execution_id}/*)
├── docs/ # Specifications, audit notes & verification records
├── terraform/ # Deployable GCP Terraform IaC blueprint
├── scripts/
│ └── validate_artifacts.py # Static artifact validation script
└── tests/ # Unit & integration test suite
```