169 lines
9.3 KiB
Markdown
169 lines
9.3 KiB
Markdown
# Google Agent Sessions and Memory Bank - Specification
|
|||
|
|
|
||
|
|
Owned directory: `src/google/sessions/`. Namespace `molo::google::sessions`.
|
||
|
|
Depends on the `src/google` foundation (`GoogleClient`, `Service`, `Operation`,
|
||
|
|
`wait_operation`, `list_all`, `gemini_types.h`). Does not depend on the runtime
|
||
|
|
module: the Agent Engine is accepted as a validated resource-name string.
|
||
|
|
|
||
|
|
## 1. Scope
|
||
|
|
|
||
|
|
Gemini Enterprise Agent Platform, Agent Engine (`reasoningEngines`) children:
|
||
|
|
|
||
|
|
- Agent Sessions: create (custom session id), get, list, patch, delete,
|
||
|
|
compact, appendEvent, list events.
|
||
|
|
- Agent Memory Bank: generate (from a session, a conversation, or given facts),
|
||
|
|
ingestEvents (streaming), retrieve (scope, similarity search, metadata
|
||
|
|
filters), retrieveProfiles (Memory Profiles, low-latency structured recall),
|
||
|
|
create, get, list, patch, delete, purge (explicit, guarded), revisions
|
||
|
|
(list, get), rollback, topics (managed and custom), scope maps, metadata.
|
||
|
|
- Long-running operations: every mutating call returns an Operation; the module
|
||
|
|
waits with `wait_operation` (hard caps in `OperationCaps`). `operation()`,
|
||
|
|
`cancel_operation()` and `wait()` expose them for one engine only.
|
||
|
|
|
||
|
|
Everything is against one API surface: `aiplatform` **v1beta1**. See section 6
|
||
|
|
for why not v1.
|
||
|
|
|
||
|
|
## 2. Module map (one class or concern per file)
|
||
|
|
|
||
|
|
| File | Concern |
|
||
|
|
|---|---|
|
||
|
|
| `caps.h` | Static ceilings (`SessionsCaps`, `MemoryCaps`) |
|
||
|
|
| `calls.h` | The ONE table of every REST call (verb, path, discovery method, request fields, query params) |
|
||
|
|
| `names.h/.cpp` | `EngineName` (validated resource name), `Check` (input validators), wire helpers |
|
||
|
|
| `session_types.h/.cpp` | `SessionSpec`, `Session`, `SessionPatch`, `CompactRequest`, `SessionEvent`, list options |
|
||
|
|
| `memory_types.h/.cpp` | `Memory`, `MemorySpec`, `MemoryPatch`, `Topic`, `MetadataValue`, `MetadataFilter`, `MemoryGenerateRequest`, `IngestRequest`, `RetrieveRequest`, `PurgeRequest`, `MemoryRevision`, `Profile` |
|
||
|
|
| `engine_service.h/.cpp` | `EngineService : Service`: table-driven `send`, `settle`, capped `list_items`, operation helpers |
|
||
|
|
| `sessions.h/.cpp` | `Sessions : EngineService` |
|
||
|
|
| `memory_bank.h/.cpp` | `MemoryBank : EngineService` |
|
||
|
|
| `tools/check_discovery.py` | Verifies `calls.h` and the typed bodies against Google's Discovery document |
|
||
|
|
|
||
|
|
Tests: `tests/src/google/sessions/test_sessions.cpp`. Example:
|
||
|
|
`example/app/agent/SessionsDemo.cpp` (routes under `/agent/sessions`), tests in
|
||
|
|
`tests/example/agent/sessions/`.
|
||
|
|
|
||
|
|
## 3. Static caps (see caps.h)
|
||
|
|
|
||
|
|
| Knob | Value |
|
||
|
|
|---|---|
|
||
|
|
| Session / memory id | 1..63 chars `[a-z0-9-]`; memory id starts with a letter, ends alphanumeric |
|
||
|
|
| Engine name | `projects/{p}/locations/{l}/reasoningEngines/{e}`, 512 chars max |
|
||
|
|
| Session TTL | `Ns` form, 24 h minimum (Google), 3650 days maximum (ours) |
|
||
|
|
| session_state / event | 64 KiB / 256 KiB serialized |
|
||
|
|
| Labels | 20, key and value 64 chars |
|
||
|
|
| List pages / items | 10 pages of 100, 1000 items; more is `RESULT_TOO_LARGE`, narrow the filter |
|
||
|
|
| Scope | 1..10 entries, 128 chars, no `*` |
|
||
|
|
| Fact / description / context | 4000 chars |
|
||
|
|
| Generate sources | 100 events, 64 KiB; direct memories max 5 (Google) |
|
||
|
|
| Retrieve | query 1000 chars, top_k 0..50 (default 5), page size 0..100 |
|
||
|
|
| Topics / metadata / filter groups | 10 / 20 entries / 10 groups of 10 filters |
|
||
|
|
| Operation wait | `OperationCaps`: 600 s, 2 s interval, 400 polls |
|
||
|
|
|
||
|
|
## 4. Contracts
|
||
|
|
|
||
|
|
- All input and every id is validated before any network traffic and throws
|
||
|
|
`GoogleError::invalid` (HTTP 400 `INVALID_ARGUMENT`, empty service name).
|
||
|
|
- No credential: every call throws `NotConfiguredError` (503) before traffic.
|
||
|
|
- Destructive calls are explicit methods: `delete_session`, `delete_memory`,
|
||
|
|
`purge`. `purge` is a server-side dry run unless `force` is set, and a forced
|
||
|
|
purge additionally needs `confirm` equal to the engine id (local guard).
|
||
|
|
Compaction rewrites history and is its own method.
|
||
|
|
- Request bodies are built only from fields named in the `calls.h` row of the
|
||
|
|
call (tested), and those fields are checked against the discovery schema.
|
||
|
|
- Unknown response parts stay raw `Json` (event `actions`, `eventMetadata`,
|
||
|
|
`rawEvent`, `sessionState`, memory `metadata`, `structuredContent`, profile
|
||
|
|
fields).
|
||
|
|
- Example routes: GET pages answer 2xx without a credential; every route that
|
||
|
|
calls Google is POST or DELETE and answers 503 `google_not_configured`
|
||
|
|
without a credential and 422 on bad input.
|
||
|
|
|
||
|
|
## 5. Verified against discovery
|
||
|
|
|
||
|
|
`python3 -I src/google/sessions/tools/check_discovery.py` fetches
|
||
|
|
`https://aiplatform.googleapis.com/$discovery/rest?version=v1beta1` (no
|
||
|
|
credential) and fails if a declared call, verb, path, request field, query
|
||
|
|
parameter, enum value, response key or nested request field is absent.
|
||
|
|
|
||
|
|
Result 2026-10-24: `OK 2026-10-24: 23 calls, 7 enums, 25 response keys, 18
|
||
|
|
nested schemas match aiplatform v1beta1 discovery`. A deliberately misspelled
|
||
|
|
field made it exit 1 (checked). Rerun it after any change to `calls.h` or the
|
||
|
|
typed bodies.
|
||
|
|
|
||
|
|
From discovery (v1beta1, `projects.locations.reasoningEngines`):
|
||
|
|
sessions create (POST, `sessionId` query, returns Operation), get, list
|
||
|
|
(`filter orderBy pageSize pageToken`), patch (`updateMask`), delete (returns
|
||
|
|
Operation), appendEvent (POST `:appendEvent`, body `SessionEvent`), compact
|
||
|
|
(POST `:compact`, returns Operation), events.list (`sessionEvents`);
|
||
|
|
memories generate / retrieve / retrieveProfiles / create (`memoryId`) / get /
|
||
|
|
list / patch (`updateMask`) / delete / purge / rollback / ingestEvents,
|
||
|
|
memories.revisions list / get; operations get / cancel. Discovery also lists
|
||
|
|
`wait`, `list`, `delete` on operations, which this module does not wrap
|
||
|
|
(`wait_operation` polls with GET).
|
||
|
|
|
||
|
|
## 6. Verified live
|
||
|
|
|
||
|
|
Read-only, 2026-10-24, project read from `GOOGLE_CLOUD_PROJECT`, no resource
|
||
|
|
created, changed or deleted. Two credentials:
|
||
|
|
|
||
|
|
Express API key (`AQ.`):
|
||
|
|
|
||
|
|
| Call | Result |
|
||
|
|
|---|---|
|
||
|
|
| GET `v1/.../reasoningEngines/1/{sessions, sessions/abc, sessions/abc/events, memories, memories/abc}` | 401 `UNAUTHENTICATED`: "API keys are not supported by this API" |
|
||
|
|
| GET `v1beta1/.../reasoningEngines/1/{sessions, sessions/abc, sessions/abc/events, memories, memories/abc, memories/abc/revisions}` | 404 `NOT_FOUND` "The ReasoningEngine does not exist." (key accepted, path routed) |
|
||
|
|
| GET `v1beta1/.../reasoningEngines/1/operations/1` | 404 `NOT_FOUND` "Operation ... not found." |
|
||
|
|
|
||
|
|
Service-account OAuth bearer token (token exchange, never stored):
|
||
|
|
|
||
|
|
| Call | Result |
|
||
|
|
|---|---|
|
||
|
|
| GET `v1` and `v1beta1` `.../reasoningEngines` | 200 `{}` (no engine exists) |
|
||
|
|
| GET `v1` and `v1beta1` `.../reasoningEngines/1/{sessions, sessions/abc, sessions/abc/events, memories, memories/abc, memories/abc/revisions}` | 404 `NOT_FOUND` "The ReasoningEngine does not exist." |
|
||
|
|
| GET `v1` and `v1beta1` `.../reasoningEngines/1/operations/1` | 404 `NOT_FOUND` "Operation ... not found." |
|
||
|
|
|
||
|
|
The module uses v1beta1 only because it is the one surface that accepts both
|
||
|
|
an express key and a token; v1 refuses keys. The opt-in test `sessions_live`
|
||
|
|
(`MOLO_LIVE_NET=1`, `GOOGLE_API_KEY` or `GOOGLE_ACCESS_TOKEN`,
|
||
|
|
`GOOGLE_CLOUD_PROJECT`; loud SKIP otherwise) repeats six of the reads through
|
||
|
|
the real client (sessions list / get / events, memories list / get /
|
||
|
|
revisions) and passed with the key and with the token on 2026-10-24.
|
||
|
|
|
||
|
|
No Agent Engine exists in the project, so **no happy path was verified
|
||
|
|
live**: create, patch, delete, append, compact, generate, ingest, retrieve,
|
||
|
|
retrieveProfiles, purge, rollback are verified by discovery only. Nothing that
|
||
|
|
costs money was called.
|
||
|
|
|
||
|
|
## 7. Unverified
|
||
|
|
|
||
|
|
Neither discovery nor the docs pages read state these; they are inferred:
|
||
|
|
|
||
|
|
- Operation `response` bodies (discovery types them as `Any`): that generate
|
||
|
|
answers `{"generatedMemories":[{"memory":{...},"action":"..."}]}`, that purge
|
||
|
|
answers `{"purgeCount":N}`, that create and patch answer the resource
|
||
|
|
(`name`, ...). Parsers are tolerant: missing keys give empty results, and
|
||
|
|
create/patch fall back to a GET when the id is known.
|
||
|
|
- `GeneratedMemory.action` values (not enumerated anywhere read).
|
||
|
|
- That `delete` Operations are returned `done` or pollable at `operations/{id}`
|
||
|
|
under the engine (the path shape follows discovery's `operations.get`).
|
||
|
|
- Filter grammar (AIP-160) beyond the field names the docs list: `topics`,
|
||
|
|
`scope` as a JSON string with equality, `timestamp` ranges for events,
|
||
|
|
`displayName` / `userId` / `labels.k` for sessions.
|
||
|
|
- Similarity search needs the engine's Memory Bank configured with a similarity
|
||
|
|
search model (docs); the error body when it is not is unread.
|
||
|
|
- Memory Profiles need schema configs on the engine (`MemoryBankConfig` in the
|
||
|
|
runtime module); the shape of `profile` is free-form and kept raw.
|
||
|
|
- Managed topic names beyond the four in discovery, and `thought`/`audio` parts
|
||
|
|
inside event `content` (typed by `gemini_types.h`, unknown parts dropped).
|
||
|
|
|
||
|
|
## 8. Gaps
|
||
|
|
|
||
|
|
- `servingProfiles` (location-level create/get/list/patch for Gemini Live,
|
||
|
|
Interactions and Response APIs) is listed by discovery next to this product
|
||
|
|
but is not engine-scoped; not implemented here. Owner: the `live` or
|
||
|
|
`models` module.
|
||
|
|
- Engine-level Memory Bank configuration (`contextSpec.memoryBankConfig`,
|
||
|
|
customization, TTL config) is part of the Agent Engine resource: runtime
|
||
|
|
module.
|
||
|
|
- Operations `list`, `delete`, `wait` (server-side) are not wrapped.
|
||
|
|
- Session and memory `labels` / `metadata` filters beyond a passthrough string.
|
||
|
|
- Token refresh is the caller's job (foundation gap).
|