This commit is contained in:
@@ -1,31 +1 @@
|
||||
"""ADK package for GCP Solution Architecture Agent."""
|
||||
|
||||
from .agents import (
|
||||
ArchitectureDesignAgent,
|
||||
DiscoveryAgent,
|
||||
OrchestratorLoopAgent,
|
||||
PackagingAgent,
|
||||
ValidationReviewAgent,
|
||||
build_adk_multi_agent_system,
|
||||
)
|
||||
from .artifacts import PostgresArtifactRepository
|
||||
from .evaluation import ADKEvaluator
|
||||
from .runners import ADKAgentRunner
|
||||
from .sessions import PostgresSessionService
|
||||
from .tools import ADK_TOOLS
|
||||
from .workflows import create_gcp_adk_workflow
|
||||
|
||||
__all__ = [
|
||||
"DiscoveryAgent",
|
||||
"ArchitectureDesignAgent",
|
||||
"ValidationReviewAgent",
|
||||
"PackagingAgent",
|
||||
"OrchestratorLoopAgent",
|
||||
"build_adk_multi_agent_system",
|
||||
"PostgresArtifactRepository",
|
||||
"PostgresSessionService",
|
||||
"ADKAgentRunner",
|
||||
"ADKEvaluator",
|
||||
"ADK_TOOLS",
|
||||
"create_gcp_adk_workflow",
|
||||
]
|
||||
"""Agent runtimes: the framework-neutral interface agents run behind, and its implementations."""
|
||||
|
||||
323
app/adk/adk_runtime.py
Normal file
323
app/adk/adk_runtime.py
Normal file
@@ -0,0 +1,323 @@
|
||||
"""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```"
|
||||
@@ -1,196 +0,0 @@
|
||||
"""ADK Multi-Agent Architecture for GCP Solution Architecture Agent.
|
||||
|
||||
Uses google.adk.agents primitives:
|
||||
- SourceDiscoveryAgent (LlmAgent)
|
||||
- DiscoveryAgent (LlmAgent)
|
||||
- ArchitectureDesignAgent (LlmAgent)
|
||||
- ValidationReviewAgent (LlmAgent)
|
||||
- PackagingAgent (LlmAgent)
|
||||
- OrchestratorLoopAgent (LoopAgent)
|
||||
"""
|
||||
|
||||
import logging
|
||||
import uuid
|
||||
from typing import Any, Dict, List, Optional
|
||||
|
||||
from app.adk.compat import BaseAgent, LlmAgent, LoopAgent, SequentialAgent
|
||||
from app.adk.tools import ADK_TOOLS
|
||||
from app.config import get_settings
|
||||
from app.database import get_db_manager
|
||||
from app.nodes import design_node, discover_node, package_node, source_discover_node, validate_node
|
||||
from app.skills.loader import SkillLoader
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class SourceDiscoveryAgent(LlmAgent):
|
||||
"""ADK Agent responsible for Phase 0a Pre-emptive Source Environment Discovery."""
|
||||
|
||||
def __init__(self, skill_loader: SkillLoader) -> None:
|
||||
super().__init__(
|
||||
name="SourceDiscoveryAgent",
|
||||
description="Audits and documents the pre-existing source environment (As-Is Architecture) before target migration.",
|
||||
instruction=skill_loader.format_skills_for_prompt("source_discover"),
|
||||
tools=[],
|
||||
)
|
||||
self.skill_loader = skill_loader
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
logger.info("Executing SourceDiscoveryAgent")
|
||||
res = source_discover_node(state, self.skill_loader)
|
||||
state_copy = dict(state)
|
||||
state_copy.update(res)
|
||||
return state_copy
|
||||
|
||||
|
||||
class DiscoveryAgent(LlmAgent):
|
||||
"""ADK Agent responsible for Phase 0 Requirements Discovery."""
|
||||
|
||||
def __init__(self, skill_loader: SkillLoader) -> None:
|
||||
super().__init__(
|
||||
name="DiscoveryAgent",
|
||||
description="Extracts functional and non-functional requirements with product selection deferred.",
|
||||
instruction=skill_loader.format_skills_for_prompt("discover"),
|
||||
tools=[],
|
||||
)
|
||||
self.skill_loader = skill_loader
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
logger.info("Executing DiscoveryAgent")
|
||||
res = discover_node(state, self.skill_loader)
|
||||
state_copy = dict(state)
|
||||
state_copy.update(res)
|
||||
return state_copy
|
||||
|
||||
|
||||
class ArchitectureDesignAgent(LlmAgent):
|
||||
"""ADK Agent responsible for Phase 1 Product Selection, Diagrams, & Terraform IaC."""
|
||||
|
||||
def __init__(self, skill_loader: SkillLoader) -> None:
|
||||
super().__init__(
|
||||
name="ArchitectureDesignAgent",
|
||||
description="Selects GCP products, generates Mermaid diagram, and produces Terraform IaC grounded by Developer Knowledge MCP.",
|
||||
instruction=skill_loader.format_skills_for_prompt("design"),
|
||||
tools=ADK_TOOLS,
|
||||
)
|
||||
self.skill_loader = skill_loader
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
logger.info("Executing ArchitectureDesignAgent")
|
||||
res = design_node(state, self.skill_loader)
|
||||
state_copy = dict(state)
|
||||
state_copy.update(res)
|
||||
return state_copy
|
||||
|
||||
|
||||
class ValidationReviewAgent(LlmAgent):
|
||||
"""ADK Agent responsible for Phase 2 Artifact Review & Quality Validation."""
|
||||
|
||||
def __init__(self, skill_loader: SkillLoader) -> None:
|
||||
super().__init__(
|
||||
name="ValidationReviewAgent",
|
||||
description="Validates Mermaid syntax, Terraform configuration, and required sections.",
|
||||
instruction=skill_loader.format_skills_for_prompt("validate"),
|
||||
tools=ADK_TOOLS,
|
||||
)
|
||||
self.skill_loader = skill_loader
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
logger.info("Executing ValidationReviewAgent")
|
||||
res = validate_node(state, self.skill_loader)
|
||||
state_copy = dict(state)
|
||||
state_copy.update(res)
|
||||
return state_copy
|
||||
|
||||
|
||||
class PackagingAgent(LlmAgent):
|
||||
"""ADK Agent responsible for Phase 3 Solution Guide Packaging."""
|
||||
|
||||
def __init__(self, skill_loader: SkillLoader) -> None:
|
||||
super().__init__(
|
||||
name="PackagingAgent",
|
||||
description="Packages final solution-architecture-guide.md.",
|
||||
instruction=skill_loader.format_skills_for_prompt("package"),
|
||||
tools=[],
|
||||
)
|
||||
self.skill_loader = skill_loader
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
logger.info("Executing PackagingAgent")
|
||||
res = package_node(state, self.skill_loader)
|
||||
state_copy = dict(state)
|
||||
state_copy.update(res)
|
||||
return state_copy
|
||||
|
||||
|
||||
class OrchestratorLoopAgent(LoopAgent):
|
||||
"""ADK Orchestrator LoopAgent that coordinates multi-agent execution & iterative quality review.
|
||||
|
||||
Uses google.adk.agents.LoopAgent to execute discovery -> design -> validation review -> packaging
|
||||
in a loop until validation passes 100% or max_iterations is reached. Writes every review iteration
|
||||
event to PostgreSQL database (`orchestrator_review_logs`).
|
||||
"""
|
||||
|
||||
def __init__(self, skill_loader: SkillLoader, max_iterations: Optional[int] = None) -> None:
|
||||
settings = get_settings()
|
||||
max_iters = max_iterations or settings.ADK_MAX_LOOP_ITERATIONS
|
||||
self.db_manager = get_db_manager()
|
||||
|
||||
self.source_discovery_agent = SourceDiscoveryAgent(skill_loader)
|
||||
self.discovery_agent = DiscoveryAgent(skill_loader)
|
||||
self.design_agent = ArchitectureDesignAgent(skill_loader)
|
||||
self.validation_agent = ValidationReviewAgent(skill_loader)
|
||||
self.packaging_agent = PackagingAgent(skill_loader)
|
||||
|
||||
sub_pipeline = SequentialAgent(
|
||||
name="MultiAgentGCPPipeline",
|
||||
sub_agents=[
|
||||
self.source_discovery_agent,
|
||||
self.discovery_agent,
|
||||
self.design_agent,
|
||||
self.validation_agent,
|
||||
self.packaging_agent,
|
||||
],
|
||||
description="Sequential pipeline of GCP architecture multi-agents.",
|
||||
)
|
||||
|
||||
def review_validator(state: Dict[str, Any]) -> bool:
|
||||
"""Check if solution meets production quality validation standards."""
|
||||
is_valid = state.get("validation_passed", False)
|
||||
errors = state.get("errors", [])
|
||||
iteration = state.get("loop_count", 1)
|
||||
execution_id = state.get("execution_id", str(uuid.uuid4()))
|
||||
|
||||
status_str = "APPROVED" if is_valid else "NEEDS_REVISION"
|
||||
feedback_str = "All architecture validation rules passed." if is_valid else f"Validation errors: {', '.join(errors)}"
|
||||
|
||||
# Record review iteration in PostgreSQL database
|
||||
self.db_manager.record_orchestrator_log(
|
||||
log_id=str(uuid.uuid4()),
|
||||
execution_id=execution_id,
|
||||
iteration=iteration,
|
||||
review_status=status_str,
|
||||
reviewer_agent="ValidationReviewAgent",
|
||||
feedback=feedback_str,
|
||||
)
|
||||
logger.info(
|
||||
"Orchestrator Review Loop #%d: status=%s, valid=%s",
|
||||
iteration,
|
||||
status_str,
|
||||
is_valid,
|
||||
)
|
||||
|
||||
return is_valid
|
||||
|
||||
super().__init__(
|
||||
name="OrchestratorLoopAgent",
|
||||
sub_agent=sub_pipeline,
|
||||
max_iterations=max_iters,
|
||||
description="Production-ready multi-agent orchestrator loop agent.",
|
||||
validator_fn=review_validator,
|
||||
)
|
||||
|
||||
|
||||
def build_adk_multi_agent_system(skill_loader: SkillLoader, max_iterations: Optional[int] = None) -> OrchestratorLoopAgent:
|
||||
"""Factory function for building the complete ADK Orchestrator LoopAgent system."""
|
||||
return OrchestratorLoopAgent(skill_loader, max_iterations=max_iterations)
|
||||
@@ -1,77 +0,0 @@
|
||||
"""ADK Artifact Management for GCP Solution Architecture Agent.
|
||||
|
||||
Uses google.adk.artifacts.ArtifactRepository backed by local filesystem and PostgreSQL persistence.
|
||||
"""
|
||||
|
||||
import logging
|
||||
from pathlib import Path
|
||||
from typing import Any, Dict, Optional, List
|
||||
|
||||
from app.adk.compat import Artifact, ArtifactRepository
|
||||
from app.database import get_db_manager
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class PostgresArtifactRepository(ArtifactRepository):
|
||||
"""ADK Artifact Repository with PostgreSQL database & filesystem synchronization."""
|
||||
|
||||
def __init__(self, base_dir: Optional[Path] = None) -> None:
|
||||
super().__init__()
|
||||
self.base_dir = base_dir or Path(".").resolve()
|
||||
self.db_manager = get_db_manager()
|
||||
|
||||
def save_solution_artifacts(self, execution_id: str, state: Dict[str, Any]) -> List[Artifact]:
|
||||
"""Write workflow execution output artifacts to disk and PostgreSQL database."""
|
||||
saved_artifacts: List[Artifact] = []
|
||||
|
||||
artifact_mapping = [
|
||||
# Structured scalable active deliverables
|
||||
("source_discovery_doc", "deliverables/as-is/source-architecture.md", "markdown"),
|
||||
("source_mermaid_diagram", "deliverables/as-is/source-architecture.mmd", "mermaid"),
|
||||
("requirements_doc", "deliverables/target/requirements.md", "markdown"),
|
||||
("architecture_doc", "deliverables/target/architecture.md", "markdown"),
|
||||
("mermaid_diagram", "deliverables/target/architecture.mmd", "mermaid"),
|
||||
("terraform_code", "terraform/main.tf", "hcl"),
|
||||
("validation_results", "deliverables/validation/validation-results.md", "markdown"),
|
||||
("solution_guide", "deliverables/guides/solution-architecture-guide.md", "markdown"),
|
||||
|
||||
# Per-execution isolated deliverables for scalable history tracking
|
||||
("source_discovery_doc", f"deliverables/executions/{execution_id}/as-is/source-architecture.md", "markdown"),
|
||||
("source_mermaid_diagram", f"deliverables/executions/{execution_id}/as-is/source-architecture.mmd", "mermaid"),
|
||||
("requirements_doc", f"deliverables/executions/{execution_id}/target/requirements.md", "markdown"),
|
||||
("architecture_doc", f"deliverables/executions/{execution_id}/target/architecture.md", "markdown"),
|
||||
("mermaid_diagram", f"deliverables/executions/{execution_id}/target/architecture.mmd", "mermaid"),
|
||||
("validation_results", f"deliverables/executions/{execution_id}/validation/validation-results.md", "markdown"),
|
||||
("solution_guide", f"deliverables/executions/{execution_id}/guides/solution-architecture-guide.md", "markdown"),
|
||||
|
||||
# Mirror docs for specification compatibility
|
||||
("source_discovery_doc", "docs/source-architecture.md", "markdown"),
|
||||
("requirements_doc", "docs/requirements.md", "markdown"),
|
||||
("architecture_doc", "docs/architecture.md", "markdown"),
|
||||
]
|
||||
|
||||
for state_key, rel_path, art_type in artifact_mapping:
|
||||
content = state.get(state_key)
|
||||
if not content:
|
||||
continue
|
||||
|
||||
full_path = self.base_dir / rel_path
|
||||
full_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
full_path.write_text(content, encoding="utf-8")
|
||||
|
||||
# Save in ADK memory store
|
||||
art = self.save_artifact(art_type, str(rel_path), content)
|
||||
saved_artifacts.append(art)
|
||||
|
||||
# Persist to PostgreSQL database
|
||||
self.db_manager.save_artifact(
|
||||
artifact_id=art.artifact_id,
|
||||
execution_id=execution_id,
|
||||
artifact_type=art_type,
|
||||
file_path=str(rel_path),
|
||||
content=content,
|
||||
)
|
||||
logger.info("Persisted ADK artifact '%s' (%s) to DB and %s", art_type, art.artifact_id, rel_path)
|
||||
|
||||
return saved_artifacts
|
||||
@@ -1,288 +0,0 @@
|
||||
"""Google ADK (Agent Development Kit) Compatibility & Abstraction Layer.
|
||||
|
||||
Re-exports native `google.adk` framework components when available, or provides
|
||||
fully functional compatibility stubs matching ADK interfaces for:
|
||||
- google.adk.agents (Agent, LlmAgent, SequentialAgent, ParallelAgent, LoopAgent)
|
||||
- google.adk.workflows (Workflow, WorkflowStep)
|
||||
- google.adk.runners (Runner)
|
||||
- google.adk.sessions (Session, SessionService, InMemorySessionService, PostgresSessionService)
|
||||
- google.adk.artifacts (Artifact, ArtifactRepository)
|
||||
- google.adk.tools (Tool, FunctionTool)
|
||||
- google.adk.evaluation (Evaluator, BenchmarkRunner)
|
||||
"""
|
||||
|
||||
import logging
|
||||
import uuid
|
||||
from typing import Any, Callable, Dict, List, Optional
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# Attempt importing native google.adk modules
|
||||
HAS_NATIVE_ADK = False
|
||||
|
||||
try:
|
||||
import google.adk.agents as _native_agents
|
||||
import google.adk.workflows as _native_workflows
|
||||
import google.adk.runners as _native_runners
|
||||
import google.adk.sessions as _native_sessions
|
||||
import google.adk.artifacts as _native_artifacts
|
||||
import google.adk.tools as _native_tools
|
||||
import google.adk.evaluation as _native_evaluation
|
||||
|
||||
HAS_NATIVE_ADK = True
|
||||
logger.info("Successfully imported native google.adk framework modules.")
|
||||
except ImportError:
|
||||
HAS_NATIVE_ADK = False
|
||||
logger.info("Native google.adk not installed; using ADK framework compatibility layer.")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 1. google.adk.agents
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class BaseAgent:
|
||||
"""Base class for ADK Agents."""
|
||||
|
||||
def __init__(self, name: str, description: str = "", instruction: str = "", tools: Optional[List[Any]] = None) -> None:
|
||||
self.name = name
|
||||
self.description = description
|
||||
self.instruction = instruction
|
||||
self.tools = tools or []
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
"""Execute agent logic against state."""
|
||||
return state
|
||||
|
||||
|
||||
class LlmAgent(BaseAgent):
|
||||
"""ADK LLM Agent primitive."""
|
||||
|
||||
def __init__(self, name: str, description: str = "", instruction: str = "", model: Any = None, tools: Optional[List[Any]] = None) -> None:
|
||||
super().__init__(name, description, instruction, tools)
|
||||
self.model = model
|
||||
|
||||
|
||||
class SequentialAgent(BaseAgent):
|
||||
"""ADK Sequential Workflow Agent."""
|
||||
|
||||
def __init__(self, name: str, sub_agents: List[BaseAgent], description: str = "") -> None:
|
||||
super().__init__(name, description)
|
||||
self.sub_agents = sub_agents
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
curr_state = dict(state)
|
||||
for agent in self.sub_agents:
|
||||
curr_state = agent.execute(curr_state)
|
||||
return curr_state
|
||||
|
||||
|
||||
class ParallelAgent(BaseAgent):
|
||||
"""ADK Parallel Workflow Agent."""
|
||||
|
||||
def __init__(self, name: str, sub_agents: List[BaseAgent], description: str = "") -> None:
|
||||
super().__init__(name, description)
|
||||
self.sub_agents = sub_agents
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
curr_state = dict(state)
|
||||
for agent in self.sub_agents:
|
||||
res = agent.execute(curr_state)
|
||||
curr_state.update(res)
|
||||
return curr_state
|
||||
|
||||
|
||||
class LoopAgent(BaseAgent):
|
||||
"""ADK Loop Agent for iterative review and validation feedback cycles."""
|
||||
|
||||
def __init__(self, name: str, sub_agent: BaseAgent, max_iterations: int = 5, description: str = "", validator_fn: Optional[Callable[[Dict[str, Any]], bool]] = None) -> None:
|
||||
super().__init__(name, description)
|
||||
self.sub_agent = sub_agent
|
||||
self.max_iterations = max_iterations
|
||||
self.validator_fn = validator_fn
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
curr_state = dict(state)
|
||||
loop_count = 0
|
||||
while loop_count < self.max_iterations:
|
||||
loop_count += 1
|
||||
curr_state["loop_count"] = loop_count
|
||||
curr_state = self.sub_agent.execute(curr_state)
|
||||
if self.validator_fn and self.validator_fn(curr_state):
|
||||
curr_state["loop_completed_successfully"] = True
|
||||
break
|
||||
curr_state["total_loop_iterations"] = loop_count
|
||||
return curr_state
|
||||
|
||||
|
||||
# Alias Agent to LlmAgent / BaseAgent
|
||||
Agent = LlmAgent
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2. google.adk.tools
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class Tool:
|
||||
"""ADK Tool Interface."""
|
||||
|
||||
def __init__(self, name: str, description: str, func: Callable) -> None:
|
||||
self.name = name
|
||||
self.description = description
|
||||
self.func = func
|
||||
|
||||
def run(self, *args, **kwargs) -> Any:
|
||||
return self.func(*args, **kwargs)
|
||||
|
||||
|
||||
class FunctionTool(Tool):
|
||||
"""ADK Function Tool primitive."""
|
||||
|
||||
@classmethod
|
||||
def from_defaults(cls, fn: Callable, name: Optional[str] = None, description: Optional[str] = None) -> "FunctionTool":
|
||||
tool_name = name or fn.__name__
|
||||
tool_desc = description or (fn.__doc__ or "")
|
||||
return cls(name=tool_name, description=tool_desc, func=fn)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 3. google.adk.artifacts
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class Artifact:
|
||||
"""ADK Artifact container."""
|
||||
|
||||
def __init__(self, artifact_id: str, artifact_type: str, file_path: str, content: str) -> None:
|
||||
self.artifact_id = artifact_id
|
||||
self.artifact_type = artifact_type
|
||||
self.file_path = file_path
|
||||
self.content = content
|
||||
|
||||
|
||||
class ArtifactRepository:
|
||||
"""ADK Artifact Repository interface."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self._store: Dict[str, Artifact] = {}
|
||||
|
||||
def save_artifact(self, artifact_type: str, file_path: str, content: str) -> Artifact:
|
||||
artifact_id = str(uuid.uuid4())
|
||||
art = Artifact(artifact_id, artifact_type, file_path, content)
|
||||
self._store[artifact_id] = art
|
||||
return art
|
||||
|
||||
def get_artifact(self, artifact_id: str) -> Optional[Artifact]:
|
||||
return self._store.get(artifact_id)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 4. google.adk.sessions
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class Session:
|
||||
"""ADK Session object."""
|
||||
|
||||
def __init__(self, session_id: str, agent_name: str, state: Optional[Dict[str, Any]] = None) -> None:
|
||||
self.session_id = session_id
|
||||
self.agent_name = agent_name
|
||||
self.state = state or {}
|
||||
|
||||
|
||||
class SessionService:
|
||||
"""ADK Session Service interface."""
|
||||
|
||||
def create_session(self, agent_name: str, session_id: Optional[str] = None) -> Session:
|
||||
sid = session_id or str(uuid.uuid4())
|
||||
return Session(sid, agent_name)
|
||||
|
||||
def get_session(self, session_id: str) -> Optional[Session]:
|
||||
raise NotImplementedError
|
||||
|
||||
def save_session(self, session: Session) -> bool:
|
||||
raise NotImplementedError
|
||||
|
||||
|
||||
class InMemorySessionService(SessionService):
|
||||
"""In-memory ADK Session Service."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self._sessions: Dict[str, Session] = {}
|
||||
|
||||
def create_session(self, agent_name: str, session_id: Optional[str] = None) -> Session:
|
||||
sid = session_id or str(uuid.uuid4())
|
||||
sess = Session(sid, agent_name)
|
||||
self._sessions[sid] = sess
|
||||
return sess
|
||||
|
||||
def get_session(self, session_id: str) -> Optional[Session]:
|
||||
return self._sessions.get(session_id)
|
||||
|
||||
def save_session(self, session: Session) -> bool:
|
||||
self._sessions[session.session_id] = session
|
||||
return True
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 5. google.adk.runners
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class Runner:
|
||||
"""ADK Runner for executing agents and workflows."""
|
||||
|
||||
def __init__(self, agent: BaseAgent, session_service: Optional[SessionService] = None) -> None:
|
||||
self.agent = agent
|
||||
self.session_service = session_service or InMemorySessionService()
|
||||
|
||||
def run(self, session_id: str, input_state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
session = self.session_service.get_session(session_id)
|
||||
if not session:
|
||||
session = self.session_service.create_session(self.agent.name, session_id)
|
||||
|
||||
merged_state = {**session.state, **input_state}
|
||||
result_state = self.agent.execute(merged_state)
|
||||
session.state = result_state
|
||||
self.session_service.save_session(session)
|
||||
return result_state
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 6. google.adk.workflows
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class WorkflowStep:
|
||||
"""ADK Workflow Step."""
|
||||
|
||||
def __init__(self, step_name: str, agent: BaseAgent) -> None:
|
||||
self.step_name = step_name
|
||||
self.agent = agent
|
||||
|
||||
|
||||
class Workflow:
|
||||
"""ADK Workflow composition container."""
|
||||
|
||||
def __init__(self, name: str, steps: List[WorkflowStep]) -> None:
|
||||
self.name = name
|
||||
self.steps = steps
|
||||
|
||||
def execute(self, initial_state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
state = dict(initial_state)
|
||||
for step in self.steps:
|
||||
state = step.agent.execute(state)
|
||||
return state
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 7. google.adk.evaluation
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class Evaluator:
|
||||
"""ADK Benchmark Evaluator."""
|
||||
|
||||
def evaluate(self, agent: BaseAgent, test_case: Dict[str, Any]) -> Dict[str, Any]:
|
||||
initial_state = test_case.get("input_state", {})
|
||||
result = agent.execute(initial_state)
|
||||
return {
|
||||
"case_id": test_case.get("case_id", "default"),
|
||||
"result_state": result,
|
||||
"passed": True,
|
||||
"score": 1.0,
|
||||
}
|
||||
@@ -1,57 +0,0 @@
|
||||
"""ADK Evaluation module for GCP Solution Architecture Agent.
|
||||
|
||||
Uses google.adk.evaluation.Evaluator with PostgreSQL database persistence.
|
||||
"""
|
||||
|
||||
import logging
|
||||
import uuid
|
||||
from typing import Any, Dict, List, Optional
|
||||
|
||||
from app.adk.compat import Evaluator
|
||||
from app.adk.runners import ADKAgentRunner
|
||||
from app.database import get_db_manager
|
||||
from eval.metrics import evaluate_case_run
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class ADKEvaluator(Evaluator):
|
||||
"""ADK Evaluator persisting evaluation results to PostgreSQL."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
super().__init__()
|
||||
self.runner = ADKAgentRunner()
|
||||
self.db_manager = get_db_manager()
|
||||
|
||||
def evaluate_benchmark_case(self, case: Dict[str, Any]) -> Dict[str, Any]:
|
||||
"""Execute and score benchmark case via ADK runner and record to PostgreSQL."""
|
||||
eval_id = str(uuid.uuid4())
|
||||
case_id = case.get("id", "case-unknown")
|
||||
req_summary = case.get("workflow_request", "")
|
||||
|
||||
run_res = self.runner.run_execution(request_summary=req_summary)
|
||||
artifacts = run_res.get("artifacts", {})
|
||||
|
||||
state_for_metrics = {
|
||||
"requirements_doc": artifacts.get("requirements_doc", ""),
|
||||
"architecture_doc": artifacts.get("architecture_doc", ""),
|
||||
"mermaid_diagram": artifacts.get("mermaid_diagram", ""),
|
||||
"terraform_code": artifacts.get("terraform_code", ""),
|
||||
"solution_guide": artifacts.get("solution_guide", ""),
|
||||
}
|
||||
|
||||
eval_result = evaluate_case_run(state_for_metrics, case)
|
||||
|
||||
# Save evaluation to PostgreSQL database
|
||||
self.db_manager.save_evaluation(
|
||||
eval_id=eval_id,
|
||||
case_id=case_id,
|
||||
total_score=eval_result["total_score"],
|
||||
max_score=eval_result["max_score"],
|
||||
pass_rate=eval_result["percentage"],
|
||||
passed=eval_result["passed"],
|
||||
details=eval_result,
|
||||
)
|
||||
|
||||
logger.info("Recorded ADK evaluation %s for case %s (Score: %.1f%%)", eval_id, case_id, eval_result["percentage"])
|
||||
return eval_result
|
||||
89
app/adk/fake_runtime.py
Normal file
89
app/adk/fake_runtime.py
Normal file
@@ -0,0 +1,89 @@
|
||||
"""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 app.adk.runtime import (
|
||||
AgentTask,
|
||||
BudgetExhausted,
|
||||
Outcome,
|
||||
RoleSpec,
|
||||
Stopped,
|
||||
ToolSpec,
|
||||
)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Call:
|
||||
tool: str
|
||||
args: Mapping[str, Any] = field(default_factory=dict)
|
||||
|
||||
|
||||
Turn = Sequence[Call] | Callable[[AgentTask], Sequence[Call]]
|
||||
|
||||
|
||||
@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
|
||||
132
app/adk/roles.py
Normal file
132
app/adk/roles.py
Normal file
@@ -0,0 +1,132 @@
|
||||
"""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
|
||||
|
||||
from pathlib import Path
|
||||
|
||||
from app.adk.runtime import RoleSpec
|
||||
from app.providers import ProviderBundle
|
||||
from app.skills.agent_skills import SkillFormatError, split_frontmatter
|
||||
from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind
|
||||
|
||||
ORCHESTRATOR = "orchestrator"
|
||||
PILLAR_ADVISOR = "pillar-advisor"
|
||||
PARTIALS_DIR = "partials"
|
||||
|
||||
_ALLOWED_FIELDS = {"role", "deliverable", "tools", "budget", "includes"}
|
||||
|
||||
|
||||
class RoleConfigError(ValueError):
|
||||
"""A role file is missing or invalid."""
|
||||
|
||||
|
||||
def load_roles(
|
||||
agents_dir: Path,
|
||||
bundle: ProviderBundle,
|
||||
*,
|
||||
orchestrator_budget: int = 40,
|
||||
specialist_budget: int = 15,
|
||||
include_preview_mcp: bool = True,
|
||||
) -> dict[str, RoleSpec]:
|
||||
specialists = {spec.specialist: kind for kind, spec in DEPENDENCY_GRAPH.items()}
|
||||
required = {ORCHESTRATOR, PILLAR_ADVISOR, *specialists}
|
||||
|
||||
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)}"
|
||||
)
|
||||
unexpected = sorted(set(roles) - required)
|
||||
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, DeliverableKind],
|
||||
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].value
|
||||
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),
|
||||
)
|
||||
@@ -1,93 +0,0 @@
|
||||
"""ADK Execution Runner for GCP Solution Architecture Agent.
|
||||
|
||||
Uses google.adk.runners.Runner integrated with PostgresSessionService,
|
||||
PostgresArtifactRepository, and PostgreSQL database state updates.
|
||||
"""
|
||||
|
||||
import logging
|
||||
import uuid
|
||||
from typing import Any, Dict, Optional
|
||||
|
||||
from app.adk.agents import build_adk_multi_agent_system
|
||||
from app.adk.artifacts import PostgresArtifactRepository
|
||||
from app.adk.compat import Runner
|
||||
from app.adk.sessions import PostgresSessionService
|
||||
from app.config import get_settings
|
||||
from app.database import get_db_manager
|
||||
from app.skills.loader import SkillLoader
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class ADKAgentRunner:
|
||||
"""Production-ready ADK Execution Runner."""
|
||||
|
||||
def __init__(self, skill_loader: SkillLoader | None = None) -> None:
|
||||
settings = get_settings()
|
||||
self.skill_loader = skill_loader or SkillLoader(settings.SKILLS_DIR)
|
||||
self.skill_loader.load_skills()
|
||||
|
||||
self.session_service = PostgresSessionService()
|
||||
self.artifact_repo = PostgresArtifactRepository(settings.BASE_DIR)
|
||||
self.db_manager = get_db_manager()
|
||||
|
||||
self.orchestrator = build_adk_multi_agent_system(
|
||||
self.skill_loader,
|
||||
max_iterations=settings.ADK_MAX_LOOP_ITERATIONS,
|
||||
)
|
||||
self.runner = Runner(agent=self.orchestrator, session_service=self.session_service)
|
||||
|
||||
def run_execution(self, session_id: Optional[str] = None, request_summary: str = "", target_dir: str = ".") -> Dict[str, Any]:
|
||||
"""Execute multi-agent workflow using ADK runner with PostgreSQL state persistence."""
|
||||
sid = session_id or str(uuid.uuid4())
|
||||
execution_id = str(uuid.uuid4())
|
||||
|
||||
initial_input = {
|
||||
"execution_id": execution_id,
|
||||
"workflow_request": request_summary or "Event-driven regional HTTP application reference architecture",
|
||||
"target_dir": target_dir,
|
||||
"active_skills": [],
|
||||
}
|
||||
|
||||
logger.info("Starting ADK runner execution %s for session %s", execution_id, sid)
|
||||
|
||||
# Run through ADK Runner
|
||||
result_state = self.runner.run(session_id=sid, input_state=initial_input)
|
||||
|
||||
# Save artifacts to disk & PostgreSQL database
|
||||
saved_artifacts = self.artifact_repo.save_solution_artifacts(execution_id, result_state)
|
||||
|
||||
# Record execution in PostgreSQL database
|
||||
self.db_manager.save_workflow_execution(
|
||||
execution_id=execution_id,
|
||||
session_id=sid,
|
||||
status="completed" if result_state.get("validation_passed") else "failed",
|
||||
current_phase=result_state.get("current_phase", "package"),
|
||||
loop_count=result_state.get("total_loop_iterations", 1),
|
||||
request_summary=request_summary,
|
||||
results={
|
||||
"validation_passed": result_state.get("validation_passed", False),
|
||||
"active_skills": result_state.get("active_skills", []),
|
||||
"artifacts_saved": len(saved_artifacts),
|
||||
},
|
||||
)
|
||||
|
||||
return {
|
||||
"execution_id": execution_id,
|
||||
"session_id": sid,
|
||||
"status": "success" if result_state.get("validation_passed") else "completed_with_warnings",
|
||||
"validation_passed": result_state.get("validation_passed", False),
|
||||
"total_loop_iterations": result_state.get("total_loop_iterations", 1),
|
||||
"current_phase": result_state.get("current_phase", "package"),
|
||||
"artifacts": {
|
||||
"source_discovery_doc": result_state.get("source_discovery_doc"),
|
||||
"source_mermaid_diagram": result_state.get("source_mermaid_diagram"),
|
||||
"requirements_doc": result_state.get("requirements_doc"),
|
||||
"architecture_doc": result_state.get("architecture_doc"),
|
||||
"mermaid_diagram": result_state.get("mermaid_diagram"),
|
||||
"terraform_code": result_state.get("terraform_code"),
|
||||
"validation_results": result_state.get("validation_results"),
|
||||
"solution_guide": result_state.get("solution_guide"),
|
||||
},
|
||||
"active_skills": result_state.get("active_skills", []),
|
||||
}
|
||||
139
app/adk/runtime.py
Normal file
139
app/adk/runtime.py
Normal file
@@ -0,0 +1,139 @@
|
||||
"""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
|
||||
|
||||
from collections.abc import Awaitable, Callable, Mapping, Sequence
|
||||
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
|
||||
|
||||
|
||||
@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."""
|
||||
|
||||
questions: tuple[str, ...]
|
||||
permission: str | None = None
|
||||
|
||||
|
||||
@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.
|
||||
ToolFactory = Callable[[RoleSpec, str | None], Sequence[ToolSpec]]
|
||||
|
||||
|
||||
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."""
|
||||
...
|
||||
@@ -1,56 +0,0 @@
|
||||
"""ADK Postgres Session Service for GCP Solution Architecture Agent.
|
||||
|
||||
Uses google.adk.sessions.SessionService backed by external PostgreSQL database.
|
||||
"""
|
||||
|
||||
import logging
|
||||
import uuid
|
||||
from typing import Any, Dict, Optional
|
||||
|
||||
from app.adk.compat import Session, SessionService
|
||||
from app.database import get_db_manager
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class PostgresSessionService(SessionService):
|
||||
"""ADK Session Service persisting state to PostgreSQL."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self.db_manager = get_db_manager()
|
||||
|
||||
def create_session(self, agent_name: str, session_id: Optional[str] = None) -> Session:
|
||||
"""Create a new session record in PostgreSQL database."""
|
||||
sid = session_id or str(uuid.uuid4())
|
||||
session = Session(session_id=sid, agent_name=agent_name, state={})
|
||||
self.db_manager.save_session(
|
||||
session_id=sid,
|
||||
agent_name=agent_name,
|
||||
state_data=session.state,
|
||||
metadata={"created_via": "PostgresSessionService"},
|
||||
)
|
||||
logger.info("Created ADK session %s in PostgreSQL database.", sid)
|
||||
return session
|
||||
|
||||
def get_session(self, session_id: str) -> Optional[Session]:
|
||||
"""Fetch session state from PostgreSQL database."""
|
||||
sess_data = self.db_manager.get_session(session_id)
|
||||
if not sess_data:
|
||||
return None
|
||||
|
||||
return Session(
|
||||
session_id=sess_data["session_id"],
|
||||
agent_name=sess_data["agent_name"],
|
||||
state=sess_data.get("state_data", {}),
|
||||
)
|
||||
|
||||
def save_session(self, session: Session) -> bool:
|
||||
"""Update session state in PostgreSQL database."""
|
||||
success = self.db_manager.save_session(
|
||||
session_id=session.session_id,
|
||||
agent_name=session.agent_name,
|
||||
state_data=session.state,
|
||||
)
|
||||
if success:
|
||||
logger.info("Updated ADK session %s in PostgreSQL database.", session.session_id)
|
||||
return success
|
||||
@@ -1,64 +0,0 @@
|
||||
"""ADK FunctionTool Wrappers for GCP Solution Architecture Agent.
|
||||
|
||||
Uses google.adk.tools.FunctionTool primitives.
|
||||
"""
|
||||
|
||||
from typing import Any, Dict
|
||||
from app.adk.compat import FunctionTool
|
||||
from app.tools.mcp_developer_knowledge import (
|
||||
developerknowledge_answer_query as _mcp_answer,
|
||||
developerknowledge_get_documents as _mcp_get,
|
||||
developerknowledge_search_documents as _mcp_search,
|
||||
)
|
||||
from app.tools.validation_tools import (
|
||||
validate_mermaid_diagram as _validate_mermaid,
|
||||
validate_repository_artifacts as _validate_repo,
|
||||
validate_terraform_syntax as _validate_terraform,
|
||||
)
|
||||
|
||||
# Convert validation functions to ADK FunctionTools
|
||||
mermaid_tool = FunctionTool.from_defaults(
|
||||
fn=_validate_mermaid.func if hasattr(_validate_mermaid, "func") else _validate_mermaid,
|
||||
name="validate_mermaid_diagram",
|
||||
description="Validates syntax and graph directives of a Mermaid diagram.",
|
||||
)
|
||||
|
||||
terraform_tool = FunctionTool.from_defaults(
|
||||
fn=_validate_terraform.func if hasattr(_validate_terraform, "func") else _validate_terraform,
|
||||
name="validate_terraform_syntax",
|
||||
description="Validates Terraform HCL basic structure and required Google Cloud resources.",
|
||||
)
|
||||
|
||||
repo_artifacts_tool = FunctionTool.from_defaults(
|
||||
fn=_validate_repo.func if hasattr(_validate_repo, "func") else _validate_repo,
|
||||
name="validate_repository_artifacts",
|
||||
description="Validates offline file existence and required section headings across repository artifacts.",
|
||||
)
|
||||
|
||||
# Convert Developer Knowledge MCP tools to ADK FunctionTools
|
||||
mcp_search_tool = FunctionTool.from_defaults(
|
||||
fn=_mcp_search.func if hasattr(_mcp_search, "func") else _mcp_search,
|
||||
name="developerknowledge_search_documents",
|
||||
description="Searches Google Cloud reference architecture, decision-making, and best-practice documents.",
|
||||
)
|
||||
|
||||
mcp_get_tool = FunctionTool.from_defaults(
|
||||
fn=_mcp_get.func if hasattr(_mcp_get, "func") else _mcp_get,
|
||||
name="developerknowledge_get_documents",
|
||||
description="Retrieves official Google Cloud document content and citations by URI.",
|
||||
)
|
||||
|
||||
mcp_answer_tool = FunctionTool.from_defaults(
|
||||
fn=_mcp_answer.func if hasattr(_mcp_answer, "func") else _mcp_answer,
|
||||
name="developerknowledge_answer_query",
|
||||
description="Answers architectural questions and checks GCP product release statuses and best practices.",
|
||||
)
|
||||
|
||||
ADK_TOOLS = [
|
||||
mermaid_tool,
|
||||
terraform_tool,
|
||||
repo_artifacts_tool,
|
||||
mcp_search_tool,
|
||||
mcp_get_tool,
|
||||
mcp_answer_tool,
|
||||
]
|
||||
@@ -1,20 +0,0 @@
|
||||
"""ADK Workflows module for GCP Solution Architecture Agent.
|
||||
|
||||
Uses google.adk.workflows.Workflow and google.adk.workflows.WorkflowStep primitives.
|
||||
"""
|
||||
|
||||
from typing import Any, Dict, List
|
||||
from app.adk.agents import OrchestratorLoopAgent
|
||||
from app.adk.compat import Workflow, WorkflowStep
|
||||
from app.skills.loader import SkillLoader
|
||||
|
||||
|
||||
def create_gcp_adk_workflow(skill_loader: SkillLoader, max_iterations: int = 5) -> Workflow:
|
||||
"""Compose the multi-agent ADK workflow."""
|
||||
orchestrator = OrchestratorLoopAgent(skill_loader, max_iterations=max_iterations)
|
||||
step = WorkflowStep(step_name="OrchestratorReviewLoopStep", agent=orchestrator)
|
||||
|
||||
return Workflow(
|
||||
name="GCP_Solution_Architecture_Workflow",
|
||||
steps=[step],
|
||||
)
|
||||
Reference in New Issue
Block a user