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>
392 lines
17 KiB
Python
392 lines
17 KiB
Python
"""The agent: the ExecutionEngine that starts and resumes Executions, and its assembly.
|
|
|
|
ExecutionEngine is the one interface the A2A server, /generate and the evaluation
|
|
harness use. Each call runs the Execution until it needs the user or finishes, and
|
|
returns an Interaction describing which.
|
|
|
|
open_assembly is the composition root: the only place concrete runtimes, tools,
|
|
checkpointers and recorders are chosen, from settings and the provider bundle.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import uuid
|
|
from collections.abc import Mapping, Sequence
|
|
from dataclasses import dataclass
|
|
from pathlib import Path
|
|
from typing import Any
|
|
|
|
from langchain_core.runnables import RunnableConfig
|
|
from langgraph.checkpoint.base import BaseCheckpointSaver
|
|
from langgraph.types import Command
|
|
|
|
from app.core.deliverables import DEPENDENCY_GRAPH, NO_CONTRACT, ProviderContract
|
|
from app.core.ledger import Ledger
|
|
from app.core.scope import ESSENTIAL, Catalogue, Scope, read_scope, slug
|
|
from app.engine.baseline import load_baseline
|
|
from app.engine.customer_case import record_intent
|
|
from app.engine.execution_graph import build_execution_graph
|
|
from app.engine.execution_state import check_customer_case
|
|
from app.engine.recorder import ExecutionRecorder, InMemoryRecorder
|
|
from app.engine.router import OrchestratorPolicy
|
|
from app.engine.runtime import (
|
|
AgentRuntime,
|
|
Decider,
|
|
RoleSpec,
|
|
RunLimiter,
|
|
SubmissionReview,
|
|
ToolFactory,
|
|
)
|
|
from app.engine.scoping import Scoping, to_working
|
|
from app.engine.toolbox import ORCHESTRATOR
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class Interaction:
|
|
execution_id: str
|
|
status: str # awaiting_user | completed | completed_with_warnings
|
|
prompt: Mapping[str, Any] | None # questions | approval | permission
|
|
state: Mapping[str, Any]
|
|
|
|
|
|
_RECURSION_LIMIT = 10_000 # loops are bounded by max_orchestrator_turns instead
|
|
AGENTS_DIR = Path(__file__).resolve().parent.parent.parent / "prompts"
|
|
|
|
|
|
class ExecutionNotAwaitingUser(RuntimeError):
|
|
pass
|
|
|
|
|
|
class ExecutionEngine:
|
|
def __init__(
|
|
self,
|
|
*,
|
|
runtime: AgentRuntime,
|
|
roles: Mapping[str, RoleSpec],
|
|
recorder: ExecutionRecorder,
|
|
checkpointer: BaseCheckpointSaver,
|
|
output_root: Path,
|
|
max_revisions: int = 3,
|
|
max_orchestrator_turns: int = 100,
|
|
tool_factory: ToolFactory | None = None,
|
|
limiter: RunLimiter | None = None,
|
|
skill_versions: Mapping[str, str] | None = None,
|
|
orchestrator: OrchestratorPolicy | None = None,
|
|
submission_review: SubmissionReview | None = None,
|
|
confirm_drafts: bool = False,
|
|
decider: Decider | None = None,
|
|
pillar_threshold: float = 1.5,
|
|
reworded_threshold: float = 0.25,
|
|
overlays: Mapping[str, str] | None = None,
|
|
default_overlays: Sequence[str] = (),
|
|
guard_user_text: bool = False,
|
|
guard_threshold: float = 0.75,
|
|
skill_references: Mapping[str, Mapping[str, Mapping[str, str]]] | None = None,
|
|
skill_threshold: float = 1.25,
|
|
assess_at_end: bool = False,
|
|
modules_available: bool = False,
|
|
default_modules: bool = False,
|
|
scope_catalogue: Catalogue | None = None,
|
|
scope_values: Mapping[str, Sequence[str]] | None = None,
|
|
scope_skill: str | None = None,
|
|
contract: ProviderContract = NO_CONTRACT,
|
|
) -> None:
|
|
required = {
|
|
ORCHESTRATOR,
|
|
*(spec.specialist for spec in DEPENDENCY_GRAPH.values()),
|
|
}
|
|
missing = sorted(required - set(roles))
|
|
if missing:
|
|
raise ValueError(f"Missing roles: {', '.join(missing)}")
|
|
self._max_revisions = max_revisions
|
|
# The catalogue a scope spec is read against (ADR-0008); None when this
|
|
# deployment's Cloud provider has none.
|
|
self._scope_catalogue = scope_catalogue
|
|
self._scope_values = dict(scope_values or {})
|
|
self._scope_skill = scope_skill
|
|
# Whether the Cloud provider approves any module sources, and whether an
|
|
# Execution uses them when its caller does not say.
|
|
self._modules_available = modules_available
|
|
self._default_modules = default_modules and modules_available
|
|
self._output_root = output_root
|
|
# Overlay Skills an Execution may name, with the version of each (ADR-0004).
|
|
self._overlays = dict(overlays or {})
|
|
self._default_overlays = tuple(default_overlays)
|
|
unknown = sorted(set(self._default_overlays) - set(self._overlays))
|
|
if unknown:
|
|
raise ValueError(f"Unknown default overlay Skills: {', '.join(unknown)}")
|
|
self._graph = build_execution_graph(
|
|
runtime=runtime,
|
|
roles=roles,
|
|
recorder=recorder,
|
|
output_root=output_root,
|
|
max_orchestrator_turns=max_orchestrator_turns,
|
|
tool_factory=tool_factory,
|
|
limiter=limiter,
|
|
skill_versions=skill_versions,
|
|
orchestrator=orchestrator,
|
|
submission_review=submission_review,
|
|
confirm_drafts=confirm_drafts,
|
|
decider=decider,
|
|
pillar_threshold=pillar_threshold,
|
|
reworded_threshold=reworded_threshold,
|
|
guard_user_text=guard_user_text,
|
|
guard_threshold=guard_threshold,
|
|
skill_references=skill_references,
|
|
skill_threshold=skill_threshold,
|
|
assess_at_end=assess_at_end,
|
|
scoping=Scoping(scope_catalogue, dict(scope_values or {}), scope_skill)
|
|
if scope_catalogue is not None
|
|
else None,
|
|
contract=contract,
|
|
).compile(checkpointer=checkpointer)
|
|
|
|
async def start(
|
|
self,
|
|
workflow_request: str,
|
|
*,
|
|
session_id: str | None = None,
|
|
customer_case: str | None = None,
|
|
pre_approved: bool | None = None,
|
|
allow_cloud_read: bool | None = None,
|
|
execution_id: str | None = None,
|
|
scripted_answers: Sequence[Sequence[str]] = (),
|
|
baseline: str | None = None,
|
|
overlay_skills: Sequence[str] = (),
|
|
terraform_modules: bool | None = None,
|
|
scope: str | Mapping[str, Any] | None = None,
|
|
time_left: Any = None,
|
|
) -> Interaction:
|
|
"""Start an Execution. `scripted_answers` are (regex, answer[, asker]) entries a
|
|
pre-approved Execution uses to answer questions, for evaluation runs.
|
|
|
|
`baseline` names a completed Execution of the same Customer case and makes
|
|
this a Change request (ADR-0006): the request says what has changed, and the
|
|
Execution starts from that Baseline's Deliverables. It is refused, before
|
|
anything runs or is recorded, when the Baseline cannot be one.
|
|
|
|
`overlay_skills` names Skills that carry an organisation's standards or
|
|
this engagement's constraints. Each must be one the deployment has
|
|
configured; an unknown name refuses the start. Every Specialist loads them
|
|
with the ones the deployment loads by default.
|
|
|
|
`terraform_modules` opts the Execution into published Terraform modules
|
|
from the sources the Cloud provider approves. Left unset, a Change request
|
|
does as its Baseline did and any other Execution takes the deployment's
|
|
default, which is plain resources. Opting in is refused when the provider
|
|
approves no sources.
|
|
|
|
`scope` is a scope spec (ADR-0008), as YAML text or already parsed. It may
|
|
be complete or partly filled. The start is refused when it names a field
|
|
the catalogue does not have or holds a value of the wrong type, and, for a
|
|
pre-approved Execution, when an essential field is not settled: nobody is
|
|
there to ask. What the spec states under `run` applies where the caller
|
|
gave no value of their own. Its statement of intent is the request when
|
|
none is given.
|
|
"""
|
|
read = self._read_scope(scope) if scope is not None else None
|
|
if read is not None:
|
|
run = read.values
|
|
if pre_approved is None:
|
|
pre_approved = bool(run.get("run.pre_approved", False))
|
|
if allow_cloud_read is None and "run.allow_cloud_read" in run:
|
|
allow_cloud_read = bool(run["run.allow_cloud_read"])
|
|
if terraform_modules is None and "run.terraform_modules" in run:
|
|
terraform_modules = bool(run["run.terraform_modules"])
|
|
overlay_skills = [*overlay_skills, *run.get("run.overlay_skills", [])]
|
|
if (
|
|
customer_case
|
|
and read.customer_case
|
|
and slug(customer_case) != (read.customer_case)
|
|
):
|
|
raise ValueError(
|
|
f"The scope spec is for {read.customer_case}, and this was "
|
|
f"started for {customer_case}."
|
|
)
|
|
customer_case = customer_case or read.customer_case
|
|
# The spec's statement is the customer's; it is what gets recorded.
|
|
workflow_request = read.statement or workflow_request
|
|
missing = read.gaps(ESSENTIAL)
|
|
if pre_approved and missing:
|
|
raise ValueError(
|
|
"The scope spec leaves essential fields unsettled, and a "
|
|
"pre-approved Execution has nobody to ask: "
|
|
+ ", ".join(gap["field"] for gap in missing)
|
|
+ ". Give each a value, or `decide` to leave it to the agent."
|
|
)
|
|
pre_approved = bool(pre_approved)
|
|
if not workflow_request.strip():
|
|
raise ValueError(
|
|
"A request is needed: text, or a scope spec with a statement."
|
|
)
|
|
customer_case = check_customer_case(customer_case)
|
|
execution_id = execution_id or str(uuid.uuid4())
|
|
if await self._exists(execution_id):
|
|
raise ValueError(f"Execution {execution_id} already exists")
|
|
if isinstance(overlay_skills, str) or not all(
|
|
isinstance(name, str) for name in overlay_skills
|
|
):
|
|
raise ValueError("overlay_skills must be a list of Skill names")
|
|
chosen = list(dict.fromkeys([*self._default_overlays, *overlay_skills]))
|
|
unknown = sorted(set(chosen) - set(self._overlays))
|
|
if unknown:
|
|
raise ValueError(
|
|
f"Unknown overlay Skills: {', '.join(unknown)}. Available: "
|
|
f"{', '.join(sorted(self._overlays)) or 'none'}"
|
|
)
|
|
loaded = (
|
|
load_baseline(self._output_root, customer_case, baseline)
|
|
if baseline
|
|
else None
|
|
)
|
|
if terraform_modules is None:
|
|
terraform_modules = (
|
|
bool(loaded.get("terraform_modules"))
|
|
if loaded
|
|
else self._default_modules
|
|
)
|
|
if not isinstance(terraform_modules, bool):
|
|
# A ValueError is what callers turn into a refused start.
|
|
raise ValueError("terraform_modules must be true or false") # noqa: TRY004
|
|
if terraform_modules and not self._modules_available:
|
|
raise ValueError(
|
|
"terraform_modules: this Cloud provider has no approved module sources"
|
|
)
|
|
if pre_approved and allow_cloud_read is None:
|
|
allow_cloud_read = False
|
|
session_id = session_id or str(uuid.uuid4())
|
|
intent_version = record_intent(
|
|
self._output_root,
|
|
customer_case,
|
|
execution_id=execution_id,
|
|
session_id=session_id,
|
|
workflow_request=workflow_request,
|
|
baseline=baseline or None,
|
|
scope_supplied=scope if isinstance(scope, str) else None,
|
|
scope_completed=read.completed(read.status(pre_approved)) if read else None,
|
|
)
|
|
initial: dict[str, Any] = {
|
|
"execution_id": execution_id,
|
|
"session_id": session_id,
|
|
"customer_case": customer_case,
|
|
"intent_version": intent_version,
|
|
"workflow_request": workflow_request,
|
|
# The Baseline of a Change request, as read from its files; else None.
|
|
"baseline": loaded,
|
|
# Overlay Skills this Execution loads, each with the version it had.
|
|
"overlay_skills": {name: self._overlays[name] for name in chosen},
|
|
"terraform_modules": terraform_modules,
|
|
# What the customer's scope spec settles and leaves open; None without one.
|
|
"scope": {
|
|
"skill": self._scope_skill,
|
|
"status": read.status(pre_approved),
|
|
"readiness": read.readiness(),
|
|
"context": read.for_context(),
|
|
# What the scope analyst starts from and completes.
|
|
"working": to_working(read),
|
|
}
|
|
if read
|
|
else None,
|
|
"risks": [],
|
|
"pre_approved": pre_approved,
|
|
"allow_cloud_read": allow_cloud_read,
|
|
"ledger": Ledger(
|
|
pre_approved=pre_approved, max_revisions=self._max_revisions
|
|
).to_dict(),
|
|
"deliverables": {},
|
|
"conversation": [{"from": "user", "text": workflow_request}],
|
|
"notes": [],
|
|
"pending_questions": [],
|
|
"awaiting_questions": [],
|
|
"answers": {},
|
|
"drafts": {},
|
|
"drafts_shown": [],
|
|
"working": {},
|
|
"pending_permission": None,
|
|
"prompt": None,
|
|
"last_reply": None,
|
|
"pending_change": None,
|
|
"awaiting_gap_decision": False,
|
|
"validation_settled": 0,
|
|
"awaiting_limit_decision": False,
|
|
"revision_limit_asked": [],
|
|
"idle_asks": 0,
|
|
"ask_fingerprint": "",
|
|
"decisions": [],
|
|
"outcomes": [],
|
|
"refusals": [],
|
|
"outcomes_applied": 0,
|
|
"events_recorded": 0,
|
|
"turns": 0,
|
|
"status": "running",
|
|
"warnings": [],
|
|
"scripted_answers": [list(entry) for entry in scripted_answers],
|
|
}
|
|
await self._advance(initial, execution_id, time_left)
|
|
return await self.interaction(execution_id)
|
|
|
|
def _read_scope(self, supplied: str | Mapping[str, Any]) -> Scope:
|
|
if self._scope_catalogue is None:
|
|
raise ValueError("This deployment has no scope spec catalogue.")
|
|
return read_scope(
|
|
supplied, self._scope_catalogue, provider_values=self._scope_values
|
|
)
|
|
|
|
async def resume(
|
|
self, execution_id: str, reply: Mapping[str, Any], time_left: Any = None
|
|
) -> Interaction:
|
|
"""Answer the Execution's current prompt: {"reply"} | {"approval"} | {"permission"}."""
|
|
current = await self.interaction(execution_id)
|
|
if current.status != "awaiting_user":
|
|
raise ExecutionNotAwaitingUser(
|
|
f"Execution {execution_id} is {current.status}, not awaiting the user"
|
|
)
|
|
await self._advance(Command(resume=dict(reply)), execution_id, time_left)
|
|
return await self.interaction(execution_id)
|
|
|
|
async def carry_on(self, execution_id: str, time_left: Any = None) -> Interaction:
|
|
"""Carry on with an Execution a request left between two steps."""
|
|
current = await self.interaction(execution_id)
|
|
if current.status == "running":
|
|
await self._advance(None, execution_id, time_left)
|
|
return await self.interaction(execution_id)
|
|
|
|
async def _advance(self, given: Any, execution_id: str, time_left: Any) -> None:
|
|
"""Run the graph. With `time_left`, stop between two steps once it reaches
|
|
zero, so the runtime's limit never cuts a step off: every finished step is
|
|
checkpointed, and `carry_on` continues from there."""
|
|
async for _ in self._graph.astream(
|
|
given, self._config(execution_id), stream_mode="updates", durability="sync"
|
|
):
|
|
if time_left is not None and time_left() <= 0:
|
|
break
|
|
|
|
async def interaction(self, execution_id: str) -> Interaction:
|
|
snapshot = await self._graph.aget_state(self._config(execution_id))
|
|
if not snapshot.values:
|
|
raise KeyError(f"Unknown Execution {execution_id}")
|
|
if snapshot.interrupts:
|
|
return Interaction(
|
|
execution_id,
|
|
"awaiting_user",
|
|
snapshot.interrupts[0].value,
|
|
snapshot.values,
|
|
)
|
|
return Interaction(
|
|
execution_id,
|
|
snapshot.values.get("status", "running"),
|
|
None,
|
|
snapshot.values,
|
|
)
|
|
|
|
async def _exists(self, execution_id: str) -> bool:
|
|
snapshot = await self._graph.aget_state(self._config(execution_id))
|
|
return bool(snapshot.values)
|
|
|
|
@staticmethod
|
|
def _config(execution_id: str) -> RunnableConfig:
|
|
return {
|
|
"configurable": {"thread_id": execution_id},
|
|
"recursion_limit": _RECURSION_LIMIT,
|
|
}
|