"""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 ( 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/` 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(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) 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, 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 _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```"