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>
This commit is contained in:
2026-09-16 09:51:02 +01:00
parent d9214c671a
commit f040493583
31 changed files with 1431 additions and 17 deletions

View File

@@ -42,23 +42,28 @@ class SkillMeta:
path: Path
def read_skill(skill_dir: Path) -> SkillMeta:
"""Parse and validate the SKILL.md in `skill_dir`."""
skill_file = skill_dir / SKILL_FILE
match = _FRONTMATTER_PATTERN.match(skill_file.read_text(encoding="utf-8"))
def split_frontmatter(text: str, source: Path) -> tuple[dict, str]:
"""Split a markdown document into its YAML frontmatter mapping and body."""
match = _FRONTMATTER_PATTERN.match(text)
if not match:
raise SkillFormatError(
f"{skill_file}: missing YAML frontmatter delimited by '---'"
)
raise SkillFormatError(f"{source}: missing YAML frontmatter delimited by '---'")
try:
frontmatter = yaml.safe_load(match.group(1))
except yaml.YAMLError as exc:
raise SkillFormatError(
f"{skill_file}: frontmatter is not valid YAML: {exc}"
f"{source}: frontmatter is not valid YAML: {exc}"
) from exc
if not isinstance(frontmatter, dict):
raise SkillFormatError(f"{skill_file}: frontmatter must be a mapping")
raise SkillFormatError(f"{source}: frontmatter must be a mapping")
return frontmatter, text[match.end() :]
def read_skill(skill_dir: Path) -> SkillMeta:
"""Parse and validate the SKILL.md in `skill_dir`."""
skill_file = skill_dir / SKILL_FILE
frontmatter, _ = split_frontmatter(
skill_file.read_text(encoding="utf-8"), skill_file
)
unknown = set(frontmatter) - _ALLOWED_FIELDS
if unknown:

196
app/agents/adk_runtime.py Normal file
View File

@@ -0,0 +1,196 @@
"""AgentRuntime on Google ADK (ADR-0003): an LlmAgent per run, with SkillToolset.
This is the only module that imports google.adk. Each run builds a fresh LlmAgent
and in-memory session (Specialists are stateless), offers the role's ToolSpecs and
Skills, and stops as soon as a tool returns an outcome or the budget is spent.
"""
from __future__ import annotations
import asyncio
import json
import re
import uuid
from collections.abc import Callable, Mapping, Sequence
from contextlib import aclosing
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
from google.adk.agents import LlmAgent
from google.adk.models.base_llm import BaseLlm
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.adk.skills import load_skill_from_dir
from google.adk.skills.models import Skill
from google.adk.tools.base_tool import BaseTool
from google.adk.tools.skill_toolset import SkillToolset
from google.adk.tools.tool_context import ToolContext
from google.genai import types
from app.agents.runtime import (
AgentTask,
BudgetExhausted,
Outcome,
RoleSpec,
Stopped,
ToolSpec,
)
APP_NAME = "solution-architect"
# run_skill_script is deliberately absent: generated or bundled scripts never run.
SKILL_TOOLS = ["list_skills", "load_skill", "load_skill_resource"]
TURN_ENDED_REPLY = "Your turn has already ended; this call was not run."
ModelFactory = Callable[[RoleSpec], BaseLlm | str]
def default_model_factory(role: RoleSpec) -> BaseLlm:
"""Wrap the role's LiteLLM model id, so any LiteLLM provider can serve the agent."""
from google.adk.models.lite_llm import LiteLlm
if not role.model:
raise ValueError(f"Role {role.name!r} has no model configured")
return LiteLlm(model=role.model)
@dataclass
class _RunControl:
budget: int
role: str
calls: int = 0
outcome: Outcome | None = None
lock: asyncio.Lock = field(default_factory=asyncio.Lock)
def before_tool(
self, tool: BaseTool, args: dict[str, Any], tool_context: Any
) -> dict[str, Any] | None:
if self.outcome is not None:
return {"error": TURN_ENDED_REPLY}
self.calls += 1
if self.calls > self.budget:
self.outcome = BudgetExhausted(
f"{self.role} used all {self.budget} tool calls before finishing."
)
return {"error": "Tool-call budget exhausted; stop now."}
return None
class _SpecTool(BaseTool):
"""Adapts a framework-neutral ToolSpec to an ADK tool."""
def __init__(self, spec: ToolSpec, control: _RunControl) -> None:
super().__init__(name=spec.name, description=spec.description)
self._spec = spec
self._control = control
def _get_declaration(self) -> types.FunctionDeclaration:
return types.FunctionDeclaration(
name=self._spec.name,
description=self._spec.description,
parameters_json_schema=dict(self._spec.parameters),
)
async def run_async(
self, *, args: dict[str, Any], tool_context: ToolContext
) -> dict[str, Any]:
# Serialise calls within a run: tools may mutate Execution state, and the
# first tool to end the turn must stop the rest of a parallel batch.
async with self._control.lock:
if self._control.outcome is not None:
return {"error": TURN_ENDED_REPLY}
try:
result = await self._spec.handler(**args)
except TypeError as exc:
return {"error": f"Invalid arguments for {self._spec.name}: {exc}"}
if result.outcome is not None:
self._control.outcome = result.outcome
return {"result": result.message}
class AdkAgentRuntime:
def __init__(
self,
*,
skill_dirs: Mapping[str, Path],
model_factory: ModelFactory = default_model_factory,
) -> None:
self._skills: dict[str, Skill] = {}
for name, path in skill_dirs.items():
try:
skill = load_skill_from_dir(path)
except Exception as exc:
raise ValueError(
f"Could not load skill {name!r} from {path}: {exc}"
) from exc
if skill.name != name:
raise ValueError(
f"Skill at {path} is named {skill.name!r}, not {name!r}"
)
self._skills[name] = skill
self._model_factory = model_factory
async def run(
self, role: RoleSpec, task: AgentTask, tools: Sequence[ToolSpec]
) -> Outcome:
control = _RunControl(budget=role.budget, role=role.name)
agent_tools: list[Any] = [_SpecTool(spec, control) for spec in tools]
if role.skills:
unknown = [name for name in role.skills if name not in self._skills]
if unknown:
raise ValueError(f"Role {role.name!r} needs unknown skills: {unknown}")
agent_tools.append(
SkillToolset(
skills=[self._skills[name] for name in role.skills],
tool_filter=SKILL_TOOLS,
)
)
instructions = role.instructions
agent = LlmAgent(
name=_agent_name(role.name),
model=self._model_factory(role),
# A callable instruction is passed verbatim: no {state} templating.
instruction=lambda _context: instructions,
tools=agent_tools,
before_tool_callback=control.before_tool,
)
runner = Runner(
app_name=APP_NAME,
agent=agent,
session_service=InMemorySessionService(),
auto_create_session=True,
)
message = types.Content(
role="user", parts=[types.Part(text=_render_task(task))]
)
final_text = ""
async with aclosing(
runner.run_async(
user_id=APP_NAME, session_id=str(uuid.uuid4()), new_message=message
)
) as events:
async for event in events:
if control.outcome is not None:
break
if event.is_final_response() and event.content and event.content.parts:
final_text = "".join(
part.text for part in event.content.parts if part.text
).strip()
if control.outcome is not None:
return control.outcome
return Stopped(
final_text
or f"{role.name} ended without calling a tool that ends its turn."
)
def _agent_name(role: str) -> str:
return re.sub(r"\W", "_", role)
def _render_task(task: AgentTask) -> str:
context = json.dumps(task.context, indent=2, default=str, ensure_ascii=False)
return f"{task.prompt}\n\nContext:\n```json\n{context}\n```"

128
app/agents/roles.py Normal file
View File

@@ -0,0 +1,128 @@
"""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),
)

View File

@@ -140,6 +140,30 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
}
def inputs_of(kind: DeliverableKind) -> tuple[DeliverableKind, ...]:
"""The Deliverables a Specialist works from, in graph order.
Every Deliverable in an earlier Phase (all approved by the time `kind` is ready),
plus everything `kind` depends on, directly or not, within its own Phase.
"""
spec = DEPENDENCY_GRAPH[kind]
earlier_phases = PHASE_ORDER[: PHASE_ORDER.index(spec.phase)]
upstream: set[DeliverableKind] = set()
frontier = set(DEPENDENCY_GRAPH[kind].depends_on)
while frontier:
upstream |= frontier
frontier = {
dependency
for item in frontier
for dependency in DEPENDENCY_GRAPH[item].depends_on
} - upstream
return tuple(
candidate
for candidate, candidate_spec in DEPENDENCY_GRAPH.items()
if candidate in upstream or candidate_spec.phase in earlier_phases
)
def deliverables_in(phase: PhaseId) -> tuple[DeliverableKind, ...]:
return tuple(kind for kind, spec in DEPENDENCY_GRAPH.items() if spec.phase is phase)

View File

@@ -31,7 +31,12 @@ from app.agents.runtime import (
ToolSpec,
TurnEnded,
)
from app.execution.deliverables import DEPENDENCY_GRAPH, PHASE_ORDER, DeliverableKind
from app.execution.deliverables import (
DEPENDENCY_GRAPH,
PHASE_ORDER,
DeliverableKind,
inputs_of,
)
from app.execution.ledger import Ledger, LedgerRefusal
from app.execution.recorder import ExecutionRecorder
from app.execution.state import ExecutionState
@@ -392,7 +397,7 @@ def _specialist_input(
"pre_approved": bool(state.get("pre_approved")),
"dependencies": {
dependency.value: dict(deliverables[dependency.value])
for dependency in spec.depends_on
for dependency in inputs_of(kind)
},
"feedback": list(ledger.feedback(kind)),
"answers": list(state.get("answers", {}).get(kind.value, [])),

103
app/execution/pillars.py Normal file
View File

@@ -0,0 +1,103 @@
"""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.
"""
from __future__ import annotations
import asyncio
import dataclasses
from collections.abc import Mapping, Sequence
from app.agents.runtime import (
AgentRuntime,
AgentTask,
RoleSpec,
Submitted,
ToolResult,
ToolSpec,
)
CONSULT_TOOL = "consult_pillar_advisors"
def pillar_consultation_tool(
runtime: AgentRuntime,
advisor: RoleSpec,
pillar_skills: Mapping[str, str],
) -> ToolSpec:
"""A tool that runs one pillar advisor per pillar, in parallel, each with its Skill."""
async def consult(brief: str, pillars: Sequence[str] | None = None) -> ToolResult:
chosen = list(pillars) if pillars else list(pillar_skills)
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)}"
)
results = await asyncio.gather(
*(
_advise(runtime, advisor, pillar, pillar_skills[pillar], brief)
for pillar in chosen
)
)
return ToolResult("\n\n".join(results))
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.",
{
"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
) -> str:
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},
)
try:
outcome = await runtime.run(role, task, [_submit_advice_tool()])
except Exception as exc: # noqa: BLE001 - one failed advisor must not lose the others
return f"## {pillar}\n\nNo guidance: the advisor failed ({exc})."
if isinstance(outcome, Submitted):
return f"## {pillar}\n\n{outcome.content.strip()}"
return (
f"## {pillar}\n\nNo guidance: the advisor ended with {type(outcome).__name__}."
)
def _submit_advice_tool() -> ToolSpec:
async def submit_advice(content: str) -> ToolResult:
if not content.strip():
return ToolResult("Not submitted: the advice is empty.")
return ToolResult("Advice submitted.", Submitted(content))
return ToolSpec(
"submit_advice",
"Submit your pillar recommendations as markdown. Ends your turn.",
{
"type": "object",
"properties": {"content": {"type": "string"}},
"required": ["content"],
},
submit_advice,
tier="execution",
)

33
app/execution/toolkit.py Normal file
View File

@@ -0,0 +1,33 @@
"""Which extra tools each role gets beyond the Execution tools.
Increment 6 adds the local general and cloud-read tools and remote MCP servers here.
"""
from __future__ import annotations
from collections.abc import Mapping, Sequence
from app.agents.roles import PILLAR_ADVISOR
from app.agents.runtime import AgentRuntime, RoleSpec, ToolSpec
from app.execution.deliverables import DeliverableKind
from app.execution.graph import ToolFactory
from app.execution.pillars import pillar_consultation_tool
def make_tool_factory(
runtime: AgentRuntime,
roles: Mapping[str, RoleSpec],
pillar_skills: Mapping[str, str],
) -> ToolFactory:
consult = (
pillar_consultation_tool(runtime, roles[PILLAR_ADVISOR], pillar_skills)
if pillar_skills and PILLAR_ADVISOR in roles
else None
)
def tools_for(role: RoleSpec, deliverable: str | None) -> Sequence[ToolSpec]:
if consult and deliverable == DeliverableKind.DESIGN_RECOMMENDATIONS.value:
return [consult]
return []
return tools_for

View File

@@ -58,6 +58,8 @@ class ProviderBundle:
mcp_auth: Mapping[str, Any]
mcp_servers: Mapping[str, McpServerSpec]
role_mcp_servers: Mapping[str, tuple[str, ...]]
role_skills: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
pillar_skills: Mapping[str, str] = field(default_factory=dict)
def mcp_servers_for_role(
self, role: str, include_preview: bool = True
@@ -146,6 +148,19 @@ def load_provider(name: str, root: Path | None = None) -> ProviderBundle:
)
role_mcp_servers[role] = tuple(server_ids or ())
role_skills = {}
for role, skill_names in (config.get("role_skills") or {}).items():
unknown = [skill for skill in skill_names or () if skill not in skills]
if unknown:
raise fail(f"role {role!r} references unknown skills: {', '.join(unknown)}")
role_skills[role] = tuple(skill_names or ())
pillar_skills = {}
for pillar, skill_name in (config.get("pillar_skills") or {}).items():
if skill_name not in skills:
raise fail(f"pillar {pillar!r} references unknown skill {skill_name!r}")
pillar_skills[str(pillar)] = skill_name
return ProviderBundle(
name=name,
skills_dirs=skills_dirs,
@@ -156,4 +171,6 @@ def load_provider(name: str, root: Path | None = None) -> ProviderBundle:
mcp_auth=dict(config.get("mcp_auth") or {}),
mcp_servers=mcp_servers,
role_mcp_servers=role_mcp_servers,
role_skills=role_skills,
pillar_skills=pillar_skills,
)