Solution architecture outcome pattern: agent and its MCP servers
Some checks failed
check agents / check (push) Failing after 13s
Some checks failed
check agents / check (push) Failing after 13s
The cp1-solution-architecture-agent and the sa-aws/azure/gcp-cloud MCP servers, a separate stream from the individual and sub-agent patterns. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,171 @@
|
||||
"""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, the local tools it uses, an optional budget and shared partials to
|
||||
include. The provider bundle supplies each role's Skills, MCP servers and model.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import dataclasses
|
||||
from pathlib import Path
|
||||
|
||||
from app.engine.runtime import RoleSpec
|
||||
from app.core.providers import ProviderBundle
|
||||
from app.skills.agent_skills import SkillFormatError, split_frontmatter
|
||||
from app.engine.modules import MODULE_TOOL
|
||||
from app.core.deliverables import DEPENDENCY_GRAPH, DeliverableKind
|
||||
|
||||
ORCHESTRATOR = "orchestrator"
|
||||
PILLAR_ADVISOR = "pillar-advisor"
|
||||
REPLY_WRITER = "reply-writer"
|
||||
LESSON_CURATOR = "lesson-curator" # runs outside any Execution
|
||||
COVERAGE_REVIEWER = "coverage-reviewer" # reviews a design before its Approval
|
||||
PARTIALS_DIR = "partials"
|
||||
|
||||
_ALLOWED_FIELDS = {"role", "deliverable", "tools", "budget", "includes"}
|
||||
|
||||
|
||||
def _deliverables_with_lessons(bundle: ProviderBundle) -> set[str]:
|
||||
if not bundle.lessons_skill:
|
||||
return set()
|
||||
folder = bundle.skills[bundle.lessons_skill].path / "references"
|
||||
return {path.stem for path in folder.glob("*.md")} if folder.is_dir() else set()
|
||||
|
||||
|
||||
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,
|
||||
lessons: bool = True,
|
||||
model_tiers: bool = False,
|
||||
) -> dict[str, RoleSpec]:
|
||||
"""`lessons` off leaves the lessons Skill out of every role, so an evaluation
|
||||
can run with and without what has been learned. `model_tiers` on gives a role
|
||||
the lighter model the bundle names for its first attempt."""
|
||||
specialists = {spec.specialist: kind for kind, spec in DEPENDENCY_GRAPH.items()}
|
||||
required = {ORCHESTRATOR, PILLAR_ADVISOR, REPLY_WRITER, *specialists}
|
||||
optional = {LESSON_CURATOR, COVERAGE_REVIEWER}
|
||||
learned = _deliverables_with_lessons(bundle) if lessons else set()
|
||||
|
||||
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)}"
|
||||
)
|
||||
for name, kind in specialists.items():
|
||||
if kind.value in learned and bundle.lessons_skill:
|
||||
# Only a Specialist whose Deliverable has lessons is given the Skill.
|
||||
roles[name] = dataclasses.replace(
|
||||
roles[name], skills=(*roles[name].skills, bundle.lessons_skill)
|
||||
)
|
||||
if model_tiers:
|
||||
for name, model in bundle.models.first_attempt.items():
|
||||
if name not in roles:
|
||||
raise RoleConfigError(
|
||||
f"'models.first_attempt' names {name!r}, which is not a role"
|
||||
)
|
||||
roles[name] = dataclasses.replace(roles[name], first_attempt_model=model)
|
||||
if bundle.terraform_modules_skill:
|
||||
for name, role in roles.items():
|
||||
if MODULE_TOOL in role.tools:
|
||||
roles[name] = dataclasses.replace(
|
||||
role, modules_skill=bundle.terraform_modules_skill
|
||||
)
|
||||
unexpected = sorted(set(roles) - required - optional)
|
||||
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}")
|
||||
|
||||
tools = tuple(frontmatter.get("tools") or ())
|
||||
offered = {name for names in bundle.tools.values() for name in names}
|
||||
unknown_tools = [tool for tool in tools if tool not in offered]
|
||||
if unknown_tools:
|
||||
raise fail(
|
||||
f"'tools' {', '.join(unknown_tools)} are not offered by the "
|
||||
f"{bundle.name} provider bundle"
|
||||
)
|
||||
|
||||
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, ())),
|
||||
tools=tools,
|
||||
mcp_servers=tuple(
|
||||
server.id
|
||||
for server in bundle.mcp_servers_for_role(name, include_preview_mcp)
|
||||
),
|
||||
model=bundle.models.for_role(name),
|
||||
model_timeout_seconds=bundle.models.timeout_for(name),
|
||||
)
|
||||
Reference in New Issue
Block a user