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,286 @@
|
||||
"""The agent-runtime interface (ADR-0003).
|
||||
|
||||
Everything an Orchestrator or Specialist needs crosses this seam as plain data:
|
||||
a RoleSpec, an AgentTask and ToolSpecs in; an Outcome back. No framework types.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import contextvars
|
||||
from collections.abc import (
|
||||
AsyncIterator,
|
||||
Awaitable,
|
||||
Callable,
|
||||
Mapping,
|
||||
MutableMapping,
|
||||
Sequence,
|
||||
)
|
||||
from contextlib import asynccontextmanager
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any, Protocol
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class RoleSpec:
|
||||
"""One agent role, parsed from agents/<role>.md."""
|
||||
|
||||
name: str
|
||||
instructions: str
|
||||
budget: int
|
||||
skills: tuple[str, ...] = ()
|
||||
tools: tuple[str, ...] = () # local tool names, e.g. terraform_validate
|
||||
mcp_servers: tuple[str, ...] = ()
|
||||
model: str | None = None
|
||||
# Seconds one model request may take; None takes the runtime's default.
|
||||
model_timeout_seconds: float | None = None
|
||||
# A lighter model for the first attempt at a Deliverable, when the bundle
|
||||
# names one and model tiers are on (iteration 5 step 6).
|
||||
first_attempt_model: str | None = None
|
||||
# The Skill on published Terraform modules, for a role that may call them. It
|
||||
# is added to the role's Skills only in an Execution that opted into modules.
|
||||
modules_skill: str | None = None
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class AgentTask:
|
||||
"""What one run of an agent is asked to do, with the context it may use."""
|
||||
|
||||
role: str
|
||||
prompt: str
|
||||
context: Mapping[str, Any] = field(default_factory=dict)
|
||||
deliverable: str | None = None
|
||||
|
||||
|
||||
# --- outcomes ----------------------------------------------------------------------
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Submitted:
|
||||
"""A Specialist's contract-complete Deliverable."""
|
||||
|
||||
content: str
|
||||
attachments: Mapping[str, str] = field(default_factory=dict)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class NeedsInput:
|
||||
"""The agent can't continue without the user. `permission` names a tool tier to grant.
|
||||
|
||||
`draft` is work the agent wants back when it is started again with the answers.
|
||||
"""
|
||||
|
||||
questions: tuple[str, ...]
|
||||
permission: str | None = None
|
||||
draft: str | None = None
|
||||
draft_attachments: Mapping[str, str] = field(default_factory=dict)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class BudgetExhausted:
|
||||
summary: str
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Stopped:
|
||||
"""The agent stopped without calling a tool that ends its turn."""
|
||||
|
||||
message: str
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class TurnEnded:
|
||||
"""The Orchestrator ended its turn by calling `tool`; the tool recorded its effect."""
|
||||
|
||||
tool: str
|
||||
|
||||
|
||||
Outcome = Submitted | NeedsInput | BudgetExhausted | Stopped | TurnEnded
|
||||
|
||||
|
||||
# --- tools -------------------------------------------------------------------------
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ToolResult:
|
||||
"""What a tool returns to the agent. A non-None `outcome` ends the agent's run."""
|
||||
|
||||
message: str
|
||||
outcome: Outcome | None = None
|
||||
|
||||
|
||||
# Files cross tool calls as a list of {path, content}, never a map keyed by path:
|
||||
# models rewrite object keys (Gemini turns "main.tf" into "main_tf").
|
||||
FILES_SCHEMA: Mapping[str, Any] = {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"path": {
|
||||
"type": "string",
|
||||
"description": "Relative path, e.g. terraform/main.tf",
|
||||
},
|
||||
"content": {"type": "string"},
|
||||
},
|
||||
"required": ["path", "content"],
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def files_from_argument(value: Any) -> dict[str, str]:
|
||||
"""A FILES_SCHEMA argument as {path: content}. A {path: content} map is accepted too."""
|
||||
if not value:
|
||||
return {}
|
||||
if isinstance(value, Mapping):
|
||||
return {str(path): str(content) for path, content in value.items()}
|
||||
files: dict[str, str] = {}
|
||||
for item in value:
|
||||
if not isinstance(item, Mapping) or "path" not in item:
|
||||
raise TypeError("each file needs a 'path' and 'content'")
|
||||
files[str(item["path"])] = str(item.get("content", ""))
|
||||
return files
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ToolSpec:
|
||||
name: str
|
||||
description: str
|
||||
parameters: Mapping[str, Any] # JSON schema for the keyword arguments
|
||||
handler: Callable[..., Awaitable[ToolResult]]
|
||||
tier: str = "general" # general | cloud_read | execution
|
||||
|
||||
|
||||
# The tools a role gets beyond the Execution tools, given the Deliverable it is producing
|
||||
# and that Deliverable's working memory: JSON-compatible data a tool may read and write,
|
||||
# kept with the Execution across attempts.
|
||||
ToolFactory = Callable[
|
||||
[RoleSpec, str | None, MutableMapping[str, Any]], Sequence[ToolSpec]
|
||||
]
|
||||
|
||||
|
||||
class RunLimiter:
|
||||
"""Caps how many agent runs are in flight at once.
|
||||
|
||||
A run that fans out to further runs lends its slot while it waits, so the cap
|
||||
holds across the whole hierarchy and a cap of 1 cannot deadlock.
|
||||
"""
|
||||
|
||||
def __init__(self, limit: int) -> None:
|
||||
if limit < 1:
|
||||
raise ValueError("limit must be at least 1")
|
||||
self.limit = limit
|
||||
self._semaphore = asyncio.Semaphore(limit)
|
||||
self._holding: contextvars.ContextVar[bool] = contextvars.ContextVar(
|
||||
"run_limiter_holding", default=False
|
||||
)
|
||||
|
||||
@asynccontextmanager
|
||||
async def slot(self) -> AsyncIterator[None]:
|
||||
async with self._semaphore:
|
||||
token = self._holding.set(True)
|
||||
try:
|
||||
yield
|
||||
finally:
|
||||
self._holding.reset(token)
|
||||
|
||||
@asynccontextmanager
|
||||
async def lend(self) -> AsyncIterator[None]:
|
||||
"""Give up the caller's slot, if it holds one, while its own fan-out runs."""
|
||||
if not self._holding.get():
|
||||
yield
|
||||
return
|
||||
self._semaphore.release()
|
||||
token = self._holding.set(False)
|
||||
try:
|
||||
yield
|
||||
finally:
|
||||
self._holding.reset(token)
|
||||
await self._semaphore.acquire()
|
||||
|
||||
|
||||
# Tool replies that mean the call did nothing. Runtimes log them, and the Execution
|
||||
# keeps them as lesson candidates.
|
||||
REJECTION_PREFIXES = (
|
||||
"Not submitted",
|
||||
"Refused",
|
||||
"Discovery gap",
|
||||
"terraform validate failed",
|
||||
)
|
||||
|
||||
|
||||
# --- decisions -----------------------------------------------------------------------
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Question:
|
||||
"""A closed question about a state. Its answer is typed, never prose.
|
||||
|
||||
choice pick one of `options`
|
||||
score rate against `options`, ordered from lowest to highest
|
||||
noul yes or no; the answer is the probability that it is yes
|
||||
"""
|
||||
|
||||
kind: str # choice | score | noul
|
||||
instructions: str
|
||||
options: tuple[str, ...] = ()
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Answer:
|
||||
"""`value` is the chosen option (choice), the level reached (score, as a number
|
||||
from 0 for the lowest option) or the probability of yes (noul)."""
|
||||
|
||||
value: str | float
|
||||
confidence: float
|
||||
probabilities: Mapping[str, float] = field(default_factory=dict)
|
||||
|
||||
def is_yes(self, threshold: float = 0.5) -> bool:
|
||||
return isinstance(self.value, (int, float)) and self.value >= threshold
|
||||
|
||||
|
||||
class Decider(Protocol):
|
||||
"""Answers closed questions about a state (ADR-0007).
|
||||
|
||||
Returns None when no decision could be made: the service is not configured,
|
||||
unreachable, over its budget, or the request is too large. The caller then takes
|
||||
its fallback; a decider never blocks an Execution. `scope` names what a budget is
|
||||
counted against, usually the Execution.
|
||||
"""
|
||||
|
||||
async def decide(
|
||||
self, state: str, questions: Mapping[str, Question], *, scope: str = ""
|
||||
) -> Mapping[str, Answer] | None: ...
|
||||
|
||||
|
||||
class NoDecider:
|
||||
"""The decider when none is configured: every caller takes its fallback."""
|
||||
|
||||
async def decide(
|
||||
self, state: str, questions: Mapping[str, Question], *, scope: str = ""
|
||||
) -> Mapping[str, Answer] | None:
|
||||
return None
|
||||
|
||||
|
||||
class SubmissionReview(Protocol):
|
||||
"""A review of a submission's meaning, beyond what its structure shows.
|
||||
|
||||
Returns what it would have the Specialist look at again, one line each; empty
|
||||
when it has nothing to raise or could not decide. `kind` is the Deliverable's
|
||||
kind, `upstream` the Deliverables it builds on.
|
||||
"""
|
||||
|
||||
async def __call__(
|
||||
self,
|
||||
kind: Any,
|
||||
attachments: Mapping[str, str],
|
||||
upstream: Mapping[str, Mapping[str, Any]] | None,
|
||||
scope: str = "",
|
||||
) -> Sequence[str]: ...
|
||||
|
||||
|
||||
class AgentRuntime(Protocol):
|
||||
async def run(
|
||||
self, role: RoleSpec, task: AgentTask, tools: Sequence[ToolSpec]
|
||||
) -> Outcome:
|
||||
"""Run one ReAct loop until a tool ends the turn, the budget is spent, or it stops."""
|
||||
...
|
||||
Reference in New Issue
Block a user