docs(clients): agent platform integration: readmes, example spec, plan gaps, suite counts

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-24 04:51:20 +02:00
co-authored by Claude Sonnet 5.5
parent 7190846704
commit fcdb7242be
5 changed files with 59 additions and 9 deletions
+1 -1
View File
@@ -31,7 +31,7 @@ make test # whole repo
make -f example/example.mk example-test # this part only, standalone
```
Expected: `example suite: 111 passed, 0 failed`. Failure action: reproduce
Expected: `example suite: 163 passed, 0 failed`. Failure action: reproduce
through the real stack first (failing route-level test), then fix; the
reproduction stays in the suite. Conventions: `tests/README.md`.
+19 -6
View File
@@ -35,13 +35,13 @@ is not defined in the Makefile yet.
## The living example
A route-level demo of every feature, with 111 integration tests on the real
A route-level demo of every feature, with 163 integration tests on the real
stack (no mocks). Standalone, no other part needed.
```sh
make -f example/example.mk example # build
./build/example/living-server 8080 # run
make -f example/example.mk example-test # expect: 111 passed, 0 failed
make -f example/example.mk example-test # expect: 163 passed, 0 failed
```
Open `http://127.0.0.1:8080/` and click through the matrix. Narrow the
@@ -65,9 +65,20 @@ GOOGLE_API_KEY=... ./build/example/living-server 8080 # then open /voice
Click Start, talk, pause: the answer is spoken back, and speaking over it
interrupts it. Optional env: `GOOGLE_VOICE_LANG` (default `nl-NL`),
`GOOGLE_VOICE_NAME`, `GOOGLE_GENAI_MODEL` (default `gemini-3.5-flash`), `GOOGLE_STT_MODEL`, `GOOGLE_TTS_MODEL` (default `gemini-2.5-flash-tts`), `GOOGLE_API_BACKEND`.
The Google layer is `src/google` (spec: `src/google/SPEC.md`); its route
tests script the Google side, `MOLO_LIVE_NET=1 make google-test` adds the
opt-in real-network checks.
The Google layer is `src/google` (spec: `src/google/SPEC.md`, plan
`plans/16-agent-platform.md`). No test scripts a Google reply: each module
is derived from Google's Discovery documents and re-checked by
`src/google/<module>/tools/check_discovery.py`; `MOLO_LIVE_NET=1 make
google-test` adds read-only live checks against real Google.
Credentials (environment, then `.env.json.local`, then `.env.json`):
`GOOGLE_API_KEY` (Vertex express keys, voice), `GOOGLE_CLOUD_PROJECT`,
`GOOGLE_CLOUD_LOCATION`, and for OAuth-only APIs either
`GOOGLE_ACCESS_TOKEN` or a service account key file in
`GOOGLE_APPLICATION_CREDENTIALS` (git-ignored `.secrets/`). `make
google-token && ./build/google/sa-token` prints an access token.
The Agent Platform demo pages are under `/agent/<module>` and, like all
`/voice`, `/google` and `/agent` routes, are excluded from locust.
Test conventions (one test file per URL, Arrange/Act/Assert, integration
only) are in `tests/README.md`.
@@ -197,7 +208,9 @@ src/app application, routers, views, forms, validation, templates
src/realtime WebSocket, SSE, Socket.IO, streaming, WebDAV, expose tunnels
src/supervisor process supervisor, tasks, replication
src/clients HTTP/REST client, OpenAPI, test double
src/google Google Cloud APIs: generic client, TTS, STT, Gemini, voice pipeline
src/google Google Cloud: generic client, OAuth + service accounts, voice, and the
Gemini Enterprise Agent Platform (models, runtime, sessions, sandbox,
registry, armor, optimize, adk, live), one dir per module
src/cli molo binary: CLI, dev server, embedder, AI, ops, i18n, CSP
src/tenancy multi-tenancy
src/audit hash-chained audit log, GDPR export/erasure, retention
+10 -1
View File
@@ -14,7 +14,7 @@ Open `http://127.0.0.1:8080/` and click through the matrix; `/stats` has the
charts (Chart.js is embedded in the binary, no CDN). Narrow the
window to 360px: the top nav collapses into a dropdown menu.
Run the suite (111 route-level integration tests, real stack, no mocks):
Run the suite (163 route-level integration tests, real stack, no mocks):
```sh
make -f example/example.mk example-test
@@ -120,6 +120,15 @@ on a missing row.
| voice speech to text | `/voice/hear` | `tests/example/voice/hear_test.cpp` | `src/google/SPEC.md` |
| voice turn | `/voice/turn` | `tests/example/voice/turn_test.cpp` | `src/google/SPEC.md` |
| voice reset | `/voice/reset` | `tests/example/voice/reset_test.cpp` | `src/google/SPEC.md` |
| agent models | `/agent/models` | `tests/example/agent/models/page_test.cpp` | `plans/16-agent-platform.md` |
| agent runtime | `/agent/runtime` | `tests/example/agent/runtime/page_test.cpp` | `plans/16-agent-platform.md` |
| agent sessions and memory | `/agent/sessions` | `tests/example/agent/sessions/page_test.cpp` | `plans/16-agent-platform.md` |
| agent sandbox | `/agent/sandbox` | `tests/example/agent/sandbox/page_test.cpp` | `plans/16-agent-platform.md` |
| agent registry, gateway, identity | `/agent/registry` | `tests/example/agent/registry/page_test.cpp` | `plans/16-agent-platform.md` |
| agent armor and security | `/agent/armor` | `tests/example/agent/armor/page_test.cpp` | `plans/16-agent-platform.md` |
| agent evaluation and optimize | `/agent/optimize` | `tests/example/agent/optimize/page_test.cpp` | `plans/16-agent-platform.md` |
| agent development kit | `/agent/adk` | `tests/example/agent/adk/page_test.cpp` | `plans/16-agent-platform.md` |
| agent live streaming | `/agent/live` | `tests/example/agent/live/page_test.cpp` | `plans/16-agent-platform.md` |
### Extended features
+8
View File
@@ -58,6 +58,14 @@ owning sibling plan and the file that will close it.
`google_error` with Google's status. Bad input: 422 or 415 before any
network call. Routes and tests use a scripted transport; the key lives
only in the `x-goog-api-key` header.
17. Agent Platform (`src/google/<module>`): nine modules, one demo page each
at `/agent/<module>` (models, runtime, sessions, sandbox, registry,
armor, optimize, adk, live). GET pages and `/status` answer 2xx with no
credential; every route that calls Google is POST or DELETE and answers
503 `google_not_configured` without one, 422 on bad input. Destructive
routes need an explicit confirmation. No route test scripts a Google
reply. All `/agent`, `/voice` and `/google` routes are excluded from
locust; `check_locust_coverage.py` fails if one is referenced.
## Caps
+21 -1
View File
@@ -1,6 +1,6 @@
# 16 Gemini Enterprise Agent Platform
Status: plan, 2026-10-24. Source: Google's announcement "Introducing Gemini
Status: implemented and merged, 2026-10-24 (all nine modules; see each module SPEC for what is verified live, by discovery, or unverified). Source: Google's announcement "Introducing Gemini
Enterprise Agent Platform" (the evolution of Vertex AI). The announcement
names products but no REST resources; each module owner researches the real
API from Google's docs and records what could and could not be verified.
@@ -131,6 +131,26 @@ collected below.
## 5. Gaps
Collected from the module reports (details in each `src/google/<module>/SPEC.md`):
- Not enabled on project `lisa-448004`, so never exercised live: Model Armor,
Security Command Center, Agent Registry, Network Services, Network Security.
Each module's opt-in live test (`MOLO_LIVE_NET=1`) reports "API NOT ENABLED"
loudly and is ready to run once an owner enables them.
- No Agent Engine exists in the project, so sessions, memories and sandboxes
were only probed for error shapes (404 for an absent engine). All mutating
calls (create, patch, delete, purge) are verified by Discovery only; none
was run against Google by design.
- Claude on Vertex (`rawPredict`) answered 429 (project quota).
- Token refresh for a pasted `GOOGLE_ACCESS_TOKEN` is the caller's job; the
service-account path refreshes itself.
- `Part` lacks `thoughtSignature` (ADK works around it), the sandbox data
plane (JWT proxy, CDP) and workspaces' REST surface do not exist/are not
implemented, A2A has no public endpoint to verify against, Agent Studio
import is JSON only.
- Pre-existing and unchanged: the example server accepts sequentially, so a
slow Google call blocks other requests meanwhile.
- Live behavior is unverified for every module except generateContent on an
express key: no OAuth project credential is available in the build
environment. Each module's SPEC lists what is only scripted.