feat: serve Executions over A2A with a pre-approved /generate

Increment 7 of .scratch/solution-architect-agent/spec.md.

- app/assembly.py: composition root building the engine from settings
  and the provider bundle (roles, ADK runtime, MCP catalog, Terraform
  tools, checkpointer, recorder).
- app/a2a: a2a-sdk 1.1 JSON-RPC server (v0.3 compatible) mapping tasks to
  Executions; questions, Approvals and permissions pause as
  input-required; Approvals accepted only as structured data; completed
  tasks return the guide and code as artifacts; agent card derived from
  the dependency graph.
- POST /generate runs a pre-approved Execution with the legacy keys.
- Specialist exceptions are relayed to the user; Orchestrator exceptions
  fail the task. Engine accepts a caller-chosen execution id.
- Dockerfile installs checksum-verified Terraform and ships agents,
  providers and skills; add mcp and a2a-sdk requirements.
- 17 new tests; full suite 206 passed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-09-16 10:23:24 +01:00
parent ed104e5697
commit ad371b2ec4
19 changed files with 1116 additions and 3 deletions

View File

@@ -35,6 +35,7 @@ ADK_ENABLE_ARTIFACT_STORE=true
# Cloud Provider Bundle (providers/<name>.yaml) & Remote MCP Servers
CLOUD_PROVIDER=gcp
MCP_ENABLED=true
MCP_ENABLE_PREVIEW=true
# MCP_QUOTA_PROJECT=your-project-id # defaults to the Application Default Credentials project
MCP_TIMEOUT_SECONDS=30
@@ -45,6 +46,9 @@ TERRAFORM_TIMEOUT_SECONDS=300
# TF_PLUGIN_CACHE_DIR=/var/cache/terraform-plugins
# Hierarchical Execution Engine
A2A_HOST=0.0.0.0
A2A_PORT=8000
# A2A_PUBLIC_URL=https://agents.example.com/solution-architect
ORCHESTRATOR_BUDGET=40
SPECIALIST_BUDGET=15
MAX_REVISIONS=3

View File

@@ -699,3 +699,51 @@ Slowest tests: eval benchmark 7.3 s, then 3–4.5 s each for the orchestrator, e
- **API propagation.** A call just after the API was enabled returned 403 and became a discovery gap, which confirms the gap path against the real endpoint. The gap message shows only `403 Forbidden`, because the SDK doesn't expose the response body; Google's reason (for example "API has not been used… or it is disabled") is lost.
- **Truncation.** `search_documents` and `get_documents` both hit the 20k-character limit, cutting their JSON mid-document. Revisit the limit, or summarise, during increment 8's evaluation.
- **No customer-resource reads yet.** No tool that reads project resources has been called. Among the discovery APIs, only `compute` and `cloudasset` are enabled in this project.
### 2026-09-16 · Increment 7: interfaces
**Done (test-first where it could be)**
- `app/assembly.py`: `open_assembly(settings, runtime=, recorder=, output_root=)` is the composition root. It loads the provider bundle and roles (budgets and preview MCP servers from settings), the ADK runtime by default, the `McpCatalog` for the servers the roles use (skipped when `MCP_ENABLED=false`), the Terraform runner and local tools, the tool factory, the configured checkpointer and a `DatabaseRecorder`, and yields `Assembly(engine, bundle, roles, mcp_gaps)`.
- `app/a2a/executor.py`: `SolutionArchitectExecutor` maps A2A tasks onto Executions: task id = `execution_id`, context id = Session.
- **New task:** enqueues the Task, then `engine.start`. `pre_approved` and `allow_cloud_read` come from message or request metadata.
- **Follow-up message:** `engine.resume`. A data part with `approval` or `permission` is the structured reply; anything else is `{"reply": text}`, so free text never approves.
- **Input required:** a text rendering of the prompt plus a `{"prompt": ...}` data part.
- **Completed:** artifacts for the solution guide and every attachment (Terraform files, `architecture.mmd`), then a completion message. `completed_with_warnings` lists the warnings.
- **Engine exception:** the task fails with the error text.
- **Cancel:** cancels the A2A task only; the checkpoint remains.
- `app/a2a/card.py`: the agent card is built from settings and `PHASE_ORDER`/`deliverables_in`, with a JSON-RPC interface at `/a2a`.
- `app/a2a/server.py`: `create_app(settings, assembly_factory)` is a Starlette app. The lifespan opens the assembly and mounts `a2a-sdk` JSON-RPC routes at `/a2a` with **v0.3 compatibility enabled**, and serves the card at `/.well-known/agent-card.json` and the legacy `/.well-known/agent.json`. `/health` reports `mcp_discovery_gaps`. **`POST /generate`** runs pre-approved (`allow_cloud_read` defaults to false), returns 400 without `request` and 500 with the error on failure. Run it with `python -m app.a2a.server` (default `A2A_HOST`/`A2A_PORT` 0.0.0.0:8000).
- `app/execution/presentation.py`: `describe_prompt`, whose approval and permission text shows the exact data reply, and `to_generate_response`. The legacy keys map as follows:
- `source_discovery_doc`: the requirements' `Current state` section
- `source_mermaid_diagram`: `None`
- `architecture_doc`: the architecture description
- `mermaid_diagram`: `architecture.mmd`
- `terraform_code`: `terraform/main.tf`
- `validation_passed`: status `completed`
- `total_loop_iterations`: revisions + 1
- `active_skills`: the Skills of the roles whose Deliverables were submitted
- also adds `warnings`
- **Engine changes.**
- `start(execution_id=)` accepts a caller-chosen id and refuses a duplicate.
- **Model errors (the increment 5 open item):** an exception in a Specialist run becomes `Stopped("it failed with …")`, relayed to the user as a question from that Deliverable. An exception in the Orchestrator propagates, which fails the A2A task or returns 500 from `/generate`, leaving the Execution at its last checkpoint.
- Settings `MCP_ENABLED`, `A2A_HOST`, `A2A_PORT` and `A2A_PUBLIC_URL`. Requirements: `mcp>=1.24,<2` (missing from increment 6's commit) and `a2a-sdk[http-server]>=1.1,<2`. `pytest.ini` filters `a2a-sdk`'s protobuf `label()` deprecation noise.
- `Dockerfile`: the builder installs Terraform 1.14.3, verified against HashiCorp's SHA256SUMS. The image copies `agents/`, `providers/` and `skills/` and exposes 8000 as well as 8080. The `CMD` is still the legacy app until increment 9.
- Tests:
- `tests/a2a/test_server.py`: 10 tests over JSON-RPC. A question pauses the task and a text reply resumes it. Approval counts only as data. A pre-approved task completes with guide and code artifacts. An engine failure fails the task. A v0.3 `message/send` client is accepted. `/generate` keeps the legacy keys, and returns 400 without a request. Health shows gaps.
- `tests/test_assembly.py`: 2 tests.
- `tests/execution/test_presentation.py`: 3 tests.
- Two engine tests: caller-chosen id, and Specialist failure relayed.
- Full suite: **206 passed**. `ruff` and `mypy` are clean.
- **Live smoke test.** `python -m app.a2a.server` started with the real assembly: ADK runtime, live authenticated `tools/list` on all 12 Google Cloud MCP servers with **no gaps**, and memory checkpointer. `/health` and the agent card responded. No message was sent, so no model was called.
**Deviations from the spec text**
- **Server stack.** The A2A server uses the Starlette routes from `a2a-sdk` 1.1 (A2A 1.0, with v0.3 compatibility), not `aiohttp`, matching `google-adk-base-agent`, which also serves A2A on Starlette. Platform base agents pin `a2a-sdk>=0.3`; the v0.3 compatibility keeps those clients working.
- **Where `/generate` lives.** `/generate` for the new engine is served by the A2A app, not behind an `AGENT_ENGINE` switch in the legacy app. The legacy app on :8080 stays unchanged until increment 9 retires it, so there's no `AGENT_ENGINE` setting.
- **No static card file.** There's no `agent_card.json`; the card is built at startup from settings and the graph.
- **Test file names.** A2A tests are HTTP-level (`tests/a2a/test_server.py`), not executor-level `test_executor.py`.
**Open**
- **Card URL.** The card advertises `A2A_PUBLIC_URL`, or `http://A2A_HOST:A2A_PORT`. Set `A2A_PUBLIC_URL` in any deployment, because the fallback shows `0.0.0.0`.
- **Task store.** The A2A task store is in memory, so tasks are lost on restart while Execution checkpoints survive. Use `a2a-sdk`'s database task store with Postgres in production.
- **Docker build unverified.** No Docker on the dev machine.
- **Disabled APIs aren't gaps at startup.** `tools/list` works whether or not a product's API is enabled, so a disabled API shows up only when a tool is called, not in `/health`.

View File

@@ -12,6 +12,16 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
COPY requirements.txt ./
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
# Terraform CLI for fmt/validate/plan tools (never apply), verified against HashiCorp's checksums
ARG TERRAFORM_VERSION=1.14.3
RUN apt-get update && apt-get install -y --no-install-recommends unzip \
&& rm -rf /var/lib/apt/lists/* \
&& curl -fsSLO "https://releases.hashicorp.com/terraform/${TERRAFORM_VERSION}/terraform_${TERRAFORM_VERSION}_linux_amd64.zip" \
&& curl -fsSLO "https://releases.hashicorp.com/terraform/${TERRAFORM_VERSION}/terraform_${TERRAFORM_VERSION}_SHA256SUMS" \
&& grep "linux_amd64.zip" "terraform_${TERRAFORM_VERSION}_SHA256SUMS" | sha256sum -c - \
&& unzip "terraform_${TERRAFORM_VERSION}_linux_amd64.zip" -d /usr/local/bin \
&& rm "terraform_${TERRAFORM_VERSION}_linux_amd64.zip" "terraform_${TERRAFORM_VERSION}_SHA256SUMS"
# Final production image stage
FROM python:3.12-slim
@@ -28,9 +38,13 @@ RUN groupadd -g 10001 appgroup && \
# Copy installed dependencies from builder
COPY --from=builder /install /usr/local
COPY --from=builder /usr/local/bin/terraform /usr/local/bin/terraform
# Copy application source, skills, and configuration
COPY app/ ./app/
COPY agents/ ./agents/
COPY providers/ ./providers/
COPY skills/ ./skills/
COPY eval/ ./eval/
COPY docs/ ./docs/
COPY deliverables/ ./deliverables/
@@ -42,7 +56,9 @@ RUN chown -R appuser:appgroup /app
USER appuser
EXPOSE 8080
# 8080: legacy REST app (removed in increment 9). 8000: A2A server with pre-approved /generate:
# python -m app.a2a.server
EXPOSE 8080 8000
HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8080/health')" || exit 1

1
app/a2a/__init__.py Normal file
View File

@@ -0,0 +1 @@
"""A2A interface for interactive Executions (A2A 1.0, with v0.3 compatibility)."""

66
app/a2a/card.py Normal file
View File

@@ -0,0 +1,66 @@
"""The A2A agent card, derived from the dependency graph and settings."""
from __future__ import annotations
from a2a.types import (
AgentCapabilities,
AgentCard,
AgentInterface,
AgentProvider,
AgentSkill,
)
from app.config import Settings
from app.execution.deliverables import PHASE_ORDER, deliverables_in
A2A_PATH = "/a2a"
def build_agent_card(settings: Settings) -> AgentCard:
base_url = (
settings.A2A_PUBLIC_URL or f"http://{settings.A2A_HOST}:{settings.A2A_PORT}"
).rstrip("/")
phases = "; ".join(
f"{phase.value}: {', '.join(kind.value for kind in deliverables_in(phase))}"
for phase in PHASE_ORDER
)
return AgentCard(
name=settings.AGENT_NAME,
description=(
"Designs a cloud solution architecture with you: requirements discovery, "
"grounded product selection, diagram, design recommendations, "
"infrastructure-as-code and dry-run validation, packaged as a solution "
f"guide. Cloud provider: {settings.CLOUD_PROVIDER}."
),
version=settings.AGENT_VERSION,
provider=AgentProvider(
organization="Kyndryl Agent Builder", url="https://www.kyndryl.com"
),
supported_interfaces=[
AgentInterface(
url=f"{base_url}{A2A_PATH}",
protocol_binding="JSONRPC",
protocol_version="1.0",
)
],
capabilities=AgentCapabilities(streaming=True, push_notifications=False),
default_input_modes=["text/plain", "application/json"],
default_output_modes=["text/plain", "text/markdown", "application/json"],
skills=[
AgentSkill(
id="solution-architecture",
name="Cloud solution architecture",
description=(
"Interactive, multi-turn engagement. Phases and their Deliverables: "
f"{phases}. Each Phase needs your approval, sent as data."
),
tags=["architecture", "cloud", settings.CLOUD_PROVIDER, "terraform"],
examples=[
"Design a regional event ingestion platform on Google Cloud.",
"Migrate our on-premises order service to managed services.",
],
input_modes=["text/plain", "application/json"],
output_modes=["text/plain", "text/markdown", "application/json"],
)
],
)

146
app/a2a/executor.py Normal file
View File

@@ -0,0 +1,146 @@
"""Maps A2A tasks onto Executions: a task is an Execution, its context is the Session.
A new task starts an Execution; a message on an input-required task answers the
Execution's prompt. Approvals and permissions count only as structured data parts,
never as free text.
"""
from __future__ import annotations
import logging
from collections.abc import Mapping
from typing import Any
from a2a.helpers.proto_helpers import (
get_data_parts,
new_data_part,
new_task,
new_text_part,
)
from a2a.server.agent_execution import AgentExecutor, RequestContext
from a2a.server.events import EventQueue
from a2a.server.tasks import TaskUpdater
from a2a.types import TaskState
from google.protobuf import json_format
from app.execution.deliverables import DeliverableKind
from app.execution.engine import ExecutionEngine, Interaction
from app.execution.graph import GUIDE_FILENAME
from app.execution.presentation import describe_prompt
logger = logging.getLogger(__name__)
STRUCTURED_REPLY_KEYS = ("approval", "permission")
class SolutionArchitectExecutor(AgentExecutor):
def __init__(self, engine: ExecutionEngine) -> None:
self._engine = engine
async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
task_id = context.task_id or ""
updater = TaskUpdater(event_queue, task_id, context.context_id or "")
try:
if context.current_task is None:
history = [context.message] if context.message is not None else []
await event_queue.enqueue_event(
new_task(
task_id,
context.context_id or "",
TaskState.TASK_STATE_SUBMITTED,
history=history,
)
)
await updater.start_work()
options = _options(context)
interaction = await self._engine.start(
context.get_user_input(),
session_id=context.context_id,
execution_id=task_id,
pre_approved=bool(options.get("pre_approved", False)),
allow_cloud_read=options.get("allow_cloud_read"),
)
else:
await updater.start_work()
interaction = await self._engine.resume(task_id, _reply(context))
except Exception as exc:
logger.exception("Execution %s failed", task_id)
await updater.failed(
updater.new_agent_message(
[
new_text_part(
f"The Execution failed: {type(exc).__name__}: {exc}"
)
]
)
)
return
await self._publish(interaction, updater)
async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None:
# The checkpoint stays; cancelling only ends the A2A task.
updater = TaskUpdater(
event_queue, context.task_id or "", context.context_id or ""
)
await updater.cancel()
async def _publish(self, interaction: Interaction, updater: TaskUpdater) -> None:
if interaction.status == "awaiting_user" and interaction.prompt is not None:
prompt = dict(interaction.prompt)
await updater.requires_input(
updater.new_agent_message(
[
new_text_part(describe_prompt(prompt)),
new_data_part({"prompt": prompt}),
]
)
)
return
deliverables: Mapping[str, Mapping[str, Any]] = interaction.state.get(
"deliverables", {}
)
guide = deliverables.get(DeliverableKind.SOLUTION_GUIDE.value)
if guide:
await updater.add_artifact(
[new_text_part(guide["content"], media_type="text/markdown")],
name=GUIDE_FILENAME,
)
for kind, deliverable in deliverables.items():
for name, content in deliverable.get("attachments", {}).items():
await updater.add_artifact(
[new_text_part(content)], name=name, metadata={"deliverable": kind}
)
warnings = list(interaction.state.get("warnings", []))
summary = (
"The solution architecture is complete and approved."
if interaction.status == "completed"
else "The Execution ended with warnings: " + "; ".join(warnings)
)
await updater.complete(
updater.new_agent_message(
[
new_text_part(summary),
new_data_part({"status": interaction.status, "warnings": warnings}),
]
)
)
def _options(context: RequestContext) -> dict[str, Any]:
options: dict[str, Any] = {}
if context.message is not None and context.message.HasField("metadata"):
options.update(json_format.MessageToDict(context.message.metadata))
options.update(context.metadata)
return options
def _reply(context: RequestContext) -> dict[str, Any]:
if context.message is not None:
for data in get_data_parts(list(context.message.parts)):
if isinstance(data, Mapping) and any(
k in data for k in STRUCTURED_REPLY_KEYS
):
return {k: data[k] for k in STRUCTURED_REPLY_KEYS if k in data}
return {"reply": context.get_user_input()}

125
app/a2a/server.py Normal file
View File

@@ -0,0 +1,125 @@
"""The A2A server: JSON-RPC at /a2a, the agent card, health, and pre-approved /generate.
Run with: python -m app.a2a.server
"""
from __future__ import annotations
import logging
from collections.abc import AsyncIterator, Callable
from contextlib import AbstractAsyncContextManager, asynccontextmanager
import click
import uvicorn
from a2a.server.request_handlers.default_request_handler_v2 import (
DefaultRequestHandlerV2,
)
from a2a.server.routes.agent_card_routes import create_agent_card_routes
from a2a.server.routes.jsonrpc_routes import create_jsonrpc_routes
from a2a.server.tasks import InMemoryTaskStore
from a2a.utils.constants import AGENT_CARD_WELL_KNOWN_PATH
from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import JSONResponse
from starlette.routing import Route
from app.a2a.card import A2A_PATH, build_agent_card
from app.a2a.executor import SolutionArchitectExecutor
from app.assembly import Assembly, open_assembly
from app.config import Settings, get_settings
from app.execution.presentation import to_generate_response
logger = logging.getLogger(__name__)
AssemblyFactory = Callable[[Settings], AbstractAsyncContextManager[Assembly]]
LEGACY_CARD_PATH = "/.well-known/agent.json"
def create_app(
settings: Settings | None = None,
assembly_factory: AssemblyFactory = open_assembly,
) -> Starlette:
settings = settings or get_settings()
card = build_agent_card(settings)
async def health(request: Request) -> JSONResponse:
assembly: Assembly = request.app.state.assembly
return JSONResponse(
{
"status": "healthy",
"agent": settings.AGENT_NAME,
"version": settings.AGENT_VERSION,
"cloud_provider": assembly.bundle.name,
"mcp_discovery_gaps": assembly.mcp_gaps,
}
)
async def generate(request: Request) -> JSONResponse:
"""Pre-approved, one-shot Execution for batch and evaluation callers."""
assembly: Assembly = request.app.state.assembly
try:
body = await request.json()
except ValueError:
body = {}
workflow_request = str(body.get("request") or "").strip()
if not workflow_request:
return JSONResponse({"error": "'request' is required"}, status_code=400)
try:
interaction = await assembly.engine.start(
workflow_request,
session_id=body.get("session_id"),
pre_approved=True,
allow_cloud_read=bool(body.get("allow_cloud_read", False)),
)
except Exception as exc:
logger.exception("/generate failed")
return JSONResponse(
{"error": f"{type(exc).__name__}: {exc}"}, status_code=500
)
return JSONResponse(to_generate_response(interaction, assembly.roles))
@asynccontextmanager
async def lifespan(app: Starlette) -> AsyncIterator[None]:
async with assembly_factory(settings) as assembly:
handler = DefaultRequestHandlerV2(
agent_executor=SolutionArchitectExecutor(assembly.engine),
task_store=InMemoryTaskStore(),
agent_card=card,
)
app.state.assembly = assembly
app.state.request_handler = handler
app.router.routes.extend(
create_jsonrpc_routes(handler, A2A_PATH, enable_v0_3_compat=True)
)
try:
yield
finally:
await handler.aclose()
return Starlette(
routes=[
Route("/health", health, methods=["GET"]),
Route("/generate", generate, methods=["POST"]),
*create_agent_card_routes(card, card_url=AGENT_CARD_WELL_KNOWN_PATH),
*create_agent_card_routes(card, card_url=LEGACY_CARD_PATH),
],
lifespan=lifespan,
)
@click.command()
@click.option("--host", default=None, help="Host to bind (default A2A_HOST)")
@click.option("--port", default=None, type=int, help="Port (default A2A_PORT)")
def main(host: str | None, port: int | None) -> None:
"""Serve the solution architect agent over A2A."""
settings = get_settings()
logging.basicConfig(level=settings.LOG_LEVEL.upper())
uvicorn.run(
create_app(settings),
host=host or settings.A2A_HOST,
port=port or settings.A2A_PORT,
)
if __name__ == "__main__":
main()

92
app/assembly.py Normal file
View File

@@ -0,0 +1,92 @@
"""Composition root: build the Execution engine from settings and the provider bundle.
The only place concrete runtimes, tools, checkpointers and recorders are chosen.
"""
from __future__ import annotations
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from dataclasses import dataclass
from pathlib import Path
from app.agents.roles import load_roles
from app.agents.runtime import AgentRuntime, RoleSpec
from app.config import Settings
from app.execution.checkpointing import open_checkpointer
from app.execution.engine import ExecutionEngine
from app.execution.recorder import DatabaseRecorder, ExecutionRecorder
from app.execution.toolkit import make_tool_factory
from app.providers import ProviderBundle, load_provider
from app.tools.local import TerraformRunner, local_tools
from app.tools.mcp import McpCatalog, auth_from_config
AGENTS_DIR = Path(__file__).resolve().parent.parent / "agents"
@dataclass(frozen=True)
class Assembly:
engine: ExecutionEngine
bundle: ProviderBundle
roles: dict[str, RoleSpec]
mcp_gaps: dict[str, str]
@asynccontextmanager
async def open_assembly(
settings: Settings,
*,
runtime: AgentRuntime | None = None,
recorder: ExecutionRecorder | None = None,
output_root: Path | None = None,
) -> AsyncIterator[Assembly]:
bundle = load_provider(settings.CLOUD_PROVIDER)
roles = load_roles(
AGENTS_DIR,
bundle,
orchestrator_budget=settings.ORCHESTRATOR_BUDGET,
specialist_budget=settings.SPECIALIST_BUDGET,
include_preview_mcp=settings.MCP_ENABLE_PREVIEW,
)
if runtime is None:
from app.agents.adk_runtime import AdkAgentRuntime
runtime = AdkAgentRuntime(
skill_dirs={name: meta.path for name, meta in bundle.skills.items()}
)
catalog = McpCatalog()
if settings.MCP_ENABLED:
used = {server_id for role in roles.values() for server_id in role.mcp_servers}
catalog = await McpCatalog.load(
[bundle.mcp_servers[server_id] for server_id in sorted(used)],
auth_from_config(bundle.mcp_auth, settings.MCP_QUOTA_PROJECT),
timeout=settings.MCP_TIMEOUT_SECONDS,
)
runner = TerraformRunner(
binary=settings.TERRAFORM_BINARY,
timeout_seconds=settings.TERRAFORM_TIMEOUT_SECONDS,
plugin_cache_dir=settings.TF_PLUGIN_CACHE_DIR,
)
offered = [name for names in bundle.tools.values() for name in names]
tool_factory = make_tool_factory(
runtime,
roles,
bundle.pillar_skills,
local_tools=local_tools(offered, runner),
catalog=catalog,
)
async with open_checkpointer(settings) as checkpointer:
engine = ExecutionEngine(
runtime=runtime,
roles=roles,
recorder=recorder or DatabaseRecorder(),
checkpointer=checkpointer,
output_root=output_root or settings.BASE_DIR,
max_revisions=settings.MAX_REVISIONS,
max_orchestrator_turns=settings.MAX_ORCHESTRATOR_TURNS,
tool_factory=tool_factory,
)
yield Assembly(engine, bundle, roles, dict(catalog.gaps))

View File

@@ -51,6 +51,7 @@ class Settings(BaseSettings):
# Cloud Provider Bundle (providers/<name>.yaml) & Remote MCP Servers
CLOUD_PROVIDER: str = "gcp"
MCP_ENABLED: bool = True
MCP_ENABLE_PREVIEW: bool = True
MCP_QUOTA_PROJECT: str | None = None # defaults to the ADC project
MCP_TIMEOUT_SECONDS: float = 30
@@ -61,6 +62,9 @@ class Settings(BaseSettings):
TF_PLUGIN_CACHE_DIR: str | None = None
# Hierarchical Execution Engine (LangGraph state, ReAct agents)
A2A_HOST: str = "0.0.0.0"
A2A_PORT: int = 8000
A2A_PUBLIC_URL: str | None = None # advertised in the agent card
ORCHESTRATOR_BUDGET: int = 40
SPECIALIST_BUDGET: int = 15
MAX_REVISIONS: int = 3

View File

@@ -76,8 +76,11 @@ class ExecutionEngine:
session_id: str | None = None,
pre_approved: bool = False,
allow_cloud_read: bool | None = None,
execution_id: str | None = None,
) -> Interaction:
execution_id = str(uuid.uuid4())
execution_id = execution_id or str(uuid.uuid4())
if await self._exists(execution_id):
raise ValueError(f"Execution {execution_id} already exists")
if pre_approved and allow_cloud_read is None:
allow_cloud_read = False
initial: dict[str, Any] = {
@@ -137,6 +140,10 @@ class ExecutionEngine:
snapshot.values,
)
async def _exists(self, execution_id: str) -> bool:
snapshot = await self._graph.aget_state(self._config(execution_id))
return bool(snapshot.values)
@staticmethod
def _config(execution_id: str) -> RunnableConfig:
return {

View File

@@ -12,6 +12,7 @@ append outcomes that the next Orchestrator turn applies in order.
from __future__ import annotations
import logging
from collections.abc import Callable, Mapping, Sequence
from pathlib import Path
from typing import Any, cast
@@ -42,6 +43,8 @@ from app.execution.recorder import ExecutionRecorder
from app.execution.state import ExecutionState
from app.execution.tools import ORCHESTRATOR, OrchestratorToolbox, specialist_tools
logger = logging.getLogger(__name__)
ToolFactory = Callable[[RoleSpec, str | None], Sequence[ToolSpec]]
NO_USER_REPLY = (
@@ -240,7 +243,11 @@ def build_execution_graph(
context=task_input["context"],
deliverable=kind.value,
)
outcome = await runtime.run(role, task, tools)
try:
outcome: Outcome = await runtime.run(role, task, tools)
except Exception as exc:
logger.exception("Specialist %s failed on %s", role.name, kind)
outcome = Stopped(f"it failed with {type(exc).__name__}: {exc}")
return {
"outcomes": [
_outcome_record(role.name, kind, task_input["attempt"], outcome)

View File

@@ -0,0 +1,141 @@
"""Presenting an Execution to callers: prompt text and the /generate response shape."""
from __future__ import annotations
import json
import re
from collections.abc import Mapping, Sequence
from typing import Any
from app.agents.runtime import RoleSpec
from app.execution.deliverables import DEPENDENCY_GRAPH, DeliverableKind
from app.execution.engine import Interaction
def describe_prompt(prompt: Mapping[str, Any]) -> str:
"""Plain-text rendering of what the user is asked, including how to answer."""
if "approval" in prompt:
approval = prompt["approval"]
reply = {"approval": {"phase": approval["phase"], "decision": "approve"}}
changes = {
"approval": {
"phase": approval["phase"],
"decision": "changes",
"feedback": "<what to change>",
}
}
return (
f"Please review the {approval['phase']} Phase: {approval['summary']}\n\n"
f"Deliverables: {', '.join(approval['deliverables'])}.\n\n"
f"To approve, reply with the data {json.dumps(reply)}. "
f"To request changes, reply with {json.dumps(changes)}. "
"A text reply is recorded as conversation and never approves."
)
if "permission" in prompt:
permission = prompt["permission"]
grant = {"permission": {permission["tier"]: True}}
return (
"May I read live resources in your cloud environment to discover the current "
f"state? Requested by: {', '.join(permission['requested_by'])}.\n\n"
f"To allow, reply with the data {json.dumps(grant)}; to refuse, use false."
)
lines = [
f"{index}. ({item['from']}) {item['question']}"
for index, item in enumerate(prompt.get("questions", []), start=1)
]
return "\n".join(lines) + "\n\nReply in text; answer every question you can."
def to_generate_response(
interaction: Interaction, roles: Mapping[str, RoleSpec]
) -> dict[str, Any]:
"""Map an Execution onto the legacy /generate response keys."""
state = interaction.state
deliverables: Mapping[str, Mapping[str, Any]] = state.get("deliverables", {})
ledger = state.get("ledger", {})
def content(kind: DeliverableKind) -> str | None:
item = deliverables.get(kind.value)
return item["content"] if item else None
def attachment(kind: DeliverableKind, name: str) -> str | None:
item = deliverables.get(kind.value)
return item.get("attachments", {}).get(name) if item else None
requirements = content(DeliverableKind.REQUIREMENTS)
revisions = sum(
d.get("revisions", 0) for d in ledger.get("deliverables", {}).values()
)
submitted = [kind for kind in DeliverableKind if kind.value in deliverables]
skills = _skills_used(submitted, roles)
status = {
"completed": "success",
"completed_with_warnings": "completed_with_warnings",
}.get(interaction.status, interaction.status)
return {
"execution_id": interaction.execution_id,
"session_id": state.get("session_id"),
"status": status,
"validation_passed": interaction.status == "completed",
"total_loop_iterations": revisions + 1,
"current_phase": _current_phase(ledger),
"artifacts": {
"source_discovery_doc": _section(requirements, "Current state"),
"source_mermaid_diagram": None,
"requirements_doc": requirements,
"architecture_doc": content(DeliverableKind.ARCHITECTURE_DESCRIPTION),
"mermaid_diagram": attachment(
DeliverableKind.ARCHITECTURE_DIAGRAM, "architecture.mmd"
),
"terraform_code": attachment(
DeliverableKind.DEPLOYMENT_GUIDANCE, "terraform/main.tf"
),
"validation_results": content(DeliverableKind.VALIDATION_RESULTS),
"solution_guide": content(DeliverableKind.SOLUTION_GUIDE),
},
"active_skills": skills,
"warnings": list(state.get("warnings", [])),
}
def _skills_used(
submitted: Sequence[DeliverableKind], roles: Mapping[str, RoleSpec]
) -> list[str]:
names: list[str] = []
for kind in submitted:
role = roles.get(DEPENDENCY_GRAPH[kind].specialist)
for skill in role.skills if role else ():
if skill not in names:
names.append(skill)
return names
def _current_phase(ledger: Mapping[str, Any]) -> str | None:
phases: Mapping[str, str] = ledger.get("phases", {})
for phase, status in phases.items():
if status != "approved":
return phase
return list(phases)[-1] if phases else None
def _section(markdown: str | None, heading: str) -> str | None:
"""The body under a heading (any level, numbering ignored), up to the next heading."""
if not markdown:
return None
lines = markdown.splitlines()
pattern = re.compile(
rf"^#{{1,6}}\s+(?:\d+(?:\.\d+)*\.?\s+)?{re.escape(heading)}\s*$", re.IGNORECASE
)
for index, line in enumerate(lines):
if pattern.match(line.strip()):
level = len(line.strip()) - len(line.strip().lstrip("#"))
body = []
for following in lines[index + 1 :]:
stripped = following.strip()
hashes = len(stripped) - len(stripped.lstrip("#"))
if stripped.startswith("#") and hashes <= level:
break
body.append(following)
return "\n".join(body).strip() or None
return None

View File

@@ -2,3 +2,5 @@
testpaths = tests
asyncio_mode = auto
asyncio_default_fixture_loop_scope = function
filterwarnings =
ignore:label\(\) is deprecated:DeprecationWarning

View File

@@ -16,3 +16,5 @@ psycopg2-binary>=2.9.9
sqlalchemy>=2.0.0
asyncpg>=0.29.0
google-adk[extensions]==2.9.0 # Skills are Experimental: pin exactly; extensions brings LiteLLM
mcp>=1.24,<2
a2a-sdk[http-server]>=1.1,<2

0
tests/a2a/__init__.py Normal file
View File

294
tests/a2a/test_server.py Normal file
View File

@@ -0,0 +1,294 @@
"""The A2A server: tasks map onto Executions, driven over JSON-RPC with a scripted runtime."""
import uuid
from contextlib import asynccontextmanager
from pathlib import Path
import pytest
from langgraph.checkpoint.memory import InMemorySaver
from starlette.testclient import TestClient
from app.a2a.server import create_app
from app.agents.fake_runtime import Call, FakeAgentRuntime
from app.agents.roles import load_roles
from app.assembly import Assembly
from app.config import get_settings
from app.execution.deliverables import DEPENDENCY_GRAPH, DeliverableKind, PhaseId
from app.execution.engine import ExecutionEngine
from app.execution.recorder import InMemoryRecorder
from app.providers import load_provider
AGENTS_DIR = Path(__file__).parents[2] / "agents"
K = DeliverableKind
LEGACY_GENERATE_KEYS = {
"execution_id",
"session_id",
"status",
"validation_passed",
"total_loop_iterations",
"current_phase",
"artifacts",
"active_skills",
}
def submission(kind: DeliverableKind) -> list[Call]:
spec = DEPENDENCY_GRAPH[kind]
body = "\n".join(f"## {section}\nDetails." for section in spec.sections)
return [
Call(
"submit_deliverable",
{
"content": f"# {kind}\n{body}\n",
"attachments": {name: f"# {name}\n" for name in spec.attachments},
},
)
]
def complete_run_turns() -> dict:
def delegate(*kinds):
return Call("delegate", {"kinds": [kind.value for kind in kinds]})
def approve(phase):
return Call("request_approval", {"phase": phase.value, "summary": "done"})
return {
"orchestrator": [
[delegate(K.REQUIREMENTS)],
[delegate(K.TECHNICAL_DECOMPOSITION)],
[approve(PhaseId.REQUIREMENTS_DISCOVERY), delegate(K.PRODUCT_SELECTION)],
[delegate(K.ARCHITECTURE_DIAGRAM, K.DESIGN_RECOMMENDATIONS)],
[delegate(K.ARCHITECTURE_DESCRIPTION, K.DEPLOYMENT_GUIDANCE)],
[approve(PhaseId.SOLUTION_ARCHITECTURE), delegate(K.VALIDATION_RESULTS)],
[approve(PhaseId.SOLUTION_VALIDATION), delegate(K.SOLUTION_GUIDE)],
[approve(PhaseId.PACKAGING), Call("finish")],
],
**{
spec.specialist: [submission(kind)]
for kind, spec in DEPENDENCY_GRAPH.items()
},
}
def client_for(tmp_path: Path, turns: dict) -> tuple[TestClient, FakeAgentRuntime]:
bundle = load_provider("gcp")
roles = load_roles(AGENTS_DIR, bundle)
runtime = FakeAgentRuntime(turns)
@asynccontextmanager
async def fake_assembly(settings):
engine = ExecutionEngine(
runtime=runtime,
roles=roles,
recorder=InMemoryRecorder(),
checkpointer=InMemorySaver(),
output_root=tmp_path,
)
yield Assembly(engine, bundle, roles, {"compute": "API not enabled"})
return TestClient(create_app(get_settings(), fake_assembly)), runtime
def send(
client: TestClient, parts: list[dict], task: dict | None = None, metadata=None
):
message = {"messageId": str(uuid.uuid4()), "role": "ROLE_USER", "parts": parts}
if task:
message.update(taskId=task["id"], contextId=task["contextId"])
if metadata:
message["metadata"] = metadata
response = client.post(
"/a2a",
json={
"jsonrpc": "2.0",
"id": 1,
"method": "SendMessage",
"params": {"message": message},
},
headers={"A2A-Version": "1.0"},
)
assert response.status_code == 200, response.text
body = response.json()
assert "error" not in body, body
return body["result"]["task"]
def status_parts(task: dict) -> tuple[str, dict | None]:
parts = task["status"]["message"]["parts"]
text = "\n".join(part["text"] for part in parts if "text" in part)
data = next((part["data"] for part in parts if "data" in part), None)
return text, data
def test_agent_card_is_served_at_current_and_legacy_paths(tmp_path):
client, _ = client_for(tmp_path, {})
with client:
for path in ("/.well-known/agent-card.json", "/.well-known/agent.json"):
card = client.get(path).json()
assert card["name"] == get_settings().AGENT_NAME
assert card["supportedInterfaces"][0]["url"].endswith("/a2a")
assert "solution_architecture" in card["skills"][0]["description"]
def test_question_pauses_the_task_and_a_text_reply_resumes_it(tmp_path):
turns = {
"orchestrator": [
[Call("ask_user", {"questions": ["What is the RTO?"]})],
lambda task: [
Call(
"ask_user",
{
"questions": [
f"Heard: {task.context['conversation'][-1]['text']}"
]
},
)
],
]
}
client, _ = client_for(tmp_path, turns)
with client:
task = send(client, [{"text": "Design regional ingestion"}])
assert task["status"]["state"] == "TASK_STATE_INPUT_REQUIRED"
text, data = status_parts(task)
assert "What is the RTO?" in text
assert data == {
"prompt": {
"questions": [{"from": "orchestrator", "question": "What is the RTO?"}]
}
}
task = send(client, [{"text": "One hour"}], task)
text, _ = status_parts(task)
assert "Heard: One hour" in text
def test_approval_counts_only_as_structured_data(tmp_path):
turns = complete_run_turns()
turns["orchestrator"][2] = [
Call("request_approval", {"phase": "requirements_discovery", "summary": "done"})
]
turns["orchestrator"][3:] = [
[
Call(
"request_approval",
{"phase": "requirements_discovery", "summary": "again"},
)
],
[Call("ask_user", {"questions": ["Approved; what next?"]})],
]
client, _ = client_for(tmp_path, turns)
with client:
task = send(client, [{"text": "Design ingestion"}])
text, data = status_parts(task)
assert data["prompt"]["approval"]["phase"] == "requirements_discovery"
assert '"decision": "approve"' in text
task = send(client, [{"text": "approve"}], task)
_, data = status_parts(task)
assert data["prompt"]["approval"]["phase"] == "requirements_discovery"
task = send(
client,
[
{
"data": {
"approval": {
"phase": "requirements_discovery",
"decision": "approve",
}
}
}
],
task,
)
text, _ = status_parts(task)
assert "Approved; what next?" in text
def test_pre_approved_task_completes_with_guide_and_code_artifacts(tmp_path):
client, _ = client_for(tmp_path, complete_run_turns())
with client:
task = send(
client, [{"text": "Design ingestion"}], metadata={"pre_approved": True}
)
assert task["status"]["state"] == "TASK_STATE_COMPLETED"
names = {artifact["name"] for artifact in task["artifacts"]}
assert {
"solution-architecture-guide.md",
"terraform/main.tf",
"architecture.mmd",
} <= names
def test_engine_failure_fails_the_task(tmp_path):
client, _ = client_for(tmp_path, {"orchestrator": []})
with client:
task = send(client, [{"text": "Design ingestion"}])
assert task["status"]["state"] == "TASK_STATE_FAILED"
assert "ScriptExhausted" in status_parts(task)[0]
def test_v0_3_clients_are_accepted(tmp_path):
client, _ = client_for(
tmp_path, {"orchestrator": [[Call("ask_user", {"questions": ["Region?"]})]]}
)
with client:
response = client.post(
"/a2a",
json={
"jsonrpc": "2.0",
"id": 1,
"method": "message/send",
"params": {
"message": {
"messageId": "m1",
"role": "user",
"kind": "message",
"parts": [{"kind": "text", "text": "Design ingestion"}],
}
},
},
)
result = response.json()["result"]
assert result["status"]["state"] == "input-required"
def test_generate_runs_pre_approved_and_keeps_the_legacy_response_keys(tmp_path):
client, _ = client_for(tmp_path, complete_run_turns())
with client:
response = client.post("/generate", json={"request": "Design ingestion"})
body = response.json()
assert response.status_code == 200, body
assert LEGACY_GENERATE_KEYS <= set(body)
assert body["status"] == "success"
assert body["validation_passed"] is True
assert body["artifacts"]["terraform_code"] == "# terraform/main.tf\n"
assert body["artifacts"]["source_discovery_doc"] == "Details."
assert "google-cloud-solution-architecture" in body["active_skills"]
assert (tmp_path / "deliverables" / "executions" / body["execution_id"]).is_dir()
@pytest.mark.parametrize("payload", [{}, {"request": " "}])
def test_generate_requires_a_request(tmp_path, payload):
client, _ = client_for(tmp_path, {})
with client:
response = client.post("/generate", json=payload)
assert response.status_code == 400
def test_health_reports_mcp_discovery_gaps(tmp_path):
client, _ = client_for(tmp_path, {})
with client:
body = client.get("/health").json()
assert body["status"] == "healthy"
assert body["mcp_discovery_gaps"] == {"compute": "API not enabled"}

View File

@@ -5,6 +5,7 @@ Driven entirely through ExecutionEngine.start/resume with a scripted agent runti
from pathlib import Path
import pytest
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
@@ -629,3 +630,34 @@ async def test_paused_execution_resumes_from_a_durable_checkpoint(tmp_path):
"questions": [{"from": "orchestrator", "question": "Resumed"}]
}
assert resumed.state["ledger"]["phases"]["requirements_discovery"] == "approved"
# --- identity and failures ------------------------------------------------------------------
async def test_caller_can_choose_the_execution_id_once(tmp_path):
runtime = FakeAgentRuntime({"orchestrator": [[ask_user("Hello?")]]})
engine = make_engine(tmp_path, runtime)
first = await engine.start("Ingestion", execution_id="task-123")
assert first.execution_id == "task-123"
with pytest.raises(ValueError, match="task-123"):
await engine.start("Again", execution_id="task-123")
async def test_a_failing_specialist_is_relayed_to_the_user_as_a_question(tmp_path):
class Failing(FakeAgentRuntime):
async def run(self, role, task, tools):
if role.name == specialist(K.REQUIREMENTS):
raise RuntimeError("model API unavailable")
return await super().run(role, task, tools)
runtime = Failing({"orchestrator": [[delegate(K.REQUIREMENTS)], [ask_user()]]})
result = await make_engine(tmp_path, runtime).start("Ingestion")
[question] = result.prompt["questions"]
assert question["from"] == "requirements"
assert "model API unavailable" in question["question"]
assert result.state["ledger"]["deliverables"]["requirements"]["status"] == "pending"

View File

@@ -0,0 +1,76 @@
"""Prompt text for plain clients and the /generate response mapping."""
import json
from app.execution.engine import Interaction
from app.execution.presentation import describe_prompt, to_generate_response
def test_approval_prompt_explains_the_structured_reply():
text = describe_prompt(
{
"approval": {
"phase": "solution_architecture",
"summary": "Cloud Run and Pub/Sub",
"deliverables": ["product_selection", "architecture_diagram"],
}
}
)
reply = {"approval": {"phase": "solution_architecture", "decision": "approve"}}
assert json.dumps(reply) in text
assert "never approves" in text
def test_questions_are_numbered_with_their_source():
text = describe_prompt(
{
"questions": [
{"from": "requirements", "question": "RTO?"},
{"from": "orchestrator", "question": "Region?"},
]
}
)
assert text.startswith("1. (requirements) RTO?\n2. (orchestrator) Region?")
def test_generate_response_maps_deliverables_onto_legacy_artifacts():
requirements = (
"# Requirements\n## 2.3. Current state\nThree VMs.\n### Detail\nNginx.\n"
"## Dependencies\nNone.\n"
)
interaction = Interaction(
"exec-1",
"completed_with_warnings",
None,
{
"session_id": "s-1",
"warnings": ["revision limit"],
"deliverables": {
"requirements": {"content": requirements, "attachments": {}},
"deployment_guidance": {
"content": "# Guide",
"attachments": {"terraform/main.tf": "resource {}"},
},
},
"ledger": {
"deliverables": {"requirements": {"revisions": 2}},
"phases": {
"requirements_discovery": "approved",
"solution_architecture": "open",
},
},
},
)
body = to_generate_response(interaction, {})
assert body["status"] == "completed_with_warnings"
assert body["validation_passed"] is False
assert body["total_loop_iterations"] == 3
assert body["current_phase"] == "solution_architecture"
assert body["artifacts"]["source_discovery_doc"] == "Three VMs.\n### Detail\nNginx."
assert body["artifacts"]["terraform_code"] == "resource {}"
assert body["artifacts"]["solution_guide"] is None
assert body["warnings"] == ["revision limit"]

50
tests/test_assembly.py Normal file
View File

@@ -0,0 +1,50 @@
"""Building the engine from settings and the provider bundle."""
from app.agents.fake_runtime import Call, FakeAgentRuntime
from app.assembly import open_assembly
from app.config import Settings
from app.execution.recorder import InMemoryRecorder
def settings(tmp_path, **overrides) -> Settings:
values = {
"CHECKPOINTER": "memory",
"MCP_ENABLED": False,
"ORCHESTRATOR_BUDGET": 9,
"SPECIALIST_BUDGET": 4,
}
values.update(overrides)
return Settings(**values)
async def test_assembly_wires_roles_budgets_and_tools_from_settings(tmp_path):
runtime = FakeAgentRuntime(
{"orchestrator": [[Call("ask_user", {"questions": ["Which region?"]})]]}
)
async with open_assembly(
settings(tmp_path),
runtime=runtime,
recorder=InMemoryRecorder(),
output_root=tmp_path,
) as assembly:
interaction = await assembly.engine.start("Design ingestion")
assert interaction.prompt["questions"][0]["question"] == "Which region?"
assert assembly.bundle.name == "gcp"
assert assembly.roles["orchestrator"].budget == 9
assert assembly.roles["validator"].budget == 4
assert assembly.mcp_gaps == {}
async def test_preview_mcp_servers_follow_the_setting(tmp_path):
async with open_assembly(
settings(tmp_path, MCP_ENABLE_PREVIEW=False),
runtime=FakeAgentRuntime({}),
recorder=InMemoryRecorder(),
output_root=tmp_path,
) as assembly:
servers = assembly.roles["requirements-analyst"].mcp_servers
assert "asset_inventory" not in servers
assert "compute" in servers