Files
gcp_solution_architecture_a…/app/agents/roles.py
Jonathan Boniface f040493583 feat: run role files on the ADK runtime with scoped Skills
Increment 5 of .scratch/solution-architect-agent/spec.md, test-first.

- agents/*.md: provider-neutral role files for the Orchestrator, nine
  Specialists and the pillar advisor, with a shared Specialist protocol.
- app/agents/roles.py: load and validate role files; Skills, MCP
  servers and models come from the provider bundle.
- app/agents/adk_runtime.py: AgentRuntime on google-adk 2.9 with a
  per-run LlmAgent, role-scoped SkillToolset (no run_skill_script),
  step budgets, early stop on turn-ending tools, LiteLLM models.
- app/execution/pillars.py + toolkit.py: design advisor fans out to one
  advisor per WAF pillar in parallel.
- Specialists receive every earlier-Phase Deliverable as input.
- Bundle gains role_skills, pillar_skills and -latest Gemini aliases;
  pin google-adk[extensions]==2.9.0.
- 37 new tests; full suite 158 passed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-16 09:51:02 +01:00

129 lines
4.2 KiB
Python

"""Load role files (agents/<role>.md) into RoleSpecs for one Cloud provider.
Role files are framework- and provider-neutral: frontmatter names the role, the
Deliverable it owns, its local tool tiers, an optional budget and shared partials to
include. The provider bundle supplies each role's Skills, MCP servers and model.
"""
from __future__ import annotations
from pathlib import Path
from app.agent_skills import SkillFormatError, split_frontmatter
from app.agents.runtime import RoleSpec
from app.execution.deliverables import DEPENDENCY_GRAPH, DeliverableKind
from app.providers import TIERS, ProviderBundle
ORCHESTRATOR = "orchestrator"
PILLAR_ADVISOR = "pillar-advisor"
PARTIALS_DIR = "partials"
_ALLOWED_FIELDS = {"role", "deliverable", "tool_tiers", "budget", "includes"}
class RoleConfigError(ValueError):
"""A role file is missing or invalid."""
def load_roles(
agents_dir: Path,
bundle: ProviderBundle,
*,
orchestrator_budget: int = 40,
specialist_budget: int = 15,
include_preview_mcp: bool = True,
) -> dict[str, RoleSpec]:
specialists = {spec.specialist: kind for kind, spec in DEPENDENCY_GRAPH.items()}
required = {ORCHESTRATOR, PILLAR_ADVISOR, *specialists}
roles = {}
for path in sorted(agents_dir.glob("*.md")):
role = _load_role(
path,
agents_dir,
bundle,
specialists,
orchestrator_budget if path.stem == ORCHESTRATOR else specialist_budget,
include_preview_mcp,
)
roles[role.name] = role
missing = sorted(required - set(roles))
if missing:
raise RoleConfigError(
f"{agents_dir}: missing role files for {', '.join(missing)}"
)
unexpected = sorted(set(roles) - required)
if unexpected:
raise RoleConfigError(
f"{agents_dir}: unexpected role files {', '.join(unexpected)}"
)
return roles
def _load_role(
path: Path,
agents_dir: Path,
bundle: ProviderBundle,
specialists: dict[str, DeliverableKind],
default_budget: int,
include_preview_mcp: bool,
) -> RoleSpec:
try:
frontmatter, body = split_frontmatter(path.read_text(encoding="utf-8"), path)
except SkillFormatError as exc:
raise RoleConfigError(str(exc)) from exc
def fail(message: str) -> RoleConfigError:
return RoleConfigError(f"{path}: {message}")
unknown = sorted(set(frontmatter) - _ALLOWED_FIELDS)
if unknown:
raise fail(
f"unsupported fields {', '.join(unknown)}; skills, MCP servers and models "
"come from the provider bundle"
)
name = frontmatter.get("role")
if name != path.stem:
raise fail(f"'role' {name!r} must match the file name {path.stem!r}")
deliverable = frontmatter.get("deliverable")
if name in specialists:
expected = specialists[name].value
if deliverable != expected:
raise fail(f"'deliverable' must be {expected!r}, not {deliverable!r}")
elif deliverable is not None:
raise fail(f"role {name!r} owns no Deliverable, but names {deliverable!r}")
tiers = tuple(frontmatter.get("tool_tiers") or ())
bad_tiers = [tier for tier in tiers if tier not in TIERS]
if bad_tiers:
raise fail(f"'tool_tiers' {', '.join(bad_tiers)} must be among {TIERS}")
budget = frontmatter.get("budget", default_budget)
if not isinstance(budget, int) or budget < 1:
raise fail("'budget' must be a positive integer")
sections = [body.strip()]
for include in frontmatter.get("includes") or ():
partial = agents_dir / PARTIALS_DIR / f"{include}.md"
if not partial.is_file():
raise fail(f"include {include!r} not found at {partial}")
sections.append(partial.read_text(encoding="utf-8").strip())
if not sections[0]:
raise fail("instructions (the body after the frontmatter) must not be empty")
return RoleSpec(
name=name,
instructions="\n\n".join(sections),
budget=budget,
skills=tuple(bundle.role_skills.get(name, ())),
tool_tiers=tiers,
mcp_servers=tuple(
server.id
for server in bundle.mcp_servers_for_role(name, include_preview_mcp)
),
model=bundle.models.for_role(name),
)