157 lines
9.8 KiB
Markdown
157 lines
9.8 KiB
Markdown
# 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
|
|
|
|
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
|
|
|
|
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.
|