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:
@@ -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`.
|
||||
|
||||
Reference in New Issue
Block a user