latest refactoring
Some checks failed
validation / verify (push) Failing after 10s

This commit is contained in:
2026-10-06 20:22:37 +01:00
parent e94b2493e7
commit 7ee49ab352
414 changed files with 15768 additions and 3896 deletions

145
README.md
View File

@@ -1,61 +1,46 @@
# GCP Solution Architecture Agent (`gcp_solution_architecture_agent`)
A production-ready Google Cloud Solution Architecture Agent built using **Google ADK (Agent Development Kit)**, **LangChain**, and **LangGraph**, featuring a multi-agent orchestration graph with iterative review loops, dynamic local skill loading, PostgreSQL database persistence, a Starlette REST API server, and an offline evaluation harness.
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.
> **Direction and current state (2026-09-15).** This agent is being built to replace the [`google-cloud-solution-architecture`](https://github.com/google/skills/blob/main/skills/cloud/google-cloud-solution-architecture/SKILL.md) skill with something that runs on any agent framework and, later, targets any Cloud provider. Google Cloud is the first provider.
> - **Target:** behaviour lives in [Agent Skills](https://agentskills.io/specification), loaded by a framework's own skill runtime (Google ADK `SkillToolset`, or LangChain Deep Agents skills). This repo supplies the tooling those Skills call. See [ADR-0002](docs/adr/0002-skills-are-the-portable-unit-of-behaviour.md).
> - **Today:** the `google.adk` classes below are local compatibility stubs. The real `google-adk` package isn't used, and Phase outputs are fixed templates, not model-generated.
>
> Vocabulary is defined in [CONTEXT.md](CONTEXT.md); decisions are recorded in [docs/adr/](docs/adr/).
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. Multi-Agent Orchestration & `google.adk.agents.LoopAgent`
The agent uses an end-to-end multi-agent graph managed by an `OrchestratorLoopAgent` (`google.adk.agents.LoopAgent`):
- **`SourceDiscoveryAgent`** (Phase 0a): Pre-emptively audits and documents the existing pre-migration source environment (As-Is Architecture) and pain points.
- **`DiscoveryAgent`** (Phase 0): Discovers functional & non-functional requirements while explicitly deferring product selection.
- **`ArchitectureDesignAgent`** (Phase 1): Resolves product selections (Cloud Run, Pub/Sub, Cloud Storage, Firestore, IAM, KMS), grounds guidance with **Google Developer Knowledge MCP**, generates Mermaid diagrams (`architecture.mmd`), and builds Terraform IaC (`terraform/main.tf`).
- **`ValidationReviewAgent`** (Phase 2): Evaluates Mermaid syntax, Terraform structural integrity, and artifact completeness using `google.adk.tools.FunctionTool`.
- **`PackagingAgent`** (Phase 3): Compiles the final comprehensive `solution-architecture-guide.md` with **Before (Source) vs After (Target)** architecture comparison.
- **`OrchestratorLoopAgent`**: Repeatedly loops through the multi-agent pipeline, reviewing and validating content in a feedback loop until production quality criteria pass or `max_iterations` is reached.
### 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`.
### 2. Google ADK Integration (`google.adk`)
Built directly on Google ADK framework primitives (with offline compatibility stubs):
- **`google.adk.agents`**: `LlmAgent`, `SequentialAgent`, `ParallelAgent`, `LoopAgent`.
- **`google.adk.tools`**: `FunctionTool` wrappers for static artifact and diagram validators, plus Google Developer Knowledge MCP tools (`developerknowledge:*`).
- **`google.adk.artifacts`**: `ArtifactRepository` synchronized with disk and PostgreSQL.
- **`google.adk.sessions`**: `PostgresSessionService` for durable session memory.
- **`google.adk.runners`**: `Runner` for managing execution workflows.
- **`google.adk.workflows`**: `Workflow` composition primitives.
- **`google.adk.evaluation`**: `Evaluator` for scoring benchmark suites.
Each Phase needs the user's explicit Approval before work that depends on it starts. A pre-approved mode serves batch and evaluation runs.
### 3. PostgreSQL Database Persistence (`app/database.py`)
State, sessions, workflow executions, review iteration logs, and evaluation metrics are written to an external PostgreSQL database (with an automatic SQLite fallback for offline development):
- `adk_sessions`: Durable session memory and state data.
- `workflow_executions`: Workflow execution status, phase, and iteration metrics.
- `adk_artifacts`: Generated solution architecture artifacts (including `docs/source-architecture.md` and `source-architecture.mmd`).
- `orchestrator_review_logs`: Detailed iteration review logs from the `OrchestratorLoopAgent`.
- `adk_evaluations`: Benchmark evaluation scores and pass rates.
### 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.
### 4. Dynamic Local Skill Loading (`app/skills/`)
Domain knowledge is stored as self-contained markdown instruction templates under `app/skills/`:
- `source_discovery/SKILL.md` (Phase 0a - Pre-emptive Source Environment Discovery)
- `requirements_discovery/SKILL.md` (Phase 0 - Requirements Discovery & Deferral)
- `architecture_design/SKILL.md` (Phase 1 - Product Selection & Terraform IaC)
- `validation_rules/SKILL.md` (Phase 2 - Pre-deployment Validation Rules)
- `packaging_guide/SKILL.md` (Phase 3 - Solution Guide Packaging)
### 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`.
The `SkillLoader` (`app/skills/loader.py`) dynamically parses frontmatter and injects instructions into phase system prompts.
### 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.
### 5. Starlette REST API Server (`app/agent.py`)
Production HTTP REST endpoints exposed via Starlette and Uvicorn:
- `GET /health`: Operational health signal & database connection status.
- `GET /card`: Agent capability card metadata.
- `POST /generate`: Trigger the ADK multi-agent workflow execution.
- `POST /validate`: Execute pre-deployment artifact validation.
- `GET /sessions/{session_id}`: Query session state from the PostgreSQL database.
`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/`.
---
@@ -69,19 +54,19 @@ pip install -r requirements-dev.txt
### Run Tests & Validation
```bash
# Run pytest test suite (100% pass rate)
pytest -v
# Run the deterministic test suite (no model or network calls)
pytest -q
# Run offline benchmark evaluation harness
python3 -m eval.eval_harness
# 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 Starlette REST Server
### Start the A2A Server
```bash
python3 app/agent.py --host 0.0.0.0 --port 8080
python3 -m app.main --host 0.0.0.0 --port 8080
```
### 🐳 Run with Podman
@@ -100,7 +85,10 @@ podman run -d --name gcp-agent \
-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 GCP_PROJECT_ID=your-project-id \
-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
```
@@ -121,10 +109,10 @@ podman run -d --name gcp-agent \
# Health Signal
curl http://localhost:8080/health
# Agent Capability Card
curl http://localhost:8080/card
# A2A Agent Card
curl http://localhost:8080/.well-known/agent-card.json
# Run Multi-Agent ADK Workflow
# 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"}'
@@ -135,31 +123,30 @@ curl -X POST http://localhost:8080/generate \
## 📁 Repository Structure
```
gcp_solution_architecture_agent/
├── app/
│ ├── adk/ # Google ADK framework primitives & fallbacks
│ │ ├── agents.py # Multi-agents & OrchestratorLoopAgent
│ │ ├── artifacts.py # PostgresArtifactRepository
│ │ ├── compat.py # ADK compatibility layer
│ │ ├── evaluation.py # ADKEvaluator
│ │ ├── runners.py # ADKAgentRunner
│ │ ├── sessions.py # PostgresSessionService
│ │ ├── tools.py # ADK FunctionTools
│ │ └── workflows.py # ADK Workflow composition
│ ├── agent.py # Starlette REST server entrypoint
│ ├── card.py # AgentCard & capability metadata
├── 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 # PostgreSQL database persistence manager
│ ├── nodes/ # Phase execution node handlers
│ ├── skills/ # Local SKILL.md instruction templates & SkillLoader
│ ├── states/ # GCPArchitectureState schema definition
│ ├── tools/ # LangChain & ADK validation tools
│ └── workflows/ # LangGraph StateGraph & Starlette REST routes
├── eval/ # ADK Evaluation & Optimization Harness
│ ├── datasets/ # Benchmark test cases (JSON)
│ ├── eval_harness.py # Benchmark runner CLI
│ ├── metrics.py # Scoring rubrics & evaluation logic
│ ├── optimizer.py # Prompt tuning optimizer
│ └── test_eval_harness.py # Evaluation unit tests
│ └── 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