feat: working orhcestration engine
This commit is contained in:
685
execution_engine/agent.py
Normal file
685
execution_engine/agent.py
Normal file
@@ -0,0 +1,685 @@
|
||||
"""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 hashlib
|
||||
import uuid
|
||||
from collections.abc import AsyncIterator, Callable, 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 execution_engine.adk.roles import load_roles
|
||||
from execution_engine.adk.runtime import (
|
||||
AgentRuntime,
|
||||
Decider,
|
||||
NoDecider,
|
||||
RoleSpec,
|
||||
RunLimiter,
|
||||
SubmissionReview,
|
||||
ToolFactory,
|
||||
)
|
||||
from execution_engine.baseline import load_baseline
|
||||
from execution_engine.checkpointing import open_checkpointer
|
||||
from execution_engine.config import Settings
|
||||
from execution_engine.customer_case import record_intent
|
||||
from execution_engine.nodes.intake import DeliveredAnswers, Intake
|
||||
from execution_engine.nodes.router import (
|
||||
REPLY_WRITER,
|
||||
OrchestratorPolicy,
|
||||
Router,
|
||||
RuntimeReplyWriter,
|
||||
Thresholds,
|
||||
)
|
||||
from execution_engine.providers import ProviderBundle, load_provider
|
||||
from execution_engine.recorder import DatabaseRecorder, ExecutionRecorder
|
||||
from execution_engine.scope import (
|
||||
ESSENTIAL,
|
||||
Catalogue,
|
||||
Scope,
|
||||
merged,
|
||||
read_scope,
|
||||
slug,
|
||||
)
|
||||
from execution_engine.skills.agent_skills import discover_skills, skill_version
|
||||
from execution_engine.states.execution_state import check_customer_case
|
||||
from execution_engine.states.ledger import Ledger
|
||||
from execution_engine.tools.execution import ORCHESTRATOR
|
||||
from execution_engine.tools.jev import JevDecider, JevLimits
|
||||
from execution_engine.tools.mcp import McpCatalog, auth_from_config
|
||||
from execution_engine.tools.scoping import Scoping, to_working
|
||||
from execution_engine.tools.skill_routing import routable
|
||||
from execution_engine.tools.toolkit import make_tool_factory
|
||||
from execution_engine.tools.workspace import safe_relative
|
||||
from execution_engine.workflows.execution_graph import build_execution_graph
|
||||
from execution_engine.workflows.workflow import Assembling, Digested, Workflow
|
||||
|
||||
# How much of a source code did not read is given to a Specialist to read.
|
||||
_DOCUMENT_LIMIT = 60_000
|
||||
_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,
|
||||
*,
|
||||
workflow: Workflow,
|
||||
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,
|
||||
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,
|
||||
scope_catalogue: Catalogue | None = None,
|
||||
scope_values: Mapping[str, Sequence[str]] | None = None,
|
||||
scope_skill: str | None = None,
|
||||
) -> None:
|
||||
required = {
|
||||
ORCHESTRATOR,
|
||||
*(spec.specialist for spec in workflow.deliverables.values()),
|
||||
}
|
||||
missing = sorted(required - set(roles))
|
||||
if missing:
|
||||
raise ValueError(f"Missing roles: {', '.join(missing)}")
|
||||
self.workflow = workflow
|
||||
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
|
||||
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(
|
||||
workflow=workflow,
|
||||
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,
|
||||
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,
|
||||
).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] = (),
|
||||
scope: str | Mapping[str, Any] | None = None,
|
||||
sources: Mapping[str, str] | None = None,
|
||||
**options: Any,
|
||||
) -> 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.
|
||||
|
||||
`sources` are files to digest into a spec, by name: what another agent
|
||||
delivered, or documents that describe what is wanted. The Workflow reads
|
||||
the ones it knows in code. Any other is given to the Specialist that
|
||||
completes the spec, to read. A `scope` given with them is laid over what
|
||||
was digested, field by field. A source is refused when its name is not a
|
||||
safe relative path, or when the Workflow knows its kind and cannot read it.
|
||||
|
||||
`options` are the choices this agent's Workflow lets a caller make for one
|
||||
Execution, by name. One left unset is taken from the spec when the spec
|
||||
states it; then a Change request does as its Baseline did, and any other
|
||||
Execution takes the Workflow's default. A name the Workflow does not have,
|
||||
or a value it does not allow, refuses the start.
|
||||
|
||||
`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.
|
||||
"""
|
||||
unknown_options = sorted(set(options) - set(self.workflow.options))
|
||||
if unknown_options:
|
||||
raise ValueError(
|
||||
f"Unknown options: {', '.join(unknown_options)}. Available: "
|
||||
f"{', '.join(sorted(self.workflow.options)) or 'none'}"
|
||||
)
|
||||
digested = self._digest(sources) if sources else None
|
||||
if digested is not None and digested.spec:
|
||||
if self._scope_catalogue is None:
|
||||
raise ValueError("This deployment has no scope spec catalogue.")
|
||||
read: Scope | None = merged(
|
||||
digested.spec,
|
||||
scope,
|
||||
self._scope_catalogue,
|
||||
provider_values=self._scope_values,
|
||||
notes=digested.notes,
|
||||
)
|
||||
else:
|
||||
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"])
|
||||
for name, option in self.workflow.options.items():
|
||||
if (
|
||||
options.get(name) is None
|
||||
and option.spec_field
|
||||
and option.spec_field in run
|
||||
):
|
||||
options[name] = run[option.spec_field]
|
||||
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
|
||||
)
|
||||
chosen_options: dict[str, Any] = {}
|
||||
for name, option in self.workflow.options.items():
|
||||
value = options.get(name)
|
||||
if value is None:
|
||||
before = (loaded or {}).get("options") or {}
|
||||
value = before.get(name, option.default)
|
||||
refused = option.check(value) if option.check else None
|
||||
if refused:
|
||||
# A ValueError is what callers turn into a refused start.
|
||||
raise ValueError(refused)
|
||||
chosen_options[name] = value
|
||||
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,
|
||||
sources=sources,
|
||||
)
|
||||
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},
|
||||
"options": chosen_options,
|
||||
# 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,
|
||||
# What the spec was digested from: each source's hash, and whether code
|
||||
# read it. The ones code did not read are documents for the Specialist
|
||||
# that completes the spec.
|
||||
"sources": {
|
||||
name: {
|
||||
"sha256": hashlib.sha256(content.encode("utf-8")).hexdigest(),
|
||||
"digested": bool(digested and name in digested.used),
|
||||
}
|
||||
for name, content in (sources or {}).items()
|
||||
},
|
||||
"source_documents": {
|
||||
name: content[:_DOCUMENT_LIMIT]
|
||||
for name, content in (sources or {}).items()
|
||||
if not (digested and name in digested.used)
|
||||
},
|
||||
"risks": [],
|
||||
"pre_approved": pre_approved,
|
||||
"allow_cloud_read": allow_cloud_read,
|
||||
"ledger": Ledger(
|
||||
self.workflow,
|
||||
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._graph.ainvoke(initial, self._config(execution_id))
|
||||
return await self.interaction(execution_id)
|
||||
|
||||
def _digest(self, sources: Mapping[str, str]) -> Digested:
|
||||
"""What the Workflow reads of the sources, after checking they are files."""
|
||||
if not isinstance(sources, Mapping) or not all(
|
||||
isinstance(name, str) and isinstance(content, str)
|
||||
for name, content in sources.items()
|
||||
):
|
||||
raise ValueError("sources must be files by name: {name: content}")
|
||||
unsafe = sorted(name for name in sources if not safe_relative(name))
|
||||
if unsafe:
|
||||
raise ValueError(
|
||||
"source names must be relative paths without '..': " + ", ".join(unsafe)
|
||||
)
|
||||
if self.workflow.digest is None:
|
||||
return Digested({})
|
||||
return self.workflow.digest(sources)
|
||||
|
||||
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]) -> 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 ----------------------------------------------------------------------
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Assembly:
|
||||
engine: ExecutionEngine
|
||||
bundle: ProviderBundle
|
||||
roles: dict[str, RoleSpec]
|
||||
mcp_gaps: dict[str, str]
|
||||
decider: Decider = field(default_factory=NoDecider)
|
||||
intake: Intake | None = None # reads a message that starts something
|
||||
# Answers a question about delivered work from its files.
|
||||
answers: DeliveredAnswers | None = None
|
||||
# The runtime the agents run on, for a caller that reports what they used.
|
||||
runtime: AgentRuntime | None = None
|
||||
|
||||
|
||||
def discover_overlays(
|
||||
settings: Settings, bundle: ProviderBundle, root: Path | None = None
|
||||
) -> dict[str, Any]:
|
||||
"""The overlay Skills this deployment has configured, by name (ADR-0004).
|
||||
|
||||
They come only from the folders the deployment names, pass the same validation
|
||||
as the provider's Skills, and may not reuse one of the provider's names.
|
||||
"""
|
||||
folders = [folder for folder in settings.overlay_dirs(root) if folder.is_dir()]
|
||||
overlays = discover_skills(folders)
|
||||
clash = sorted(set(overlays) & set(bundle.skills))
|
||||
if clash:
|
||||
raise ValueError(
|
||||
f"Overlay Skills reuse the names of provider Skills: {', '.join(clash)}"
|
||||
)
|
||||
return overlays
|
||||
|
||||
|
||||
def skill_dirs(
|
||||
settings: Settings, bundle: ProviderBundle, root: Path | None = None
|
||||
) -> dict[str, Path]:
|
||||
"""Every Skill a runtime may be asked to load: the provider's and the overlays."""
|
||||
return {
|
||||
**{name: meta.path for name, meta in bundle.skills.items()},
|
||||
**{
|
||||
name: meta.path
|
||||
for name, meta in discover_overlays(settings, bundle, root).items()
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def role_references(
|
||||
roles: Mapping[str, RoleSpec], bundle: ProviderBundle
|
||||
) -> dict[str, dict[str, dict[str, str]]]:
|
||||
"""For each role, its Skills that hold enough references to choose among, with
|
||||
what each reference covers (iteration 5 step 8)."""
|
||||
worth = routable({name: meta.path for name, meta in bundle.skills.items()})
|
||||
by_role = {
|
||||
name: {skill: worth[skill] for skill in role.skills if skill in worth}
|
||||
for name, role in roles.items()
|
||||
}
|
||||
return {name: skills for name, skills in by_role.items() if skills}
|
||||
|
||||
|
||||
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,
|
||||
workflow: Workflow | Callable[[Settings, ProviderBundle], Workflow],
|
||||
*,
|
||||
root: Path,
|
||||
runtime: AgentRuntime | None = None,
|
||||
recorder: ExecutionRecorder | None = None,
|
||||
output_root: Path | None = None,
|
||||
) -> AsyncIterator[Assembly]:
|
||||
"""Assemble an agent: the engine, and the Workflow that makes it about a subject.
|
||||
|
||||
`root` is the agent's own folder: its provider bundles are under `providers/`,
|
||||
its role files under `agents/`, and its Skills where the bundle says. `workflow`
|
||||
is the Workflow, or a function that builds it for the settings and the bundle
|
||||
when parts of it depend on them.
|
||||
"""
|
||||
bundle = load_provider(settings.CLOUD_PROVIDER, root)
|
||||
if not isinstance(workflow, Workflow):
|
||||
workflow = workflow(settings, bundle)
|
||||
roles = load_roles(
|
||||
root / "agents",
|
||||
bundle,
|
||||
workflow,
|
||||
orchestrator_budget=settings.ORCHESTRATOR_BUDGET,
|
||||
specialist_budget=settings.SPECIALIST_BUDGET,
|
||||
include_preview_mcp=settings.MCP_ENABLE_PREVIEW,
|
||||
lessons=settings.LESSONS_ENABLED,
|
||||
model_tiers=settings.MODEL_TIERS,
|
||||
)
|
||||
overlays = discover_overlays(settings, bundle, root)
|
||||
if runtime is None:
|
||||
from execution_engine.adk.adk_runtime import AdkAgentRuntime
|
||||
|
||||
runtime = AdkAgentRuntime(
|
||||
skill_dirs=skill_dirs(settings, bundle, root),
|
||||
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,
|
||||
)
|
||||
|
||||
# One cap for Specialists and the agents they fan out to.
|
||||
limiter = RunLimiter(settings.MAX_PARALLEL_SPECIALISTS)
|
||||
decider = open_decider(settings)
|
||||
assembling = Assembling(settings, bundle, runtime, roles, decider)
|
||||
tool_factory = make_tool_factory(
|
||||
workflow,
|
||||
runtime,
|
||||
roles,
|
||||
local_tools=workflow.local_tools(assembling) if workflow.local_tools else (),
|
||||
catalog=catalog,
|
||||
limiter=limiter,
|
||||
guard=decider
|
||||
if settings.JEV_GUARDRAIL and isinstance(decider, JevDecider)
|
||||
else None,
|
||||
withhold_at=settings.JEV_GUARDRAIL_THRESHOLD,
|
||||
)
|
||||
|
||||
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}"
|
||||
)
|
||||
|
||||
# What is looked at in a submission before it is accepted. Each review raises
|
||||
# what it finds once and never blocks.
|
||||
submission_review = workflow.reviews(assembling) if workflow.reviews else None
|
||||
|
||||
async with open_checkpointer(settings) as checkpointer:
|
||||
engine = ExecutionEngine(
|
||||
workflow=workflow,
|
||||
runtime=runtime,
|
||||
roles=roles,
|
||||
recorder=recorder or DatabaseRecorder(),
|
||||
checkpointer=checkpointer,
|
||||
output_root=output_root or root,
|
||||
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,
|
||||
submission_review=submission_review,
|
||||
confirm_drafts=settings.CONFIRM_DRAFTS,
|
||||
decider=decider,
|
||||
reworded_threshold=settings.JEV_REWORDED_THRESHOLD,
|
||||
guard_user_text=settings.JEV_GUARDRAIL,
|
||||
guard_threshold=settings.JEV_GUARDRAIL_THRESHOLD,
|
||||
skill_references=role_references(roles, bundle)
|
||||
if settings.JEV_SKILL_ROUTING
|
||||
else None,
|
||||
skill_threshold=settings.JEV_SKILL_THRESHOLD,
|
||||
assess_at_end=settings.JEV_ASSESS_EXECUTIONS,
|
||||
scope_catalogue=bundle.scope_catalogue() if bundle.scope_skill else None,
|
||||
scope_values=bundle.scope_values,
|
||||
scope_skill=bundle.scope_skill,
|
||||
overlays={
|
||||
name: skill_version(meta.path) for name, meta in overlays.items()
|
||||
},
|
||||
default_overlays=settings.default_overlays(),
|
||||
)
|
||||
try:
|
||||
yield Assembly(
|
||||
engine,
|
||||
bundle,
|
||||
roles,
|
||||
dict(catalog.gaps),
|
||||
decider,
|
||||
Intake(
|
||||
decider,
|
||||
output_root or root,
|
||||
act=settings.JEV_ACT_THRESHOLD,
|
||||
),
|
||||
DeliveredAnswers(
|
||||
runtime,
|
||||
roles[REPLY_WRITER],
|
||||
output_root or root,
|
||||
workflow.final,
|
||||
),
|
||||
runtime,
|
||||
)
|
||||
finally:
|
||||
if isinstance(decider, JevDecider):
|
||||
await decider.aclose()
|
||||
Reference in New Issue
Block a user