The reference agent's subject, cloud solution architecture, as an agent in the operating model agent's pattern: the Execution engine (from orchestration_engine) and one Workflow in app/solution_architecture, built for the settings and provider bundle by assembly.workflow_for. Copied from gcp_solution_architecture_agent at 8b397cd without its own engine: its role files, Skills, provider bundle, ADRs, vocabulary, scripts and evaluation datasets. The image takes the engine from a named build context and installs Terraform. It is called through the Orchestration engine, and its files are what the operating model agent digests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
375 lines
14 KiB
Python
375 lines
14 KiB
Python
"""The design advisor's fan-out to one advisor per architecture-framework pillar.
|
|
|
|
Pillar advice is working material for the design recommendations Deliverable, not a
|
|
Deliverable itself, so it never touches the Ledger. It is kept in that Deliverable's
|
|
working memory, so a Revision re-consults only the pillars its feedback touches.
|
|
|
|
Each advisor also returns its review of the pillar's own checklist: for every item,
|
|
whether its advice addresses it, or why it does not apply. The reviews are kept
|
|
beside the advice and written into the Deliverable by code when it is submitted, so
|
|
an architect sees the whole checklist accounted for and no model spends output
|
|
copying it.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import asyncio
|
|
import dataclasses
|
|
from collections.abc import Mapping, MutableMapping, Sequence
|
|
from contextlib import AsyncExitStack
|
|
from typing import Any
|
|
|
|
from execution_engine.adk.runtime import (
|
|
AgentRuntime,
|
|
AgentTask,
|
|
Decider,
|
|
Question,
|
|
RoleSpec,
|
|
RunLimiter,
|
|
Submitted,
|
|
ToolResult,
|
|
ToolSpec,
|
|
)
|
|
|
|
CONSULT_TOOL = "consult_pillar_advisors"
|
|
NO_GUIDANCE = "No guidance"
|
|
ADVICE_KEY = "pillar_advice" # working memory: pillar -> the advice last given
|
|
CHECKLIST_KEY = "pillar_checklists" # working memory: pillar -> its checklist review
|
|
REVIEW_HEADING = "Architecture framework checklist review"
|
|
# What a Change request carries over from its Baseline's working memory.
|
|
KEPT_FOR_CHANGES = (ADVICE_KEY, CHECKLIST_KEY)
|
|
_CHANGE_LIMIT = 6_000
|
|
NEEDS_CUSTOMER = "needs_customer_input"
|
|
STATUSES = ("addressed", "not_applicable", NEEDS_CUSTOMER, "not_addressed")
|
|
_STATUS_WORDS = {
|
|
"addressed": "Addressed",
|
|
"not_applicable": "Does not apply",
|
|
# The item applies, and the customer's request does not say what would settle
|
|
# it. That is missing information, not a fault in the design: it is reported
|
|
# with the question to put to the customer.
|
|
NEEDS_CUSTOMER: "To confirm with the customer",
|
|
"not_addressed": "Not addressed",
|
|
}
|
|
QUESTIONS_HEADING = "Questions for the customer"
|
|
|
|
|
|
AFFECTED = ("not at all", "only indirectly", "directly")
|
|
|
|
|
|
async def pillars_touched(
|
|
decider: Decider,
|
|
pillars: Sequence[str],
|
|
change: str,
|
|
*,
|
|
threshold: float = 1.5,
|
|
scope: str = "",
|
|
) -> list[str] | None:
|
|
"""The pillars whose recommendations a change affects directly (ADR-0007).
|
|
|
|
One graded question per pillar: not at all, only indirectly, directly. A pillar
|
|
at `threshold` or above, on that scale of 0 to 2, is consulted again. An empty
|
|
list means the change touches none of them. None means no decision was
|
|
available, and every pillar is consulted.
|
|
|
|
Asked as a yes or no ("does this change call for revisiting ...?") the answer
|
|
was yes for nearly every pillar of every change; measured on 2026-10-09.
|
|
"""
|
|
if not change.strip() or not pillars:
|
|
return None
|
|
answers = await decider.decide(
|
|
f"A change to a cloud solution architecture:\n{change[:_CHANGE_LIMIT]}",
|
|
{
|
|
pillar: Question(
|
|
"score",
|
|
f"How directly does this change affect the {pillar} "
|
|
"recommendations for the workload?",
|
|
AFFECTED,
|
|
)
|
|
for pillar in pillars
|
|
},
|
|
scope=scope,
|
|
)
|
|
if not answers:
|
|
return None
|
|
return [
|
|
pillar
|
|
for pillar in pillars
|
|
if (answer := answers.get(pillar)) is not None
|
|
and isinstance(answer.value, (int, float))
|
|
and answer.value >= threshold
|
|
]
|
|
|
|
|
|
def pillar_consultation_tool(
|
|
runtime: AgentRuntime,
|
|
advisor: RoleSpec,
|
|
pillar_skills: Mapping[str, str],
|
|
extra_tools: Sequence[ToolSpec] = (),
|
|
memory: MutableMapping[str, Any] | None = None,
|
|
limiter: RunLimiter | None = None,
|
|
) -> ToolSpec:
|
|
"""A tool that runs one pillar advisor per pillar, in parallel, each with its Skill.
|
|
|
|
With `memory`, advice is remembered: naming `pillars` re-consults only those and
|
|
returns the remembered advice for the rest.
|
|
"""
|
|
|
|
async def advise(pillar: str, brief: str) -> tuple[str, list[dict[str, str]]]:
|
|
async with AsyncExitStack() as stack:
|
|
if limiter:
|
|
await stack.enter_async_context(limiter.slot())
|
|
return await _advise(
|
|
runtime, advisor, pillar, pillar_skills[pillar], brief, extra_tools
|
|
)
|
|
|
|
async def consult(brief: str, pillars: Sequence[str] | None = None) -> ToolResult:
|
|
# No `pillars` consults them all; an empty list consults none, and returns
|
|
# what was said before.
|
|
chosen = list(pillar_skills) if pillars is None else list(pillars)
|
|
unknown = [pillar for pillar in chosen if pillar not in pillar_skills]
|
|
if unknown:
|
|
return ToolResult(
|
|
f"Refused: unknown pillars {', '.join(unknown)}; "
|
|
f"choose from {', '.join(pillar_skills)}"
|
|
)
|
|
async with AsyncExitStack() as stack:
|
|
if limiter:
|
|
# The calling Specialist only waits here, so its slot goes to advisors.
|
|
await stack.enter_async_context(limiter.lend())
|
|
fresh = dict(
|
|
zip(
|
|
chosen,
|
|
await asyncio.gather(*(advise(pillar, brief) for pillar in chosen)),
|
|
)
|
|
)
|
|
remembered: dict[str, str] = (
|
|
dict(memory.get(ADVICE_KEY, {})) if memory is not None else {}
|
|
)
|
|
reviews: dict[str, list[dict[str, str]]] = (
|
|
dict(memory.get(CHECKLIST_KEY, {})) if memory is not None else {}
|
|
)
|
|
sections = []
|
|
for pillar in pillar_skills:
|
|
if pillar in fresh:
|
|
advice, review = fresh[pillar]
|
|
if not advice.startswith(NO_GUIDANCE):
|
|
remembered[pillar] = advice
|
|
reviews[pillar] = review
|
|
sections.append(f"## {pillar}\n\n{advice}")
|
|
elif pillar in remembered:
|
|
sections.append(
|
|
f"## {pillar} (from your earlier consultation)\n\n"
|
|
f"{remembered[pillar]}"
|
|
)
|
|
if memory is not None:
|
|
memory[ADVICE_KEY] = remembered
|
|
memory[CHECKLIST_KEY] = reviews
|
|
return ToolResult("\n\n".join(sections))
|
|
|
|
return ToolSpec(
|
|
CONSULT_TOOL,
|
|
"Get guidance from one advisor per architecture-framework pillar, in parallel. "
|
|
"Give a brief with the workload, its requirements and the selected products. "
|
|
"Omit `pillars` to consult every pillar afresh. Name `pillars` to re-consult "
|
|
"only those; advice already given for the others is returned unchanged. An "
|
|
"empty list consults none and returns the advice already given.",
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"brief": {"type": "string"},
|
|
"pillars": {
|
|
"type": "array",
|
|
"items": {"type": "string", "enum": list(pillar_skills)},
|
|
},
|
|
},
|
|
"required": ["brief"],
|
|
},
|
|
consult,
|
|
)
|
|
|
|
|
|
async def _advise(
|
|
runtime: AgentRuntime,
|
|
advisor: RoleSpec,
|
|
pillar: str,
|
|
skill: str,
|
|
brief: str,
|
|
extra_tools: Sequence[ToolSpec],
|
|
) -> tuple[str, list[dict[str, str]]]:
|
|
"""One advisor's advice, and its review of the pillar's checklist."""
|
|
role = dataclasses.replace(advisor, skills=(skill,))
|
|
task = AgentTask(
|
|
role=advisor.name,
|
|
prompt=f"Advise on the {pillar} pillar for this workload.",
|
|
context={"pillar": pillar, "brief": brief},
|
|
)
|
|
review: list[dict[str, str]] = []
|
|
try:
|
|
outcome = await runtime.run(
|
|
role, task, [_submit_advice_tool(review), *extra_tools]
|
|
)
|
|
except Exception as exc: # noqa: BLE001 - one failed advisor must not lose the others
|
|
return f"{NO_GUIDANCE}: the advisor failed ({exc}).", []
|
|
if isinstance(outcome, Submitted):
|
|
return outcome.content.strip(), review
|
|
return f"{NO_GUIDANCE}: the advisor ended with {type(outcome).__name__}.", []
|
|
|
|
|
|
def _submit_advice_tool(review: list[dict[str, str]]) -> ToolSpec:
|
|
"""`review` receives the checklist review the advisor submits with its advice."""
|
|
|
|
async def submit_advice(content: str, checklist: Sequence[Any] = ()) -> ToolResult:
|
|
if not content.strip():
|
|
return ToolResult("Not submitted: the advice is empty.")
|
|
entries = [
|
|
{
|
|
"item": " ".join(str(entry.get("item", "")).split()),
|
|
"status": str(entry.get("status", "")),
|
|
"note": " ".join(str(entry.get("note", "")).split()),
|
|
"question": " ".join(str(entry.get("question") or "").split()),
|
|
}
|
|
for entry in checklist or ()
|
|
if isinstance(entry, Mapping)
|
|
and str(entry.get("item", "")).strip()
|
|
and entry.get("status") in STATUSES
|
|
]
|
|
unasked = [
|
|
entry["item"]
|
|
for entry in entries
|
|
if entry["status"] == NEEDS_CUSTOMER and not entry["question"]
|
|
]
|
|
if unasked:
|
|
return ToolResult(
|
|
"Not submitted: an item to confirm with the customer needs the "
|
|
"`question` to put to them. Missing for: " + "; ".join(unasked)
|
|
)
|
|
review[:] = entries
|
|
return ToolResult("Advice submitted.", Submitted(content))
|
|
|
|
text = {"type": "string"}
|
|
return ToolSpec(
|
|
"submit_advice",
|
|
"Submit your pillar recommendations as markdown, with your review of the "
|
|
"pillar's checklist. Ends your turn.",
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"content": text,
|
|
"checklist": {
|
|
"type": "array",
|
|
"description": "One entry for every item of the Skill's "
|
|
"validation checklist.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"item": text,
|
|
"status": {"type": "string", "enum": list(STATUSES)},
|
|
"note": {
|
|
"type": "string",
|
|
"description": "How your advice addresses it, why "
|
|
"it does not apply to this workload, or what the "
|
|
"request leaves unsaid.",
|
|
},
|
|
"question": {
|
|
"type": "string",
|
|
"description": "For needs_customer_input only: "
|
|
"the question to put to the customer, answerable "
|
|
"by someone who knows their organisation.",
|
|
},
|
|
},
|
|
"required": ["item", "status", "note"],
|
|
},
|
|
},
|
|
},
|
|
"required": ["content"],
|
|
},
|
|
submit_advice,
|
|
tier="execution",
|
|
)
|
|
|
|
|
|
def render_checklist_review(working: Mapping[str, Any]) -> str:
|
|
"""The advisors' checklist reviews as one section of markdown tables, or "" when
|
|
there are none. Written by code from what the advisors recorded."""
|
|
reviews = working.get(CHECKLIST_KEY)
|
|
if not isinstance(reviews, Mapping) or not any(reviews.values()):
|
|
return ""
|
|
parts = [
|
|
f"## {REVIEW_HEADING}",
|
|
"",
|
|
(
|
|
"Each pillar advisor's review of its pillar's checklist for this "
|
|
"workload: what its advice addresses, what does not apply and why, and "
|
|
"what the request does not say enough to settle."
|
|
),
|
|
]
|
|
for pillar, entries in reviews.items():
|
|
if not entries:
|
|
continue
|
|
parts += [
|
|
"",
|
|
f"### {pillar}",
|
|
"",
|
|
"| Checklist item | Review | How, or why not |",
|
|
"| --- | --- | --- |",
|
|
]
|
|
parts += [
|
|
"| "
|
|
+ " | ".join(
|
|
str(value).replace("|", "\\|")
|
|
for value in (
|
|
entry.get("item", ""),
|
|
_STATUS_WORDS.get(str(entry.get("status")), ""),
|
|
entry.get("note", ""),
|
|
)
|
|
)
|
|
+ " |"
|
|
for entry in entries
|
|
if isinstance(entry, Mapping)
|
|
]
|
|
questions = customer_questions(working)
|
|
if questions:
|
|
parts += [
|
|
"",
|
|
f"### {QUESTIONS_HEADING}",
|
|
"",
|
|
(
|
|
"The request does not say enough to settle these. They are not "
|
|
"faults in the design: each is something to ask the customer, and "
|
|
"the answer may change a recommendation."
|
|
),
|
|
"",
|
|
"| Pillar | About | Question |",
|
|
"| --- | --- | --- |",
|
|
]
|
|
parts += [
|
|
"| "
|
|
+ " | ".join(
|
|
value.replace("|", "\\|")
|
|
for value in (item["pillar"], item["item"], item["question"])
|
|
)
|
|
+ " |"
|
|
for item in questions
|
|
]
|
|
return "\n".join(parts) + "\n"
|
|
|
|
|
|
def customer_questions(working: Mapping[str, Any]) -> list[dict[str, str]]:
|
|
"""What the advisors found the request does not say: each checklist item that
|
|
needs the customer's answer, with the question to put to them."""
|
|
reviews = working.get(CHECKLIST_KEY)
|
|
if not isinstance(reviews, Mapping):
|
|
return []
|
|
return [
|
|
{
|
|
"pillar": str(pillar),
|
|
"item": str(entry.get("item", "")),
|
|
"question": str(entry.get("question", "")),
|
|
}
|
|
for pillar, entries in reviews.items()
|
|
for entry in entries or ()
|
|
if isinstance(entry, Mapping)
|
|
and entry.get("status") == NEEDS_CUSTOMER
|
|
and entry.get("question")
|
|
]
|