feat: add the hierarchical Execution engine on LangGraph
Increment 4 of .scratch/solution-architect-agent/spec.md, test-first. - app/agents/runtime.py: framework-neutral AgentRuntime interface (RoleSpec, AgentTask, ToolSpec, outcomes); fake_runtime.py replays scripted tool calls through the real tools with step budgets. - app/execution/graph.py: Orchestrator turn fans out to parallel Specialist tasks (Send), pauses with interrupt() for questions, Approvals and cloud-read permission, and finalizes or ends with warnings. Only the Orchestrator turn writes the Ledger. - app/execution/tools.py: Orchestrator tools, Specialist submit and needs_input, and the cloud-read permission gate. - app/execution/engine.py: ExecutionEngine.start/resume returning an Interaction; the single interface for A2A, /generate and eval. - Recorders (in-memory, DatabaseManager), configurable checkpointer (memory, sqlite, postgres), engine settings, langgraph checkpoint dependencies. - 19 new tests; full suite 121 passed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
145
app/execution/engine.py
Normal file
145
app/execution/engine.py
Normal file
@@ -0,0 +1,145 @@
|
||||
"""ExecutionEngine: start and resume Executions.
|
||||
|
||||
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.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import uuid
|
||||
from collections.abc import Mapping
|
||||
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.agents.runtime import AgentRuntime, RoleSpec
|
||||
from app.execution.deliverables import DEPENDENCY_GRAPH
|
||||
from app.execution.graph import ToolFactory, build_execution_graph
|
||||
from app.execution.ledger import Ledger
|
||||
from app.execution.recorder import ExecutionRecorder
|
||||
from app.execution.tools import ORCHESTRATOR
|
||||
|
||||
_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,
|
||||
) -> 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._graph = build_execution_graph(
|
||||
runtime=runtime,
|
||||
roles=roles,
|
||||
recorder=recorder,
|
||||
output_root=output_root,
|
||||
max_orchestrator_turns=max_orchestrator_turns,
|
||||
tool_factory=tool_factory,
|
||||
).compile(checkpointer=checkpointer)
|
||||
|
||||
async def start(
|
||||
self,
|
||||
workflow_request: str,
|
||||
*,
|
||||
session_id: str | None = None,
|
||||
pre_approved: bool = False,
|
||||
allow_cloud_read: bool | None = None,
|
||||
) -> Interaction:
|
||||
execution_id = str(uuid.uuid4())
|
||||
if pre_approved and allow_cloud_read is None:
|
||||
allow_cloud_read = False
|
||||
initial: dict[str, Any] = {
|
||||
"execution_id": execution_id,
|
||||
"session_id": session_id or str(uuid.uuid4()),
|
||||
"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": {},
|
||||
"pending_permission": None,
|
||||
"prompt": None,
|
||||
"outcomes": [],
|
||||
"outcomes_applied": 0,
|
||||
"events_recorded": 0,
|
||||
"turns": 0,
|
||||
"status": "running",
|
||||
"warnings": [],
|
||||
}
|
||||
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,
|
||||
)
|
||||
|
||||
@staticmethod
|
||||
def _config(execution_id: str) -> RunnableConfig:
|
||||
return {
|
||||
"configurable": {"thread_id": execution_id},
|
||||
"recursion_limit": _RECURSION_LIMIT,
|
||||
}
|
||||
Reference in New Issue
Block a user