177 lines
9.0 KiB
Markdown
177 lines
9.0 KiB
Markdown
# 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.
|
|
|
|
---
|
|
|
|
## 🌟 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.
|
|
|
|
### 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.
|
|
|
|
### 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.
|
|
|
|
### 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)
|
|
|
|
The `SkillLoader` (`app/skills/loader.py`) dynamically parses frontmatter and injects instructions into phase system prompts.
|
|
|
|
### 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.
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start & Commands
|
|
|
|
### Install Dependencies
|
|
```bash
|
|
pip install -r requirements.txt
|
|
pip install -r requirements-dev.txt
|
|
```
|
|
|
|
### Run Tests & Validation
|
|
```bash
|
|
# Run pytest test suite (100% pass rate)
|
|
pytest -v
|
|
|
|
# Run offline benchmark evaluation harness
|
|
python3 -m eval.eval_harness
|
|
|
|
# Run static artifact validation
|
|
python3 scripts/validate_artifacts.py
|
|
```
|
|
|
|
### Start Starlette REST Server
|
|
```bash
|
|
python3 app/agent.py --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 GCP_PROJECT_ID=your-project-id \
|
|
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
|
|
|
|
# Agent Capability Card
|
|
curl http://localhost:8080/card
|
|
|
|
# Run Multi-Agent ADK Workflow
|
|
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/
|
|
├── 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
|
|
│ ├── 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
|
|
├── 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
|
|
```
|
|
|