343 lines
12 KiB
Python
343 lines
12 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 dataclasses
|
|
import uuid
|
|
from collections.abc import AsyncIterator, Mapping, Sequence
|
|
from contextlib import asynccontextmanager
|
|
from dataclasses import dataclass, field
|
|
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,
|
|
Decider,
|
|
NoDecider,
|
|
RoleSpec,
|
|
RunLimiter,
|
|
ToolFactory,
|
|
)
|
|
from app.checkpointing import open_checkpointer
|
|
from app.config import Settings
|
|
from app.customer_case import record_intent
|
|
from app.nodes.router import (
|
|
REPLY_WRITER,
|
|
OrchestratorPolicy,
|
|
Router,
|
|
RuntimeReplyWriter,
|
|
Thresholds,
|
|
)
|
|
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.jev import JevDecider, JevLimits
|
|
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,
|
|
orchestrator: OrchestratorPolicy | 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,
|
|
orchestrator=orchestrator,
|
|
).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,
|
|
"last_reply": None,
|
|
"pending_change": None,
|
|
"awaiting_gap_decision": False,
|
|
"validation_settled": 0,
|
|
"decisions": [],
|
|
"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]
|
|
decider: Decider = field(default_factory=NoDecider)
|
|
|
|
|
|
def open_decider(settings: Settings) -> Decider:
|
|
"""The Jev client when a key is configured; otherwise a decider that always
|
|
sends its caller to the fallback."""
|
|
if not settings.TYPESAFE_API_KEY:
|
|
return NoDecider()
|
|
return JevDecider(
|
|
api_key=settings.TYPESAFE_API_KEY,
|
|
base_url=settings.TYPESAFE_BASE_URL,
|
|
model=settings.TYPESAFE_DEFAULT_MODEL,
|
|
limits=dataclasses.replace(
|
|
JevLimits(),
|
|
request_timeout=settings.JEV_TIMEOUT_SECONDS,
|
|
requests_per_second=settings.JEV_REQUESTS_PER_SECOND,
|
|
max_in_flight=settings.JEV_MAX_IN_FLIGHT,
|
|
budget_calls=settings.JEV_BUDGET_CALLS,
|
|
budget_tokens=settings.JEV_BUDGET_TOKENS,
|
|
),
|
|
)
|
|
|
|
|
|
@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(),
|
|
providers=bundle.terraform_providers,
|
|
)
|
|
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=lambda working_copy: local_tools(offered, runner, working_copy),
|
|
catalog=catalog,
|
|
limiter=limiter,
|
|
)
|
|
|
|
decider = open_decider(settings)
|
|
orchestrator: OrchestratorPolicy | None = None
|
|
if settings.ORCHESTRATOR == "router":
|
|
# The Orchestrator routes: Jev reads, the playbook decides, and a model only
|
|
# writes what the user reads. With no Jev key the playbook runs on its rules.
|
|
orchestrator = Router(
|
|
decider,
|
|
RuntimeReplyWriter(runtime, roles[REPLY_WRITER]),
|
|
Thresholds(
|
|
act=settings.JEV_ACT_THRESHOLD,
|
|
close=settings.JEV_CLOSE_THRESHOLD,
|
|
confidence=settings.JEV_CONFIDENCE_THRESHOLD,
|
|
),
|
|
)
|
|
elif settings.ORCHESTRATOR != "model":
|
|
raise ValueError(
|
|
f"ORCHESTRATOR must be router or model, not {settings.ORCHESTRATOR!r}"
|
|
)
|
|
|
|
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()
|
|
},
|
|
orchestrator=orchestrator,
|
|
)
|
|
try:
|
|
yield Assembly(engine, bundle, roles, dict(catalog.gaps), decider)
|
|
finally:
|
|
if isinstance(decider, JevDecider):
|
|
await decider.aclose()
|