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

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