Files
gcp_solution_architecture_a…/app/adk/adk_runtime.py
Jonathan Boniface 7ee49ab352
Some checks failed
validation / verify (push) Failing after 10s
latest refactoring
2026-10-06 20:22:37 +01:00

324 lines
12 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 app.adk.runtime import (
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."
)
# Tool replies that mean the call did nothing, logged so stuck agents can be diagnosed.
REJECTION_PREFIXES = (
"Not submitted",
"Refused",
"Discovery gap",
"terraform validate failed",
)
# 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_VERTEXAI=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 _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] = {}
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(),
)
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)
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)
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) -> types.GenerateContentConfig | None:
if self._model_timeout_seconds is None:
return None
return types.GenerateContentConfig(
http_options=types.HttpOptions(
timeout=int(self._model_timeout_seconds * 1000)
)
)
def _agent_name(role: str) -> str:
return re.sub(r"\W", "_", role)
def _render_task(task: AgentTask, skills: Sequence[str] = ()) -> str:
context = json.dumps(task.context, indent=2, 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```"