feat(clients): models+runtime: close gaps (all Discovery methods wrapped, live re-verification)

models: EndpointAdmin and PublisherAdmin wrap every remaining method of the
owned resources (84 call table rows, 132 Discovery methods covered, v1beta1
twins, IAM, operations, responses, export, config, enableModel); planner
rejects undeclared body keys; VertexModel::TurnBuilder replays model turns
with every thoughtSignature; Lyria WAV mime from bytes; veo-3.1 default.
runtime: v1beta1 feedbackEntries, A2A gateway (40 rpcs), a2aTasks, task store
records, scoped operations, beta twin flag (103 rows, 214 methods covered);
checker verifies twins, a2aEndpoint patterns and coverage.
example: admin routes for both parts. SPECs: live results moved from
Unverified to Verified live (Veo, Lyria, thought signatures, v1beta1 routes).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-24 05:47:34 +02:00
co-authored by Claude Sonnet 5.5
parent 29d775a923
commit 8e807945a2
38 changed files with 4437 additions and 72 deletions
+99 -18
View File
@@ -14,9 +14,18 @@ spec (package, container, source, env, secret env, scaling, resource limits,
service account or agent identity, build spec, KMS key). Unknown fields stay
raw Json and are sent back unchanged.
Not here: sessions, memories, sandboxes (other modules), A2A endpoints
(`a2a`, `a2aTasks`, owner: adk), `examples` and `feedbackEntries` (v1beta1,
not implemented, see Gaps).
Also (v1beta1, added to close the gap list): the A2A gateway of an engine and
of a runtime revision (agent card, extended card, tasks, push notification
configs, cancel, subscribe, message send and stream, plain and `v1` routes),
`a2aTasks` (create, get, list, delete, appendEvents, events), the A2A task
store (`taskStores/.../a2aTaskRecords` and the store's operations),
`feedbackEntries` (list, get, create, patch, delete, feedback context) and
the operations of runtime revisions, examples, feedback entries and task
stores. Every v1 row also exists in v1beta1 (`AgentRuntime(beta=true)`).
Not here: sessions, memories, sandboxes (other modules). `examples` has no
method of its own in Discovery, only `operations` (get, cancel, wait,
delete), wrapped here.
## 2. Module map
@@ -26,7 +35,10 @@ not implemented, see Gaps).
| `calls.h/.cpp` | The ONE table of REST calls (`kCalls`) and used schema fields (`kSchemas`); `render`, `method_of`, `endpoint_of` |
| `deployment_spec.h/.cpp` | `EngineSpec`, `DeploymentSpec`, `PackageSpec`, `ContainerSpec`, `SourceCodeSpec`, `IdentityType` (validate, to/from Json, updateMask parts) |
| `engine.h/.cpp` | `Engine` (response), `EngineDraft` (create), `EngineUpdate` (patch with derived `updateMask`) |
| `agent_runtime.h/.cpp` | `AgentRuntime : Service`, `Revision` |
| `agent_runtime.h/.cpp` | `AgentRuntime : Service`, `Revision`; `beta` flag selects the v1beta1 twin of every v1 row |
| `operation_calls.h/.cpp` | `OperationCalls`: get, list, cancel, wait (server side), delete for the operations of an engine, revision, example, feedback entry or task store; the name must belong to the scope |
| `feedback.h/.cpp` | `FeedbackEntry`, `RuntimeFeedback`: `feedbackEntries` and the feedback context |
| `a2a.h/.cpp` | `RuntimeA2a`: A2A gateway (`A2aRequest`: target, protocol, op), `a2aTasks`, `a2aTaskRecords`; `A2aTaskInfo` |
| `tools/check_discovery.py` | Fails when any row of the call table or schema table is absent from Google's Discovery documents |
## 3. Static caps
@@ -42,7 +54,11 @@ not implemented, see Gaps).
| query input / execute inputs / policy | 1 MiB serialized |
| classMethod | 1..64 of `[A-Za-z0-9_]` |
| list filter | 512 chars; page size 50, 20 pages max |
| stream events delivered | 5000 (example route: 100) |
| stream events delivered | 5000 (example route: 100); A2A stream 5000 |
| operations: server side wait / list pages | 1..600 s / 5 |
| feedback: text / labels / label chars / context | 4000 / 20 / 64 / 256 KiB |
| A2A: body / historyLength / task id | 1 MiB / 0..1000 / 1..63 of `[a-z0-9-]` on create |
| A2A list pages / items returned | 20 / 2000 |
| updateMask | 512 chars |
| wait for an operation | 600 s / 400 polls (`operation.h`), multi-day work uses `*_start` plus `operation()` |
| ids | `valid_segment`; operation names must start `projects/`, no `..` or `?` |
@@ -67,12 +83,32 @@ not implemented, see Gaps).
`reasoningEngines.query` through a Cloud Run or Workflows target. Nothing
is implemented for it; this is not an API of this part.
- A2A gateway tails are never free text: `(target, protocol, op)` selects the
Discovery rpc and builds the `a2aEndpoint` tail (`card`, `tasks/{id}`,
`v1/message`, ...). `tools/check_discovery.py` compares each tail shape with
the `a2aEndpoint` pattern Discovery declares for that rpc.
- `GET ...:subscribe` answers server-sent events; the foundation only streams
POSTs, so `subscribe()` returns one JSON document or raises `BAD_RESPONSE`.
- Deleting a feedback entry, task, task record or operation record needs
`confirm=true` (library) and is a dry run in the example.
- The project-less forms `aiplatform.reasoningEngines.*` (`/v1/reasoningEngines`
with a `parent` query parameter) are only other URLs of the same RPCs; the
checker requires the same HTTP method and request schema as the covered
`projects.locations` row and counts them as covered.
## 5. Example routes (`/agent/runtime`)
GET `/agent/runtime` (page), `/status`, `/calls` (the call table). POST
`/list`, `/get`, `/create` (starts, answers 202 and the operation name),
`/operation`, `/query`, `/stream`, `/async`, `/delete`. No credential: 503
`google_not_configured`; bad input: 422; oversize body: 413.
`/operation`, `/query`, `/stream`, `/async`, `/delete`, and the extended
routes `/operations` (get, list, cancel, wait, delete for every scope),
`/revisions` (get, list, delete, query, stream), `/update`, `/iam` (get, test,
set), `/code`, `/async/cancel`, `/feedback` (list, get, create, patch, delete,
context, context_update), `/a2a` (gateway: target, protocol, op), `/a2a/tasks`
and `/a2a/records` (create, get, list, delete, append, events). Input is
validated first (422), then a credential is required (503
`google_not_configured`); destructive actions are dry runs unless
`"confirm":true`; oversize body: 413.
## Sources
@@ -89,9 +125,19 @@ GET `/agent/runtime` (page), `/status`, `/calls` (the call table). POST
## Verified against discovery
`python3 -I src/google/runtime/tools/check_discovery.py`, run 2026-10-24:
`discovery ok: 22 calls, 20 schemas, revisions v1 20261012, v1beta1 20261012`.
`discovery ok: 103 calls, 30 schemas, 214 owned discovery methods covered,
revisions v1 20261012, v1beta1 20261012`.
Checks HTTP method, path, rpc id, query parameters, request body fields and
every schema field the code reads or writes. Findings it caught or confirmed:
every schema field the code reads or writes, and three more things:
- twin: every v1 row exists in v1beta1 with the same method, path, rpc id,
query parameters and body fields (`AgentRuntime(beta=true)`);
- a2aEndpoint: the tail the code builds for each of the 40 A2A gateway rows
equals the `a2aEndpoint` pattern Discovery declares for that rpc
(`^card$`, `^v1/tasks/[^/]+$`, `^message$`, ...);
- coverage: every method under `reasoningEngines` and `taskStores` (v1 and
v1beta1) is a row, a twin, a project-less alias of a row (same method and
request schema), or belongs to `sessions`, `memories` or `sandboxEnvironment*`
(other modules, `OTHER_MODULES`). A new Discovery method fails the check. Findings it caught or confirmed:
revision list items key is `reasoningEngineRuntimeRevisions` (not
`runtimeRevisions`), v1 `setIamPolicy` takes only `policy`, secret env uses
`secretRef{secret,version}`.
@@ -109,28 +155,63 @@ read-only (`MOLO_LIVE_NET=1`, test `runtime_live.read_only_calls`):
| `POST .../reasoningEngines/1234567890123:query` | 404 NOT_FOUND |
| `GET .../reasoningEngines/molo-does-not-exist` | 400 INVALID_ARGUMENT (ids are numeric) |
2026-10-24, service account OAuth token (project `lisa-448004`), read-only,
tests `runtime_live_extra.*` through the new classes:
| Call | Result |
|---|---|
| v1 and v1beta1 `reasoningEngines` list (`us-central1`) | 200 `{}` (no `reasoningEngines` key when empty) |
| `GET .../reasoningEngines/{missing}/operations` | 200 `{}` |
| `GET .../operations/1` under a missing engine | 404 "Operation ... not found" |
| `POST ...:getIamPolicy` on a missing engine | 404 "ReasoningEngine ... not found" |
| v1beta1 `runtimeRevisions`, `feedbackEntries`, `a2aTasks` list of a missing engine | 404 "Reasoning Engine [project number: ..., reasoning engine id: ...] is not found" |
| v1beta1 `.../a2a/card` and `.../a2a/v1/card` of a missing engine | 404 "The reasoning engine resource [...] is not found" (both routes exist) |
| v1beta1 `taskStores/{id}/a2aTaskRecords` list | 501 UNIMPLEMENTED "Operation is not implemented, or supported, or enabled." (the task store service is not enabled for the project) |
Everything else (create, patch, delete, streamQuery, asyncQuery, executeCode,
IAM, operations, revisions) is verified by discovery only: no OAuth token is
available and no resource may be created. Rerun:
`MOLO_LIVE_NET=1 GOOGLE_CLOUD_PROJECT=... GOOGLE_API_KEY=... make google-test`.
IAM set, feedback and task writes, revisions delete, operations cancel, wait
and delete, A2A calls that reach a live engine) is verified by discovery only:
no Agent Engine exists in the project and no resource may be created. Rerun:
`MOLO_LIVE_NET=1 GOOGLE_CLOUD_PROJECT=... GOOGLE_ACCESS_TOKEN=... make google-test`.
## Unverified
Settled on 2026-10-24: the v1beta1 `feedbackEntries`, `a2aTasks`, `a2a/...` and
revision routes exist and map a missing engine to 404 (table above); an OAuth
token works for the reads (the express key was only proven for list/get/query).
- Whether the create/patch operation `response` is a `ReasoningEngine` with
`name` (discovery types it as `Any`; `create` fails loudly with 502
`BAD_RESPONSE` if no name is present).
`BAD_RESPONSE` if no name is present). Needs a create; none is allowed. The
Veo operation `response` was seen live (`@type` plus payload fields, see the
models SPEC), so the `Any` convention is real, but the engine one is not seen.
- The streamQuery wire format (discovery: `HttpBody`; decoded as plain JSON
or SSE by the foundation decoder).
or SSE by the foundation decoder). Needs a deployed engine.
- Nested `updateMask` names such as `spec.deploymentSpec` (FieldMask dotted
syntax per docs; not exercised, no write credential).
- That an express key can call any mutating method (list/get/query do work).
- `executeCode` chunk shape (`Chunk`) is passed through as raw Json.
- The A2A gateway answers (agent card, task, message) are the agent's own A2A
JSON and stay raw; none was seen because no engine exists. `message:stream`
is read as SSE/JSON events like `streamQuery`.
- `GET ...:subscribe` is a server-sent-event stream on a GET; the foundation
streams POSTs only, so `subscribe()` was not exercised against a stream.
- `feedbackEntries`/`a2aTasks` create semantics beyond the schema: required
fields, the id Google assigns, ttl format, `generation` handling in
`appendEvents`, and the `view` values of `a2aTasks.get`. Writes are not run.
- The task store (`taskStores/.../a2aTaskRecords`): the service answers 501 in
this project, so nothing about it is seen beyond Discovery.
- The feedback context path `.../feedbackEntries/{id}/feedbackContext` is
taken from the Discovery `name` pattern, not from a live response.
## Gaps
- v1beta1 `examples`, `feedbackEntries` and `a2a*` resources are not typed
here (A2A belongs to adk).
- `trafficConfig`, `revisionGarbageCollectionStrategy` (v1beta1 engine
fields) travel as raw `extra` only on the v1beta1 revision path; the v1
`Engine` does not carry them.
fields) are readable from `Engine::raw` with `AgentRuntime(beta=true)` but
`EngineDraft`/`EngineUpdate` do not write them (owner: `engine.cpp`).
- Responses of the A2A gateway are raw Json (the agent defines them), not
typed structs.
- `:subscribe` (GET server-sent events) needs a streaming GET in the
foundation `GoogleClient` (foundation gap); `RuntimeA2a::subscribe` returns
one JSON document or `BAD_RESPONSE`.
- No OAuth refresh (foundation gap).
+343
View File
@@ -0,0 +1,343 @@
#include "google/runtime/a2a.h"
#include "clients/url.h"
#include "google/errors.h"
#include "google/operation.h"
namespace molo::google::runtime {
using clients::body::Json;
namespace {
std::string str(const Json& doc, const char* key) {
const Json* v = doc.is_object() ? doc.find(key) : nullptr;
return v && v->is_string() ? v->as_string() : std::string();
}
void check_size(const Json& j, const char* what) {
if (j.dump().size() > A2aCaps::kMaxBodyBytes)
throw GoogleError::invalid(std::string(what) + " over " +
std::to_string(A2aCaps::kMaxBodyBytes) + " bytes");
}
void check_filter(const std::string& filter, const std::string& order_by) {
if (filter.size() > 512) throw GoogleError::invalid("filter over 512 characters");
if (order_by.size() > 128) throw GoogleError::invalid("orderBy over 128 characters");
}
void check_segment(const std::string& id, const char* what) {
if (!valid_segment(id)) throw GoogleError::invalid(std::string("bad ") + what);
}
std::string enc(const std::string& s) { return clients::Url::encode_component(s); }
void set_if(Json& o, const char* key, const std::string& v) {
if (!v.empty()) o.set(key, Json(v));
}
} // namespace
bool A2aRequest::is_get() const {
return op != A2aOp::kTaskCancel && op != A2aOp::kMessageSend && op != A2aOp::kMessageStream;
}
void A2aTaskInfo::validate() const {
if (context_id.size() > 256 || app_id.size() > 256 || user_id.size() > 256 ||
ttl.size() > 32 || expire_time.size() > 64)
throw GoogleError::invalid("task field too long");
if (!metadata.is_null()) {
if (!metadata.is_object()) throw GoogleError::invalid("metadata must be an object");
check_size(metadata, "metadata");
}
}
Json A2aTaskInfo::to_json() const {
validate();
Json o = Json::object();
set_if(o, "contextId", context_id);
set_if(o, "appId", app_id);
set_if(o, "userId", user_id);
set_if(o, "ttl", ttl);
set_if(o, "expireTime", expire_time);
if (metadata.is_object()) o.set("metadata", metadata);
return o;
}
A2aTaskInfo A2aTaskInfo::from_json(const Json& doc) {
A2aTaskInfo t;
t.raw = doc;
t.name = str(doc, "name");
t.context_id = str(doc, "contextId");
t.app_id = str(doc, "appId");
t.user_id = str(doc, "userId");
t.ttl = str(doc, "ttl");
t.expire_time = str(doc, "expireTime");
t.create_time = str(doc, "createTime");
t.update_time = str(doc, "updateTime");
t.generation = str(doc, "generation");
if (const Json* s = doc.is_object() ? doc.find("state") : nullptr; s && s->is_string())
t.state = s->as_string();
else if (const Json* st = doc.is_object() ? doc.find("status") : nullptr; st && st->is_object())
t.state = str(*st, "state");
if (const Json* m = doc.is_object() ? doc.find("metadata") : nullptr; m && m->is_object())
t.metadata = *m;
return t;
}
RuntimeA2a::RuntimeA2a(std::shared_ptr<GoogleClient> client, CloudContext context)
: Service(std::move(client), endpoints::aiplatform_beta(context.location)),
context_(std::move(context)) {}
std::string RuntimeA2a::engine_name(const std::string& engine_id) const {
return context_.child("reasoningEngines", engine_id);
}
std::string RuntimeA2a::store_name(const std::string& store_id) const {
return context_.child("taskStores", store_id);
}
void RuntimeA2a::check_task_id(const std::string& id) {
if (id.empty() || id.size() > A2aCaps::kMaxTaskIdChars)
throw GoogleError::invalid("task id must be 1.." + std::to_string(A2aCaps::kMaxTaskIdChars) +
" characters");
for (std::size_t i = 0; i < id.size(); ++i) {
char c = id[i];
bool alnum = (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9');
if (!(alnum || (i > 0 && c == '-')))
throw GoogleError::invalid("task id must be lowercase letters, digits and hyphens, "
"starting with a letter or digit");
}
}
std::string RuntimeA2a::task_name(const std::string& engine_id, const std::string& task_id) const {
check_segment(task_id, "task id");
return engine_name(engine_id) + "/a2aTasks/" + task_id;
}
std::string RuntimeA2a::record_name(const std::string& store_id,
const std::string& record_id) const {
check_segment(record_id, "record id");
return store_name(store_id) + "/a2aTaskRecords/" + record_id;
}
Json RuntimeA2a::send(Call call, const std::string& target, const std::string& query,
const Json* body) const {
return client_->request(method_of(call), endpoint_of(call, context_.location, true),
render(call, target) + query, body);
}
// --- gateway -----------------------------------------------------------------
Call RuntimeA2a::call_of(A2aTarget target, A2aProtocol protocol, A2aOp op) {
int family = static_cast<int>(target) * 2 + static_cast<int>(protocol);
return static_cast<Call>(static_cast<int>(Call::kA2aEngineCard) + family * 10 +
static_cast<int>(op));
}
std::string RuntimeA2a::tail_of(const A2aRequest& r) {
std::string pre = r.protocol == A2aProtocol::kV1 ? "v1/" : "";
switch (r.op) {
case A2aOp::kCard: return pre + "card";
case A2aOp::kExtendedAgentCard: return pre + "extendedAgentCard";
case A2aOp::kTasks: return pre + "tasks";
case A2aOp::kTaskGet:
case A2aOp::kTaskCancel:
case A2aOp::kTaskSubscribe: return pre + "tasks/" + r.task_id;
case A2aOp::kPushConfigs: return pre + "tasks/" + r.task_id + "/pushNotificationConfigs";
case A2aOp::kPushConfigGet:
return pre + "tasks/" + r.task_id + "/pushNotificationConfigs/" + r.config_id;
case A2aOp::kMessageSend:
case A2aOp::kMessageStream: return pre + "message";
}
throw GoogleError::invalid("unknown A2A op");
}
std::string RuntimeA2a::path_of(const A2aRequest& r) const {
std::string target = engine_name(r.engine_id);
if (r.target == A2aTarget::kRevision) {
check_segment(r.revision_id, "revision id");
target += "/runtimeRevisions/" + r.revision_id;
} else if (!r.revision_id.empty()) {
throw GoogleError::invalid("revision id given for an engine target");
}
bool needs_task = r.op == A2aOp::kTaskGet || r.op == A2aOp::kTaskCancel ||
r.op == A2aOp::kTaskSubscribe || r.op == A2aOp::kPushConfigs ||
r.op == A2aOp::kPushConfigGet;
if (needs_task) check_segment(r.task_id, "task id");
else if (!r.task_id.empty()) throw GoogleError::invalid("task id given for an op without one");
if (r.op == A2aOp::kPushConfigGet) check_segment(r.config_id, "config id");
else if (!r.config_id.empty()) throw GoogleError::invalid("config id given for an op without one");
if (r.history_length < 0 || r.history_length > A2aCaps::kMaxHistoryLength)
throw GoogleError::invalid("historyLength outside 0.." +
std::to_string(A2aCaps::kMaxHistoryLength));
if (r.history_length > 0 && (!r.is_get() || r.op == A2aOp::kTaskSubscribe))
throw GoogleError::invalid("historyLength applies to GET ops without subscribe");
std::string path = render(call_of(r.target, r.protocol, r.op), target, tail_of(r));
if (r.history_length > 0) path += "?historyLength=" + std::to_string(r.history_length);
return path;
}
Json RuntimeA2a::call(const A2aRequest& r) const {
if (r.is_stream() || r.op == A2aOp::kTaskSubscribe)
throw GoogleError::invalid("use stream() or subscribe() for this op");
std::string path = path_of(r);
const Json* body = nullptr;
if (!r.is_get()) {
if (!r.body.is_object()) throw GoogleError::invalid("body must be an object");
check_size(r.body, "body");
body = &r.body;
}
Call c = call_of(r.target, r.protocol, r.op);
return client_->request(method_of(c), endpoint_of(c, context_.location, true), path, body);
}
std::size_t RuntimeA2a::stream(const A2aRequest& r, const GoogleClient::EventSink& sink) const {
if (!r.is_stream()) throw GoogleError::invalid("stream() takes the message stream op");
std::string path = path_of(r);
if (!r.body.is_object()) throw GoogleError::invalid("body must be an object");
check_size(r.body, "body");
Call c = call_of(r.target, r.protocol, r.op);
std::size_t n = 0;
client_->stream_json(endpoint_of(c, context_.location, true), path, r.body,
[&](const Json& e) {
++n;
return sink(e) && n < A2aCaps::kMaxStreamEvents;
});
return n;
}
Json RuntimeA2a::subscribe(const A2aRequest& r) const {
if (r.op != A2aOp::kTaskSubscribe) throw GoogleError::invalid("subscribe() takes the subscribe op");
Call c = call_of(r.target, r.protocol, r.op);
return client_->request(method_of(c), endpoint_of(c, context_.location, true), path_of(r));
}
// --- tasks and records ---------------------------------------------------------
std::vector<A2aTaskInfo> RuntimeA2a::list_items(Call call, const std::string& parent,
const std::string& key,
const std::string& filter,
const std::string& order_by) const {
check_filter(filter, order_by);
std::string path = render(call, parent) + "?pageSize=50";
if (!filter.empty()) path += "&filter=" + enc(filter);
if (!order_by.empty()) path += "&orderBy=" + enc(order_by);
Json items = list_all(*client_, endpoint_of(call, context_.location, true), path, key,
A2aCaps::kMaxListPages);
std::vector<A2aTaskInfo> out;
for (const Json& j : items.as_array()) {
if (out.size() >= A2aCaps::kMaxItemsReturned) break;
out.push_back(A2aTaskInfo::from_json(j));
}
return out;
}
A2aTaskInfo RuntimeA2a::create_task(const std::string& engine_id, const std::string& task_id,
const A2aTaskInfo& task) const {
check_task_id(task_id);
Json body = task.to_json();
return A2aTaskInfo::from_json(send(Call::kA2aTaskCreate, engine_name(engine_id),
"?a2aTaskId=" + enc(task_id), &body));
}
A2aTaskInfo RuntimeA2a::get_task(const std::string& engine_id, const std::string& task_id,
const std::string& view) const {
std::string q;
if (!view.empty()) {
if (view.size() > 64) throw GoogleError::invalid("bad view");
for (char c : view)
if (!((c >= 'A' && c <= 'Z') || c == '_')) throw GoogleError::invalid("bad view");
q = "?view=" + view;
}
return A2aTaskInfo::from_json(send(Call::kA2aTaskGet, task_name(engine_id, task_id), q));
}
std::vector<A2aTaskInfo> RuntimeA2a::list_tasks(const std::string& engine_id,
const std::string& filter,
const std::string& order_by) const {
return list_items(Call::kA2aTaskList, engine_name(engine_id), "a2aTasks", filter, order_by);
}
void RuntimeA2a::delete_task(const std::string& engine_id, const std::string& task_id,
bool confirm) const {
if (!confirm) throw GoogleError::invalid("deleting a task needs confirm=true");
send(Call::kA2aTaskDelete, task_name(engine_id, task_id));
}
namespace {
Json append_body(const Json& events, const std::string& generation) {
if (!events.is_array() || events.as_array().empty() || events.as_array().size() > 100)
throw GoogleError::invalid("events must be an array of 1..100 items");
check_size(events, "events");
if (generation.size() > 32) throw GoogleError::invalid("generation too long");
Json body = Json::object();
body.set("events", events);
if (!generation.empty()) body.set("generation", Json(generation));
return body;
}
} // namespace
Json RuntimeA2a::append_task_events(const std::string& engine_id, const std::string& task_id,
const Json& events, const std::string& generation) const {
Json body = append_body(events, generation);
return send(Call::kA2aTaskAppendEvents, task_name(engine_id, task_id), "", &body);
}
Json RuntimeA2a::list_task_events(const std::string& engine_id, const std::string& task_id,
const std::string& filter) const {
check_filter(filter, "");
return send(Call::kA2aTaskEventsList, task_name(engine_id, task_id),
"?pageSize=100" + (filter.empty() ? std::string() : "&filter=" + enc(filter)));
}
A2aTaskInfo RuntimeA2a::create_record(const std::string& store_id, const std::string& record_id,
const A2aTaskInfo& record) const {
std::string q;
if (!record_id.empty()) {
check_segment(record_id, "record id");
q = "?a2aTaskRecordId=" + enc(record_id);
}
Json body = record.to_json();
return A2aTaskInfo::from_json(send(Call::kTaskRecordCreate, store_name(store_id), q, &body));
}
A2aTaskInfo RuntimeA2a::get_record(const std::string& store_id, const std::string& record_id,
const std::string& view) const {
std::string q;
if (!view.empty()) {
if (view.size() > 64) throw GoogleError::invalid("bad view");
for (char c : view)
if (!((c >= 'A' && c <= 'Z') || c == '_')) throw GoogleError::invalid("bad view");
q = "?view=" + view;
}
return A2aTaskInfo::from_json(send(Call::kTaskRecordGet, record_name(store_id, record_id), q));
}
std::vector<A2aTaskInfo> RuntimeA2a::list_records(const std::string& store_id,
const std::string& filter,
const std::string& order_by) const {
return list_items(Call::kTaskRecordList, store_name(store_id), "a2aTaskRecords", filter,
order_by);
}
A2aTaskInfo RuntimeA2a::delete_record(const std::string& store_id, const std::string& record_id,
bool confirm) const {
if (!confirm) throw GoogleError::invalid("deleting a task record needs confirm=true");
return A2aTaskInfo::from_json(send(Call::kTaskRecordDelete, record_name(store_id, record_id)));
}
Json RuntimeA2a::append_record_events(const std::string& store_id, const std::string& record_id,
const Json& events, const std::string& generation) const {
Json body = append_body(events, generation);
return send(Call::kTaskRecordAppendEvents, record_name(store_id, record_id), "", &body);
}
Json RuntimeA2a::list_record_events(const std::string& store_id, const std::string& record_id,
const std::string& filter) const {
check_filter(filter, "");
return send(Call::kTaskRecordEventsList, record_name(store_id, record_id),
"?pageSize=100" + (filter.empty() ? std::string() : "&filter=" + enc(filter)));
}
} // namespace molo::google::runtime
+149
View File
@@ -0,0 +1,149 @@
#pragma once
// A2A on Agent Runtime (all v1beta1):
// - the A2A gateway of an engine or runtime revision: agent card, extended
// card, tasks, push notification configs, cancel, subscribe, message send
// and stream. Each (target, protocol, op) is one Discovery rpc; the
// `a2aEndpoint` tail is derived from the op (never free text), so it
// always matches the pattern Discovery declares (checked by
// tools/check_discovery.py).
// - `a2aTasks` of an engine (create, get, list, delete, appendEvents, events)
// - `a2aTaskRecords` of a task store (the same operations on a store)
// Responses of the gateway are the agent's own A2A JSON and stay raw.
#include <memory>
#include <string>
#include <vector>
#include "clients/body/json.h"
#include "google/resource.h"
#include "google/runtime/calls.h"
#include "google/runtime/operation_calls.h"
#include "google/service.h"
namespace molo::google::runtime {
struct A2aCaps {
static constexpr std::size_t kMaxBodyBytes = 1024 * 1024;
static constexpr int kMaxHistoryLength = 1000;
static constexpr std::size_t kMaxStreamEvents = 5000;
static constexpr int kMaxListPages = 20;
static constexpr std::size_t kMaxItemsReturned = 2000;
static constexpr std::size_t kMaxTaskIdChars = 63;
};
enum class A2aTarget { kEngine, kRevision };
enum class A2aProtocol { kPlain, kV1 }; // kV1: routes under .../a2a/v1/...
// Order matches the rows of calls.cpp (see Call::kA2aEngineCard).
enum class A2aOp {
kCard, kExtendedAgentCard, kTasks, kTaskGet, kPushConfigs, kPushConfigGet, kTaskCancel,
kTaskSubscribe, kMessageSend, kMessageStream,
};
struct A2aRequest {
A2aTarget target = A2aTarget::kEngine;
A2aProtocol protocol = A2aProtocol::kPlain;
A2aOp op = A2aOp::kCard;
std::string engine_id;
std::string revision_id; // required when target is kRevision
std::string task_id; // kTaskGet, kPushConfigs, kPushConfigGet, kTaskCancel, kTaskSubscribe
std::string config_id; // kPushConfigGet
int history_length = 0; // GET ops only; 0: not sent
clients::body::Json body = clients::body::Json::object(); // POST ops
bool is_get() const;
bool is_stream() const { return op == A2aOp::kMessageStream; }
};
// An A2A task of an engine (a2aTasks) or of a task store (a2aTaskRecords).
// Output only fields are read, never sent.
struct A2aTaskInfo {
std::string name;
std::string context_id;
std::string app_id;
std::string user_id;
std::string ttl;
std::string expire_time;
std::string state; // output only
std::string create_time;
std::string update_time;
std::string generation;
clients::body::Json metadata; // object or null
clients::body::Json raw;
void validate() const;
clients::body::Json to_json() const;
static A2aTaskInfo from_json(const clients::body::Json& doc);
};
class RuntimeA2a : public Service {
public:
RuntimeA2a(std::shared_ptr<GoogleClient> client, CloudContext context);
// --- gateway ----------------------------------------------------------
static Call call_of(A2aTarget target, A2aProtocol protocol, A2aOp op);
// The `a2aEndpoint` the op's rpc takes, e.g. "v1/tasks/t1".
static std::string tail_of(const A2aRequest& request);
std::string path_of(const A2aRequest& request) const; // validates everything
// Any op except stream and subscribe: one JSON answer.
clients::body::Json call(const A2aRequest& request) const;
// :stream (POST, server-sent events). Returns events delivered (capped).
std::size_t stream(const A2aRequest& request, const GoogleClient::EventSink& sink) const;
// :subscribe is a GET that answers server-sent events; the foundation only
// streams POSTs, so this returns the single JSON document of the reply and
// raises BAD_RESPONSE for an event stream (see SPEC Gaps).
clients::body::Json subscribe(const A2aRequest& request) const;
// --- a2aTasks of an engine ----------------------------------------------
A2aTaskInfo create_task(const std::string& engine_id, const std::string& task_id,
const A2aTaskInfo& task) const;
A2aTaskInfo get_task(const std::string& engine_id, const std::string& task_id,
const std::string& view = "") const;
std::vector<A2aTaskInfo> list_tasks(const std::string& engine_id,
const std::string& filter = "",
const std::string& order_by = "") const;
void delete_task(const std::string& engine_id, const std::string& task_id, bool confirm) const;
// events: array of A2aTaskEvent objects; generation guards concurrent writers.
clients::body::Json append_task_events(const std::string& engine_id, const std::string& task_id,
const clients::body::Json& events,
const std::string& generation = "") const;
clients::body::Json list_task_events(const std::string& engine_id, const std::string& task_id,
const std::string& filter = "") const;
// --- a2aTaskRecords of a task store ---------------------------------------
A2aTaskInfo create_record(const std::string& store_id, const std::string& record_id,
const A2aTaskInfo& record) const;
A2aTaskInfo get_record(const std::string& store_id, const std::string& record_id,
const std::string& view = "") const;
std::vector<A2aTaskInfo> list_records(const std::string& store_id,
const std::string& filter = "",
const std::string& order_by = "") const;
A2aTaskInfo delete_record(const std::string& store_id, const std::string& record_id,
bool confirm) const;
clients::body::Json append_record_events(const std::string& store_id,
const std::string& record_id,
const clients::body::Json& events,
const std::string& generation = "") const;
clients::body::Json list_record_events(const std::string& store_id,
const std::string& record_id,
const std::string& filter = "") const;
// Task ids Google accepts on create: 1..63 of [a-z0-9-], not starting with "-".
static void check_task_id(const std::string& id);
OperationCalls operations() const { return OperationCalls(client_, context_.location, true); }
std::string engine_name(const std::string& engine_id) const;
std::string store_name(const std::string& store_id) const;
private:
clients::body::Json send(Call call, const std::string& target, const std::string& query = "",
const clients::body::Json* body = nullptr) const;
std::vector<A2aTaskInfo> list_items(Call call, const std::string& parent,
const std::string& key, const std::string& filter,
const std::string& order_by) const;
std::string task_name(const std::string& engine_id, const std::string& task_id) const;
std::string record_name(const std::string& store_id, const std::string& record_id) const;
CloudContext context_;
};
} // namespace molo::google::runtime
+21 -9
View File
@@ -54,10 +54,16 @@ Revision Revision::from_json(const Json& doc) {
}
AgentRuntime::AgentRuntime(std::shared_ptr<GoogleClient> client, CloudContext context,
Sleeper sleeper)
: Service(std::move(client), endpoints::aiplatform(context.location)),
Sleeper sleeper, bool beta)
: Service(std::move(client), beta ? endpoints::aiplatform_beta(context.location)
: endpoints::aiplatform(context.location)),
context_(std::move(context)),
sleeper_(std::move(sleeper)) {}
sleeper_(std::move(sleeper)),
beta_(beta) {}
OperationCalls AgentRuntime::operations() const {
return OperationCalls(client_, context_.location, beta_);
}
std::string AgentRuntime::name_of(const std::string& id) const {
return context_.child("reasoningEngines", id);
@@ -78,13 +84,13 @@ std::string AgentRuntime::checked_operation(const std::string& name) {
Json AgentRuntime::send(Call call, const std::string& target, const std::string& query,
const Json* body) const {
std::string path = render(call, target) + query;
return client_->request(method_of(call), endpoint_of(call, context_.location), path, body);
return client_->request(method_of(call), endpoint_of(call, context_.location, beta_), path, body);
}
std::size_t AgentRuntime::stream_call(Call call, const std::string& target, const Json& body,
const GoogleClient::EventSink& sink) const {
std::size_t n = 0;
client_->stream_json(endpoint_of(call, context_.location), render(call, target), body,
client_->stream_json(endpoint_of(call, context_.location, beta_), render(call, target), body,
[&](const Json& event) {
++n;
bool more = sink(event);
@@ -98,7 +104,7 @@ Json AgentRuntime::list_items(Call call, const std::string& parent, const std::s
if (filter.size() > RuntimeCaps::kMaxFilterChars) throw GoogleError::invalid("filter too long");
std::string path = render(call, parent) + "?pageSize=50";
if (!filter.empty()) path += "&filter=" + enc(filter);
return list_all(*client_, endpoint_of(call, context_.location), path, key,
return list_all(*client_, endpoint_of(call, context_.location, beta_), path, key,
RuntimeCaps::kMaxListPages);
}
@@ -286,21 +292,27 @@ std::vector<Revision> AgentRuntime::list_revisions(const std::string& id) const
return out;
}
Operation AgentRuntime::destroy_revision_start(const std::string& id,
const std::string& revision) const {
return Operation::from_json(send(Call::kRevisionDelete, revision_of(id, revision)));
}
Operation AgentRuntime::destroy_revision(const std::string& id, const std::string& revision) const {
return finish(Operation::from_json(send(Call::kRevisionDelete, revision_of(id, revision))));
return finish(destroy_revision_start(id, revision));
}
Json AgentRuntime::query_revision(const std::string& id, const std::string& revision,
const Json& input, const std::string& class_method) const {
Json body = query_body(input, class_method);
return send(Call::kRevisionQuery, revision_of(id, revision), "", &body);
return send(beta_ ? Call::kRevisionQuery : Call::kRevisionQueryV1, revision_of(id, revision), "", &body);
}
std::size_t AgentRuntime::stream_query_revision(const std::string& id, const std::string& revision,
const Json& input,
const GoogleClient::EventSink& sink,
const std::string& class_method) const {
return stream_call(Call::kRevisionStreamQuery, revision_of(id, revision),
return stream_call(beta_ ? Call::kRevisionStreamQuery : Call::kRevisionStreamQueryV1,
revision_of(id, revision),
query_body(input, class_method), sink);
}
+12 -1
View File
@@ -12,6 +12,7 @@
#include <vector>
#include "google/operation.h"
#include "google/runtime/operation_calls.h"
#include "google/resource.h"
#include "google/runtime/calls.h"
#include "google/runtime/engine.h"
@@ -31,10 +32,17 @@ struct Revision {
class AgentRuntime : public Service {
public:
// beta: send the v1beta1 twin of every v1 row (same methods, checked by
// tools/check_discovery.py). v1beta1 engines also carry trafficConfig and
// revisionGarbageCollectionStrategy, which travel as raw Json.
AgentRuntime(std::shared_ptr<GoogleClient> client, CloudContext context,
Sleeper sleeper = nullptr);
Sleeper sleeper = nullptr, bool beta = false);
const CloudContext& context() const { return context_; }
bool beta() const { return beta_; }
// get/list/cancel/wait/delete for the operations of an engine, revision,
// example, feedback entry or task store.
OperationCalls operations() const;
// --- engines (v1) ---------------------------------------------------
Operation create_start(const EngineDraft& draft) const;
@@ -84,6 +92,8 @@ class AgentRuntime : public Service {
Revision get_revision(const std::string& id, const std::string& revision) const;
std::vector<Revision> list_revisions(const std::string& id) const;
Operation destroy_revision(const std::string& id, const std::string& revision) const;
// Starts the delete and returns the Operation without waiting.
Operation destroy_revision_start(const std::string& id, const std::string& revision) const;
clients::body::Json query_revision(const std::string& id, const std::string& revision,
const clients::body::Json& input,
const std::string& class_method = "query") const;
@@ -107,6 +117,7 @@ class AgentRuntime : public Service {
CloudContext context_;
Sleeper sleeper_;
bool beta_;
};
} // namespace molo::google::runtime
+113 -3
View File
@@ -31,6 +31,87 @@ static const CallSpec kCalls[] = {
{Call::kRevisionDelete, "DELETE", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.delete", "", ""},
{Call::kRevisionQuery, "POST", "v1beta1/{+name}:query", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.query", "input,classMethod", ""},
{Call::kRevisionStreamQuery, "POST", "v1beta1/{+name}:streamQuery", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.streamQuery", "input,classMethod", ""},
{Call::kOperationWait, "POST", "v1/{+name}:wait", "v1", "aiplatform.projects.locations.reasoningEngines.operations.wait", "", "timeout"},
{Call::kRevisionQueryV1, "POST", "v1/{+name}:query", "v1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.query", "input,classMethod", ""},
{Call::kRevisionStreamQueryV1, "POST", "v1/{+name}:streamQuery", "v1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.streamQuery", "input,classMethod", ""},
{Call::kRevisionOperationGet, "GET", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.operations.get", "", ""},
{Call::kRevisionOperationList, "GET", "v1beta1/{+name}/operations", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.operations.list", "", "returnPartialSuccess,pageSize,pageToken,filter"},
{Call::kRevisionOperationCancel, "POST", "v1beta1/{+name}:cancel", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.operations.cancel", "", ""},
{Call::kRevisionOperationWait, "POST", "v1beta1/{+name}:wait", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.operations.wait", "", "timeout"},
{Call::kRevisionOperationDelete, "DELETE", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.operations.delete", "", ""},
{Call::kExampleOperationGet, "GET", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.examples.operations.get", "", ""},
{Call::kExampleOperationCancel, "POST", "v1beta1/{+name}:cancel", "v1beta1", "aiplatform.projects.locations.reasoningEngines.examples.operations.cancel", "", ""},
{Call::kExampleOperationWait, "POST", "v1beta1/{+name}:wait", "v1beta1", "aiplatform.projects.locations.reasoningEngines.examples.operations.wait", "", "timeout"},
{Call::kExampleOperationDelete, "DELETE", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.examples.operations.delete", "", ""},
{Call::kFeedbackList, "GET", "v1beta1/{+parent}/feedbackEntries", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.list", "", "filter,orderBy,pageToken,pageSize"},
{Call::kFeedbackCreate, "POST", "v1beta1/{+parent}/feedbackEntries", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.create", "eventId,source,createTime,sessionId,userId,feedbackType,feedbackText,feedbackLabels,name,updateTime,customMetadata", ""},
{Call::kFeedbackGet, "GET", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.get", "", ""},
{Call::kFeedbackPatch, "PATCH", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.patch", "eventId,source,createTime,sessionId,userId,feedbackType,feedbackText,feedbackLabels,name,updateTime,customMetadata", "updateMask"},
{Call::kFeedbackDelete, "DELETE", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.delete", "", ""},
{Call::kFeedbackUpdateContext, "PATCH", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.updateFeedbackContext", "name,contextEvents", "updateMask"},
{Call::kFeedbackGetContext, "GET", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.getFeedbackContext", "", ""},
{Call::kFeedbackOperationGet, "GET", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.operations.get", "", ""},
{Call::kFeedbackOperationList, "GET", "v1beta1/{+name}/operations", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.operations.list", "", "pageSize,returnPartialSuccess,pageToken,filter"},
{Call::kFeedbackOperationCancel, "POST", "v1beta1/{+name}:cancel", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.operations.cancel", "", ""},
{Call::kFeedbackOperationWait, "POST", "v1beta1/{+name}:wait", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.operations.wait", "", "timeout"},
{Call::kFeedbackOperationDelete, "DELETE", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.operations.delete", "", ""},
{Call::kA2aTaskCreate, "POST", "v1beta1/{+parent}/a2aTasks", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2aTasks.create", "ttl,createTime,state,metadata,updateTime,userId,artifacts,nextEventSequenceNumber,appId,statusDetails,output,contextId,history,expireTime,generation,name,status", "a2aTaskId"},
{Call::kA2aTaskAppendEvents, "POST", "v1beta1/{+name}:appendEvents", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2aTasks.appendEvents", "generation,taskEvents,events", ""},
{Call::kA2aTaskDelete, "DELETE", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2aTasks.delete", "", ""},
{Call::kA2aTaskList, "GET", "v1beta1/{+parent}/a2aTasks", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2aTasks.list", "", "pageSize,filter,orderBy,pageToken"},
{Call::kA2aTaskGet, "GET", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2aTasks.get", "", "view"},
{Call::kA2aTaskEventsList, "GET", "v1beta1/{+parent}/events", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2aTasks.events.list", "", "pageSize,pageToken,filter,orderBy"},
{Call::kTaskRecordCreate, "POST", "v1beta1/{+parent}/a2aTaskRecords", "v1beta1", "aiplatform.projects.locations.taskStores.a2aTaskRecords.create", "deleteTime,generation,expireTime,appId,userId,artifacts,ttl,name,metadata,updateTime,purgeTime,createTime,contextId,status,serviceMetadata,history", "a2aTaskRecordId"},
{Call::kTaskRecordAppendEvents, "POST", "v1beta1/{+name}:appendEvents", "v1beta1", "aiplatform.projects.locations.taskStores.a2aTaskRecords.appendEvents", "events,generation", ""},
{Call::kTaskRecordDelete, "DELETE", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.taskStores.a2aTaskRecords.delete", "", ""},
{Call::kTaskRecordList, "GET", "v1beta1/{+parent}/a2aTaskRecords", "v1beta1", "aiplatform.projects.locations.taskStores.a2aTaskRecords.list", "", "orderBy,pageToken,filter,pageSize"},
{Call::kTaskRecordGet, "GET", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.taskStores.a2aTaskRecords.get", "", "view"},
{Call::kA2aEngineCard, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.card", "", "historyLength"},
{Call::kA2aEngineExtendedAgentCard, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.extendedAgentCard", "", "historyLength"},
{Call::kA2aEngineTasks, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.tasks", "", "historyLength"},
{Call::kA2aEngineTasksGetEngine, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.tasks.a2aGetReasoningEngine", "", "historyLength"},
{Call::kA2aEngineTasksPushConfigs, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.tasks.pushNotificationConfigs", "", "historyLength"},
{Call::kA2aEngineTasksPushConfigsGetEngine, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.tasks.pushNotificationConfigs.a2aGetReasoningEngine", "", "historyLength"},
{Call::kA2aEngineTasksCancel, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:cancel", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.tasks.cancel", "", ""},
{Call::kA2aEngineTasksSubscribe, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}:subscribe", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.tasks.subscribe", "", ""},
{Call::kA2aEngineMessageSend, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:send", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.message.send", "", ""},
{Call::kA2aEngineMessageStream, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:stream", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.message.stream", "", ""},
{Call::kA2aEngineV1Card, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.card", "", "historyLength"},
{Call::kA2aEngineV1ExtendedAgentCard, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.extendedAgentCard", "", "historyLength"},
{Call::kA2aEngineV1Tasks, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.tasks", "", "historyLength"},
{Call::kA2aEngineV1TasksGetEngine, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.tasks.a2aGetReasoningEngine", "", "historyLength"},
{Call::kA2aEngineV1TasksPushConfigs, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.tasks.pushNotificationConfigs", "", "historyLength"},
{Call::kA2aEngineV1TasksPushConfigsGetEngine, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.tasks.pushNotificationConfigs.a2aGetReasoningEngine", "", "historyLength"},
{Call::kA2aEngineV1TasksCancel, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:cancel", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.tasks.cancel", "", ""},
{Call::kA2aEngineV1TasksSubscribe, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}:subscribe", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.tasks.subscribe", "", ""},
{Call::kA2aEngineV1MessageSend, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:send", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.message.send", "", ""},
{Call::kA2aEngineV1MessageStream, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:stream", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.message.stream", "", ""},
{Call::kA2aRevisionCard, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.card", "", "historyLength"},
{Call::kA2aRevisionExtendedAgentCard, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.extendedAgentCard", "", "historyLength"},
{Call::kA2aRevisionTasks, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.tasks", "", "historyLength"},
{Call::kA2aRevisionTasksGetEngine, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.tasks.a2aGetReasoningEngine", "", "historyLength"},
{Call::kA2aRevisionTasksPushConfigs, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.tasks.pushNotificationConfigs", "", "historyLength"},
{Call::kA2aRevisionTasksPushConfigsGetEngine, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.tasks.pushNotificationConfigs.a2aGetReasoningEngine", "", "historyLength"},
{Call::kA2aRevisionTasksCancel, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:cancel", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.tasks.cancel", "", ""},
{Call::kA2aRevisionTasksSubscribe, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}:subscribe", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.tasks.subscribe", "", ""},
{Call::kA2aRevisionMessageSend, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:send", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.message.send", "", ""},
{Call::kA2aRevisionMessageStream, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:stream", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.message.stream", "", ""},
{Call::kA2aRevisionV1Card, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.card", "", "historyLength"},
{Call::kA2aRevisionV1ExtendedAgentCard, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.extendedAgentCard", "", "historyLength"},
{Call::kA2aRevisionV1Tasks, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.tasks", "", "historyLength"},
{Call::kA2aRevisionV1TasksGetEngine, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.tasks.a2aGetReasoningEngine", "", "historyLength"},
{Call::kA2aRevisionV1TasksPushConfigs, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.tasks.pushNotificationConfigs", "", "historyLength"},
{Call::kA2aRevisionV1TasksPushConfigsGetEngine, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.tasks.pushNotificationConfigs.a2aGetReasoningEngine", "", "historyLength"},
{Call::kA2aRevisionV1TasksCancel, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:cancel", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.tasks.cancel", "", ""},
{Call::kA2aRevisionV1TasksSubscribe, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}:subscribe", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.tasks.subscribe", "", ""},
{Call::kA2aRevisionV1MessageSend, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:send", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.message.send", "", ""},
{Call::kA2aRevisionV1MessageStream, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:stream", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.message.stream", "", ""},
{Call::kTaskStoreOperationGet, "GET", "v1/{+name}", "v1", "aiplatform.projects.locations.taskStores.operations.get", "", ""},
{Call::kTaskStoreOperationList, "GET", "v1/{+name}/operations", "v1", "aiplatform.projects.locations.taskStores.operations.list", "", "returnPartialSuccess,pageToken,filter,pageSize"},
{Call::kTaskStoreOperationCancel, "POST", "v1/{+name}:cancel", "v1", "aiplatform.projects.locations.taskStores.operations.cancel", "", ""},
{Call::kTaskStoreOperationWait, "POST", "v1/{+name}:wait", "v1", "aiplatform.projects.locations.taskStores.operations.wait", "", "timeout"},
{Call::kTaskStoreOperationDelete, "DELETE", "v1/{+name}", "v1", "aiplatform.projects.locations.taskStores.operations.delete", "", ""},
{Call::kTaskRecordEventsList, "GET", "v1beta1/{+parent}/events", "v1beta1", "aiplatform.projects.locations.taskStores.a2aTaskRecords.events.list", "", "filter,orderBy,pageSize,pageToken"},
};
// CALLS-END
@@ -56,6 +137,16 @@ static const SchemaFields kSchemas[] = {
{"ListReasoningEngineRuntimeRevisionsResponse", "v1beta1", "reasoningEngineRuntimeRevisions,nextPageToken"},
{"ReasoningEngineSpecDeploymentSpec", "v1beta1", "agentServerMode"},
{"ReasoningEngineSpec", "v1beta1", "agentCard"},
{"FeedbackEntry", "v1beta1", "name,eventId,source,createTime,updateTime,sessionId,userId,feedbackType,feedbackText,feedbackLabels,customMetadata"},
{"FeedbackContext", "v1beta1", "name,contextEvents"},
{"ListFeedbackEntriesResponse", "v1beta1", "feedbackEntries,nextPageToken"},
{"A2aTask", "v1beta1", "name,ttl,createTime,state,metadata,updateTime,userId,nextEventSequenceNumber,appId,statusDetails,output,contextId,expireTime,generation,status"},
{"ListA2aTasksResponse", "v1beta1", "a2aTasks,nextPageToken"},
{"ListA2aTaskEventsResponse", "v1beta1", "events,nextPageToken,taskEvents"},
{"AppendA2aTaskEventsResponse", "v1beta1", "generation"},
{"A2ATaskRecord", "v1beta1", "name,ttl,metadata,createTime,updateTime,userId,appId,contextId,status,serviceMetadata,generation,expireTime"},
{"ListA2ATaskRecordsResponse", "v1beta1", "a2aTaskRecords,nextPageToken"},
{"AppendA2ATaskRecordEventsResponse", "v1beta1", "generation"},
};
// SCHEMAS-END
@@ -73,19 +164,38 @@ clients::Method method_of(Call call) {
return clients::Method::kDelete;
}
ServiceEndpoint endpoint_of(Call call, const std::string& location) {
return std::strcmp(spec_of(call).version, "v1beta1") == 0
std::size_t call_count() { return sizeof(kCalls) / sizeof(kCalls[0]); }
const CallSpec& spec_at(std::size_t index) {
if (index >= call_count()) throw GoogleError::invalid("call index out of range");
return kCalls[index];
}
ServiceEndpoint endpoint_of(Call call, const std::string& location, bool beta) {
return beta || std::strcmp(spec_of(call).version, "v1beta1") == 0
? endpoints::aiplatform_beta(location)
: endpoints::aiplatform(location);
}
std::string render(Call call, const std::string& target) {
std::string render(Call call, const std::string& target, const std::string& tail) {
std::string path = spec_of(call).path;
path.erase(0, path.find('/') + 1); // drop the version prefix; the endpoint has it
for (const char* key : {"{+name}", "{+parent}", "{+resource}"}) {
auto at = path.find(key);
if (at != std::string::npos) path.replace(at, std::strlen(key), target);
}
auto at = path.find("{+a2aEndpoint}");
if (at != std::string::npos) {
if (tail.empty() || tail.size() > 256 || tail.find("..") != std::string::npos ||
tail.front() == '/' || tail.back() == '/')
throw GoogleError::invalid("a2a endpoint must be 1..256 characters, no leading or "
"trailing slash, no ..");
for (char c : tail)
if (!((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') ||
c == '.' || c == '_' || c == '-' || c == '/' || c == ':'))
throw GoogleError::invalid("a2a endpoint has invalid characters");
path.replace(at, std::strlen("{+a2aEndpoint}"), tail);
}
return "/" + path;
}
+38 -4
View File
@@ -16,6 +16,34 @@ enum class Call {
kCancelAsyncQuery, kExecuteCode, kGetIamPolicy, kSetIamPolicy, kTestIamPermissions,
kOperationGet, kOperationList, kOperationCancel, kOperationDelete,
kRevisionGet, kRevisionList, kRevisionDelete, kRevisionQuery, kRevisionStreamQuery,
// Rows below were added from Discovery to close the gap list. Families of
// A2A gateway calls: Engine/EngineV1 hang off an engine, Revision/RevisionV1
// off a runtime revision; the V1 forms are `.../a2a/v1/...` routes.
kOperationWait, kRevisionQueryV1, kRevisionStreamQueryV1, kRevisionOperationGet,
kRevisionOperationList, kRevisionOperationCancel, kRevisionOperationWait,
kRevisionOperationDelete, kExampleOperationGet, kExampleOperationCancel,
kExampleOperationWait, kExampleOperationDelete, kFeedbackList, kFeedbackCreate, kFeedbackGet,
kFeedbackPatch, kFeedbackDelete, kFeedbackUpdateContext, kFeedbackGetContext,
kFeedbackOperationGet, kFeedbackOperationList, kFeedbackOperationCancel,
kFeedbackOperationWait, kFeedbackOperationDelete, kA2aTaskCreate, kA2aTaskAppendEvents,
kA2aTaskDelete, kA2aTaskList, kA2aTaskGet, kA2aTaskEventsList, kTaskRecordCreate,
kTaskRecordAppendEvents, kTaskRecordDelete, kTaskRecordList, kTaskRecordGet, kA2aEngineCard,
kA2aEngineExtendedAgentCard, kA2aEngineTasks, kA2aEngineTasksGetEngine,
kA2aEngineTasksPushConfigs, kA2aEngineTasksPushConfigsGetEngine, kA2aEngineTasksCancel,
kA2aEngineTasksSubscribe, kA2aEngineMessageSend, kA2aEngineMessageStream, kA2aEngineV1Card,
kA2aEngineV1ExtendedAgentCard, kA2aEngineV1Tasks, kA2aEngineV1TasksGetEngine,
kA2aEngineV1TasksPushConfigs, kA2aEngineV1TasksPushConfigsGetEngine, kA2aEngineV1TasksCancel,
kA2aEngineV1TasksSubscribe, kA2aEngineV1MessageSend, kA2aEngineV1MessageStream,
kA2aRevisionCard, kA2aRevisionExtendedAgentCard, kA2aRevisionTasks,
kA2aRevisionTasksGetEngine, kA2aRevisionTasksPushConfigs,
kA2aRevisionTasksPushConfigsGetEngine, kA2aRevisionTasksCancel, kA2aRevisionTasksSubscribe,
kA2aRevisionMessageSend, kA2aRevisionMessageStream, kA2aRevisionV1Card,
kA2aRevisionV1ExtendedAgentCard, kA2aRevisionV1Tasks, kA2aRevisionV1TasksGetEngine,
kA2aRevisionV1TasksPushConfigs, kA2aRevisionV1TasksPushConfigsGetEngine,
kA2aRevisionV1TasksCancel, kA2aRevisionV1TasksSubscribe, kA2aRevisionV1MessageSend,
kA2aRevisionV1MessageStream, kTaskStoreOperationGet, kTaskStoreOperationList,
kTaskStoreOperationCancel, kTaskStoreOperationWait, kTaskStoreOperationDelete,
kTaskRecordEventsList,
};
struct CallSpec {
@@ -36,10 +64,16 @@ struct SchemaFields {
const CallSpec& spec_of(Call call);
clients::Method method_of(Call call);
// Endpoint for the call's API version in a location.
ServiceEndpoint endpoint_of(Call call, const std::string& location);
// The table itself, for listing (demo, tests, conformance).
std::size_t call_count();
const CallSpec& spec_at(std::size_t index);
// Endpoint for the call's API version in a location. `beta` selects the
// v1beta1 twin of a v1 row (tools/check_discovery.py verifies every v1 row
// has the same method, path, rpc id and fields in v1beta1).
ServiceEndpoint endpoint_of(Call call, const std::string& location, bool beta = false);
// Path under the endpoint base: "/projects/.../reasoningEngines/x:query".
// `target` replaces the {+name}, {+parent} or {+resource} placeholder.
std::string render(Call call, const std::string& target);
// `target` replaces the {+name}, {+parent} or {+resource} placeholder; `tail`
// replaces {+a2aEndpoint} (validated: segments of [A-Za-z0-9._:-], no "..").
std::string render(Call call, const std::string& target, const std::string& tail = "");
} // namespace molo::google::runtime
+193
View File
@@ -0,0 +1,193 @@
#include "google/runtime/feedback.h"
#include "clients/url.h"
#include "google/errors.h"
namespace molo::google::runtime {
using clients::body::Json;
namespace {
std::string str(const Json& doc, const char* key) {
const Json* v = doc.is_object() ? doc.find(key) : nullptr;
return v && v->is_string() ? v->as_string() : std::string();
}
void check_field(const std::string& value, const char* what, std::size_t max) {
if (value.size() > max)
throw GoogleError::invalid(std::string(what) + " over " + std::to_string(max) + " characters");
}
void set_if(Json& o, const char* key, const std::string& v) {
if (!v.empty()) o.set(key, Json(v));
}
} // namespace
void FeedbackEntry::validate() const {
check_field(event_id, "eventId", FeedbackCaps::kMaxFieldChars);
check_field(source, "source", FeedbackCaps::kMaxFieldChars);
check_field(session_id, "sessionId", FeedbackCaps::kMaxFieldChars);
check_field(user_id, "userId", FeedbackCaps::kMaxFieldChars);
check_field(feedback_type, "feedbackType", FeedbackCaps::kMaxFieldChars);
check_field(feedback_text, "feedbackText", FeedbackCaps::kMaxTextChars);
if (feedback_labels.size() > FeedbackCaps::kMaxLabels)
throw GoogleError::invalid("more than " + std::to_string(FeedbackCaps::kMaxLabels) +
" feedback labels");
for (const std::string& l : feedback_labels) {
if (l.empty()) throw GoogleError::invalid("empty feedback label");
check_field(l, "feedback label", FeedbackCaps::kMaxLabelChars);
}
if (!custom_metadata.is_null() && !custom_metadata.is_object())
throw GoogleError::invalid("customMetadata must be an object");
if (custom_metadata.is_object() &&
custom_metadata.dump().size() > FeedbackCaps::kMaxContextBytes)
throw GoogleError::invalid("customMetadata too large");
}
Json FeedbackEntry::to_json() const {
validate();
Json o = Json::object();
set_if(o, "eventId", event_id);
set_if(o, "source", source);
set_if(o, "sessionId", session_id);
set_if(o, "userId", user_id);
set_if(o, "feedbackType", feedback_type);
set_if(o, "feedbackText", feedback_text);
if (!feedback_labels.empty()) {
Json arr = Json::array();
for (const std::string& l : feedback_labels) arr.push(Json(l));
o.set("feedbackLabels", arr);
}
if (custom_metadata.is_object()) o.set("customMetadata", custom_metadata);
return o;
}
std::string FeedbackEntry::update_mask() const {
std::string mask;
auto add = [&](bool set, const char* field) {
if (!set) return;
mask += (mask.empty() ? "" : ",") + std::string(field);
};
add(!event_id.empty(), "eventId");
add(!source.empty(), "source");
add(!session_id.empty(), "sessionId");
add(!user_id.empty(), "userId");
add(!feedback_type.empty(), "feedbackType");
add(!feedback_text.empty(), "feedbackText");
add(!feedback_labels.empty(), "feedbackLabels");
add(custom_metadata.is_object(), "customMetadata");
return mask;
}
FeedbackEntry FeedbackEntry::from_json(const Json& doc) {
FeedbackEntry e;
e.name = str(doc, "name");
e.event_id = str(doc, "eventId");
e.source = str(doc, "source");
e.session_id = str(doc, "sessionId");
e.user_id = str(doc, "userId");
e.feedback_type = str(doc, "feedbackType");
e.feedback_text = str(doc, "feedbackText");
e.create_time = str(doc, "createTime");
e.update_time = str(doc, "updateTime");
if (const Json* l = doc.is_object() ? doc.find("feedbackLabels") : nullptr; l && l->is_array())
for (const Json& x : l->as_array())
if (x.is_string()) e.feedback_labels.push_back(x.as_string());
if (const Json* m = doc.is_object() ? doc.find("customMetadata") : nullptr; m && m->is_object())
e.custom_metadata = *m;
return e;
}
RuntimeFeedback::RuntimeFeedback(std::shared_ptr<GoogleClient> client, CloudContext context,
bool beta)
: Service(std::move(client), endpoints::aiplatform_beta(context.location)),
context_(std::move(context)) {
(void)beta; // feedbackEntries exist in v1beta1 only
}
std::string RuntimeFeedback::engine_name(const std::string& engine_id) const {
return context_.child("reasoningEngines", engine_id);
}
std::string RuntimeFeedback::entry_name(const std::string& engine_id,
const std::string& entry_id) const {
if (!valid_segment(entry_id)) throw GoogleError::invalid("bad feedback entry id");
return engine_name(engine_id) + "/feedbackEntries/" + entry_id;
}
Json RuntimeFeedback::send(Call call, const std::string& target, const std::string& query,
const Json* body) const {
return client_->request(method_of(call), endpoint_, render(call, target) + query, body);
}
std::vector<FeedbackEntry> RuntimeFeedback::list(const std::string& engine_id,
const std::string& filter,
const std::string& order_by) const {
if (filter.size() > 512) throw GoogleError::invalid("filter over 512 characters");
if (order_by.size() > 128) throw GoogleError::invalid("orderBy over 128 characters");
std::string parent = engine_name(engine_id);
std::string q = "?pageSize=50";
if (!filter.empty()) q += "&filter=" + clients::Url::encode_component(filter);
if (!order_by.empty()) q += "&orderBy=" + clients::Url::encode_component(order_by);
Json items = list_all(*client_, endpoint_, render(Call::kFeedbackList, parent) + q,
"feedbackEntries", FeedbackCaps::kMaxListPages);
std::vector<FeedbackEntry> out;
for (const Json& j : items.as_array()) {
if (out.size() >= FeedbackCaps::kMaxEntriesReturned) break;
out.push_back(FeedbackEntry::from_json(j));
}
return out;
}
FeedbackEntry RuntimeFeedback::get(const std::string& engine_id,
const std::string& entry_id) const {
return FeedbackEntry::from_json(send(Call::kFeedbackGet, entry_name(engine_id, entry_id)));
}
Operation RuntimeFeedback::create(const std::string& engine_id, const FeedbackEntry& entry) const {
Json body = entry.to_json();
if (body.as_object().empty()) throw GoogleError::invalid("feedback entry has no fields");
return Operation::from_json(send(Call::kFeedbackCreate, engine_name(engine_id), "", &body));
}
Operation RuntimeFeedback::patch(const std::string& engine_id, const std::string& entry_id,
const FeedbackEntry& changes) const {
std::string mask = changes.update_mask();
if (mask.empty()) throw GoogleError::invalid("no feedback fields set to update");
Json body = changes.to_json();
std::string name = entry_name(engine_id, entry_id);
body.set("name", Json(name));
return Operation::from_json(send(Call::kFeedbackPatch, name,
"?updateMask=" + clients::Url::encode_component(mask), &body));
}
Operation RuntimeFeedback::destroy(const std::string& engine_id, const std::string& entry_id,
bool confirm) const {
if (!confirm) throw GoogleError::invalid("deleting feedback needs confirm=true");
return Operation::from_json(send(Call::kFeedbackDelete, entry_name(engine_id, entry_id)));
}
Json RuntimeFeedback::get_context(const std::string& engine_id,
const std::string& entry_id) const {
// The context is a child singleton of the entry: .../feedbackEntries/{id}/feedbackContext
return send(Call::kFeedbackGetContext, entry_name(engine_id, entry_id) + "/feedbackContext");
}
Operation RuntimeFeedback::update_context(const std::string& engine_id,
const std::string& entry_id,
const Json& context_events) const {
if (!context_events.is_array() || context_events.as_array().empty())
throw GoogleError::invalid("contextEvents must be a non-empty array");
if (context_events.dump().size() > FeedbackCaps::kMaxContextBytes)
throw GoogleError::invalid("contextEvents too large");
std::string name = entry_name(engine_id, entry_id) + "/feedbackContext";
Json body = Json::object();
body.set("name", Json(name));
body.set("contextEvents", context_events);
return Operation::from_json(send(Call::kFeedbackUpdateContext, name,
"?updateMask=contextEvents", &body));
}
} // namespace molo::google::runtime
+79
View File
@@ -0,0 +1,79 @@
#pragma once
// Feedback on an agent's conversations: the v1beta1 `feedbackEntries`
// resource of an engine and its feedback context. Create, patch, delete and
// context updates are long-running calls: they return the Operation.
#include <memory>
#include <string>
#include <vector>
#include "clients/body/json.h"
#include "google/operation.h"
#include "google/resource.h"
#include "google/runtime/operation_calls.h"
#include "google/service.h"
namespace molo::google::runtime {
struct FeedbackCaps {
static constexpr std::size_t kMaxTextChars = 4000;
static constexpr std::size_t kMaxLabels = 20;
static constexpr std::size_t kMaxLabelChars = 64;
static constexpr std::size_t kMaxFieldChars = 256; // ids, source, type
static constexpr std::size_t kMaxContextBytes = 256 * 1024;
static constexpr int kMaxListPages = 20;
static constexpr std::size_t kMaxEntriesReturned = 2000;
};
struct FeedbackEntry {
std::string name; // .../reasoningEngines/{e}/feedbackEntries/{id}
std::string event_id;
std::string source;
std::string session_id;
std::string user_id;
std::string feedback_type;
std::string feedback_text;
std::vector<std::string> feedback_labels;
clients::body::Json custom_metadata; // object or null
std::string create_time; // output only
std::string update_time; // output only
void validate() const;
// Writable fields only (output only fields are never sent).
clients::body::Json to_json() const;
// updateMask for the fields that are set, e.g. "feedbackText,feedbackLabels".
std::string update_mask() const;
static FeedbackEntry from_json(const clients::body::Json& doc);
};
class RuntimeFeedback : public Service {
public:
RuntimeFeedback(std::shared_ptr<GoogleClient> client, CloudContext context,
bool beta = true);
std::vector<FeedbackEntry> list(const std::string& engine_id, const std::string& filter = "",
const std::string& order_by = "") const;
FeedbackEntry get(const std::string& engine_id, const std::string& entry_id) const;
// entry_id may be empty (Google assigns one).
Operation create(const std::string& engine_id, const FeedbackEntry& entry) const;
Operation patch(const std::string& engine_id, const std::string& entry_id,
const FeedbackEntry& changes) const;
Operation destroy(const std::string& engine_id, const std::string& entry_id,
bool confirm) const;
// Context events are SessionEvent objects, kept as raw Json.
clients::body::Json get_context(const std::string& engine_id, const std::string& entry_id) const;
Operation update_context(const std::string& engine_id, const std::string& entry_id,
const clients::body::Json& context_events) const;
OperationCalls operations() const { return OperationCalls(client_, context_.location, true); }
std::string entry_name(const std::string& engine_id, const std::string& entry_id) const;
std::string engine_name(const std::string& engine_id) const;
private:
clients::body::Json send(Call call, const std::string& target, const std::string& query = "",
const clients::body::Json* body = nullptr) const;
CloudContext context_;
};
} // namespace molo::google::runtime
+139
View File
@@ -0,0 +1,139 @@
#include "google/runtime/operation_calls.h"
#include <cstring>
#include "clients/url.h"
#include "google/errors.h"
namespace molo::google::runtime {
using clients::body::Json;
namespace {
struct Set {
OperationScope scope;
const char* label;
const char* marker;
bool has_list;
Call get, list, cancel, wait, remove;
};
// list is unused for examples (Discovery has no examples.operations.list).
const Set kSets[] = {
{OperationScope::kEngine, "engine", "/reasoningEngines/", true, Call::kOperationGet,
Call::kOperationList, Call::kOperationCancel, Call::kOperationWait, Call::kOperationDelete},
{OperationScope::kRevision, "revision", "/runtimeRevisions/", true,
Call::kRevisionOperationGet, Call::kRevisionOperationList, Call::kRevisionOperationCancel,
Call::kRevisionOperationWait, Call::kRevisionOperationDelete},
{OperationScope::kExample, "example", "/examples/", false, Call::kExampleOperationGet,
Call::kExampleOperationGet, Call::kExampleOperationCancel, Call::kExampleOperationWait,
Call::kExampleOperationDelete},
{OperationScope::kFeedback, "feedback", "/feedbackEntries/", true,
Call::kFeedbackOperationGet, Call::kFeedbackOperationList, Call::kFeedbackOperationCancel,
Call::kFeedbackOperationWait, Call::kFeedbackOperationDelete},
{OperationScope::kTaskStore, "taskStore", "/taskStores/", true,
Call::kTaskStoreOperationGet, Call::kTaskStoreOperationList,
Call::kTaskStoreOperationCancel, Call::kTaskStoreOperationWait,
Call::kTaskStoreOperationDelete},
};
const Set& set_of(OperationScope scope) {
for (const Set& s : kSets)
if (s.scope == scope) return s;
throw GoogleError::invalid("unknown operation scope");
}
} // namespace
OperationCalls::OperationCalls(std::shared_ptr<GoogleClient> client, std::string location,
bool beta)
: client_(std::move(client)), location_(std::move(location)), beta_(beta) {}
OperationScope OperationCalls::scope_from(const std::string& name) {
// Most specific marker first: a revision lives under an engine.
for (OperationScope s : {OperationScope::kFeedback, OperationScope::kRevision,
OperationScope::kExample, OperationScope::kTaskStore,
OperationScope::kEngine})
if (name.find(set_of(s).marker) != std::string::npos) return s;
throw GoogleError::invalid("operation name is not under a runtime resource");
}
const char* OperationCalls::scope_name(OperationScope scope) { return set_of(scope).label; }
bool OperationCalls::has_list(OperationScope scope) { return set_of(scope).has_list; }
const std::string& OperationCalls::check(OperationScope scope, const std::string& name) {
if (name.rfind("projects/", 0) != 0 || name.size() > ScopedOperationCaps::kMaxNameChars ||
name.find("..") != std::string::npos || name.find('?') != std::string::npos ||
name.find('#') != std::string::npos)
throw GoogleError::invalid("bad operation name");
if (name.find(set_of(scope).marker) == std::string::npos ||
scope_from(name) != scope)
throw GoogleError::invalid(std::string("operation name is not under ") + set_of(scope).marker);
return name;
}
Call OperationCalls::call_for(OperationScope scope, const char* verb) {
const Set& s = set_of(scope);
if (!std::strcmp(verb, "get")) return s.get;
if (!std::strcmp(verb, "list")) return s.list;
if (!std::strcmp(verb, "cancel")) return s.cancel;
if (!std::strcmp(verb, "wait")) return s.wait;
if (!std::strcmp(verb, "delete")) return s.remove;
throw GoogleError::invalid("unknown operation verb");
}
Json OperationCalls::send(Call call, const std::string& target, const std::string& query) const {
return client_->request(method_of(call), endpoint_of(call, location_, beta_),
render(call, target) + query, nullptr);
}
Operation OperationCalls::get(OperationScope scope, const std::string& name) const {
return Operation::from_json(send(set_of(scope).get, check(scope, name)));
}
std::vector<Operation> OperationCalls::list(OperationScope scope, const std::string& parent,
const std::string& filter) const {
const Set& s = set_of(scope);
if (!s.has_list) throw GoogleError::invalid(std::string(s.label) + " operations cannot be listed");
if (parent.rfind("projects/", 0) != 0 || parent.size() > ScopedOperationCaps::kMaxNameChars ||
parent.find("..") != std::string::npos || parent.find('?') != std::string::npos ||
parent.find(s.marker) == std::string::npos)
throw GoogleError::invalid("bad parent resource name");
if (filter.size() > 256) throw GoogleError::invalid("filter over 256 characters");
std::vector<Operation> out;
std::string token;
for (int page = 0; page < ScopedOperationCaps::kMaxListPages; ++page) {
std::string q = "?pageSize=50";
if (!filter.empty()) q += "&filter=" + clients::Url::encode_component(filter);
if (!token.empty()) q += "&pageToken=" + clients::Url::encode_component(token);
Json reply = send(s.list, parent, q);
if (const Json* items = reply.find("operations"); items && items->is_array())
for (const Json& j : items->as_array()) out.push_back(Operation::from_json(j));
const Json* next = reply.find("nextPageToken");
if (!next || !next->is_string() || next->as_string().empty()) break;
token = next->as_string();
}
return out;
}
void OperationCalls::cancel(OperationScope scope, const std::string& name) const {
send(set_of(scope).cancel, check(scope, name));
}
Operation OperationCalls::wait(OperationScope scope, const std::string& name,
int timeout_seconds) const {
if (timeout_seconds < 1 || timeout_seconds > ScopedOperationCaps::kMaxWaitSeconds)
throw GoogleError::invalid("timeout outside 1.." +
std::to_string(ScopedOperationCaps::kMaxWaitSeconds) + " seconds");
return Operation::from_json(send(set_of(scope).wait, check(scope, name),
"?timeout=" + std::to_string(timeout_seconds) + "s"));
}
void OperationCalls::remove(OperationScope scope, const std::string& name, bool confirm) const {
if (!confirm) throw GoogleError::invalid("deleting an operation record needs confirm=true");
send(set_of(scope).remove, check(scope, name));
}
} // namespace molo::google::runtime
+63
View File
@@ -0,0 +1,63 @@
#pragma once
// The long-running operation methods that hang off the runtime's resources:
// get, list, cancel, wait, delete, for an engine, a runtime revision, an
// example, a feedback entry and the A2A task store. One class, one table of
// call sets (calls.h rows), one validation rule: the operation name must
// belong to the scope it is used with.
#include <memory>
#include <string>
#include <vector>
#include "google/client.h"
#include "google/operation.h"
#include "google/runtime/calls.h"
namespace molo::google::runtime {
enum class OperationScope { kEngine, kRevision, kExample, kFeedback, kTaskStore };
struct ScopedOperationCaps {
static constexpr int kMaxWaitSeconds = 600; // server side wait, per call
static constexpr int kMaxListPages = 5;
static constexpr std::size_t kMaxNameChars = 512;
};
class OperationCalls {
public:
OperationCalls(std::shared_ptr<GoogleClient> client, std::string location, bool beta);
static OperationScope scope_from(const std::string& name); // throws invalid
static const char* scope_name(OperationScope scope);
static bool has_list(OperationScope scope);
// Throws GoogleError::invalid unless `name` is "projects/..." within
// kMaxNameChars, has no "..", "?" or "#", and contains the scope's marker
// ("/runtimeRevisions/", "/feedbackEntries/", ...).
static const std::string& check(OperationScope scope, const std::string& name);
Operation get(OperationScope scope, const std::string& name) const;
// `parent` is the resource whose operations are listed (engine, revision,
// feedback entry, task store name). Examples have no list method.
std::vector<Operation> list(OperationScope scope, const std::string& parent,
const std::string& filter = "") const;
void cancel(OperationScope scope, const std::string& name) const;
// POST :wait with a server side timeout of 1..kMaxWaitSeconds seconds.
Operation wait(OperationScope scope, const std::string& name, int timeout_seconds) const;
// Removes the operation record only; needs confirm.
void remove(OperationScope scope, const std::string& name, bool confirm) const;
// The table rows used for a scope (conformance tests).
static Call call_for(OperationScope scope, const char* verb);
private:
clients::body::Json send(Call call, const std::string& target,
const std::string& query = "") const;
std::shared_ptr<GoogleClient> client_;
std::string location_;
bool beta_;
};
} // namespace molo::google::runtime
+87 -1
View File
@@ -6,6 +6,19 @@ differs, or a request body field, query parameter or schema field we use is
not in the discovery document. Python 3 stdlib only, no credentials needed.
python3 -I src/google/runtime/tools/check_discovery.py
Besides the rows it checks three more things:
twin every v1 row also exists in v1beta1 with the same HTTP method,
path (v1beta1 prefix), rpc id, query parameters and body fields
(selected in code with AgentRuntime's beta flag);
alias the project-less form `aiplatform.reasoningEngines.X` of a covered
`aiplatform.projects.locations.reasoningEngines.X` has the same
HTTP method and request schema (it is only another URL for the
same RPC, so the row covers it);
coverage every Discovery method under reasoningEngines (and taskStores,
the A2A task record store) is a row, an alias, or belongs to a
resource owned by another module (OTHER_MODULES). A new Discovery
method fails the check until it is wrapped or excluded on purpose.
"""
import json
import os
@@ -16,6 +29,12 @@ import urllib.request
HERE = os.path.dirname(os.path.abspath(__file__))
CALLS = os.path.join(HERE, "..", "calls.cpp")
URL = "https://aiplatform.googleapis.com/$discovery/rest?version=%s"
OWNED = ("aiplatform.projects.locations.reasoningEngines.",
"aiplatform.projects.locations.taskStores.",
"aiplatform.reasoningEngines.")
# sub-resources of reasoningEngines wrapped by other modules (src/google/sessions,
# src/google/sandbox); they are not this module's gaps.
OTHER_MODULES = ("sessions", "memories", "sandboxEnvironment") # incl. Snapshots, Templates
PREFIX = {"v1": "GoogleCloudAiplatformV1", "v1beta1": "GoogleCloudAiplatformV1beta1"}
ROW = re.compile(r'^\s*\{(.*)\},?\s*$')
@@ -83,13 +102,80 @@ def main():
for f in fields.split(","):
if f not in props:
bad.append("schema %s.%s absent" % (name, f))
covered = {(v, rpc) for _, _, v, rpc, _, _ in calls}
# twin: every v1 row exists in v1beta1
for http, path, version, rpc, body, query in calls:
if version != "v1":
continue
m = index["v1beta1"].get(rpc)
if not m:
bad.append("twin: %s absent in v1beta1" % rpc)
continue
covered.add(("v1beta1", rpc))
if m["httpMethod"] != http or m["path"] != path.replace("v1/", "v1beta1/", 1):
bad.append("twin: %s differs in v1beta1 (%s %s)" % (rpc, m["httpMethod"], m["path"]))
params = m.get("parameters", {})
for q in filter(None, query.split(",")):
if q not in params or params[q].get("location") != "query":
bad.append("twin: %s query param %s absent in v1beta1" % (rpc, q))
ref = m.get("request", {}).get("$ref")
props = docs["v1beta1"]["schemas"].get(ref, {}).get("properties", {})
for f in filter(None, body.split(",")):
if f not in props:
bad.append("twin: %s body field %s absent in v1beta1" % (rpc, f))
# a2aEndpoint: the tail the code builds for an op must match Discovery's pattern
shapes = {"card": "card", "extendedAgentCard": "extendedAgentCard", "tasks": "tasks",
"tasks.a2aGetReasoningEngine": "tasks/[^/]+",
"tasks.pushNotificationConfigs": "tasks/[^/]+/pushNotificationConfigs",
"tasks.pushNotificationConfigs.a2aGetReasoningEngine":
"tasks/[^/]+/pushNotificationConfigs/[^/]+",
"tasks.cancel": "tasks/[^/]+", "tasks.subscribe": "tasks/[^/]+",
"message.send": "message", "message.stream": "message"}
a2a_rows = 0
for http, path, version, rpc, body, query in calls:
if "{+a2aEndpoint}" not in path:
continue
a2a_rows += 1
rest = rpc.split("reasoningEngines.", 1)[1].replace("runtimeRevisions.", "", 1)
rest = rest[len("a2a."):]
pre = ""
if rest.startswith("v1."):
pre, rest = "v1/", rest[3:]
want = "^" + pre + shapes.get(rest, "?") + "$"
got = index[version][rpc].get("parameters", {}).get("a2aEndpoint", {}).get("pattern")
if got != want:
bad.append("a2aEndpoint pattern of %s is %s, code builds %s" % (rpc, got, want))
if a2a_rows != 40:
bad.append("expected 40 A2A gateway rows, table has %d" % a2a_rows)
# coverage and alias
owned = 0
for v in ("v1", "v1beta1"):
for rpc, m in index[v].items():
if not rpc.startswith(OWNED):
continue
tail = rpc.split("reasoningEngines.", 1)[-1] if "reasoningEngines." in rpc else rpc
if tail.startswith(OTHER_MODULES):
continue
owned += 1
if (v, rpc) in covered:
continue
if rpc.startswith("aiplatform.reasoningEngines."):
twin = "aiplatform.projects.locations.reasoningEngines." + tail
tm = index[v].get(twin)
if tm and (v, twin) in covered and tm["httpMethod"] == m["httpMethod"] \
and tm.get("request", {}).get("$ref") == m.get("request", {}).get("$ref"):
continue
bad.append("alias %s %s differs from or lacks a covered %s" % (v, rpc, twin))
continue
bad.append("unwrapped discovery method %s %s" % (v, rpc))
revs = {v: docs[v].get("revision") for v in docs}
if bad:
print("DISCOVERY CHECK FAILED (revisions %s)" % revs)
for b in bad:
print(" " + b)
return 1
print("discovery ok: %d calls, %d schemas, revisions %s" % (len(calls), len(schemas), revs))
print("discovery ok: %d calls, %d schemas, %d owned discovery methods covered, revisions %s"
% (len(calls), len(schemas), owned, revs))
return 0