Files
moloapp/plans/16-agent-platform.md
T

137 lines
8.5 KiB
Markdown
Raw Normal View History

# 16 Gemini Enterprise Agent Platform
Status: plan, 2026-10-24. 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.
Foundation (already in `src/google/`, read it first): `GoogleClient`
(all verbs, streaming via `stream_json`), `Service`, `GoogleError`,
`Credentials` (API key, OAuth bearer via `GOOGLE_ACCESS_TOKEN`),
`CloudContext` + `endpoints::aiplatform(location)` (`resource.h`),
`wait_operation` + `list_all` (`operation.h`), typed Gemini content and the
`LanguageModel` seam (`gemini_types.h`), `StreamDecoder`.
## 1. Modules (one worktree each)
| Module | Dir (src / tests / example) | Covers |
|---|---|---|
| models | `src/google/models` | Model Garden, Gemini on Vertex (generate, stream, count tokens, embeddings), partner models (Claude via rawPredict), open models (Gemma endpoints), media generation (image, music), `VertexModel : LanguageModel` |
| runtime | `src/google/runtime` | Agent Runtime (Agent Engine, `reasoningEngines`): create/get/list/update/delete, query, streamQuery, deployment spec, identity type, batch and event-driven triggers (BigQuery, Pub/Sub) where an API exists |
| sessions | `src/google/sessions` | Agent Sessions (events, custom session IDs) and Agent Memory Bank (generate, retrieve, create, list, delete, memory profiles) |
| sandbox | `src/google/sandbox` | Agent Sandbox (code execution, computer use / browser) and Workspaces (bash, files) |
| registry | `src/google/registry` | Agent Registry, Agent Gateway, Agent Identity |
| armor | `src/google/armor` | Model Armor (templates, sanitize prompt/response), Agent Anomaly Detection, Agent Threat Detection, Agent Security dashboard (Security Command Center findings), `GuardedModel` decorator |
| optimize | `src/google/optimize` | Agent Evaluation, Agent Simulation, Agent Observability (traces, logs), Agent Optimizer |
| adk | `src/google/adk` | Agent Development Kit in C++: agents, tools, runner, multi-agent graph, MCP client, A2A client, Agent Studio export/import, Agent Garden catalog, AP2 types, session/memory seams |
| live | `src/google/live` | Multimodal streaming: Live API over WebSocket (bidirectional audio, video, text), RFC 6455 client |
## 2. Rules for every module
1. Read `AGENTS.md`, `src/google/SPEC.md`, the foundation headers, one
finished service (`generative.*`, `voice*.*`) and its tests.
2. Research first. Use WebFetch/WebSearch on Google's official docs
(`docs.cloud.google.com/gemini-enterprise-agent-platform`, Vertex AI
REST references, `cloud.google.com/*/docs`). Record exact resource
paths, HTTP methods, request and response fields.
3. The module SPEC (`src/google/<module>/SPEC.md`) has: scope, module map
(one class per concern), static caps table, contracts, `## Sources`
(URLs read), `## Unverified` (every shape or path inferred rather than
read from docs), `## Gaps`. Never invent an endpoint silently. If a
product has no public API, say so and implement only what exists, with
any local abstraction named as local.
4. Object oriented, one concern per file, namespace
`molo::google::<module>`, services derive from `Service`. Hard caps for
every count, size, interval and wait; validate all input and every id
(`valid_segment`) before any network traffic; list calls cap pages.
Destructive calls (delete, purge) are explicit methods, never defaults.
5. Tests: `tests/src/google/<module>/test_*.cpp` with `MockTransport`
scripted from the documented shapes: request shape, happy path, error
mapping, validation, caps, pagination and long-running paths. Use the
existing harness (`TEST(suite, name)`, `framework.h`).
6. Example: fill `example/app/agent/<Module>Demo.cpp`. Routes live under
`/agent/<module>`. Contract: GET page and status routes answer 2xx with
no credential (the matrix crawler hits them); every route that would
call Google is a POST (or DELETE) and answers 503
`google_not_configured` without a credential, 422 on bad input. Pages
are mobile-first (360px), one template registered inside the register
function plus an optional script `example/assets/agent_<module>.js`.
Register matrix rows with `services.add_feature(name, "/agent/<module>")`
for the GET page only. State is created inside the register function;
do not edit `Services`.
7. Example tests: `tests/example/agent/<module>/*_test.cpp` (Arrange / Act /
Assert as in `tests/README.md`) using `support/GoogleRig.hpp`: happy
path, no credential, validation, 405, one limit case. Set
`GOOGLE_CLOUD_PROJECT` with `setenv` inside the test.
8. All of `/agent/*`, `/google/*`, `/voice/*` are excluded from locust
(`example/check_locust_coverage.py`). Do not add them to
`example/locustfile.py`.
9. Do not edit shared files: `Makefile`, `src/google/google.mk`,
`example/example.mk`, `example/app/App.*`, `example/app/AgentDemos.hpp`,
`example/app/agent/AgentDemos.cpp`, `example/app/Templates.cpp`,
`example/locustfile.py`, `example/check_locust_coverage.py`,
`tests/example/support/*`, any README or `example/SPEC.md`, other
modules' files, or `src/google/*.{h,cpp}` foundation files. If a
foundation gap blocks you, work around it inside your module and list it
in your report. Build globs pick up new files automatically.
10. No live network, no keys. The suite is scripted. Never print or commit
a credential. No em dashes anywhere (code, docs, comments, commits).
11. Build and test: `make google-test` (framework tests) and
`make -f example/example.mk example-test` (example suite). Do not run
`make lint` or a full-repo build.
12. Commit on your worktree branch when green: `feat(clients): <module>:
<summary>`, ending with the Co-Authored-By line from your system
reminder. Final report (under 250 words): files added, routes, test
counts, the Unverified list, foundation gaps.
## 3. Module notes
- models: express-mode keys use `https://aiplatform.googleapis.com/v1/
publishers/google/models/{m}:generateContent` (verified live); project
scoped calls use `projects/{p}/locations/{l}/publishers/{pub}/models/{m}`.
Support both. `VertexModel` implements `LanguageModel` (streaming via
`?alt=sse` and `stream_json`). Existing `Generative` and the voice code
must keep working untouched.
- runtime: long-running create/delete use `wait_operation`; deployment
spec fields (package, container, env, scaling, service account / agent
identity) typed, unknown fields kept as raw Json.
- sessions: both resources hang off a runtime resource name; accept the
full name as a string, validated, so this module does not depend on
runtime.
- sandbox: execution results (stdout, stderr, files, exit status) typed;
output sizes capped.
- registry: governance data is read and written by humans too, so list and
get come before mutate; approvals are explicit methods.
- armor: `GuardedModel` wraps any `LanguageModel`, sanitizes the prompt
before and the response after, and throws a typed block error with the
matched filters. Findings are read-only.
- optimize: local scoring logic (multi-turn autorater prompts, failure
clustering, instruction suggestions) codes against `LanguageModel` and is
tested with a fake; API surfaces (evaluateInstances, traces, logs) are
scripted.
- adk: codes against `LanguageModel` only; ships a private
`DirectModel` adapter over `GoogleClient` so it needs no other module.
The runner has a hard step cap, tool-call cap and wall-clock cap. Tests
use a fake model. MCP over HTTP (JSON-RPC `tools/list`, `tools/call`),
A2A agent cards and task send, and ADK's agent-config format are
researched, not guessed.
- live: if `src/realtime` has no usable WebSocket client, implement an
RFC 6455 client in the module (masking, fragmentation, ping/pong, close,
frame and message caps) over plain TCP and over the existing wolfSSL
`ITlsSession` (`clients/transports/tls_wolfssl.h`). Tests run against a
loopback WebSocket server written in the test. The example relays over
HTTP (the example server has no WebSocket): create session, send, poll
events by cursor, close.
## 4. Integration (after the worktrees finish)
The owner merges each branch, then writes the READMEs, `example/SPEC.md`
rows, and the per-module row in this file. Gaps found by module owners are
collected below.
## 5. Gaps
- 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.