Files
gcp_solution_architecture_a…/app/adk/runtime.py
Jonathan Boniface e9246828b3 feat: establish the Target architecture as a graph before code
Design is now approved before any infrastructure code is written (ADR-0005).
A new target-architect Specialist produces one graph of Elements,
Relationships and Checks; the diagram is rendered from it, deployment
guidance must account for every Check, and validation gives a verdict per
Check. Requirements, components, products and recommendations carry ids in
data files, and a submission with a gap in the Requirements chain is refused.

Also in this commit:
- Customer cases group Executions, with an intent history per case
- lesson candidates are captured when an Execution ends
- evaluation gains chain, verdict, judged and interactive checks, and
  per-case thresholds
- Terraform providers are cached between checks
- the requirements analyst proposes defaults instead of asking
- the legacy-baseline case and the checks that only read it are removed
- ADR-0006 (Change requests) accepted; ADR-0004 and ADR-0007 proposed
- plans for iterations 4 to 7 under .agents/plans/

Unproven with a real model: no evaluation run has completed on this design.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 13:59:09 +01:00

209 lines
5.8 KiB
Python

"""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
import asyncio
import contextvars
from collections.abc import (
AsyncIterator,
Awaitable,
Callable,
Mapping,
MutableMapping,
Sequence,
)
from contextlib import asynccontextmanager
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.
`draft` is work the agent wants back when it is started again with the answers.
"""
questions: tuple[str, ...]
permission: str | None = None
draft: str | None = None
draft_attachments: Mapping[str, str] = field(default_factory=dict)
@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
# and that Deliverable's working memory: JSON-compatible data a tool may read and write,
# kept with the Execution across attempts.
ToolFactory = Callable[
[RoleSpec, str | None, MutableMapping[str, Any]], Sequence[ToolSpec]
]
class RunLimiter:
"""Caps how many agent runs are in flight at once.
A run that fans out to further runs lends its slot while it waits, so the cap
holds across the whole hierarchy and a cap of 1 cannot deadlock.
"""
def __init__(self, limit: int) -> None:
if limit < 1:
raise ValueError("limit must be at least 1")
self.limit = limit
self._semaphore = asyncio.Semaphore(limit)
self._holding: contextvars.ContextVar[bool] = contextvars.ContextVar(
"run_limiter_holding", default=False
)
@asynccontextmanager
async def slot(self) -> AsyncIterator[None]:
async with self._semaphore:
token = self._holding.set(True)
try:
yield
finally:
self._holding.reset(token)
@asynccontextmanager
async def lend(self) -> AsyncIterator[None]:
"""Give up the caller's slot, if it holds one, while its own fan-out runs."""
if not self._holding.get():
yield
return
self._semaphore.release()
token = self._holding.set(False)
try:
yield
finally:
self._holding.reset(token)
await self._semaphore.acquire()
# Tool replies that mean the call did nothing. Runtimes log them, and the Execution
# keeps them as lesson candidates.
REJECTION_PREFIXES = (
"Not submitted",
"Refused",
"Discovery gap",
"terraform validate failed",
)
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."""
...