feat: working orhcestration engine
This commit is contained in:
1
execution_engine/adk/__init__.py
Normal file
1
execution_engine/adk/__init__.py
Normal file
@@ -0,0 +1 @@
|
||||
"""Agent runtimes: the framework-neutral interface agents run behind, and its implementations."""
|
||||
448
execution_engine/adk/adk_runtime.py
Normal file
448
execution_engine/adk/adk_runtime.py
Normal file
@@ -0,0 +1,448 @@
|
||||
"""AgentRuntime on Google ADK (ADR-0003): an LlmAgent per run, with SkillToolset.
|
||||
|
||||
This is the only module that imports google.adk. Each run builds a fresh LlmAgent
|
||||
and in-memory session (Specialists are stateless), offers the role's ToolSpecs and
|
||||
Skills, and stops as soon as a tool returns an outcome or the budget is spent.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import json
|
||||
import logging
|
||||
import re
|
||||
import uuid
|
||||
from collections.abc import Callable, Mapping, Sequence
|
||||
from contextlib import aclosing
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
from google.adk.agents import LlmAgent
|
||||
from google.adk.models.base_llm import BaseLlm
|
||||
from google.adk.runners import Runner
|
||||
from google.adk.sessions import InMemorySessionService
|
||||
from google.adk.skills import load_skill_from_dir
|
||||
from google.adk.skills.models import Skill
|
||||
from google.adk.tools.base_tool import BaseTool
|
||||
from google.adk.tools.skill_toolset import SkillToolset
|
||||
from google.adk.tools.tool_context import ToolContext
|
||||
from google.genai import types
|
||||
|
||||
from execution_engine.adk.runtime import (
|
||||
REJECTION_PREFIXES,
|
||||
AgentTask,
|
||||
BudgetExhausted,
|
||||
Outcome,
|
||||
RoleSpec,
|
||||
Stopped,
|
||||
ToolSpec,
|
||||
)
|
||||
|
||||
APP_NAME = "solution-architect"
|
||||
# run_skill_script is deliberately absent: generated or bundled scripts never run.
|
||||
SKILL_TOOLS = ["list_skills", "load_skill", "load_skill_resource"]
|
||||
TURN_ENDED_REPLY = "Your turn has already ended; this call was not run."
|
||||
NUDGE = (
|
||||
"You stopped without calling a tool that ends your turn, so nothing was recorded. "
|
||||
"Continue the task, and finish by calling the tool your instructions name for "
|
||||
"ending your turn. If you need the user, use the tool for asking questions."
|
||||
)
|
||||
TIMED_OUT = (
|
||||
"Your last model request timed out, so its reply was lost. Continue the task, "
|
||||
"and finish by calling the tool your instructions name for ending your turn."
|
||||
)
|
||||
# Client-side timeouts from either HTTP stack google-genai may use (httpx or aiohttp,
|
||||
# whose timeout errors subclass TimeoutError).
|
||||
MODEL_TIMEOUTS = (TimeoutError, httpx.TimeoutException)
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
ModelFactory = Callable[[RoleSpec], BaseLlm | str]
|
||||
|
||||
|
||||
GEMINI_PREFIX = "gemini/"
|
||||
|
||||
|
||||
def default_model_factory(role: RoleSpec) -> BaseLlm:
|
||||
"""Model for a role's LiteLLM-style id.
|
||||
|
||||
`gemini/<model>` uses ADK's native Gemini client, which targets Vertex AI when
|
||||
GOOGLE_GENAI_USE_ENTERPRISE=true (with GOOGLE_CLOUD_PROJECT and
|
||||
GOOGLE_CLOUD_LOCATION) and the Gemini API otherwise. Any other id goes through
|
||||
LiteLLM, so other model providers need no code changes.
|
||||
"""
|
||||
if not role.model:
|
||||
raise ValueError(f"Role {role.name!r} has no model configured")
|
||||
if role.model.startswith(GEMINI_PREFIX):
|
||||
from google.adk.models.google_llm import Gemini
|
||||
|
||||
return Gemini(
|
||||
model=role.model.removeprefix(GEMINI_PREFIX),
|
||||
retry_options=types.HttpRetryOptions(attempts=5, initial_delay=2.0),
|
||||
)
|
||||
from google.adk.models.lite_llm import LiteLlm
|
||||
|
||||
return LiteLlm(model=role.model)
|
||||
|
||||
|
||||
USAGE_FIELDS = {
|
||||
"requests": None,
|
||||
"prompt": "prompt_token_count",
|
||||
"cached": "cached_content_token_count",
|
||||
"tool_prompt": "tool_use_prompt_token_count",
|
||||
"output": "candidates_token_count",
|
||||
"thinking": "thoughts_token_count",
|
||||
"total": "total_token_count",
|
||||
}
|
||||
|
||||
|
||||
@dataclass
|
||||
class TokenUsage:
|
||||
"""Model token counts, summed over every model response of one role and model."""
|
||||
|
||||
requests: int = 0
|
||||
prompt: int = 0
|
||||
cached: int = 0
|
||||
tool_prompt: int = 0
|
||||
output: int = 0
|
||||
thinking: int = 0
|
||||
total: int = 0
|
||||
|
||||
def add(self, metadata: Any) -> None:
|
||||
self.requests += 1
|
||||
for name, source in USAGE_FIELDS.items():
|
||||
if source:
|
||||
setattr(
|
||||
self,
|
||||
name,
|
||||
getattr(self, name) + (getattr(metadata, source, 0) or 0),
|
||||
)
|
||||
|
||||
|
||||
@dataclass
|
||||
class Carried:
|
||||
"""What one source put into a role's conversations, in characters.
|
||||
|
||||
A model request re-sends the whole conversation so far. So what an item costs
|
||||
is its size times the number of requests it is sent in: something added early
|
||||
in a long run is paid for many times. `carried` is that product, summed.
|
||||
"""
|
||||
|
||||
items: int = 0
|
||||
chars: int = 0
|
||||
carried: int = 0
|
||||
|
||||
|
||||
def _size(value: Any) -> int:
|
||||
"""The size of what a tool was sent or returned, as the model reads it."""
|
||||
if isinstance(value, str):
|
||||
return len(value)
|
||||
try:
|
||||
return len(json.dumps(value, default=str, ensure_ascii=False))
|
||||
except (TypeError, ValueError):
|
||||
return len(str(value))
|
||||
|
||||
|
||||
def _entered(event: Any) -> list[tuple[str, int]]:
|
||||
"""(source, characters) for everything one event adds to the conversation."""
|
||||
found = []
|
||||
for part in getattr(getattr(event, "content", None), "parts", None) or ():
|
||||
if getattr(part, "thought", False):
|
||||
continue # thinking is paid for once, as output; it is not re-sent
|
||||
response = getattr(part, "function_response", None)
|
||||
call = getattr(part, "function_call", None)
|
||||
if response is not None:
|
||||
found.append((f"result: {response.name}", _size(response.response)))
|
||||
elif call is not None:
|
||||
found.append((f"call: {call.name}", _size(call.args)))
|
||||
elif getattr(part, "text", None):
|
||||
found.append(("model text", len(part.text)))
|
||||
return found
|
||||
|
||||
|
||||
@dataclass
|
||||
class _RunControl:
|
||||
budget: int
|
||||
role: str
|
||||
calls: int = 0
|
||||
outcome: Outcome | None = None
|
||||
lock: asyncio.Lock = field(default_factory=asyncio.Lock)
|
||||
|
||||
def before_tool(
|
||||
self, tool: BaseTool, args: dict[str, Any], tool_context: Any
|
||||
) -> dict[str, Any] | None:
|
||||
if self.outcome is not None:
|
||||
return {"error": TURN_ENDED_REPLY}
|
||||
self.calls += 1
|
||||
logger.info(
|
||||
"%s tool call %d/%d: %s", self.role, self.calls, self.budget, tool.name
|
||||
)
|
||||
if self.calls > self.budget:
|
||||
self.outcome = BudgetExhausted(
|
||||
f"{self.role} used all {self.budget} tool calls before finishing."
|
||||
)
|
||||
return {"error": "Tool-call budget exhausted; stop now."}
|
||||
return None
|
||||
|
||||
|
||||
class _SpecTool(BaseTool):
|
||||
"""Adapts a framework-neutral ToolSpec to an ADK tool."""
|
||||
|
||||
def __init__(self, spec: ToolSpec, control: _RunControl) -> None:
|
||||
super().__init__(name=spec.name, description=spec.description)
|
||||
self._spec = spec
|
||||
self._control = control
|
||||
|
||||
def _get_declaration(self) -> types.FunctionDeclaration:
|
||||
return types.FunctionDeclaration(
|
||||
name=self._spec.name,
|
||||
description=self._spec.description,
|
||||
parameters_json_schema=dict(self._spec.parameters),
|
||||
)
|
||||
|
||||
async def run_async(
|
||||
self, *, args: dict[str, Any], tool_context: ToolContext
|
||||
) -> dict[str, Any]:
|
||||
# Serialise calls within a run: tools may mutate Execution state, and the
|
||||
# first tool to end the turn must stop the rest of a parallel batch.
|
||||
async with self._control.lock:
|
||||
if self._control.outcome is not None:
|
||||
return {"error": TURN_ENDED_REPLY}
|
||||
try:
|
||||
result = await self._spec.handler(**args)
|
||||
except TypeError as exc:
|
||||
logger.info("%s: invalid arguments: %s", self._spec.name, exc)
|
||||
return {"error": f"Invalid arguments for {self._spec.name}: {exc}"}
|
||||
if result.outcome is not None:
|
||||
self._control.outcome = result.outcome
|
||||
elif result.message.startswith(REJECTION_PREFIXES):
|
||||
logger.info(
|
||||
"%s rejected by %s: %s",
|
||||
self._control.role,
|
||||
self._spec.name,
|
||||
result.message[:500],
|
||||
)
|
||||
return {"result": result.message}
|
||||
|
||||
|
||||
class AdkAgentRuntime:
|
||||
def __init__(
|
||||
self,
|
||||
*,
|
||||
skill_dirs: Mapping[str, Path],
|
||||
model_factory: ModelFactory = default_model_factory,
|
||||
max_nudges: int = 2,
|
||||
model_timeout_seconds: float | None = None,
|
||||
) -> None:
|
||||
self._max_nudges = max_nudges
|
||||
self._model_timeout_seconds = model_timeout_seconds
|
||||
self._skills: dict[str, Skill] = {}
|
||||
for name, path in skill_dirs.items():
|
||||
try:
|
||||
skill = load_skill_from_dir(path)
|
||||
except Exception as exc:
|
||||
raise ValueError(
|
||||
f"Could not load skill {name!r} from {path}: {exc}"
|
||||
) from exc
|
||||
if skill.name != name:
|
||||
raise ValueError(
|
||||
f"Skill at {path} is named {skill.name!r}, not {name!r}"
|
||||
)
|
||||
self._skills[name] = skill
|
||||
self._model_factory = model_factory
|
||||
# (role, model) -> usage across every run of this runtime
|
||||
self.usage: dict[tuple[str, str], TokenUsage] = {}
|
||||
# (role, source) -> what that source put into the role's conversations.
|
||||
# Measured here and kept here: nothing is sent anywhere.
|
||||
self.sizes: dict[tuple[str, str], Carried] = {}
|
||||
|
||||
async def run(
|
||||
self, role: RoleSpec, task: AgentTask, tools: Sequence[ToolSpec]
|
||||
) -> Outcome:
|
||||
control = _RunControl(budget=role.budget, role=role.name)
|
||||
agent_tools: list[Any] = [_SpecTool(spec, control) for spec in tools]
|
||||
if role.skills:
|
||||
unknown = [name for name in role.skills if name not in self._skills]
|
||||
if unknown:
|
||||
raise ValueError(f"Role {role.name!r} needs unknown skills: {unknown}")
|
||||
agent_tools.append(
|
||||
SkillToolset(
|
||||
skills=[self._skills[name] for name in role.skills],
|
||||
tool_filter=SKILL_TOOLS,
|
||||
)
|
||||
)
|
||||
|
||||
instructions = role.instructions
|
||||
agent = LlmAgent(
|
||||
name=_agent_name(role.name),
|
||||
model=self._model_factory(role),
|
||||
# A callable instruction is passed verbatim: no {state} templating.
|
||||
instruction=lambda _context: instructions,
|
||||
tools=agent_tools,
|
||||
before_tool_callback=control.before_tool,
|
||||
generate_content_config=self._content_config(role),
|
||||
)
|
||||
runner = Runner(
|
||||
app_name=APP_NAME,
|
||||
agent=agent,
|
||||
session_service=InMemorySessionService(),
|
||||
auto_create_session=True,
|
||||
)
|
||||
session_id = str(uuid.uuid4())
|
||||
usage = self.usage.setdefault((role.name, role.model or "?"), TokenUsage())
|
||||
prompt = _render_task(task, role.skills)
|
||||
# What entered this run's conversation, and after how many requests.
|
||||
definitions = [
|
||||
{"name": t.name, "description": t.description, "parameters": t.parameters}
|
||||
for t in tools
|
||||
]
|
||||
entered: list[tuple[str, int, int]] = [
|
||||
("instructions", len(instructions), 0),
|
||||
("tool definitions", _size(definitions), 0),
|
||||
("task: prompt", len(task.prompt), 0),
|
||||
*(
|
||||
(f"task: {key}", _size(value), 0)
|
||||
for key, value in task.context.items()
|
||||
if value not in (None, [], {}, "")
|
||||
),
|
||||
]
|
||||
made = [0] # model responses in this run: each one was a request
|
||||
try:
|
||||
return await self._converse(
|
||||
role, runner, session_id, prompt, control, usage, entered, made
|
||||
)
|
||||
finally:
|
||||
requests = max(1, made[0])
|
||||
for source, chars, after in entered:
|
||||
kept = self.sizes.setdefault((role.name, source), Carried())
|
||||
kept.items += 1
|
||||
kept.chars += chars
|
||||
# Sent in every request made after it entered.
|
||||
kept.carried += chars * max(0, requests - after)
|
||||
|
||||
async def _converse(
|
||||
self,
|
||||
role: RoleSpec,
|
||||
runner: Runner,
|
||||
session_id: str,
|
||||
prompt: str,
|
||||
control: _RunControl,
|
||||
usage: TokenUsage,
|
||||
entered: list[tuple[str, int, int]],
|
||||
made: list[int],
|
||||
) -> Outcome:
|
||||
final_text = ""
|
||||
for attempt in range(self._max_nudges + 1):
|
||||
if attempt:
|
||||
logger.info(
|
||||
"Nudging %s to end its turn (attempt %d)", role.name, attempt
|
||||
)
|
||||
message = types.Content(role="user", parts=[types.Part(text=prompt)])
|
||||
prompt = NUDGE
|
||||
try:
|
||||
async with aclosing(
|
||||
runner.run_async(
|
||||
user_id=APP_NAME, session_id=session_id, new_message=message
|
||||
)
|
||||
) as events:
|
||||
async for event in events:
|
||||
if event.usage_metadata is not None:
|
||||
usage.add(event.usage_metadata)
|
||||
content = getattr(event, "content", None)
|
||||
if content is not None and content.role == "model":
|
||||
made[0] += 1
|
||||
entered.extend(
|
||||
(source, chars, made[0])
|
||||
for source, chars in _entered(event)
|
||||
)
|
||||
if control.outcome is not None:
|
||||
break
|
||||
if (
|
||||
event.is_final_response()
|
||||
and event.content
|
||||
and event.content.parts
|
||||
):
|
||||
text = "".join(
|
||||
part.text for part in event.content.parts if part.text
|
||||
).strip()
|
||||
final_text = text or final_text # keep the last real reply
|
||||
except MODEL_TIMEOUTS as exc:
|
||||
if control.outcome is not None:
|
||||
return control.outcome
|
||||
logger.warning(
|
||||
"%s model request timed out (%s)", role.name, type(exc).__name__
|
||||
)
|
||||
final_text = final_text or f"{role.name}'s model requests timed out."
|
||||
prompt = TIMED_OUT
|
||||
if control.outcome is not None:
|
||||
return control.outcome
|
||||
|
||||
return Stopped(
|
||||
final_text
|
||||
or f"{role.name} ended without calling a tool that ends its turn."
|
||||
)
|
||||
|
||||
def _content_config(self, role: RoleSpec) -> types.GenerateContentConfig | None:
|
||||
# A role whose replies are long is given longer than the default.
|
||||
seconds = role.model_timeout_seconds or self._model_timeout_seconds
|
||||
if seconds is None:
|
||||
return None
|
||||
return types.GenerateContentConfig(
|
||||
http_options=types.HttpOptions(timeout=int(seconds * 1000))
|
||||
)
|
||||
|
||||
|
||||
def _agent_name(role: str) -> str:
|
||||
return re.sub(r"\W", "_", role)
|
||||
|
||||
|
||||
def _for_model(context: Mapping[str, Any]) -> dict[str, Any]:
|
||||
"""The task context as it is written for the model: each data file among the
|
||||
dependencies as the data it holds, not as a string of JSON inside JSON.
|
||||
|
||||
Written that way, every quote and line break in a data file was escaped, and
|
||||
the whole was indented: the same facts in a third more characters, sent with
|
||||
every request of the run.
|
||||
"""
|
||||
shown = dict(context)
|
||||
dependencies = context.get("dependencies")
|
||||
if isinstance(dependencies, Mapping):
|
||||
opened = {}
|
||||
for name, deliverable in dependencies.items():
|
||||
entry = (
|
||||
dict(deliverable) if isinstance(deliverable, Mapping) else deliverable
|
||||
)
|
||||
files = entry.get("attachments") if isinstance(entry, dict) else None
|
||||
if isinstance(files, Mapping):
|
||||
entry["attachments"] = {
|
||||
file: _opened(file, text) for file, text in files.items()
|
||||
}
|
||||
opened[name] = entry
|
||||
shown["dependencies"] = opened
|
||||
return shown
|
||||
|
||||
|
||||
def _opened(name: str, text: Any) -> Any:
|
||||
if not (isinstance(text, str) and name.endswith(".json")):
|
||||
return text
|
||||
try:
|
||||
return json.loads(text)
|
||||
except ValueError:
|
||||
return text
|
||||
|
||||
|
||||
def _render_task(task: AgentTask, skills: Sequence[str] = ()) -> str:
|
||||
context = json.dumps(
|
||||
_for_model(task.context),
|
||||
separators=(",", ":"),
|
||||
default=str,
|
||||
ensure_ascii=False,
|
||||
)
|
||||
skill_line = (
|
||||
f"\n\nSkills available to you (load with load_skill): {', '.join(skills)}."
|
||||
if skills
|
||||
else ""
|
||||
)
|
||||
return f"{task.prompt}{skill_line}\n\nContext:\n```json\n{context}\n```"
|
||||
130
execution_engine/adk/fake_runtime.py
Normal file
130
execution_engine/adk/fake_runtime.py
Normal file
@@ -0,0 +1,130 @@
|
||||
"""A scripted AgentRuntime for deterministic tests and evaluation dry runs.
|
||||
|
||||
Each role has a queue of turns; a turn is a list of tool calls, or a function of the
|
||||
task that returns one. Calls go through the real ToolSpecs, so every rule the tools
|
||||
enforce is exercised exactly as a model would meet it.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections import deque
|
||||
from collections.abc import Callable, Mapping, Sequence
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.adk.runtime import (
|
||||
AgentTask,
|
||||
Answer,
|
||||
BudgetExhausted,
|
||||
Outcome,
|
||||
Question,
|
||||
RoleSpec,
|
||||
Stopped,
|
||||
ToolSpec,
|
||||
)
|
||||
from execution_engine.workflows.workflow import Workflow
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Call:
|
||||
tool: str
|
||||
args: Mapping[str, Any] = field(default_factory=dict)
|
||||
|
||||
|
||||
Turn = Sequence[Call] | Callable[[AgentTask], Sequence[Call]]
|
||||
|
||||
|
||||
def sample_submission(workflow: Workflow, kind: str, note: str = "") -> Call:
|
||||
"""A `submit_deliverable` call that meets the Deliverable's contract."""
|
||||
spec = workflow.deliverables[kind]
|
||||
parts = [f"# {kind}", note or "Summary."]
|
||||
parts += [f"## {section}\n{note or 'Details.'}" for section in spec.sections]
|
||||
attachments = {
|
||||
name: workflow.samples.get(name, f"# {name}\n") for name in spec.attachments
|
||||
}
|
||||
return Call(
|
||||
"submit_deliverable",
|
||||
{"content": "\n".join(parts) + "\n", "attachments": attachments},
|
||||
)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class RunRecord:
|
||||
role: str
|
||||
task: AgentTask
|
||||
tools: tuple[str, ...]
|
||||
results: tuple[tuple[str, str], ...] # (tool name, message)
|
||||
outcome: Outcome
|
||||
|
||||
|
||||
class ScriptExhausted(AssertionError):
|
||||
"""A role was run more times than the test scripted."""
|
||||
|
||||
|
||||
class FakeAgentRuntime:
|
||||
def __init__(self, turns: Mapping[str, Sequence[Turn]]) -> None:
|
||||
self._turns = {role: deque(role_turns) for role, role_turns in turns.items()}
|
||||
self.runs: list[RunRecord] = []
|
||||
|
||||
def remaining(self, role: str) -> int:
|
||||
return len(self._turns.get(role, ()))
|
||||
|
||||
async def run(
|
||||
self, role: RoleSpec, task: AgentTask, tools: Sequence[ToolSpec]
|
||||
) -> Outcome:
|
||||
queue = self._turns.get(role.name)
|
||||
if not queue:
|
||||
raise ScriptExhausted(f"No scripted turn left for role {role.name!r}")
|
||||
turn = queue.popleft()
|
||||
calls = turn(task) if callable(turn) else turn
|
||||
by_name = {tool.name: tool for tool in tools}
|
||||
|
||||
results: list[tuple[str, str]] = []
|
||||
outcome: Outcome = Stopped(
|
||||
"The script ended without a tool that ends the turn."
|
||||
)
|
||||
for index, call in enumerate(calls):
|
||||
if index >= role.budget:
|
||||
outcome = BudgetExhausted(
|
||||
f"{role.name} used all {role.budget} tool calls before finishing."
|
||||
)
|
||||
break
|
||||
if call.tool not in by_name:
|
||||
raise ValueError(
|
||||
f"{role.name} called {call.tool!r}, which it was not offered: "
|
||||
f"{sorted(by_name)}"
|
||||
)
|
||||
result = await by_name[call.tool].handler(**call.args)
|
||||
results.append((call.tool, result.message))
|
||||
if result.outcome is not None:
|
||||
outcome = result.outcome
|
||||
break
|
||||
|
||||
self.runs.append(
|
||||
RunRecord(role.name, task, tuple(by_name), tuple(results), outcome)
|
||||
)
|
||||
return outcome
|
||||
|
||||
|
||||
class FakeDecider:
|
||||
"""A scripted Decider: answers by question id, or declines so callers fall back.
|
||||
|
||||
`answers` maps a question id to an Answer, or to a function of (state, question)
|
||||
returning one. An id with no entry makes the whole decision unavailable.
|
||||
"""
|
||||
|
||||
def __init__(self, answers: Mapping[str, Any] | None = None) -> None:
|
||||
self.answers = dict(answers or {})
|
||||
self.asked: list[tuple[str, dict[str, Question], str]] = []
|
||||
|
||||
async def decide(
|
||||
self, state: str, questions: Mapping[str, Question], *, scope: str = ""
|
||||
) -> Mapping[str, Answer] | None:
|
||||
self.asked.append((state, dict(questions), scope))
|
||||
decided = {}
|
||||
for name, question in questions.items():
|
||||
if name not in self.answers:
|
||||
return None
|
||||
answer = self.answers[name]
|
||||
decided[name] = answer(state, question) if callable(answer) else answer
|
||||
return decided
|
||||
165
execution_engine/adk/roles.py
Normal file
165
execution_engine/adk/roles.py
Normal file
@@ -0,0 +1,165 @@
|
||||
"""Load role files (agents/<role>.md) into RoleSpecs for one Cloud provider.
|
||||
|
||||
Role files are framework- and provider-neutral: frontmatter names the role, the
|
||||
Deliverable it owns, the local tools it uses, an optional budget and shared partials to
|
||||
include. The provider bundle supplies each role's Skills, MCP servers and model.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import dataclasses
|
||||
from pathlib import Path
|
||||
|
||||
from execution_engine.adk.runtime import RoleSpec
|
||||
from execution_engine.providers import ProviderBundle
|
||||
from execution_engine.skills.agent_skills import SkillFormatError, split_frontmatter
|
||||
from execution_engine.workflows.workflow import Workflow
|
||||
|
||||
ORCHESTRATOR = "orchestrator"
|
||||
REPLY_WRITER = "reply-writer"
|
||||
LESSON_CURATOR = "lesson-curator" # runs outside any Execution
|
||||
PARTIALS_DIR = "partials"
|
||||
|
||||
_ALLOWED_FIELDS = {"role", "deliverable", "tools", "budget", "includes"}
|
||||
|
||||
|
||||
def _deliverables_with_lessons(bundle: ProviderBundle) -> set[str]:
|
||||
if not bundle.lessons_skill:
|
||||
return set()
|
||||
folder = bundle.skills[bundle.lessons_skill].path / "references"
|
||||
return {path.stem for path in folder.glob("*.md")} if folder.is_dir() else set()
|
||||
|
||||
|
||||
class RoleConfigError(ValueError):
|
||||
"""A role file is missing or invalid."""
|
||||
|
||||
|
||||
def load_roles(
|
||||
agents_dir: Path,
|
||||
bundle: ProviderBundle,
|
||||
workflow: Workflow,
|
||||
*,
|
||||
orchestrator_budget: int = 40,
|
||||
specialist_budget: int = 15,
|
||||
include_preview_mcp: bool = True,
|
||||
lessons: bool = True,
|
||||
model_tiers: bool = False,
|
||||
) -> dict[str, RoleSpec]:
|
||||
"""`lessons` off leaves the lessons Skill out of every role, so an evaluation
|
||||
can run with and without what has been learned. `model_tiers` on gives a role
|
||||
the lighter model the bundle names for its first attempt."""
|
||||
specialists = workflow.specialists()
|
||||
required = {ORCHESTRATOR, REPLY_WRITER, *specialists, *workflow.roles}
|
||||
optional = {LESSON_CURATOR, *workflow.optional_roles}
|
||||
learned = _deliverables_with_lessons(bundle) if lessons else set()
|
||||
|
||||
roles = {}
|
||||
for path in sorted(agents_dir.glob("*.md")):
|
||||
role = _load_role(
|
||||
path,
|
||||
agents_dir,
|
||||
bundle,
|
||||
specialists,
|
||||
orchestrator_budget if path.stem == ORCHESTRATOR else specialist_budget,
|
||||
include_preview_mcp,
|
||||
)
|
||||
roles[role.name] = role
|
||||
|
||||
missing = sorted(required - set(roles))
|
||||
if missing:
|
||||
raise RoleConfigError(
|
||||
f"{agents_dir}: missing role files for {', '.join(missing)}"
|
||||
)
|
||||
for name, kind in specialists.items():
|
||||
if kind in learned and bundle.lessons_skill:
|
||||
# Only a Specialist whose Deliverable has lessons is given the Skill.
|
||||
roles[name] = dataclasses.replace(
|
||||
roles[name], skills=(*roles[name].skills, bundle.lessons_skill)
|
||||
)
|
||||
if model_tiers:
|
||||
for name, model in bundle.models.first_attempt.items():
|
||||
if name not in roles:
|
||||
raise RoleConfigError(
|
||||
f"'models.first_attempt' names {name!r}, which is not a role"
|
||||
)
|
||||
roles[name] = dataclasses.replace(roles[name], first_attempt_model=model)
|
||||
if workflow.adjust_roles:
|
||||
roles = dict(workflow.adjust_roles(roles, bundle))
|
||||
unexpected = sorted(set(roles) - required - optional)
|
||||
if unexpected:
|
||||
raise RoleConfigError(
|
||||
f"{agents_dir}: unexpected role files {', '.join(unexpected)}"
|
||||
)
|
||||
return roles
|
||||
|
||||
|
||||
def _load_role(
|
||||
path: Path,
|
||||
agents_dir: Path,
|
||||
bundle: ProviderBundle,
|
||||
specialists: dict[str, str],
|
||||
default_budget: int,
|
||||
include_preview_mcp: bool,
|
||||
) -> RoleSpec:
|
||||
try:
|
||||
frontmatter, body = split_frontmatter(path.read_text(encoding="utf-8"), path)
|
||||
except SkillFormatError as exc:
|
||||
raise RoleConfigError(str(exc)) from exc
|
||||
|
||||
def fail(message: str) -> RoleConfigError:
|
||||
return RoleConfigError(f"{path}: {message}")
|
||||
|
||||
unknown = sorted(set(frontmatter) - _ALLOWED_FIELDS)
|
||||
if unknown:
|
||||
raise fail(
|
||||
f"unsupported fields {', '.join(unknown)}; skills, MCP servers and models "
|
||||
"come from the provider bundle"
|
||||
)
|
||||
|
||||
name = frontmatter.get("role")
|
||||
if name != path.stem:
|
||||
raise fail(f"'role' {name!r} must match the file name {path.stem!r}")
|
||||
|
||||
deliverable = frontmatter.get("deliverable")
|
||||
if name in specialists:
|
||||
expected = specialists[name]
|
||||
if deliverable != expected:
|
||||
raise fail(f"'deliverable' must be {expected!r}, not {deliverable!r}")
|
||||
elif deliverable is not None:
|
||||
raise fail(f"role {name!r} owns no Deliverable, but names {deliverable!r}")
|
||||
|
||||
tools = tuple(frontmatter.get("tools") or ())
|
||||
offered = {name for names in bundle.tools.values() for name in names}
|
||||
unknown_tools = [tool for tool in tools if tool not in offered]
|
||||
if unknown_tools:
|
||||
raise fail(
|
||||
f"'tools' {', '.join(unknown_tools)} are not offered by the "
|
||||
f"{bundle.name} provider bundle"
|
||||
)
|
||||
|
||||
budget = frontmatter.get("budget", default_budget)
|
||||
if not isinstance(budget, int) or budget < 1:
|
||||
raise fail("'budget' must be a positive integer")
|
||||
|
||||
sections = [body.strip()]
|
||||
for include in frontmatter.get("includes") or ():
|
||||
partial = agents_dir / PARTIALS_DIR / f"{include}.md"
|
||||
if not partial.is_file():
|
||||
raise fail(f"include {include!r} not found at {partial}")
|
||||
sections.append(partial.read_text(encoding="utf-8").strip())
|
||||
if not sections[0]:
|
||||
raise fail("instructions (the body after the frontmatter) must not be empty")
|
||||
|
||||
return RoleSpec(
|
||||
name=name,
|
||||
instructions="\n\n".join(sections),
|
||||
budget=budget,
|
||||
skills=tuple(bundle.role_skills.get(name, ())),
|
||||
tools=tools,
|
||||
mcp_servers=tuple(
|
||||
server.id
|
||||
for server in bundle.mcp_servers_for_role(name, include_preview_mcp)
|
||||
),
|
||||
model=bundle.models.for_role(name),
|
||||
model_timeout_seconds=bundle.models.timeout_for(name),
|
||||
)
|
||||
286
execution_engine/adk/runtime.py
Normal file
286
execution_engine/adk/runtime.py
Normal file
@@ -0,0 +1,286 @@
|
||||
"""The agent-runtime interface (ADR-0003).
|
||||
|
||||
Everything an Orchestrator or Specialist needs crosses this seam as plain data:
|
||||
a RoleSpec, an AgentTask and ToolSpecs in; an Outcome back. No framework types.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import contextvars
|
||||
from collections.abc import (
|
||||
AsyncIterator,
|
||||
Awaitable,
|
||||
Callable,
|
||||
Mapping,
|
||||
MutableMapping,
|
||||
Sequence,
|
||||
)
|
||||
from contextlib import asynccontextmanager
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any, Protocol
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class RoleSpec:
|
||||
"""One agent role, parsed from agents/<role>.md."""
|
||||
|
||||
name: str
|
||||
instructions: str
|
||||
budget: int
|
||||
skills: tuple[str, ...] = ()
|
||||
tools: tuple[str, ...] = () # local tool names, e.g. terraform_validate
|
||||
mcp_servers: tuple[str, ...] = ()
|
||||
model: str | None = None
|
||||
# Seconds one model request may take; None takes the runtime's default.
|
||||
model_timeout_seconds: float | None = None
|
||||
# A lighter model for the first attempt at a Deliverable, when the bundle
|
||||
# names one and model tiers are on (iteration 5 step 6).
|
||||
first_attempt_model: str | None = None
|
||||
# The Skill on published Terraform modules, for a role that may call them. It
|
||||
# is added to the role's Skills only in an Execution that opted into modules.
|
||||
modules_skill: str | None = None
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class AgentTask:
|
||||
"""What one run of an agent is asked to do, with the context it may use."""
|
||||
|
||||
role: str
|
||||
prompt: str
|
||||
context: Mapping[str, Any] = field(default_factory=dict)
|
||||
deliverable: str | None = None
|
||||
|
||||
|
||||
# --- outcomes ----------------------------------------------------------------------
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Submitted:
|
||||
"""A Specialist's contract-complete Deliverable."""
|
||||
|
||||
content: str
|
||||
attachments: Mapping[str, str] = field(default_factory=dict)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class NeedsInput:
|
||||
"""The agent can't continue without the user. `permission` names a tool tier to grant.
|
||||
|
||||
`draft` is work the agent wants back when it is started again with the answers.
|
||||
"""
|
||||
|
||||
questions: tuple[str, ...]
|
||||
permission: str | None = None
|
||||
draft: str | None = None
|
||||
draft_attachments: Mapping[str, str] = field(default_factory=dict)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class BudgetExhausted:
|
||||
summary: str
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Stopped:
|
||||
"""The agent stopped without calling a tool that ends its turn."""
|
||||
|
||||
message: str
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class TurnEnded:
|
||||
"""The Orchestrator ended its turn by calling `tool`; the tool recorded its effect."""
|
||||
|
||||
tool: str
|
||||
|
||||
|
||||
Outcome = Submitted | NeedsInput | BudgetExhausted | Stopped | TurnEnded
|
||||
|
||||
|
||||
# --- tools -------------------------------------------------------------------------
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ToolResult:
|
||||
"""What a tool returns to the agent. A non-None `outcome` ends the agent's run."""
|
||||
|
||||
message: str
|
||||
outcome: Outcome | None = None
|
||||
|
||||
|
||||
# Files cross tool calls as a list of {path, content}, never a map keyed by path:
|
||||
# models rewrite object keys (Gemini turns "main.tf" into "main_tf").
|
||||
FILES_SCHEMA: Mapping[str, Any] = {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"path": {
|
||||
"type": "string",
|
||||
"description": "Relative path, e.g. terraform/main.tf",
|
||||
},
|
||||
"content": {"type": "string"},
|
||||
},
|
||||
"required": ["path", "content"],
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def files_from_argument(value: Any) -> dict[str, str]:
|
||||
"""A FILES_SCHEMA argument as {path: content}. A {path: content} map is accepted too."""
|
||||
if not value:
|
||||
return {}
|
||||
if isinstance(value, Mapping):
|
||||
return {str(path): str(content) for path, content in value.items()}
|
||||
files: dict[str, str] = {}
|
||||
for item in value:
|
||||
if not isinstance(item, Mapping) or "path" not in item:
|
||||
raise TypeError("each file needs a 'path' and 'content'")
|
||||
files[str(item["path"])] = str(item.get("content", ""))
|
||||
return files
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ToolSpec:
|
||||
name: str
|
||||
description: str
|
||||
parameters: Mapping[str, Any] # JSON schema for the keyword arguments
|
||||
handler: Callable[..., Awaitable[ToolResult]]
|
||||
tier: str = "general" # general | cloud_read | execution
|
||||
|
||||
|
||||
# The tools a role gets beyond the Execution tools, given the Deliverable it is producing
|
||||
# and that Deliverable's working memory: JSON-compatible data a tool may read and write,
|
||||
# kept with the Execution across attempts.
|
||||
ToolFactory = Callable[
|
||||
[RoleSpec, str | None, MutableMapping[str, Any]], Sequence[ToolSpec]
|
||||
]
|
||||
|
||||
|
||||
class RunLimiter:
|
||||
"""Caps how many agent runs are in flight at once.
|
||||
|
||||
A run that fans out to further runs lends its slot while it waits, so the cap
|
||||
holds across the whole hierarchy and a cap of 1 cannot deadlock.
|
||||
"""
|
||||
|
||||
def __init__(self, limit: int) -> None:
|
||||
if limit < 1:
|
||||
raise ValueError("limit must be at least 1")
|
||||
self.limit = limit
|
||||
self._semaphore = asyncio.Semaphore(limit)
|
||||
self._holding: contextvars.ContextVar[bool] = contextvars.ContextVar(
|
||||
"run_limiter_holding", default=False
|
||||
)
|
||||
|
||||
@asynccontextmanager
|
||||
async def slot(self) -> AsyncIterator[None]:
|
||||
async with self._semaphore:
|
||||
token = self._holding.set(True)
|
||||
try:
|
||||
yield
|
||||
finally:
|
||||
self._holding.reset(token)
|
||||
|
||||
@asynccontextmanager
|
||||
async def lend(self) -> AsyncIterator[None]:
|
||||
"""Give up the caller's slot, if it holds one, while its own fan-out runs."""
|
||||
if not self._holding.get():
|
||||
yield
|
||||
return
|
||||
self._semaphore.release()
|
||||
token = self._holding.set(False)
|
||||
try:
|
||||
yield
|
||||
finally:
|
||||
self._holding.reset(token)
|
||||
await self._semaphore.acquire()
|
||||
|
||||
|
||||
# Tool replies that mean the call did nothing. Runtimes log them, and the Execution
|
||||
# keeps them as lesson candidates.
|
||||
REJECTION_PREFIXES = (
|
||||
"Not submitted",
|
||||
"Refused",
|
||||
"Discovery gap",
|
||||
"terraform validate failed",
|
||||
)
|
||||
|
||||
|
||||
# --- decisions -----------------------------------------------------------------------
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Question:
|
||||
"""A closed question about a state. Its answer is typed, never prose.
|
||||
|
||||
choice pick one of `options`
|
||||
score rate against `options`, ordered from lowest to highest
|
||||
noul yes or no; the answer is the probability that it is yes
|
||||
"""
|
||||
|
||||
kind: str # choice | score | noul
|
||||
instructions: str
|
||||
options: tuple[str, ...] = ()
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Answer:
|
||||
"""`value` is the chosen option (choice), the level reached (score, as a number
|
||||
from 0 for the lowest option) or the probability of yes (noul)."""
|
||||
|
||||
value: str | float
|
||||
confidence: float
|
||||
probabilities: Mapping[str, float] = field(default_factory=dict)
|
||||
|
||||
def is_yes(self, threshold: float = 0.5) -> bool:
|
||||
return isinstance(self.value, (int, float)) and self.value >= threshold
|
||||
|
||||
|
||||
class Decider(Protocol):
|
||||
"""Answers closed questions about a state (ADR-0007).
|
||||
|
||||
Returns None when no decision could be made: the service is not configured,
|
||||
unreachable, over its budget, or the request is too large. The caller then takes
|
||||
its fallback; a decider never blocks an Execution. `scope` names what a budget is
|
||||
counted against, usually the Execution.
|
||||
"""
|
||||
|
||||
async def decide(
|
||||
self, state: str, questions: Mapping[str, Question], *, scope: str = ""
|
||||
) -> Mapping[str, Answer] | None: ...
|
||||
|
||||
|
||||
class NoDecider:
|
||||
"""The decider when none is configured: every caller takes its fallback."""
|
||||
|
||||
async def decide(
|
||||
self, state: str, questions: Mapping[str, Question], *, scope: str = ""
|
||||
) -> Mapping[str, Answer] | None:
|
||||
return None
|
||||
|
||||
|
||||
class SubmissionReview(Protocol):
|
||||
"""A review of a submission's meaning, beyond what its structure shows.
|
||||
|
||||
Returns what it would have the Specialist look at again, one line each; empty
|
||||
when it has nothing to raise or could not decide. `kind` is the Deliverable's
|
||||
kind, `upstream` the Deliverables it builds on.
|
||||
"""
|
||||
|
||||
async def __call__(
|
||||
self,
|
||||
kind: Any,
|
||||
attachments: Mapping[str, str],
|
||||
upstream: Mapping[str, Mapping[str, Any]] | None,
|
||||
scope: str = "",
|
||||
) -> Sequence[str]: ...
|
||||
|
||||
|
||||
class AgentRuntime(Protocol):
|
||||
async def run(
|
||||
self, role: RoleSpec, task: AgentTask, tools: Sequence[ToolSpec]
|
||||
) -> Outcome:
|
||||
"""Run one ReAct loop until a tool ends the turn, the budget is spent, or it stops."""
|
||||
...
|
||||
Reference in New Issue
Block a user