Jonathan Boniface d41607f505 fix: read only the user's own words, and stop the router looping at a limit
Case 04, the first interactive evaluation, stopped at 100 Orchestrator
turns on two router faults:

- A reply that quoted the agent's question back was judged on that question.
  A reply now reaches the router with quoted questions and Q:/A: labels
  removed, and the questions are given to the decider as background.
- At a Revision limit the reply was read as another change request for the
  same Deliverable, and the refusal repeated. The user is now told once,
  the reply is taken as the answer, that Deliverable is not reopened again,
  and the Execution carries on with it as it stands.
- Any run that asks the user four times running with no work done in
  between now ends with a warning.

The validator is told to confirm with the user in an interactive Execution.

Plans record the fixes and the rerun, which did not finish: both fixes
held, and a third fault appeared that is not fixed here. A scripted answer
restating a requirement, given to a draft-confirmation question, reopens
requirements.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-08 15:05:03 +01:00
2026-10-06 20:22:37 +01:00
2026-10-06 20:22:37 +01:00
2026-10-06 20:22:37 +01:00

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 skill with an agent that runs anywhere. Google Cloud is the first Cloud provider.

Vocabulary is defined in CONTEXT.md, decisions in docs/adr/, and the plan and history of each iteration in .agents/plans/.


🌟 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 (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.

The design Phase ends with the Target architecture: one explicit graph of Elements, Relationships and Checks (ADR-0005). 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:

  • 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-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)

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.

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

pip install -r requirements.txt
pip install -r requirements-dev.txt

Run Tests & Validation

# 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

Start the A2A Server

python3 -m app.main --host 0.0.0.0 --port 8080

🐳 Run with Podman

1. Build the Podman Container Image

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:

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

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

# 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 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/
│   └── 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 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
├── 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
Description
Generated deliverable: gcp_solution_architecture_agent
Readme 2.3 MiB
Languages
Python 86.5%
Mermaid 10.7%
HCL 1.6%
Dockerfile 0.8%
Shell 0.4%