Merge runtime module (Agent Runtime / Agent Engine)

This commit is contained in:
2026-10-24 04:31:26 +02:00
22 changed files with 2262 additions and 3 deletions
+136
View File
@@ -0,0 +1,136 @@
# Agent Runtime (Agent Engine) - Specification
Owned directory: `src/google/runtime/`. Namespace `molo::google::runtime`.
Depends on the `src/google` foundation (`GoogleClient`, `Service`,
`operation.h`, `resource.h`). Plan: `plans/16-agent-platform.md`.
## 1. Scope
The `reasoningEngines` resource on `aiplatform.googleapis.com`: create, get,
list, patch, delete, query, streamQuery, asyncQuery, cancelAsyncQuery,
executeCode, IAM (get, set, test), the engine's `operations`, and runtime
revisions (v1beta1: get, list, delete, query, streamQuery). Typed deployment
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).
## 2. Module map
| File | Concern |
|---|---|
| `caps.h` | Static ceilings (`RuntimeCaps`) |
| `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` |
| `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
| Knob | Value |
|---|---|
| displayName / description | 128 / 1000 chars |
| labels, key and value | 64, 63 chars |
| env + secret env variables | 100, value 4096 chars |
| minInstances / maxInstances | 0..75 / 1..1000 (Google ranges), min <= max |
| containerConcurrency | 1..1000 |
| cpu / memory | 1,2,4,6,8 / 1Gi..32Gi (Google "only supported values") |
| 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) |
| 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 `?` |
## 4. Contracts
- Every URL comes from `kCalls`; no path literal elsewhere.
- Input is validated before any network traffic; invalid input is
`GoogleError` 400 `INVALID_ARGUMENT`. No credential: `NotConfiguredError`.
- `create`, `update`, `destroy` wait via `wait_operation`; `*_start` return
the `Operation`. `create` finishes with a `get` of the new engine.
- Destructive calls are `destroy`/`destroy_start`/`destroy_revision`; `force`
has no default. The example `delete` route is a dry run unless
`"confirm":true`.
- `identityType AGENT_IDENTITY` rejects a `serviceAccount` (documented rule).
- `effectiveIdentity` is output only and never sent.
- `streamQuery` is read through `GoogleClient::stream_json` (plain JSON or SSE).
- Triggers: Google exposes no API that wires BigQuery or Pub/Sub events to an
engine. The real surface for batch is `asyncQuery`/`cancelAsyncQuery`
(Cloud Storage in and out, long-running, implemented). Event-driven use is
a pattern only: Eventarc or a Pub/Sub push subscription calls
`reasoningEngines.query` through a Cloud Run or Workflows target. Nothing
is implemented for it; this is not an API of this part.
## 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.
## Sources
- Discovery documents, fetched 2026-10-24 (revision 20261012 for both):
`https://aiplatform.googleapis.com/$discovery/rest?version=v1` and
`?version=v1beta1`.
- `https://docs.cloud.google.com/gemini-enterprise-agent-platform/reference/rest/v1/projects.locations.reasoningEngines`
and its `query`, `streamQuery`, `create`, `delete`, `list`, `patch`,
`asyncQuery`, `cancelAsyncQuery` pages (semantics, defaults, ranges).
- Web search for Eventarc/Pub/Sub/BigQuery triggers for Agent Engine: no
Agent Engine target found (Eventarc targets Cloud Run, Functions, GKE,
Workflows).
## 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`.
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:
revision list items key is `reasoningEngineRuntimeRevisions` (not
`runtimeRevisions`), v1 `setIamPolicy` takes only `policy`, secret env uses
`secretRef{secret,version}`.
## Verified live
2026-10-24, express key (`AQ.`), project from `GOOGLE_CLOUD_PROJECT`,
read-only (`MOLO_LIVE_NET=1`, test `runtime_live.read_only_calls`):
| Call | Result |
|---|---|
| `GET .../locations/us-central1/reasoningEngines` | 200, 0 engines |
| `GET .../locations/europe-west4/reasoningEngines` | 200, 0 engines |
| `GET .../reasoningEngines/1234567890123` | 404 NOT_FOUND |
| `POST .../reasoningEngines/1234567890123:query` | 404 NOT_FOUND |
| `GET .../reasoningEngines/molo-does-not-exist` | 400 INVALID_ARGUMENT (ids are numeric) |
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`.
## Unverified
- 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).
- The streamQuery wire format (discovery: `HttpBody`; decoded as plain JSON
or SSE by the foundation decoder).
- 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.
## 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.
- No OAuth refresh (foundation gap).
+307
View File
@@ -0,0 +1,307 @@
#include "google/runtime/agent_runtime.h"
#include <cctype>
#include "clients/url.h"
#include "google/errors.h"
#include "google/runtime/caps.h"
namespace molo::google::runtime {
using clients::body::Json;
namespace {
void check_method(const std::string& m) {
if (m.empty() || m.size() > RuntimeCaps::kMaxMethodChars)
throw GoogleError::invalid("bad classMethod");
for (char c : m)
if (!((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') ||
c == '_'))
throw GoogleError::invalid("bad classMethod");
}
void check_gcs(const std::string& uri, const char* what) {
if (uri.rfind("gs://", 0) != 0 || uri.size() <= 5 ||
uri.size() > RuntimeCaps::kMaxUriChars)
throw GoogleError::invalid(std::string(what) + " must be a gs:// URI");
for (char c : uri)
if (static_cast<unsigned char>(c) <= 0x20) throw GoogleError::invalid("bad gs:// URI");
}
void check_size(const Json& j, const char* what) {
if (j.dump().size() > RuntimeCaps::kMaxInputBytes)
throw GoogleError::invalid(std::string(what) + " too large");
}
std::string enc(const std::string& s) { return clients::Url::encode_component(s); }
} // namespace
Revision Revision::from_json(const Json& doc) {
Revision r;
r.raw = doc;
if (!doc.is_object()) return r;
auto s = [&](const char* k) {
const Json* v = doc.find(k);
return v && v->is_string() ? v->as_string() : std::string();
};
r.name = s("name");
r.state = s("state");
r.create_time = s("createTime");
if (const Json* sp = doc.find("spec")) r.spec = EngineSpec::from_json(*sp);
return r;
}
AgentRuntime::AgentRuntime(std::shared_ptr<GoogleClient> client, CloudContext context,
Sleeper sleeper)
: Service(std::move(client), endpoints::aiplatform(context.location)),
context_(std::move(context)),
sleeper_(std::move(sleeper)) {}
std::string AgentRuntime::name_of(const std::string& id) const {
return context_.child("reasoningEngines", id);
}
std::string AgentRuntime::revision_of(const std::string& id, const std::string& revision) const {
if (!valid_segment(revision)) throw GoogleError::invalid("bad revision id");
return name_of(id) + "/runtimeRevisions/" + revision;
}
std::string AgentRuntime::checked_operation(const std::string& name) {
if (name.rfind("projects/", 0) != 0 || name.size() > 512 ||
name.find("..") != std::string::npos || name.find('?') != std::string::npos)
throw GoogleError::invalid("bad operation name");
return 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);
}
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,
[&](const Json& event) {
++n;
bool more = sink(event);
return more && n < RuntimeCaps::kMaxStreamEvents;
});
return n;
}
Json AgentRuntime::list_items(Call call, const std::string& parent, const std::string& key,
const std::string& filter) const {
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,
RuntimeCaps::kMaxListPages);
}
Operation AgentRuntime::finish(Operation op) const {
if (!op.done) return wait_operation(*client_, endpoint_, checked_operation(op.name), sleeper_);
if (op.failed()) throw GoogleError(502, "OPERATION_FAILED", op.error_message, endpoint_.name);
return op;
}
Engine AgentRuntime::engine_from(const Operation& op) const {
if (op.response.is_object()) {
Engine e = Engine::from_json(op.response);
if (!e.name.empty()) return get(e.id());
}
throw GoogleError(502, "BAD_RESPONSE", "operation finished without an engine name",
endpoint_.name);
}
// --- engines ---------------------------------------------------------------
Operation AgentRuntime::create_start(const EngineDraft& draft) const {
Json body = draft.to_json();
return Operation::from_json(send(Call::kCreate, context_.parent(), "", &body));
}
Engine AgentRuntime::create(const EngineDraft& draft) const {
return engine_from(finish(create_start(draft)));
}
Engine AgentRuntime::get(const std::string& id) const {
return Engine::from_json(send(Call::kGet, name_of(id)));
}
std::vector<Engine> AgentRuntime::list(const std::string& filter) const {
Json items = list_items(Call::kList, context_.parent(), "reasoningEngines", filter);
std::vector<Engine> out;
for (const Json& j : items.as_array()) out.push_back(Engine::from_json(j));
return out;
}
Operation AgentRuntime::update_start(const std::string& id, const EngineUpdate& update) const {
std::string name = name_of(id);
Json body = update.to_json();
body.set("name", Json(name));
return Operation::from_json(
send(Call::kPatch, name, "?updateMask=" + enc(update.update_mask()), &body));
}
Engine AgentRuntime::update(const std::string& id, const EngineUpdate& update_in) const {
finish(update_start(id, update_in));
return get(id);
}
Operation AgentRuntime::destroy_start(const std::string& id, bool force) const {
return Operation::from_json(
send(Call::kDelete, name_of(id), force ? "?force=true" : "?force=false"));
}
Operation AgentRuntime::destroy(const std::string& id, bool force) const {
return finish(destroy_start(id, force));
}
// --- queries ---------------------------------------------------------------
Json AgentRuntime::query_body(const Json& input, const std::string& class_method) {
check_method(class_method);
if (!input.is_object()) throw GoogleError::invalid("input must be a JSON object");
check_size(input, "input");
Json body = Json::object();
body.set("input", input);
body.set("classMethod", Json(class_method));
return body;
}
Json AgentRuntime::query(const std::string& id, const Json& input,
const std::string& class_method) const {
Json body = query_body(input, class_method);
return send(Call::kQuery, name_of(id), "", &body);
}
std::size_t AgentRuntime::stream_query(const std::string& id, const Json& input,
const GoogleClient::EventSink& sink,
const std::string& class_method) const {
return stream_call(Call::kStreamQuery, name_of(id), query_body(input, class_method), sink);
}
Operation AgentRuntime::async_query(const std::string& id, const std::string& input_gcs_uri,
const std::string& output_gcs_uri) const {
check_gcs(input_gcs_uri, "inputGcsUri");
check_gcs(output_gcs_uri, "outputGcsUri");
Json body = Json::object();
body.set("inputGcsUri", Json(input_gcs_uri));
body.set("outputGcsUri", Json(output_gcs_uri));
return Operation::from_json(send(Call::kAsyncQuery, name_of(id), "", &body));
}
void AgentRuntime::cancel_async_query(const std::string& id,
const std::string& operation_name) const {
Json body = Json::object();
body.set("operationName", Json(checked_operation(operation_name)));
send(Call::kCancelAsyncQuery, name_of(id), "", &body);
}
Json AgentRuntime::execute_code(const std::string& id, const Json& inputs) const {
if (!inputs.is_array() || inputs.as_array().empty())
throw GoogleError::invalid("inputs must be a non-empty array of chunks");
check_size(inputs, "inputs");
Json body = Json::object();
body.set("inputs", inputs);
return send(Call::kExecuteCode, name_of(id), "", &body);
}
// --- IAM -------------------------------------------------------------------
Json AgentRuntime::get_iam_policy(const std::string& id, int policy_version) const {
if (policy_version < 0 || policy_version > 3) throw GoogleError::invalid("policy version 0..3");
std::string q = policy_version ? "?options.requestedPolicyVersion=" + std::to_string(policy_version)
: "";
return send(Call::kGetIamPolicy, name_of(id), q);
}
Json AgentRuntime::set_iam_policy(const std::string& id, const Json& policy) const {
if (!policy.is_object()) throw GoogleError::invalid("policy must be an object");
check_size(policy, "policy");
Json body = Json::object();
body.set("policy", policy);
return send(Call::kSetIamPolicy, name_of(id), "", &body);
}
std::vector<std::string> AgentRuntime::test_iam_permissions(
const std::string& id, const std::vector<std::string>& permissions) const {
if (permissions.empty() || permissions.size() > 64)
throw GoogleError::invalid("1 to 64 permissions");
std::string q;
for (const auto& p : permissions) {
if (p.empty() || p.size() > 128) throw GoogleError::invalid("bad permission");
for (char c : p)
if (!std::isalnum(static_cast<unsigned char>(c)) && c != '.' && c != '_')
throw GoogleError::invalid("bad permission");
q += (q.empty() ? "?permissions=" : "&permissions=") + enc(p);
}
Json reply = send(Call::kTestIamPermissions, name_of(id), q);
std::vector<std::string> out;
if (const Json* a = reply.find("permissions"); a && a->is_array())
for (const Json& p : a->as_array())
if (p.is_string()) out.push_back(p.as_string());
return out;
}
// --- operations ------------------------------------------------------------
Operation AgentRuntime::operation(const std::string& operation_name) const {
return Operation::from_json(send(Call::kOperationGet, checked_operation(operation_name)));
}
Operation AgentRuntime::wait(const std::string& operation_name) const {
return wait_operation(*client_, endpoint_, checked_operation(operation_name), sleeper_);
}
std::vector<Operation> AgentRuntime::list_operations(const std::string& id) const {
Json items = list_items(Call::kOperationList, name_of(id), "operations", "");
std::vector<Operation> out;
for (const Json& j : items.as_array()) out.push_back(Operation::from_json(j));
return out;
}
void AgentRuntime::cancel_operation(const std::string& operation_name) const {
send(Call::kOperationCancel, checked_operation(operation_name));
}
void AgentRuntime::delete_operation(const std::string& operation_name) const {
send(Call::kOperationDelete, checked_operation(operation_name));
}
// --- revisions -------------------------------------------------------------
Revision AgentRuntime::get_revision(const std::string& id, const std::string& revision) const {
return Revision::from_json(send(Call::kRevisionGet, revision_of(id, revision)));
}
std::vector<Revision> AgentRuntime::list_revisions(const std::string& id) const {
Json items = list_items(Call::kRevisionList, name_of(id), "reasoningEngineRuntimeRevisions", "");
std::vector<Revision> out;
for (const Json& j : items.as_array()) out.push_back(Revision::from_json(j));
return out;
}
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))));
}
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);
}
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),
query_body(input, class_method), sink);
}
} // namespace molo::google::runtime
+112
View File
@@ -0,0 +1,112 @@
#pragma once
// Agent Runtime (Agent Engine): the reasoningEngines resource on the
// aiplatform host. Every URL comes from the discovery-checked table in
// calls.h. Long-running calls come in two forms: *_start returns the
// Operation at once (use for multi-day work and poll operation()), the plain
// form waits with wait_operation (capped, see operation.h).
#include <functional>
#include <memory>
#include <string>
#include <vector>
#include "google/operation.h"
#include "google/resource.h"
#include "google/runtime/calls.h"
#include "google/runtime/engine.h"
#include "google/service.h"
namespace molo::google::runtime {
// A runtime revision (v1beta1): one immutable deployment of an engine.
struct Revision {
std::string name;
std::string state; // ACTIVE, ARCHIVED
std::string create_time;
EngineSpec spec;
clients::body::Json raw;
static Revision from_json(const clients::body::Json& doc);
};
class AgentRuntime : public Service {
public:
AgentRuntime(std::shared_ptr<GoogleClient> client, CloudContext context,
Sleeper sleeper = nullptr);
const CloudContext& context() const { return context_; }
// --- engines (v1) ---------------------------------------------------
Operation create_start(const EngineDraft& draft) const;
Engine create(const EngineDraft& draft) const;
Engine get(const std::string& id) const;
std::vector<Engine> list(const std::string& filter = "") const;
Operation update_start(const std::string& id, const EngineUpdate& update) const;
Engine update(const std::string& id, const EngineUpdate& update) const;
// Destructive: explicit method, explicit force (no default).
Operation destroy_start(const std::string& id, bool force) const;
Operation destroy(const std::string& id, bool force) const;
// --- queries --------------------------------------------------------
// Body builder, public so callers and tests can inspect what is sent.
static clients::body::Json query_body(const clients::body::Json& input,
const std::string& class_method);
// Returns the whole response document ("output" inside).
clients::body::Json query(const std::string& id, const clients::body::Json& input,
const std::string& class_method = "query") const;
// Events go to sink; false stops early. Returns events delivered (capped).
std::size_t stream_query(const std::string& id, const clients::body::Json& input,
const GoogleClient::EventSink& sink,
const std::string& class_method = "stream_query") const;
// Batch pattern: asyncQuery with Cloud Storage in and out; may run for days.
Operation async_query(const std::string& id, const std::string& input_gcs_uri,
const std::string& output_gcs_uri) const;
void cancel_async_query(const std::string& id, const std::string& operation_name) const;
// Stateless code execution; inputs is a Json array of Chunk objects.
clients::body::Json execute_code(const std::string& id,
const clients::body::Json& inputs) const;
// --- IAM ------------------------------------------------------------
clients::body::Json get_iam_policy(const std::string& id, int policy_version = 0) const;
clients::body::Json set_iam_policy(const std::string& id,
const clients::body::Json& policy) const;
std::vector<std::string> test_iam_permissions(
const std::string& id, const std::vector<std::string>& permissions) const;
// --- operations -----------------------------------------------------
Operation operation(const std::string& operation_name) const; // one poll
Operation wait(const std::string& operation_name) const; // capped wait
std::vector<Operation> list_operations(const std::string& id) const;
void cancel_operation(const std::string& operation_name) const;
void delete_operation(const std::string& operation_name) const;
// --- runtime revisions (v1beta1) -------------------------------------
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;
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;
std::size_t stream_query_revision(const std::string& id, const std::string& revision,
const clients::body::Json& input,
const GoogleClient::EventSink& sink,
const std::string& class_method = "stream_query") const;
private:
std::string name_of(const std::string& id) const;
std::string revision_of(const std::string& id, const std::string& revision) const;
static std::string checked_operation(const std::string& name);
clients::body::Json send(Call call, const std::string& target, const std::string& query = "",
const clients::body::Json* body = nullptr) const;
std::size_t stream_call(Call call, const std::string& target, const clients::body::Json& body,
const GoogleClient::EventSink& sink) const;
clients::body::Json list_items(Call call, const std::string& parent,
const std::string& items_key, const std::string& filter) const;
Engine engine_from(const Operation& op) const;
Operation finish(Operation op) const;
CloudContext context_;
Sleeper sleeper_;
};
} // namespace molo::google::runtime
+92
View File
@@ -0,0 +1,92 @@
#include "google/runtime/calls.h"
#include <cstring>
#include "google/errors.h"
#include "google/resource.h"
namespace molo::google::runtime {
// CALLS-BEGIN (parsed by tools/check_discovery.py; one row per line)
static const CallSpec kCalls[] = {
{Call::kCreate, "POST", "v1/{+parent}/reasoningEngines", "v1", "aiplatform.projects.locations.reasoningEngines.create", "displayName,description,labels,spec,encryptionSpec", ""},
{Call::kGet, "GET", "v1/{+name}", "v1", "aiplatform.projects.locations.reasoningEngines.get", "", ""},
{Call::kList, "GET", "v1/{+parent}/reasoningEngines", "v1", "aiplatform.projects.locations.reasoningEngines.list", "", "filter,pageSize,pageToken"},
{Call::kPatch, "PATCH", "v1/{+name}", "v1", "aiplatform.projects.locations.reasoningEngines.patch", "name,displayName,description,labels,spec", "updateMask"},
{Call::kDelete, "DELETE", "v1/{+name}", "v1", "aiplatform.projects.locations.reasoningEngines.delete", "", "force"},
{Call::kQuery, "POST", "v1/{+name}:query", "v1", "aiplatform.projects.locations.reasoningEngines.query", "input,classMethod", ""},
{Call::kStreamQuery, "POST", "v1/{+name}:streamQuery", "v1", "aiplatform.projects.locations.reasoningEngines.streamQuery", "input,classMethod", ""},
{Call::kAsyncQuery, "POST", "v1/{+name}:asyncQuery", "v1", "aiplatform.projects.locations.reasoningEngines.asyncQuery", "inputGcsUri,outputGcsUri", ""},
{Call::kCancelAsyncQuery, "POST", "v1/{+name}:cancelAsyncQuery", "v1", "aiplatform.projects.locations.reasoningEngines.cancelAsyncQuery", "operationName", ""},
{Call::kExecuteCode, "POST", "v1/{+name}:executeCode", "v1", "aiplatform.projects.locations.reasoningEngines.executeCode", "inputs", ""},
{Call::kGetIamPolicy, "POST", "v1/{+resource}:getIamPolicy", "v1", "aiplatform.projects.locations.reasoningEngines.getIamPolicy", "", "options.requestedPolicyVersion"},
{Call::kSetIamPolicy, "POST", "v1/{+resource}:setIamPolicy", "v1", "aiplatform.projects.locations.reasoningEngines.setIamPolicy", "policy", ""},
{Call::kTestIamPermissions, "POST", "v1/{+resource}:testIamPermissions", "v1", "aiplatform.projects.locations.reasoningEngines.testIamPermissions", "", "permissions"},
{Call::kOperationGet, "GET", "v1/{+name}", "v1", "aiplatform.projects.locations.reasoningEngines.operations.get", "", ""},
{Call::kOperationList, "GET", "v1/{+name}/operations", "v1", "aiplatform.projects.locations.reasoningEngines.operations.list", "", "filter,pageSize,pageToken"},
{Call::kOperationCancel, "POST", "v1/{+name}:cancel", "v1", "aiplatform.projects.locations.reasoningEngines.operations.cancel", "", ""},
{Call::kOperationDelete, "DELETE", "v1/{+name}", "v1", "aiplatform.projects.locations.reasoningEngines.operations.delete", "", ""},
{Call::kRevisionGet, "GET", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.get", "", ""},
{Call::kRevisionList, "GET", "v1beta1/{+parent}/runtimeRevisions", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.list", "", "filter,pageSize,pageToken"},
{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", ""},
};
// CALLS-END
// SCHEMAS-BEGIN (parsed by tools/check_discovery.py; one row per line)
static const SchemaFields kSchemas[] = {
{"ReasoningEngine", "v1", "name,displayName,description,labels,spec,etag,createTime,updateTime,encryptionSpec,contextSpec"},
{"ReasoningEngineSpec", "v1", "agentFramework,packageSpec,containerSpec,sourceCodeSpec,deploymentSpec,buildSpec,identityType,serviceAccount,effectiveIdentity,classMethods"},
{"ReasoningEngineSpecPackageSpec", "v1", "pythonVersion,pickleObjectGcsUri,dependencyFilesGcsUri,requirementsGcsUri"},
{"ReasoningEngineSpecContainerSpec", "v1", "imageUri,port"},
{"ReasoningEngineSpecSourceCodeSpec", "v1", "pythonSpec,inlineSource,developerConnectSource,imageSpec,agentConfigSource"},
{"ReasoningEngineSpecSourceCodeSpecPythonSpec", "v1", "version,entrypointModule,entrypointObject,requirementsFile"},
{"ReasoningEngineSpecBuildSpec", "v1", "serviceAccount,workerPool"},
{"ReasoningEngineSpecDeploymentSpec", "v1", "env,secretEnv,resourceLimits,minInstances,maxInstances,containerConcurrency,pscInterfaceConfig,keepAliveProbe,agentGatewayConfig"},
{"EnvVar", "v1", "name,value"},
{"SecretEnvVar", "v1", "name,secretRef"},
{"SecretRef", "v1", "secret,version"},
{"EncryptionSpec", "v1", "kmsKeyName"},
{"ListReasoningEnginesResponse", "v1", "reasoningEngines,nextPageToken"},
{"QueryReasoningEngineResponse", "v1", "output"},
{"ExecuteCodeResponse", "v1", "outputs"},
{"ReasoningEngine", "v1beta1", "trafficConfig,revisionGarbageCollectionStrategy"},
{"ReasoningEngineRuntimeRevision", "v1beta1", "name,state,createTime,spec"},
{"ListReasoningEngineRuntimeRevisionsResponse", "v1beta1", "reasoningEngineRuntimeRevisions,nextPageToken"},
{"ReasoningEngineSpecDeploymentSpec", "v1beta1", "agentServerMode"},
{"ReasoningEngineSpec", "v1beta1", "agentCard"},
};
// SCHEMAS-END
const CallSpec& spec_of(Call call) {
for (const CallSpec& s : kCalls)
if (s.call == call) return s;
throw GoogleError::invalid("unknown call");
}
clients::Method method_of(Call call) {
const char* m = spec_of(call).http_method;
if (!std::strcmp(m, "GET")) return clients::Method::kGet;
if (!std::strcmp(m, "POST")) return clients::Method::kPost;
if (!std::strcmp(m, "PATCH")) return clients::Method::kPatch;
return clients::Method::kDelete;
}
ServiceEndpoint endpoint_of(Call call, const std::string& location) {
return 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 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);
}
return "/" + path;
}
} // namespace molo::google::runtime
+45
View File
@@ -0,0 +1,45 @@
#pragma once
// The ONE table of REST calls this module makes. Every row is checked against
// Google's Discovery document by tools/check_discovery.py. Code builds every
// URL from this table, never from a literal.
#include <string>
#include "clients/request.h"
#include "google/endpoints.h"
namespace molo::google::runtime {
enum class Call {
kCreate, kGet, kList, kPatch, kDelete, kQuery, kStreamQuery, kAsyncQuery,
kCancelAsyncQuery, kExecuteCode, kGetIamPolicy, kSetIamPolicy, kTestIamPermissions,
kOperationGet, kOperationList, kOperationCancel, kOperationDelete,
kRevisionGet, kRevisionList, kRevisionDelete, kRevisionQuery, kRevisionStreamQuery,
};
struct CallSpec {
Call call;
const char* http_method; // as in discovery: GET POST PATCH DELETE
const char* path; // discovery "path", e.g. "v1/{+name}:query"
const char* version; // "v1" or "v1beta1"
const char* rpc_id; // discovery method id
const char* body_fields; // comma list: request body fields we send
const char* query_params; // comma list: query parameters we send
};
struct SchemaFields {
const char* schema; // discovery schema name without the version prefix
const char* version; // "v1" or "v1beta1"
const char* fields; // comma list: fields we read or write
};
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);
// 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);
} // namespace molo::google::runtime
+29
View File
@@ -0,0 +1,29 @@
#pragma once
// Static ceilings for Agent Runtime. Never autotuned.
#include <cstddef>
namespace molo::google::runtime {
struct RuntimeCaps {
static constexpr std::size_t kMaxDisplayName = 128;
static constexpr std::size_t kMaxDescription = 1000;
static constexpr std::size_t kMaxLabels = 64;
static constexpr std::size_t kMaxLabelChars = 63;
static constexpr std::size_t kMaxEnvVars = 100;
static constexpr std::size_t kMaxEnvValueChars = 4096;
static constexpr std::size_t kMaxUriChars = 1024;
static constexpr std::size_t kMaxServiceAccountChars = 256;
static constexpr int kMinInstancesMax = 75; // minInstances in [0, 75]
static constexpr int kMaxInstancesMax = 1000; // maxInstances in [1, 1000]
static constexpr int kMaxConcurrency = 1000;
static constexpr std::size_t kMaxInputBytes = 1024 * 1024; // serialized query input
static constexpr std::size_t kMaxMethodChars = 64;
static constexpr std::size_t kMaxFilterChars = 512;
static constexpr std::size_t kMaxMaskChars = 512;
static constexpr int kMaxListPages = 20;
static constexpr std::size_t kMaxStreamEvents = 5000;
};
} // namespace molo::google::runtime
+324
View File
@@ -0,0 +1,324 @@
#include "google/runtime/deployment_spec.h"
#include <cctype>
#include <set>
#include "google/errors.h"
#include "google/resource.h"
#include "google/runtime/caps.h"
namespace molo::google::runtime {
using clients::body::Json;
namespace {
[[noreturn]] void bad(const std::string& what) { throw GoogleError::invalid(what); }
bool valid_env_name(const std::string& n) {
if (n.empty() || n.size() > 128) return false;
if (std::isdigit(static_cast<unsigned char>(n[0]))) return false;
for (char c : n)
if (!std::isalnum(static_cast<unsigned char>(c)) && c != '_') return false;
return true;
}
bool printable_token(const std::string& s, std::size_t max) {
if (s.empty() || s.size() > max) return false;
for (char c : s)
if (static_cast<unsigned char>(c) <= 0x20 || c == 0x7f) return false;
return true;
}
void check_gcs(const std::string& uri, const char* what) {
if (uri.empty()) return;
if (uri.rfind("gs://", 0) != 0 || !printable_token(uri, RuntimeCaps::kMaxUriChars))
bad(std::string(what) + " must be a gs:// URI");
}
void check_python(const std::string& v) {
static const std::set<std::string> ok = {"3.10", "3.11", "3.12", "3.13", "3.14"};
if (!v.empty() && !ok.count(v)) bad("python version must be 3.10 to 3.14");
}
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() : "";
}
void put(Json& obj, const char* key, const std::string& v) {
if (!v.empty()) obj.set(key, Json(v));
}
Json known_free(const Json& doc, const std::set<std::string>& known) {
Json rest = Json::object();
if (!doc.is_object()) return rest;
for (const auto& [k, v] : doc.as_object())
if (!known.count(k)) rest.set(k, v);
return rest;
}
} // namespace
const char* identity_type_name(IdentityType t) {
switch (t) {
case IdentityType::kServiceAccount: return "SERVICE_ACCOUNT";
case IdentityType::kAgentIdentity: return "AGENT_IDENTITY";
default: return "IDENTITY_TYPE_UNSPECIFIED";
}
}
IdentityType identity_type_from(const std::string& name) {
if (name == "SERVICE_ACCOUNT") return IdentityType::kServiceAccount;
if (name == "AGENT_IDENTITY") return IdentityType::kAgentIdentity;
return IdentityType::kUnspecified;
}
// --- DeploymentSpec -------------------------------------------------------
void DeploymentSpec::validate() const {
if (env.size() + secret_env.size() > RuntimeCaps::kMaxEnvVars)
bad("too many environment variables");
std::set<std::string> seen;
for (const auto& e : env) {
if (!valid_env_name(e.name)) bad("bad environment variable name");
if (e.value.size() > RuntimeCaps::kMaxEnvValueChars) bad("environment value too long");
if (!seen.insert(e.name).second) bad("duplicate environment variable");
}
for (const auto& s : secret_env) {
if (!valid_env_name(s.name)) bad("bad secret environment variable name");
if (!valid_segment(s.secret)) bad("bad secret id");
if (!s.version.empty() && !valid_segment(s.version)) bad("bad secret version");
if (!seen.insert(s.name).second) bad("duplicate environment variable");
}
static const std::set<std::string> cpus = {"1", "2", "4", "6", "8"};
if (!cpu.empty() && !cpus.count(cpu)) bad("cpu must be 1, 2, 4, 6 or 8");
if (!memory.empty()) { // 1Gi .. 32Gi
bool okm = memory.size() >= 3 && memory.size() <= 4 && memory.substr(memory.size() - 2) == "Gi";
int gi = 0;
if (okm) {
for (std::size_t i = 0; i + 2 < memory.size(); ++i) {
if (!std::isdigit(static_cast<unsigned char>(memory[i]))) okm = false;
else gi = gi * 10 + (memory[i] - '0');
}
}
if (!okm || gi < 1 || gi > 32) bad("memory must be 1Gi to 32Gi");
}
if (min_instances && (*min_instances < 0 || *min_instances > RuntimeCaps::kMinInstancesMax))
bad("minInstances must be 0..75");
if (max_instances && (*max_instances < 1 || *max_instances > RuntimeCaps::kMaxInstancesMax))
bad("maxInstances must be 1..1000");
if (min_instances && max_instances && *min_instances > *max_instances)
bad("minInstances exceeds maxInstances");
if (container_concurrency &&
(*container_concurrency < 1 || *container_concurrency > RuntimeCaps::kMaxConcurrency))
bad("containerConcurrency must be 1..1000");
}
Json DeploymentSpec::to_json() const {
Json o = Json::object();
if (!env.empty()) {
Json a = Json::array();
for (const auto& e : env) {
Json v = Json::object();
v.set("name", Json(e.name));
v.set("value", Json(e.value));
a.push(v);
}
o.set("env", a);
}
if (!secret_env.empty()) {
Json a = Json::array();
for (const auto& s : secret_env) {
Json ref = Json::object();
ref.set("secret", Json(s.secret));
if (!s.version.empty()) ref.set("version", Json(s.version));
Json v = Json::object();
v.set("name", Json(s.name));
v.set("secretRef", ref);
a.push(v);
}
o.set("secretEnv", a);
}
if (!cpu.empty() || !memory.empty()) {
Json lim = Json::object();
put(lim, "cpu", cpu);
put(lim, "memory", memory);
o.set("resourceLimits", lim);
}
if (min_instances) o.set("minInstances", Json(*min_instances));
if (max_instances) o.set("maxInstances", Json(*max_instances));
if (container_concurrency) o.set("containerConcurrency", Json(*container_concurrency));
if (!psc_interface_config.is_null()) o.set("pscInterfaceConfig", psc_interface_config);
if (extra.is_object())
for (const auto& [k, v] : extra.as_object()) o.set(k, v);
return o;
}
DeploymentSpec DeploymentSpec::from_json(const Json& doc) {
DeploymentSpec d;
if (!doc.is_object()) return d;
if (const Json* a = doc.find("env"); a && a->is_array())
for (const Json& e : a->as_array()) d.env.push_back({str(e, "name"), str(e, "value")});
if (const Json* a = doc.find("secretEnv"); a && a->is_array())
for (const Json& e : a->as_array()) {
const Json* ref = e.is_object() ? e.find("secretRef") : nullptr;
d.secret_env.push_back(
{str(e, "name"), ref ? str(*ref, "secret") : "", ref ? str(*ref, "version") : ""});
}
if (const Json* lim = doc.find("resourceLimits")) {
d.cpu = str(*lim, "cpu");
d.memory = str(*lim, "memory");
}
auto num = [&](const char* k) -> std::optional<int> {
const Json* v = doc.find(k);
if (v && v->is_number()) return static_cast<int>(v->as_int());
return std::nullopt;
};
d.min_instances = num("minInstances");
d.max_instances = num("maxInstances");
d.container_concurrency = num("containerConcurrency");
if (const Json* p = doc.find("pscInterfaceConfig")) d.psc_interface_config = *p;
d.extra = known_free(doc, {"env", "secretEnv", "resourceLimits", "minInstances", "maxInstances",
"containerConcurrency", "pscInterfaceConfig"});
return d;
}
// --- EngineSpec -----------------------------------------------------------
void EngineSpec::validate() const {
static const std::set<std::string> frameworks = {"google-adk", "langchain", "langgraph",
"ag2", "llama-index", "custom"};
if (!agent_framework.empty() && !frameworks.count(agent_framework))
bad("unknown agentFramework");
int sources = (package ? 1 : 0) + (container ? 1 : 0) + (source ? 1 : 0);
if (sources > 1) bad("set only one of package, container, source");
if (package) {
check_python(package->python_version);
check_gcs(package->pickle_object_gcs_uri, "pickleObjectGcsUri");
check_gcs(package->dependency_files_gcs_uri, "dependencyFilesGcsUri");
check_gcs(package->requirements_gcs_uri, "requirementsGcsUri");
}
if (container && !printable_token(container->image_uri, RuntimeCaps::kMaxUriChars))
bad("containerSpec.imageUri is required");
if (source) {
check_python(source->python_version);
for (const std::string* s : {&source->entrypoint_module, &source->entrypoint_object,
&source->requirements_file})
if (s->size() > 256) bad("source entrypoint field too long");
}
if (container && container->port && (*container->port < 1 || *container->port > 65535))
bad("containerSpec.port must be 1..65535");
if (deployment) deployment->validate();
if (build_service_account.size() > RuntimeCaps::kMaxServiceAccountChars ||
build_worker_pool.size() > 512)
bad("buildSpec field too long");
if (!service_account.empty()) {
if (identity == IdentityType::kAgentIdentity)
bad("serviceAccount must not be set with AGENT_IDENTITY");
if (!printable_token(service_account, RuntimeCaps::kMaxServiceAccountChars) ||
service_account.find('@') == std::string::npos)
bad("serviceAccount must be an email address");
}
}
Json EngineSpec::to_json() const {
validate();
Json o = extra.is_object() ? extra : Json::object();
put(o, "agentFramework", agent_framework);
if (package) {
Json p = Json::object();
put(p, "pythonVersion", package->python_version);
put(p, "pickleObjectGcsUri", package->pickle_object_gcs_uri);
put(p, "dependencyFilesGcsUri", package->dependency_files_gcs_uri);
put(p, "requirementsGcsUri", package->requirements_gcs_uri);
o.set("packageSpec", p);
}
if (container) {
Json c = Json::object();
c.set("imageUri", Json(container->image_uri));
if (container->port) c.set("port", Json(*container->port));
o.set("containerSpec", c);
}
if (source) {
Json py = Json::object();
put(py, "entrypointModule", source->entrypoint_module);
put(py, "entrypointObject", source->entrypoint_object);
put(py, "requirementsFile", source->requirements_file);
put(py, "version", source->python_version);
Json s = source->source_extra.is_object() ? source->source_extra : Json::object();
s.set("pythonSpec", py);
o.set("sourceCodeSpec", s);
}
if (deployment) o.set("deploymentSpec", deployment->to_json());
if (!build_service_account.empty() || !build_worker_pool.empty()) {
Json b = Json::object();
put(b, "serviceAccount", build_service_account);
put(b, "workerPool", build_worker_pool);
o.set("buildSpec", b);
}
if (identity != IdentityType::kUnspecified) o.set("identityType", Json(identity_type_name(identity)));
put(o, "serviceAccount", service_account);
if (class_methods.is_array()) o.set("classMethods", class_methods);
return o;
}
EngineSpec EngineSpec::from_json(const Json& doc) {
EngineSpec s;
if (!doc.is_object()) return s;
s.agent_framework = str(doc, "agentFramework");
if (const Json* p = doc.find("packageSpec")) {
PackageSpec ps;
ps.python_version = str(*p, "pythonVersion");
ps.pickle_object_gcs_uri = str(*p, "pickleObjectGcsUri");
ps.dependency_files_gcs_uri = str(*p, "dependencyFilesGcsUri");
ps.requirements_gcs_uri = str(*p, "requirementsGcsUri");
s.package = ps;
}
if (const Json* c = doc.find("containerSpec")) {
ContainerSpec cs;
cs.image_uri = str(*c, "imageUri");
if (const Json* p = c->find("port"); p && p->is_number()) cs.port = static_cast<int>(p->as_int());
s.container = cs;
}
if (const Json* b = doc.find("buildSpec")) {
s.build_service_account = str(*b, "serviceAccount");
s.build_worker_pool = str(*b, "workerPool");
}
s.effective_identity = str(doc, "effectiveIdentity");
if (const Json* c = doc.find("sourceCodeSpec")) {
SourceCodeSpec ss;
if (const Json* py = c->find("pythonSpec")) {
ss.entrypoint_module = str(*py, "entrypointModule");
ss.entrypoint_object = str(*py, "entrypointObject");
ss.requirements_file = str(*py, "requirementsFile");
ss.python_version = str(*py, "version");
}
ss.source_extra = known_free(*c, {"pythonSpec"});
s.source = ss;
}
if (const Json* d = doc.find("deploymentSpec")) s.deployment = DeploymentSpec::from_json(*d);
s.identity = identity_type_from(str(doc, "identityType"));
s.service_account = str(doc, "serviceAccount");
if (const Json* m = doc.find("classMethods"); m && m->is_array()) s.class_methods = *m;
s.extra = known_free(doc, {"agentFramework", "packageSpec", "containerSpec", "sourceCodeSpec",
"deploymentSpec", "identityType", "serviceAccount", "classMethods",
"buildSpec", "effectiveIdentity"});
return s;
}
std::vector<std::string> EngineSpec::mask() const {
std::vector<std::string> m;
if (!agent_framework.empty()) m.push_back("spec.agentFramework");
if (package) m.push_back("spec.packageSpec");
if (container) m.push_back("spec.containerSpec");
if (source) m.push_back("spec.sourceCodeSpec");
if (deployment) m.push_back("spec.deploymentSpec");
if (!build_service_account.empty() || !build_worker_pool.empty()) m.push_back("spec.buildSpec");
if (identity != IdentityType::kUnspecified) m.push_back("spec.identityType");
if (!service_account.empty()) m.push_back("spec.serviceAccount");
if (class_methods.is_array()) m.push_back("spec.classMethods");
return m;
}
} // namespace molo::google::runtime
+92
View File
@@ -0,0 +1,92 @@
#pragma once
// Typed deployment description of a reasoning engine (Agent Engine). Unknown
// fields are kept as raw Json (`extra`) and sent back unchanged.
#include <optional>
#include <string>
#include <vector>
#include "clients/body/json.h"
namespace molo::google::runtime {
enum class IdentityType { kUnspecified, kServiceAccount, kAgentIdentity };
const char* identity_type_name(IdentityType t);
IdentityType identity_type_from(const std::string& name);
// Python package deployment (packageSpec).
struct PackageSpec {
std::string python_version; // 3.10 .. 3.14
std::string pickle_object_gcs_uri;
std::string dependency_files_gcs_uri; // tar.gz
std::string requirements_gcs_uri;
};
// Container deployment (containerSpec).
struct ContainerSpec {
std::string image_uri; // Artifact Registry image
std::optional<int> port;
};
// Deploy from source (sourceCodeSpec.pythonSpec); inline or Developer Connect
// source stay in `source_extra`.
struct SourceCodeSpec {
std::string entrypoint_module;
std::string entrypoint_object;
std::string requirements_file;
std::string python_version;
clients::body::Json source_extra; // inlineSource / developerConnectSource
};
struct EnvVar {
std::string name;
std::string value;
};
struct SecretEnvVar {
std::string name;
std::string secret; // Secret Manager secret id
std::string version; // "latest" or a number
};
// deploymentSpec: runtime environment and scaling.
struct DeploymentSpec {
std::vector<EnvVar> env;
std::vector<SecretEnvVar> secret_env;
std::string cpu; // resourceLimits.cpu, e.g. "4"
std::string memory; // resourceLimits.memory, e.g. "8Gi"
std::optional<int> min_instances; // [0, 75], Google default 1
std::optional<int> max_instances; // [1, 1000], Google default 100
std::optional<int> container_concurrency; // Google default 9
clients::body::Json psc_interface_config; // raw, null when unset
clients::body::Json extra; // keepAliveProbe, agentGatewayConfig, agentServerMode (beta), ...
void validate() const;
clients::body::Json to_json() const;
static DeploymentSpec from_json(const clients::body::Json& doc);
};
// spec of a reasoning engine. At most one deployment source may be set.
struct EngineSpec {
std::string agent_framework; // google-adk, langchain, langgraph, ag2, llama-index, custom
std::optional<PackageSpec> package;
std::optional<ContainerSpec> container;
std::optional<SourceCodeSpec> source;
std::optional<DeploymentSpec> deployment;
IdentityType identity = IdentityType::kUnspecified;
std::string service_account; // must be empty for AGENT_IDENTITY
std::string build_service_account; // buildSpec.serviceAccount
std::string build_worker_pool; // buildSpec.workerPool
std::string effective_identity; // output only, never sent
clients::body::Json class_methods; // raw OpenAPI array, null when unset
clients::body::Json extra; // unknown spec fields, merged on output
void validate() const;
clients::body::Json to_json() const;
static EngineSpec from_json(const clients::body::Json& doc);
// updateMask entries for the parts that are set ("spec.deploymentSpec", ...).
std::vector<std::string> mask() const;
};
} // namespace molo::google::runtime
+128
View File
@@ -0,0 +1,128 @@
#include "google/runtime/engine.h"
#include "google/errors.h"
#include "google/runtime/caps.h"
namespace molo::google::runtime {
using clients::body::Json;
namespace {
void check_text(const std::string& s, std::size_t max, const char* what) {
if (s.size() > max) throw GoogleError::invalid(std::string(what) + " too long");
}
void check_labels(const std::map<std::string, std::string>& labels) {
if (labels.size() > RuntimeCaps::kMaxLabels)
throw GoogleError::invalid("too many labels");
for (const auto& [k, v] : labels) {
if (k.empty() || k.size() > RuntimeCaps::kMaxLabelChars ||
v.size() > RuntimeCaps::kMaxLabelChars)
throw GoogleError::invalid("bad label");
}
}
Json labels_json(const std::map<std::string, std::string>& labels) {
Json o = Json::object();
for (const auto& [k, v] : labels) o.set(k, Json(v));
return o;
}
std::string str(const Json& doc, const char* key) {
const Json* v = doc.find(key);
return v && v->is_string() ? v->as_string() : "";
}
} // namespace
std::string Engine::id() const {
auto slash = name.rfind('/');
return slash == std::string::npos ? name : name.substr(slash + 1);
}
Engine Engine::from_json(const Json& doc) {
Engine e;
e.raw = doc;
if (!doc.is_object()) return e;
e.name = str(doc, "name");
e.display_name = str(doc, "displayName");
e.description = str(doc, "description");
e.etag = str(doc, "etag");
e.create_time = str(doc, "createTime");
e.update_time = str(doc, "updateTime");
if (const Json* l = doc.find("labels"); l && l->is_object())
for (const auto& [k, v] : l->as_object())
if (v.is_string()) e.labels[k] = v.as_string();
if (const Json* s = doc.find("spec")) e.spec = EngineSpec::from_json(*s);
if (const Json* k = doc.find("encryptionSpec")) e.kms_key_name = str(*k, "kmsKeyName");
return e;
}
void EngineDraft::validate() const {
if (display_name.empty()) throw GoogleError::invalid("displayName is required");
check_text(display_name, RuntimeCaps::kMaxDisplayName, "displayName");
check_text(description, RuntimeCaps::kMaxDescription, "description");
check_labels(labels);
check_text(kms_key_name, 512, "kmsKeyName");
spec.validate();
}
Json EngineDraft::to_json() const {
validate();
Json o = Json::object();
o.set("displayName", Json(display_name));
if (!description.empty()) o.set("description", Json(description));
if (!labels.empty()) o.set("labels", labels_json(labels));
Json s = spec.to_json();
if (!s.as_object().empty()) o.set("spec", s);
if (!kms_key_name.empty()) {
Json k = Json::object();
k.set("kmsKeyName", Json(kms_key_name));
o.set("encryptionSpec", k);
}
return o;
}
void EngineUpdate::validate() const {
if (!display_name && !description && !labels && !spec)
throw GoogleError::invalid("nothing to update");
if (display_name) {
if (display_name->empty()) throw GoogleError::invalid("displayName must not be empty");
check_text(*display_name, RuntimeCaps::kMaxDisplayName, "displayName");
}
if (description) check_text(*description, RuntimeCaps::kMaxDescription, "description");
if (labels) check_labels(*labels);
if (spec) {
spec->validate();
if (spec->mask().empty()) throw GoogleError::invalid("spec has no fields to update");
}
}
Json EngineUpdate::to_json() const {
validate();
Json o = Json::object();
if (display_name) o.set("displayName", Json(*display_name));
if (description) o.set("description", Json(*description));
if (labels) o.set("labels", labels_json(*labels));
if (spec) o.set("spec", spec->to_json());
return o;
}
std::string EngineUpdate::update_mask() const {
validate();
std::string m;
auto add = [&](const std::string& part) {
if (!m.empty()) m += ",";
m += part;
};
if (display_name) add("displayName");
if (description) add("description");
if (labels) add("labels");
if (spec)
for (const auto& p : spec->mask()) add(p);
if (m.size() > RuntimeCaps::kMaxMaskChars) throw GoogleError::invalid("updateMask too long");
return m;
}
} // namespace molo::google::runtime
+54
View File
@@ -0,0 +1,54 @@
#pragma once
// A reasoning engine (Agent Engine) as Google returns it, plus the input
// types for create and update.
#include <map>
#include <optional>
#include <string>
#include "clients/body/json.h"
#include "google/runtime/deployment_spec.h"
namespace molo::google::runtime {
struct Engine {
std::string name; // projects/{p}/locations/{l}/reasoningEngines/{id}
std::string display_name;
std::string description;
std::string etag;
std::string create_time;
std::string update_time;
std::map<std::string, std::string> labels;
EngineSpec spec;
std::string kms_key_name; // encryptionSpec.kmsKeyName
clients::body::Json raw; // the full response document
std::string id() const; // last segment of name
static Engine from_json(const clients::body::Json& doc);
};
struct EngineDraft {
std::string display_name; // required
std::string description;
std::map<std::string, std::string> labels;
EngineSpec spec;
std::string kms_key_name; // optional customer-managed key
void validate() const;
clients::body::Json to_json() const;
};
// Only the set fields are sent; updateMask is derived from them.
struct EngineUpdate {
std::optional<std::string> display_name;
std::optional<std::string> description;
std::optional<std::map<std::string, std::string>> labels;
std::optional<EngineSpec> spec;
void validate() const;
clients::body::Json to_json() const;
std::string update_mask() const; // comma separated, never empty after validate()
};
} // namespace molo::google::runtime
@@ -0,0 +1,97 @@
#!/usr/bin/env python3
"""Check src/google/runtime/calls.cpp against Google's Discovery documents.
Fails (exit 1) when a declared call is absent, its HTTP method or path
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
"""
import json
import os
import re
import sys
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"
PREFIX = {"v1": "GoogleCloudAiplatformV1", "v1beta1": "GoogleCloudAiplatformV1beta1"}
ROW = re.compile(r'^\s*\{(.*)\},?\s*$')
STR = re.compile(r'"([^"]*)"')
def block(text, begin, end):
a = text.index(begin)
b = text.index(end)
rows = []
for line in text[a:b].splitlines()[1:]:
m = ROW.match(line)
if m and '"' in line:
rows.append(STR.findall(m.group(1)))
return rows
def fetch(version):
with urllib.request.urlopen(URL % version, timeout=60) as r:
return json.load(r)
def methods(node, out):
for m in node.get("methods", {}).values():
out[m["id"]] = m
for child in node.get("resources", {}).values():
methods(child, out)
def main():
text = open(CALLS).read()
calls = block(text, "// CALLS-BEGIN", "// CALLS-END")
schemas = block(text, "// SCHEMAS-BEGIN", "// SCHEMAS-END")
docs, index = {}, {}
for v in ("v1", "v1beta1"):
docs[v] = fetch(v)
index[v] = {}
methods(docs[v], index[v])
bad = []
for http, path, version, rpc, body, query in calls:
m = index[version].get(rpc)
if not m:
bad.append("missing rpc " + rpc)
continue
if m["httpMethod"] != http:
bad.append("%s: http %s != %s" % (rpc, http, m["httpMethod"]))
if m["path"] != path:
bad.append("%s: path %s != %s" % (rpc, path, 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("%s: query param %s absent" % (rpc, q))
fields = [f for f in body.split(",") if f]
if fields:
ref = m.get("request", {}).get("$ref")
props = docs[version]["schemas"].get(ref, {}).get("properties", {})
for f in fields:
if f not in props:
bad.append("%s: body field %s absent in %s" % (rpc, f, ref))
for name, version, fields in schemas:
props = docs[version]["schemas"].get(PREFIX[version] + name, {}).get("properties")
if props is None:
bad.append("missing schema %s %s" % (version, name))
continue
for f in fields.split(","):
if f not in props:
bad.append("schema %s.%s absent" % (name, f))
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))
return 0
if __name__ == "__main__":
sys.exit(main())