diff --git a/.env.example b/.env.example index f30aef4..28909d9 100644 --- a/.env.example +++ b/.env.example @@ -35,6 +35,7 @@ ADK_ENABLE_ARTIFACT_STORE=true # Cloud Provider Bundle (providers/.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 diff --git a/.scratch/solution-architect-agent/spec.md b/.scratch/solution-architect-agent/spec.md index 359563e..64ecfdc 100644 --- a/.scratch/solution-architect-agent/spec.md +++ b/.scratch/solution-architect-agent/spec.md @@ -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`. diff --git a/Dockerfile b/Dockerfile index 186db42..7e837e7 100644 --- a/Dockerfile +++ b/Dockerfile @@ -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 diff --git a/app/a2a/__init__.py b/app/a2a/__init__.py new file mode 100644 index 0000000..7ee0dc4 --- /dev/null +++ b/app/a2a/__init__.py @@ -0,0 +1 @@ +"""A2A interface for interactive Executions (A2A 1.0, with v0.3 compatibility).""" diff --git a/app/a2a/card.py b/app/a2a/card.py new file mode 100644 index 0000000..47e07c5 --- /dev/null +++ b/app/a2a/card.py @@ -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"], + ) + ], + ) diff --git a/app/a2a/executor.py b/app/a2a/executor.py new file mode 100644 index 0000000..36e54dc --- /dev/null +++ b/app/a2a/executor.py @@ -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()} diff --git a/app/a2a/server.py b/app/a2a/server.py new file mode 100644 index 0000000..7cc1503 --- /dev/null +++ b/app/a2a/server.py @@ -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() diff --git a/app/assembly.py b/app/assembly.py new file mode 100644 index 0000000..c1d0e24 --- /dev/null +++ b/app/assembly.py @@ -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)) diff --git a/app/config.py b/app/config.py index 4c602ea..ef3507a 100644 --- a/app/config.py +++ b/app/config.py @@ -51,6 +51,7 @@ class Settings(BaseSettings): # Cloud Provider Bundle (providers/.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 diff --git a/app/execution/engine.py b/app/execution/engine.py index 0ebda5b..9a9b76e 100644 --- a/app/execution/engine.py +++ b/app/execution/engine.py @@ -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 { diff --git a/app/execution/graph.py b/app/execution/graph.py index 8ed92a9..850644e 100644 --- a/app/execution/graph.py +++ b/app/execution/graph.py @@ -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) diff --git a/app/execution/presentation.py b/app/execution/presentation.py new file mode 100644 index 0000000..f536301 --- /dev/null +++ b/app/execution/presentation.py @@ -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": "", + } + } + 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 diff --git a/pytest.ini b/pytest.ini index 778f4ed..5b71f0b 100644 --- a/pytest.ini +++ b/pytest.ini @@ -2,3 +2,5 @@ testpaths = tests asyncio_mode = auto asyncio_default_fixture_loop_scope = function +filterwarnings = + ignore:label\(\) is deprecated:DeprecationWarning diff --git a/requirements.txt b/requirements.txt index 7d2eb23..e18e67e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -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 diff --git a/tests/a2a/__init__.py b/tests/a2a/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/a2a/test_server.py b/tests/a2a/test_server.py new file mode 100644 index 0000000..32d083d --- /dev/null +++ b/tests/a2a/test_server.py @@ -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"} diff --git a/tests/execution/test_engine.py b/tests/execution/test_engine.py index 06af275..708e3e2 100644 --- a/tests/execution/test_engine.py +++ b/tests/execution/test_engine.py @@ -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" diff --git a/tests/execution/test_presentation.py b/tests/execution/test_presentation.py new file mode 100644 index 0000000..80d743b --- /dev/null +++ b/tests/execution/test_presentation.py @@ -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"] diff --git a/tests/test_assembly.py b/tests/test_assembly.py new file mode 100644 index 0000000..f3471e7 --- /dev/null +++ b/tests/test_assembly.py @@ -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