10 KiB
16 Gemini Enterprise Agent Platform
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.
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
- Read
AGENTS.md,src/google/SPEC.md, the foundation headers, one finished service (generative.*,voice*.*) and its tests. - Research first, from machine-readable sources. For every Google API
fetch its Discovery document (
https://<service>.googleapis.com/$discovery/ rest?version=<v>, no auth) and derive paths, methods, parameters and fields from it; read the official docs for semantics. Protocols without Discovery (WebSocket, MCP, A2A) are read from their primary spec. - The module SPEC (
src/google/<module>/SPEC.md) has: scope, module map (one class per concern), static caps table, contracts,## Sources,## Verified against discovery(date, counts),## Verified live(call, status, date),## Unverified(every shape inferred rather than read or seen),## Gaps. Never invent an endpoint silently. If a product has no public API, say so and name any local abstraction as local. - Object oriented, one concern per file, namespace
molo::google::<module>, services derive fromService. 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. - NO verification with scripted Google responses. Each module declares its
calls in one table and ships
tools/check_discovery.py(python3 stdlib) that fails when a declared call or request field is absent from Discovery. Tests undertests/src/google/<module>/are deterministic and local (validation, caps, ids, request bodies against the table, local logic with a fakeLanguageModel, loopback servers for non-Google protocols) plus opt-in live tests (MOLO_LIVE_NET=1, loud SKIP otherwise). Live checks are read-only or a few tokens: no resource creation, update or delete. - 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 503google_not_configuredwithout a credential, 422 on bad input. Pages are mobile-first (360px), one template registered inside the register function plus an optional scriptexample/assets/agent_<module>.js. Register matrix rows withservices.add_feature(name, "/agent/<module>")for the GET page only. State is created inside the register function; do not editServices. - Example tests:
tests/example/agent/<module>/*_test.cpp(Arrange / Act / Assert as intests/README.md) withsupport/GoogleRig.hpponly to inject an unconfigured or dummy client: GET pages, 405, 422, 503google_not_configured, limit cases. Never script a Google reply. - All of
/agent/*,/google/*,/voice/*are excluded from locust (example/check_locust_coverage.py). Do not add them toexample/locustfile.py. - 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 orexample/SPEC.md, other modules' files, orsrc/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. - Live checks use
GOOGLE_API_KEY/GOOGLE_CLOUD_PROJECTfrom the environment andexport GOOGLE_ACCESS_TOKEN=$(cd /home/retoor/projects/ moloapp && ./build/google/sa-token)for OAuth; never print, log or commit a credential. No em dashes anywhere (code, docs, comments, commits). - Build and test:
make google-test(framework tests) andmake -f example/example.mk example-test(example suite). Do not runmake lintor a full-repo build. - Commit on your worktree branch when green: `feat(clients): :
`, 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 useprojects/{p}/locations/{l}/publishers/{pub}/models/{m}. Support both.VertexModelimplementsLanguageModel(streaming via?alt=sseandstream_json). ExistingGenerativeand 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:
GuardedModelwraps anyLanguageModel, 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
LanguageModeland is tested with a fake; API surfaces (evaluateInstances, traces, logs) are scripted. - adk: codes against
LanguageModelonly; ships a privateDirectModeladapter overGoogleClientso 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-RPCtools/list,tools/call), A2A agent cards and task send, and ADK's agent-config format are researched, not guessed. - live: if
src/realtimehas 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 wolfSSLITlsSession(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
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_TOKENis the caller's job; the service-account path refreshes itself. -
PartlacksthoughtSignature(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.