449 lines
16 KiB
Python
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```"
|