Files
gcp_solution_architecture_a…/app/agent.py
Jonathan Boniface e9246828b3 feat: establish the Target architecture as a graph before code
Design is now approved before any infrastructure code is written (ADR-0005).
A new target-architect Specialist produces one graph of Elements,
Relationships and Checks; the diagram is rendered from it, deployment
guidance must account for every Check, and validation gives a verdict per
Check. Requirements, components, products and recommendations carry ids in
data files, and a submission with a gap in the Requirements chain is refused.

Also in this commit:
- Customer cases group Executions, with an intent history per case
- lesson candidates are captured when an Execution ends
- evaluation gains chain, verdict, judged and interactive checks, and
  per-case thresholds
- Terraform providers are cached between checks
- the requirements analyst proposes defaults instead of asking
- the legacy-baseline case and the checks that only read it are removed
- ADR-0006 (Change requests) accepted; ADR-0004 and ADR-0007 proposed
- plans for iterations 4 to 7 under .agents/plans/

Unproven with a real model: no evaluation run has completed on this design.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 13:59:09 +01:00

274 lines
9.9 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 AsyncIterator, Mapping, Sequence
from contextlib import asynccontextmanager
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.adk.roles import load_roles
from app.adk.runtime import AgentRuntime, RoleSpec, RunLimiter, ToolFactory
from app.checkpointing import open_checkpointer
from app.config import Settings
from app.customer_case import record_intent
from app.providers import ProviderBundle, load_provider
from app.recorder import DatabaseRecorder, ExecutionRecorder
from app.skills.agent_skills import skill_version
from app.states.execution_state import check_customer_case
from app.states.ledger import Ledger
from app.tools.execution import ORCHESTRATOR
from app.tools.local import TerraformRunner, local_tools
from app.tools.mcp import McpCatalog, auth_from_config
from app.tools.toolkit import make_tool_factory
from app.workflows.deliverables import DEPENDENCY_GRAPH
from app.workflows.execution_graph import build_execution_graph
_RECURSION_LIMIT = 10_000 # loops are bounded by max_orchestrator_turns instead
@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]
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,
) -> 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
self._output_root = output_root
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,
).compile(checkpointer=checkpointer)
async def start(
self,
workflow_request: str,
*,
session_id: str | None = None,
customer_case: str | None = None,
pre_approved: bool = False,
allow_cloud_read: bool | None = None,
execution_id: str | None = None,
scripted_answers: Sequence[tuple[str, str]] = (),
) -> Interaction:
"""Start an Execution. `scripted_answers` are (regex, answer) pairs a
pre-approved Execution uses to answer questions, for evaluation runs."""
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 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,
)
initial: dict[str, Any] = {
"execution_id": execution_id,
"session_id": session_id,
"customer_case": customer_case,
"intent_version": intent_version,
"workflow_request": workflow_request,
"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": {},
"working": {},
"pending_permission": None,
"prompt": None,
"outcomes": [],
"refusals": [],
"outcomes_applied": 0,
"events_recorded": 0,
"turns": 0,
"status": "running",
"warnings": [],
"scripted_answers": [
[pattern, answer] for pattern, answer in scripted_answers
],
}
await self._graph.ainvoke(initial, self._config(execution_id))
return await self.interaction(execution_id)
async def resume(self, execution_id: str, reply: Mapping[str, Any]) -> 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._graph.ainvoke(
Command(resume=dict(reply)), self._config(execution_id)
)
return await self.interaction(execution_id)
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,
}
# --- assembly ----------------------------------------------------------------------
AGENTS_DIR = Path(__file__).resolve().parent.parent / "agents"
@dataclass(frozen=True)
class Assembly:
engine: ExecutionEngine
bundle: ProviderBundle
roles: dict[str, RoleSpec]
mcp_gaps: dict[str, str]
@asynccontextmanager
async def open_assembly(
settings: Settings,
*,
runtime: AgentRuntime | None = None,
recorder: ExecutionRecorder | None = None,
output_root: Path | None = None,
) -> AsyncIterator[Assembly]:
bundle = load_provider(settings.CLOUD_PROVIDER)
roles = load_roles(
AGENTS_DIR,
bundle,
orchestrator_budget=settings.ORCHESTRATOR_BUDGET,
specialist_budget=settings.SPECIALIST_BUDGET,
include_preview_mcp=settings.MCP_ENABLE_PREVIEW,
)
if runtime is None:
from app.adk.adk_runtime import AdkAgentRuntime
runtime = AdkAgentRuntime(
skill_dirs={name: meta.path for name, meta in bundle.skills.items()},
model_timeout_seconds=settings.MODEL_TIMEOUT_SECONDS,
)
catalog = McpCatalog()
if settings.MCP_ENABLED:
used = {server_id for role in roles.values() for server_id in role.mcp_servers}
catalog = await McpCatalog.load(
[bundle.mcp_servers[server_id] for server_id in sorted(used)],
auth_from_config(bundle.mcp_auth, settings.MCP_QUOTA_PROJECT),
timeout=settings.MCP_TIMEOUT_SECONDS,
)
runner = TerraformRunner(
binary=settings.TERRAFORM_BINARY,
timeout_seconds=settings.TERRAFORM_TIMEOUT_SECONDS,
plugin_cache_dir=settings.terraform_plugin_cache(),
)
offered = [name for names in bundle.tools.values() for name in names]
# One cap for Specialists and the pillar advisors they fan out to.
limiter = RunLimiter(settings.MAX_PARALLEL_SPECIALISTS)
tool_factory = make_tool_factory(
runtime,
roles,
bundle.pillar_skills,
local_tools=local_tools(offered, runner),
catalog=catalog,
limiter=limiter,
)
async with open_checkpointer(settings) as checkpointer:
engine = ExecutionEngine(
runtime=runtime,
roles=roles,
recorder=recorder or DatabaseRecorder(),
checkpointer=checkpointer,
output_root=output_root or settings.BASE_DIR,
max_revisions=settings.MAX_REVISIONS,
max_orchestrator_turns=settings.MAX_ORCHESTRATOR_TURNS,
tool_factory=tool_factory,
limiter=limiter,
skill_versions={
name: skill_version(meta.path) for name, meta in bundle.skills.items()
},
)
yield Assembly(engine, bundle, roles, dict(catalog.gaps))