Files
orchestration_engine/execution_engine/adk/adk_runtime.py

449 lines
16 KiB
Python

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