"""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))