feat(clients): runtime: Agent Engine reasoningEngines client, discovery-checked call table, typed deployment spec, demo routes

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-24 04:31:12 +02:00
co-authored by Claude Sonnet 5.5
parent 6d744a433f
commit fedee6d03a
22 changed files with 2262 additions and 3 deletions
+325 -3
View File
@@ -1,13 +1,335 @@
#include "../AgentDemos.hpp"
#include <cstdlib>
#include "../../fw/Router.hpp"
#include "../../fw/Templates.hpp"
#include "google/resource.h"
#include "google/runtime/agent_runtime.h"
#include "google/runtime/calls.h"
#include "google/runtime/caps.h"
namespace molo::example::app {
// Agent Platform: runtime. Stub: the module agent fills this in.
// Agent Platform: Agent Runtime (Agent Engine, reasoningEngines) over the
// real src/google/runtime part. GET routes need no credential. Every route
// that calls Google is a POST: 503 google_not_configured without a
// credential, 422 on bad input. Create never waits (deployments can take
// long): it answers the operation name; poll it with /agent/runtime/operation.
// Delete is a dry run unless the body says "confirm":true.
namespace {
namespace rt = google::runtime;
using Json = clients::body::Json;
constexpr std::size_t kMaxBody = 256 * 1024;
constexpr std::size_t kMaxStreamEventsShown = 100;
const char kPage[] = R"RUNTIME({% extends "base.html" %}
{% block content %}
<h1>Agent Runtime</h1>
<p class="hint">Deploy and call agents on Agent Engine (reasoningEngines).
Lists and queries only; create and delete stay behind explicit calls.</p>
<p id="rt-config" class="hint">Checking Google credentials...</p>
<section class="rt">
<label>Engine id <input id="rt-id" type="text" maxlength="128" placeholder="numeric engine id"></label>
<div class="rt-actions">
<button id="rt-list" type="button" class="primary">List engines</button>
<button id="rt-get" type="button">Get</button>
</div>
<label>Query input (JSON object) <textarea id="rt-input" rows="3">{"message":"hello"}</textarea></label>
<label>Class method <input id="rt-method" type="text" maxlength="64" value="query"></label>
<div class="rt-actions">
<button id="rt-query" type="button">Query</button>
<button id="rt-stream" type="button">Stream query</button>
</div>
<p id="rt-error" class="error" role="alert"></p>
<pre id="rt-out" class="rt-out"></pre>
</section>
<style>
.rt label{display:block;margin:.5rem 0}
.rt input,.rt textarea{width:100%;box-sizing:border-box}
.rt-actions{display:flex;flex-wrap:wrap;gap:.5rem;margin:.5rem 0}
.rt-out{overflow:auto;max-height:24rem;white-space:pre-wrap;word-break:break-word}
</style>
<script src="/embedded/agent_runtime.js"></script>
{% endblock %}
)RUNTIME";
std::string quote(const std::string& s) { return "\"" + fw::json_escape(s) + "\""; }
fw::Response json_out(const Json& j, int status = 200) {
fw::Response res = fw::JsonResponse(j.dump(), status);
res.headers.set("Cache-Control", "no-store");
return res;
}
[[noreturn]] void rethrow(const google::GoogleError& e) {
if (e.http_status() == 503 && e.status() == "NOT_CONFIGURED")
throw fw::HttpError(503, "google_not_configured", e.message());
if (e.service().empty() && e.status() == "INVALID_ARGUMENT")
throw fw::HttpError(422, "validation_error", e.message());
throw fw::HttpError(502, "google_error", e.status() + ": " + e.message());
}
template <typename F>
auto guarded(F&& f) -> decltype(f()) {
try {
return f();
} catch (const google::GoogleError& e) {
rethrow(e);
}
}
[[noreturn]] void bad(const std::string& why) {
throw fw::HttpError(422, "validation_error", why);
}
Json parse_body(const fw::Request& req) {
if (req.body.size() > kMaxBody) throw fw::HttpError(413, "payload_too_large", "body too large");
if (req.body.empty()) return Json::object();
try {
Json j = Json::parse(req.body);
if (!j.is_object()) bad("body must be a JSON object");
return j;
} catch (const clients::body::JsonError&) {
bad("body is not valid JSON");
}
}
std::string text(const Json& body, const char* key, bool required = false) {
const Json* v = body.find(key);
if (!v || v->is_null()) {
if (required) bad(std::string(key) + " is required");
return "";
}
if (!v->is_string()) bad(std::string(key) + " must be a string");
return v->as_string();
}
std::optional<int> number(const Json& body, const char* key) {
const Json* v = body.find(key);
if (!v || v->is_null()) return std::nullopt;
if (!v->is_number()) bad(std::string(key) + " must be a number");
return static_cast<int>(v->as_int());
}
std::string engine_id(const Json& body) {
std::string id = text(body, "id", true);
if (!google::valid_segment(id)) bad("id must be 1-128 chars of A-Z a-z 0-9 . _ -");
return id;
}
Json engine_summary(const rt::Engine& e) {
Json o = Json::object();
o.set("name", Json(e.name));
o.set("id", Json(e.id()));
o.set("displayName", Json(e.display_name));
o.set("createTime", Json(e.create_time));
o.set("updateTime", Json(e.update_time));
o.set("agentFramework", Json(e.spec.agent_framework));
return o;
}
Json operation_json(const google::Operation& op) {
Json o = Json::object();
o.set("operation", Json(op.name));
o.set("done", Json(op.done));
if (op.failed()) o.set("error", Json(op.error_message));
if (op.done && op.response.is_object()) o.set("response", op.response);
return o;
}
rt::EngineDraft draft_from(const Json& body) {
rt::EngineDraft d;
d.display_name = text(body, "displayName", true);
d.description = text(body, "description");
d.spec.agent_framework = text(body, "agentFramework");
std::string image = text(body, "imageUri");
if (!image.empty()) d.spec.container = rt::ContainerSpec{image, std::nullopt};
std::string identity = text(body, "identityType");
if (!identity.empty()) {
if (identity != "SERVICE_ACCOUNT" && identity != "AGENT_IDENTITY")
bad("identityType must be SERVICE_ACCOUNT or AGENT_IDENTITY");
d.spec.identity = rt::identity_type_from(identity);
}
d.spec.service_account = text(body, "serviceAccount");
rt::DeploymentSpec dep;
bool has_dep = false;
if (auto n = number(body, "minInstances")) { dep.min_instances = n; has_dep = true; }
if (auto n = number(body, "maxInstances")) { dep.max_instances = n; has_dep = true; }
dep.cpu = text(body, "cpu");
dep.memory = text(body, "memory");
if (!dep.cpu.empty() || !dep.memory.empty()) has_dep = true;
if (has_dep) d.spec.deployment = dep;
try {
d.validate(); // local rules first: 422 before any credential check
} catch (const google::GoogleError& e) {
rethrow(e);
}
return d;
}
} // namespace
void register_agent_runtime_demo(fw::Router& router, Services& services) {
(void)router;
(void)services;
if (!services.google) services.google = google::GoogleClient::from_env();
auto client = services.google;
fw::Environment* env = services.templates.get();
services.templates->add_template("agent_runtime.html", kPage);
services.add_feature("agent-runtime", "/agent/runtime");
// Fresh per request so the environment is read when the call happens.
auto runtime = [client]() {
if (!client->configured()) throw google::NotConfiguredError("aiplatform");
return rt::AgentRuntime(client, google::CloudContext::from_env());
};
router.get("/agent/runtime", "agent-runtime-page", [env](fw::Request req) {
(void)req;
fw::TemplateCtx ctx;
ctx["title"] = std::string("Agent Runtime");
return fw::Response(200, env->render("agent_runtime.html", ctx), "text/html; charset=utf-8");
});
router.get("/agent/runtime/status", "agent-runtime-status", [client](fw::Request req) {
(void)req;
google::CloudContext ctx = google::CloudContext::from_env();
Json o = Json::object();
o.set("configured", Json(client->configured()));
o.set("project_set", Json(!ctx.project.empty()));
o.set("location", Json(ctx.location));
o.set("max_stream_events", Json(static_cast<int>(kMaxStreamEventsShown)));
return json_out(o);
});
// The discovery-checked call table, for humans.
router.get("/agent/runtime/calls", "agent-runtime-calls", [](fw::Request req) {
(void)req;
Json arr = Json::array();
for (int c = static_cast<int>(rt::Call::kCreate); c <= static_cast<int>(rt::Call::kRevisionStreamQuery); ++c) {
const rt::CallSpec& s = rt::spec_of(static_cast<rt::Call>(c));
Json row = Json::object();
row.set("http", Json(s.http_method));
row.set("path", Json(s.path));
row.set("version", Json(s.version));
row.set("rpc", Json(s.rpc_id));
arr.push(row);
}
Json o = Json::object();
o.set("calls", arr);
return json_out(o);
});
router.post("/agent/runtime/list", "agent-runtime-list", [runtime](fw::Request req) {
Json body = parse_body(req);
std::string filter = text(body, "filter");
if (filter.size() > rt::RuntimeCaps::kMaxFilterChars) bad("filter too long");
return guarded([&] {
Json arr = Json::array();
for (const auto& e : runtime().list(filter)) arr.push(engine_summary(e));
Json o = Json::object();
o.set("engines", arr);
return json_out(o);
});
});
router.post("/agent/runtime/get", "agent-runtime-get", [runtime](fw::Request req) {
Json body = parse_body(req);
std::string id = engine_id(body);
return guarded([&] { return json_out(runtime().get(id).raw); });
});
router.post("/agent/runtime/create", "agent-runtime-create", [runtime](fw::Request req) {
Json body = parse_body(req);
rt::EngineDraft draft = draft_from(body);
return guarded([&] { return json_out(operation_json(runtime().create_start(draft)), 202); });
});
router.post("/agent/runtime/operation", "agent-runtime-operation", [runtime](fw::Request req) {
Json body = parse_body(req);
std::string name = text(body, "name", true);
if (name.rfind("projects/", 0) != 0 || name.size() > 512 || name.find("..") != std::string::npos)
bad("name must be an operation name starting with projects/");
return guarded([&] { return json_out(operation_json(runtime().operation(name))); });
});
auto query_args = [](const Json& body, std::string& id, Json& input, std::string& method) {
id = engine_id(body);
const Json* in = body.find("input");
input = in && in->is_object() ? *in : Json::object();
if (in && !in->is_object() && !in->is_null()) bad("input must be a JSON object");
method = text(body, "classMethod");
if (!method.empty()) {
try {
rt::AgentRuntime::query_body(input, method); // validates method and size
} catch (const google::GoogleError& e) {
rethrow(e);
}
}
};
router.post("/agent/runtime/query", "agent-runtime-query", [runtime, query_args](fw::Request req) {
Json body = parse_body(req);
std::string id, method;
Json input;
query_args(body, id, input, method);
return guarded([&] {
auto r = runtime();
return json_out(method.empty() ? r.query(id, input) : r.query(id, input, method));
});
});
// Streams server side, answers the first events as one JSON array.
router.post("/agent/runtime/stream", "agent-runtime-stream", [runtime, query_args](fw::Request req) {
Json body = parse_body(req);
std::string id, method;
Json input;
query_args(body, id, input, method);
return guarded([&] {
auto r = runtime();
Json events = Json::array();
auto sink = [&](const Json& e) {
events.push(e);
return events.as_array().size() < kMaxStreamEventsShown;
};
if (method.empty()) r.stream_query(id, input, sink);
else r.stream_query(id, input, sink, method);
Json o = Json::object();
o.set("events", events);
return json_out(o);
});
});
router.post("/agent/runtime/async", "agent-runtime-async", [runtime](fw::Request req) {
Json body = parse_body(req);
std::string id = engine_id(body);
std::string in = text(body, "inputGcsUri", true), out = text(body, "outputGcsUri", true);
if (in.rfind("gs://", 0) != 0 || out.rfind("gs://", 0) != 0)
bad("inputGcsUri and outputGcsUri must be gs:// URIs");
return guarded([&] { return json_out(operation_json(runtime().async_query(id, in, out)), 202); });
});
// Destructive: a dry run unless "confirm":true; force is its own field.
router.post("/agent/runtime/delete", "agent-runtime-delete", [runtime](fw::Request req) {
Json body = parse_body(req);
std::string id = engine_id(body);
const Json* f = body.find("force");
if (f && !f->is_bool()) bad("force must be true or false");
const Json* c = body.find("confirm");
if (c && !c->is_bool()) bad("confirm must be true or false");
bool force = f && f->as_bool();
if (!(c && c->as_bool())) {
Json o = Json::object();
o.set("dry_run", Json(true));
o.set("would_delete", Json(id));
o.set("force", Json(force));
o.set("hint", Json("send confirm:true to delete"));
return json_out(o);
}
return guarded([&] { return json_out(operation_json(runtime().destroy_start(id, force)), 202); });
});
}
} // namespace molo::example::app