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
+316
View File
@@ -0,0 +1,316 @@
// Agent Runtime: deterministic local tests (call table, request bodies,
// validation, caps, no-credential behavior) plus an opt-in live read-only
// check. No scripted Google replies: shapes are verified against Google's
// Discovery documents by src/google/runtime/tools/check_discovery.py and,
// where a credential allows, live (see src/google/runtime/SPEC.md).
#include <cstdlib>
#include <iostream>
#include <memory>
#include "framework.h"
#include "clients/transports/http_transport.h"
#include "clients/transports/mock_transport.h"
#include "google/credentials.h"
#include "google/runtime/agent_runtime.h"
#include "google/runtime/calls.h"
#include "google/runtime/caps.h"
using namespace molo::google;
using namespace molo::google::runtime;
using molo::clients::Method;
using molo::clients::body::Json;
using molo::clients::transports::MockTransport;
namespace {
// A runtime without credentials: any call that passes validation throws
// NotConfiguredError before network traffic, so validation is observable.
struct Rig {
MockTransport* mock;
std::unique_ptr<AgentRuntime> rt;
Rig() {
auto t = std::make_unique<MockTransport>();
mock = t.get();
auto client = std::make_shared<GoogleClient>(std::move(t), nullptr);
CloudContext ctx;
ctx.project = "p1";
rt = std::make_unique<AgentRuntime>(client, ctx);
}
};
EngineDraft draft() {
EngineDraft d;
d.display_name = "Support agent";
d.spec.agent_framework = "google-adk";
ContainerSpec c;
c.image_uri = "us-docker.pkg.dev/p1/r/agent:1";
c.port = 8080;
d.spec.container = c;
DeploymentSpec dep;
dep.env.push_back({"MODE", "prod"});
dep.secret_env.push_back({"API_KEY", "my-secret", "latest"});
dep.min_instances = 1;
dep.max_instances = 10;
dep.container_concurrency = 9;
dep.cpu = "4";
dep.memory = "8Gi";
d.spec.deployment = dep;
d.spec.identity = IdentityType::kAgentIdentity;
d.spec.build_service_account = "build@p1.iam.gserviceaccount.com";
d.kms_key_name = "projects/p1/locations/us-central1/keyRings/r/cryptoKeys/k";
return d;
}
template <typename F>
bool invalid(F&& f) {
try {
f();
} catch (const NotConfiguredError&) {
return false; // passed validation, stopped at the credential check
} catch (const GoogleError& e) {
return e.http_status() == 400 && e.status() == "INVALID_ARGUMENT";
}
return false;
}
} // namespace
TEST(runtime, call_table_paths) {
ASSERT_EQ(render(Call::kCreate, "projects/p/locations/l"),
"/projects/p/locations/l/reasoningEngines");
ASSERT_EQ(render(Call::kQuery, "projects/p/locations/l/reasoningEngines/e"),
"/projects/p/locations/l/reasoningEngines/e:query");
ASSERT_EQ(render(Call::kStreamQuery, "n"), "/n:streamQuery");
ASSERT_EQ(render(Call::kGetIamPolicy, "n"), "/n:getIamPolicy");
ASSERT_EQ(render(Call::kOperationList, "n"), "/n/operations");
ASSERT_EQ(render(Call::kRevisionList, "n"), "/n/runtimeRevisions");
ASSERT_TRUE(method_of(Call::kPatch) == Method::kPatch);
ASSERT_TRUE(method_of(Call::kDelete) == Method::kDelete);
ASSERT_EQ(endpoint_of(Call::kGet, "us-central1").base_url,
"https://us-central1-aiplatform.googleapis.com/v1");
ASSERT_EQ(endpoint_of(Call::kRevisionGet, "us-central1").base_url,
"https://us-central1-aiplatform.googleapis.com/v1beta1");
}
TEST(runtime, create_body_matches_discovery_field_names) {
Json b = draft().to_json();
ASSERT_EQ(b.find("displayName")->as_string(), "Support agent");
ASSERT_TRUE(b.find("encryptionSpec")->find("kmsKeyName") != nullptr);
const Json* spec = b.find("spec");
ASSERT_EQ(spec->find("agentFramework")->as_string(), "google-adk");
ASSERT_EQ(spec->find("identityType")->as_string(), "AGENT_IDENTITY");
ASSERT_EQ(spec->find("containerSpec")->find("port")->as_int(), 8080);
ASSERT_EQ(spec->find("buildSpec")->find("serviceAccount")->as_string(),
"build@p1.iam.gserviceaccount.com");
const Json* dep = spec->find("deploymentSpec");
ASSERT_EQ(dep->find("maxInstances")->as_int(), 10);
ASSERT_EQ(dep->find("containerConcurrency")->as_int(), 9);
ASSERT_EQ(dep->find("resourceLimits")->find("memory")->as_string(), "8Gi");
ASSERT_EQ(dep->find("env")->as_array()[0].find("name")->as_string(), "MODE");
ASSERT_EQ(dep->find("secretEnv")->as_array()[0].find("secretRef")->find("secret")->as_string(),
"my-secret");
}
TEST(runtime, spec_roundtrip_keeps_unknown_fields) {
Json doc = Json::parse(
"{\"name\":\"projects/p/locations/l/reasoningEngines/e1\",\"displayName\":\"x\","
"\"spec\":{\"agentFramework\":\"custom\",\"futureField\":{\"a\":1},"
"\"effectiveIdentity\":\"agent://x\",\"deploymentSpec\":{\"keepAliveProbe\":{\"maxSeconds\":5},"
"\"agentServerMode\":\"STABLE\",\"minInstances\":2}}}");
Engine e = Engine::from_json(doc);
ASSERT_EQ(e.id(), "e1");
ASSERT_EQ(e.spec.effective_identity, "agent://x");
Json out = e.spec.to_json();
ASSERT_TRUE(out.find("futureField") != nullptr);
ASSERT_TRUE(out.find("effectiveIdentity") == nullptr); // output only
ASSERT_TRUE(out.find("deploymentSpec")->find("keepAliveProbe") != nullptr);
ASSERT_EQ(out.find("deploymentSpec")->find("agentServerMode")->as_string(), "STABLE");
}
TEST(runtime, update_mask_and_body) {
EngineUpdate u;
u.display_name = "New";
EngineSpec s;
DeploymentSpec dep;
dep.max_instances = 20;
s.deployment = dep;
u.spec = s;
ASSERT_EQ(u.update_mask(), "displayName,spec.deploymentSpec");
Json body = u.to_json();
ASSERT_EQ(body.find("displayName")->as_string(), "New");
ASSERT_TRUE(body.find("spec")->find("containerSpec") == nullptr);
EngineUpdate empty;
ASSERT_TRUE(invalid([&] { empty.to_json(); }));
EngineUpdate no_spec_fields;
no_spec_fields.spec = EngineSpec{};
ASSERT_TRUE(invalid([&] { no_spec_fields.to_json(); }));
}
TEST(runtime, query_body_shape) {
Json in = Json::object();
in.set("message", Json("hi"));
Json b = AgentRuntime::query_body(in, "query");
ASSERT_EQ(b.find("classMethod")->as_string(), "query");
ASSERT_EQ(b.find("input")->find("message")->as_string(), "hi");
ASSERT_TRUE(invalid([&] { AgentRuntime::query_body(Json("str"), "query"); }));
ASSERT_TRUE(invalid([&] { AgentRuntime::query_body(in, "bad method"); }));
ASSERT_TRUE(invalid([&] { AgentRuntime::query_body(in, ""); }));
}
TEST(runtime, ids_and_names_validated_before_network) {
Rig r;
Json in = Json::object();
ASSERT_TRUE(invalid([&] { r.rt->get("../x"); }));
ASSERT_TRUE(invalid([&] { r.rt->get(""); }));
ASSERT_TRUE(invalid([&] { r.rt->get("a/b"); }));
ASSERT_TRUE(invalid([&] { r.rt->destroy("../x", false); }));
ASSERT_TRUE(invalid([&] { r.rt->get_revision("e1", "../r"); }));
ASSERT_TRUE(invalid([&] { r.rt->wait("../etc"); }));
ASSERT_TRUE(invalid([&] { r.rt->operation("operations/1"); }));
ASSERT_TRUE(invalid([&] { r.rt->cancel_operation("projects/p/../q"); }));
ASSERT_TRUE(invalid([&] { r.rt->cancel_async_query("e1", "x"); }));
ASSERT_TRUE(invalid([&] { r.rt->async_query("e1", "http://x", "gs://o"); }));
ASSERT_TRUE(invalid([&] { r.rt->async_query("e1", "gs://i", "gs://"); }));
ASSERT_TRUE(invalid([&] { r.rt->execute_code("e1", Json::array()); }));
ASSERT_TRUE(invalid([&] { r.rt->set_iam_policy("e1", Json("x")); }));
ASSERT_TRUE(invalid([&] { r.rt->get_iam_policy("e1", 9); }));
ASSERT_TRUE(invalid([&] { r.rt->test_iam_permissions("e1", {}); }));
ASSERT_TRUE(invalid([&] { r.rt->test_iam_permissions("e1", {"a b"}); }));
EngineDraft d = draft();
d.display_name = "";
ASSERT_TRUE(invalid([&] { r.rt->create_start(d); }));
ASSERT_EQ(r.mock->send_count(), 0u);
}
TEST(runtime, spec_rules) {
EngineDraft d = draft();
d.spec.service_account = "sa@p1.iam.gserviceaccount.com"; // with AGENT_IDENTITY
ASSERT_TRUE(invalid([&] { d.to_json(); }));
d = draft();
d.spec.identity = IdentityType::kServiceAccount;
d.spec.service_account = "not-an-email";
ASSERT_TRUE(invalid([&] { d.to_json(); }));
d.spec.service_account = "sa@p1.iam.gserviceaccount.com";
d.to_json(); // valid
d = draft();
d.spec.package = PackageSpec{}; // container and package together
ASSERT_TRUE(invalid([&] { d.to_json(); }));
d = draft();
d.spec.container = std::nullopt;
PackageSpec p;
p.python_version = "2.7";
d.spec.package = p;
ASSERT_TRUE(invalid([&] { d.to_json(); }));
p.python_version = "3.12";
p.requirements_gcs_uri = "https://x/r.txt";
d.spec.package = p;
ASSERT_TRUE(invalid([&] { d.to_json(); }));
d = draft();
d.spec.agent_framework = "magic";
ASSERT_TRUE(invalid([&] { d.to_json(); }));
d = draft();
d.spec.container->port = 70000;
ASSERT_TRUE(invalid([&] { d.to_json(); }));
d = draft();
d.spec.container->image_uri = "";
ASSERT_TRUE(invalid([&] { d.to_json(); }));
}
TEST(runtime, deployment_caps) {
auto bad = [](auto mutate) {
EngineDraft d = draft();
mutate(*d.spec.deployment);
return invalid([&] { d.to_json(); });
};
ASSERT_TRUE(bad([](DeploymentSpec& s) { s.max_instances = 1001; }));
ASSERT_TRUE(bad([](DeploymentSpec& s) { s.max_instances = 0; }));
ASSERT_TRUE(bad([](DeploymentSpec& s) { s.min_instances = 76; }));
ASSERT_TRUE(bad([](DeploymentSpec& s) { s.min_instances = 11; })); // above max 10
ASSERT_TRUE(bad([](DeploymentSpec& s) { s.container_concurrency = 0; }));
ASSERT_TRUE(bad([](DeploymentSpec& s) { s.cpu = "3"; }));
ASSERT_TRUE(bad([](DeploymentSpec& s) { s.memory = "33Gi"; }));
ASSERT_TRUE(bad([](DeploymentSpec& s) { s.memory = "8GB"; }));
ASSERT_TRUE(bad([](DeploymentSpec& s) { s.env.push_back({"MODE", "dup"}); }));
ASSERT_TRUE(bad([](DeploymentSpec& s) { s.env.push_back({"1BAD", "x"}); }));
ASSERT_TRUE(bad([](DeploymentSpec& s) {
s.env.push_back({"BIG", std::string(RuntimeCaps::kMaxEnvValueChars + 1, 'a')});
}));
ASSERT_TRUE(bad([](DeploymentSpec& s) {
for (std::size_t i = 0; i < RuntimeCaps::kMaxEnvVars; ++i)
s.env.push_back({"V" + std::to_string(i), "x"});
}));
EngineDraft d = draft();
d.description = std::string(RuntimeCaps::kMaxDescription + 1, 'a');
ASSERT_TRUE(invalid([&] { d.to_json(); }));
d = draft();
d.display_name = std::string(RuntimeCaps::kMaxDisplayName + 1, 'a');
ASSERT_TRUE(invalid([&] { d.to_json(); }));
d = draft();
for (std::size_t i = 0; i < RuntimeCaps::kMaxLabels + 1; ++i) d.labels["k" + std::to_string(i)] = "v";
ASSERT_TRUE(invalid([&] { d.to_json(); }));
Json big = Json::object();
big.set("m", Json(std::string(RuntimeCaps::kMaxInputBytes + 1, 'a')));
ASSERT_TRUE(invalid([&] { AgentRuntime::query_body(big, "query"); }));
Rig r;
ASSERT_TRUE(invalid([&] { r.rt->list(std::string(RuntimeCaps::kMaxFilterChars + 1, 'f')); }));
}
TEST(runtime, no_credential_is_loud_and_offline) {
Rig r;
try {
r.rt->get("e1");
FAIL("must throw");
} catch (const NotConfiguredError& e) {
ASSERT_EQ(e.http_status(), 503);
}
ASSERT_THROW(r.rt->list(), NotConfiguredError);
ASSERT_THROW(r.rt->destroy("e1", true), NotConfiguredError);
ASSERT_EQ(r.mock->send_count(), 0u);
}
TEST(runtime, identity_and_secret_env_roundtrip) {
DeploymentSpec d;
d.secret_env.push_back({"API_KEY", "my-secret", "latest"});
d.container_concurrency = 5;
d.validate();
DeploymentSpec back = DeploymentSpec::from_json(d.to_json());
ASSERT_EQ(back.secret_env.size(), 1u);
ASSERT_EQ(back.secret_env[0].secret, "my-secret");
ASSERT_EQ(*back.container_concurrency, 5);
ASSERT_TRUE(identity_type_from("SERVICE_ACCOUNT") == IdentityType::kServiceAccount);
ASSERT_TRUE(identity_type_from("nonsense") == IdentityType::kUnspecified);
}
// Live, read-only. Needs MOLO_LIVE_NET=1, GOOGLE_CLOUD_PROJECT and a
// credential (an express key AQ... is enough for these reads). Never creates,
// updates or deletes anything.
TEST(runtime_live, read_only_calls) {
CloudContext ctx = CloudContext::from_env();
auto client = GoogleClient::from_env();
if (!std::getenv("MOLO_LIVE_NET") || !client->configured() || ctx.project.empty()) {
std::cout << "SKIP runtime_live.read_only_calls (set MOLO_LIVE_NET=1, GOOGLE_CLOUD_PROJECT "
"and a Google credential)\n";
return;
}
ctx.location = "us-central1";
AgentRuntime rt(client, ctx);
auto engines = rt.list();
std::cout << " engines in us-central1: " << engines.size() << "\n";
// A missing engine must map to a typed NOT_FOUND-style error, not a crash.
try {
rt.get("1234567890123");
FAIL("a missing engine must not be found");
} catch (const GoogleError& e) {
std::cout << " get missing: " << e.http_status() << " " << e.status() << "\n";
ASSERT_TRUE(e.http_status() == 404 || e.http_status() == 403 || e.http_status() == 400);
}
try {
rt.query("1234567890123", Json::object());
FAIL("a missing engine must not answer a query");
} catch (const GoogleError& e) {
std::cout << " query missing: " << e.http_status() << " " << e.status() << "\n";
ASSERT_TRUE(e.http_status() >= 400 && e.http_status() < 500);
}
ctx.location = "europe-west4";
AgentRuntime eu(client, ctx);
std::cout << " engines in europe-west4: " << eu.list().size() << "\n";
}