docs: bring the README, runbook, glossary and ADR notes up to date
Some checks failed
validation / verify (push) Failing after 11s
Some checks failed
validation / verify (push) Failing after 11s
The README now covers the router, Change requests, overlay Skills, Jev's uses and the current layout. VALIDATION.md no longer points at the removed root Terraform. ADR-0004 and ADR-0007 gain dated "As built" notes; ADR-0007's says which uses of Jev send Deliverable content. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
49
README.md
49
README.md
@@ -1,6 +1,6 @@
|
||||
# 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.
|
||||
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).
|
||||
|
||||
@@ -9,7 +9,7 @@ Vocabulary is defined in [CONTEXT.md](CONTEXT.md), decisions in [docs/adr/](docs
|
||||
## 🌟 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:
|
||||
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`.
|
||||
@@ -18,6 +18,8 @@ One Orchestrator coordinates an Execution and is the only agent that talks to th
|
||||
|
||||
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/`)
|
||||
@@ -33,17 +35,28 @@ Execution records (status, Ledger events, submitted Deliverables) go to PostgreS
|
||||
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. Empty until one is.
|
||||
- `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.
|
||||
|
||||
`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`)
|
||||
### 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; over A2A, send `customer_case` in the message metadata.
|
||||
- `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, and `overlay_skills` (a list of names) to apply overlay Skills. 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/`.
|
||||
|
||||
@@ -66,6 +79,8 @@ pytest -q
|
||||
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
|
||||
@@ -127,18 +142,22 @@ curl -X POST http://localhost:8080/generate \
|
||||
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
|
||||
├── 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 (orchestrator, specialist, user)
|
||||
│ ├── workflows/ # Execution graph wiring and the Deliverable dependency graph
|
||||
│ ├── 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
|
||||
│ ├── 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
|
||||
@@ -148,7 +167,10 @@ gcp_solution_architecture_agent/
|
||||
├── eval/ # Evaluation
|
||||
│ ├── solution_eval.py # Real-model evaluation of the Execution engine
|
||||
│ ├── scoring.py # Checks applied to a finished Execution
|
||||
│ └── datasets/ # Benchmark cases (JSON)
|
||||
│ ├── 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>/
|
||||
@@ -156,14 +178,17 @@ gcp_solution_architecture_agent/
|
||||
│ │ ├── 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 and files of this Execution
|
||||
│ ├── 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
|
||||
│ ├── 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
|
||||
|
||||
Reference in New Issue
Block a user