Files
moloapp/plans/16-agent-platform.md
T
retoorandClaude Sonnet 5.5 6d744a433f feat(clients): google foundation for the agent platform: all-verb client, streaming, typed Gemini content, operations
GoogleClient gets every verb and stream_json (SSE and plain JSON), typed
Content/Part/Tool/GenerateRequest with the LanguageModel seam, CloudContext
resource names, long-running operation polling and pagination, OAuth bearer
tokens via GOOGLE_ACCESS_TOKEN. Example scaffold: one stub per agent module
under example/app/agent, wildcard builds, locust excludes /voice /google
/agent. plans/16-agent-platform.md splits the work into nine modules.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-24 04:12:52 +02:00

8.5 KiB

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): : `, 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.