feat(clients): sessions: Agent Sessions and Memory Bank, discovery-checked call table, guarded purge, live read probes
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,13 +1,360 @@
|
||||
#include "../AgentDemos.hpp"
|
||||
|
||||
#include <memory>
|
||||
|
||||
#include "../../fw/Router.hpp"
|
||||
#include "../../fw/Templates.hpp"
|
||||
#include "../../fw/Validate.hpp"
|
||||
#include "google/resource.h"
|
||||
#include "google/sessions/caps.h"
|
||||
#include "google/sessions/calls.h"
|
||||
#include "google/sessions/memory_bank.h"
|
||||
#include "google/sessions/sessions.h"
|
||||
|
||||
namespace molo::example::app {
|
||||
|
||||
// Agent Platform: sessions. Stub: the module agent fills this in.
|
||||
// Agent Platform: Agent Sessions and Agent Memory Bank over src/google/sessions.
|
||||
// Every route that would call Google is a POST (or DELETE) and answers 503
|
||||
// google_not_configured without a credential and 422 on bad input. The engine
|
||||
// is a full reasoningEngines name or a bare engine id (project from
|
||||
// GOOGLE_CLOUD_PROJECT). Live behavior needs an Agent Engine resource and a
|
||||
// credential Google accepts for it; see src/google/sessions/SPEC.md.
|
||||
|
||||
namespace {
|
||||
|
||||
namespace gs = molo::google::sessions;
|
||||
using Flat = std::map<std::string, std::string>;
|
||||
using GJson = molo::clients::body::Json;
|
||||
|
||||
const char kSessionsPage[] = R"SESSIONS({% extends "base.html" %}
|
||||
{% block content %}
|
||||
<h1>Agent sessions and memory</h1>
|
||||
<p>Sessions and Memory Bank under one Agent Engine
|
||||
(<code>projects/P/locations/L/reasoningEngines/E</code>, or a bare engine id).
|
||||
Every call below is a JSON POST (or DELETE) and answers 503
|
||||
<code>google_not_configured</code> without a credential.</p>
|
||||
<p><a href="/agent/sessions/status">Status</a></p>
|
||||
<div style="overflow-x:auto">
|
||||
<table>
|
||||
<thead><tr><th>Route</th><th>Body</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td>POST /agent/sessions/create</td><td>engine, user_id, session_id?, display_name?, ttl?</td></tr>
|
||||
<tr><td>POST /agent/sessions/get</td><td>engine, session_id</td></tr>
|
||||
<tr><td>POST /agent/sessions/list</td><td>engine, filter?</td></tr>
|
||||
<tr><td>DELETE /agent/sessions/session</td><td>query: engine, id</td></tr>
|
||||
<tr><td>POST /agent/sessions/events/append</td><td>engine, session_id, author, invocation_id, timestamp, text</td></tr>
|
||||
<tr><td>POST /agent/sessions/events/list</td><td>engine, session_id</td></tr>
|
||||
<tr><td>POST /agent/sessions/memories/generate</td><td>engine, scope_key, scope_value, text or session_id</td></tr>
|
||||
<tr><td>POST /agent/sessions/memories/retrieve</td><td>engine, scope_key, scope_value, query?, top_k?</td></tr>
|
||||
<tr><td>POST /agent/sessions/memories/create</td><td>engine, scope_key, scope_value, fact, memory_id?</td></tr>
|
||||
<tr><td>POST /agent/sessions/memories/get</td><td>engine, memory_id</td></tr>
|
||||
<tr><td>POST /agent/sessions/memories/list</td><td>engine, filter?</td></tr>
|
||||
<tr><td>DELETE /agent/sessions/memories/memory</td><td>query: engine, id</td></tr>
|
||||
<tr><td>POST /agent/sessions/memories/profiles</td><td>engine, scope_key, scope_value</td></tr>
|
||||
<tr><td>POST /agent/sessions/memories/purge</td><td>engine, filter, force?, confirm? (dry run by default)</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
{% endblock %}
|
||||
)SESSIONS";
|
||||
|
||||
[[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);
|
||||
}
|
||||
}
|
||||
|
||||
std::string field(const Flat& in, const std::string& key) {
|
||||
auto it = in.find(key);
|
||||
return it == in.end() ? "" : it->second;
|
||||
}
|
||||
|
||||
fw::Response answer(const GJson& body, int status = 200) {
|
||||
fw::Response res = fw::JsonResponse(body.dump(), status);
|
||||
res.headers.set("Cache-Control", "no-store");
|
||||
return res;
|
||||
}
|
||||
|
||||
// Routes for one demo: resolves the engine and runs the typed services.
|
||||
class SessionsRoutes {
|
||||
public:
|
||||
explicit SessionsRoutes(std::shared_ptr<google::GoogleClient> client)
|
||||
: client_(std::move(client)) {}
|
||||
|
||||
bool configured() const { return client_->configured(); }
|
||||
|
||||
gs::EngineName engine_of(const std::string& value) const {
|
||||
if (value.rfind("projects/", 0) == 0) return gs::EngineName(value);
|
||||
google::CloudContext ctx = google::CloudContext::from_env();
|
||||
return gs::EngineName(ctx.child("reasoningEngines", value));
|
||||
}
|
||||
gs::Sessions sessions(const std::string& engine) const {
|
||||
return gs::Sessions(client_, engine_of(engine));
|
||||
}
|
||||
gs::MemoryBank bank(const std::string& engine) const {
|
||||
return gs::MemoryBank(client_, engine_of(engine));
|
||||
}
|
||||
|
||||
static gs::StringMap scope_of(const Flat& in) {
|
||||
gs::StringMap scope;
|
||||
if (!field(in, "scope_key").empty() || !field(in, "scope_value").empty())
|
||||
scope[field(in, "scope_key")] = field(in, "scope_value");
|
||||
return scope;
|
||||
}
|
||||
|
||||
private:
|
||||
std::shared_ptr<google::GoogleClient> client_;
|
||||
};
|
||||
|
||||
GJson memory_json(const gs::Memory& m) { return m.to_json(); }
|
||||
|
||||
} // namespace
|
||||
|
||||
void register_agent_sessions_demo(fw::Router& router, Services& services) {
|
||||
(void)router;
|
||||
(void)services;
|
||||
if (!services.google) services.google = google::GoogleClient::from_env();
|
||||
auto routes = std::make_shared<SessionsRoutes>(services.google);
|
||||
fw::Environment* env = services.templates.get();
|
||||
env->add_template("agent_sessions.html", kSessionsPage);
|
||||
|
||||
services.add_feature("agent sessions", "/agent/sessions");
|
||||
|
||||
router.get("/agent/sessions", "agent-sessions-page", [env](fw::Request req) {
|
||||
(void)req;
|
||||
fw::TemplateCtx ctx;
|
||||
ctx["title"] = std::string("Agent sessions");
|
||||
return fw::Response(200, env->render("agent_sessions.html", ctx),
|
||||
"text/html; charset=utf-8");
|
||||
});
|
||||
|
||||
router.get("/agent/sessions/status", "agent-sessions-status", [routes](fw::Request req) {
|
||||
(void)req;
|
||||
GJson out = GJson::object();
|
||||
out.set("configured", GJson(routes->configured()));
|
||||
out.set("surface", GJson(std::string(gs::kDiscoveryService) + " " + gs::kDiscoveryVersion));
|
||||
out.set("calls", GJson(static_cast<int>(gs::Call::kCount)));
|
||||
GJson caps = GJson::object();
|
||||
caps.set("max_session_id_chars", GJson(static_cast<int>(gs::SessionsCaps::kMaxIdChars)));
|
||||
caps.set("max_list_items", GJson(static_cast<int>(gs::SessionsCaps::kMaxListItems)));
|
||||
caps.set("max_top_k", GJson(gs::MemoryCaps::kMaxTopK));
|
||||
caps.set("max_fact_chars", GJson(static_cast<int>(gs::MemoryCaps::kMaxFactChars)));
|
||||
out.set("caps", caps);
|
||||
return answer(out);
|
||||
});
|
||||
|
||||
// Sessions ---------------------------------------------------------------
|
||||
|
||||
router.post("/agent/sessions/create", "agent-sessions-create", [routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
gs::SessionSpec spec;
|
||||
spec.session_id = field(in, "session_id");
|
||||
spec.user_id = field(in, "user_id");
|
||||
spec.display_name = field(in, "display_name");
|
||||
spec.ttl = field(in, "ttl");
|
||||
return answer(routes->sessions(field(in, "engine")).create(spec).to_json(), 201);
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/get", "agent-sessions-get", [routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
return answer(routes->sessions(field(in, "engine")).get(field(in, "session_id")).to_json());
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/list", "agent-sessions-list", [routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
gs::SessionListOptions options;
|
||||
options.filter = field(in, "filter");
|
||||
GJson arr = GJson::array();
|
||||
for (const gs::Session& s : routes->sessions(field(in, "engine")).list(options))
|
||||
arr.push(s.to_json());
|
||||
GJson out = GJson::object();
|
||||
out.set("sessions", arr);
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
router.del("/agent/sessions/session", "agent-sessions-delete", [routes](fw::Request req) {
|
||||
return guarded([&] {
|
||||
routes->sessions(req.query_or("engine", "")).delete_session(req.query_or("id", ""));
|
||||
GJson out = GJson::object();
|
||||
out.set("deleted", GJson(true));
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/events/append", "agent-sessions-event-append",
|
||||
[routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
gs::SessionEvent ev;
|
||||
ev.author = field(in, "author");
|
||||
ev.invocation_id = field(in, "invocation_id");
|
||||
ev.timestamp = field(in, "timestamp");
|
||||
if (!field(in, "text").empty()) {
|
||||
std::string role = field(in, "role").empty() ? "user" : field(in, "role");
|
||||
google::Content c = role == "model" ? google::Content::model(field(in, "text"))
|
||||
: google::Content::user(field(in, "text"));
|
||||
ev.content = c;
|
||||
}
|
||||
routes->sessions(field(in, "engine")).append_event(field(in, "session_id"), ev);
|
||||
GJson out = GJson::object();
|
||||
out.set("appended", GJson(true));
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/events/list", "agent-sessions-event-list",
|
||||
[routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
GJson arr = GJson::array();
|
||||
for (const gs::SessionEvent& e :
|
||||
routes->sessions(field(in, "engine")).list_events(field(in, "session_id")))
|
||||
arr.push(e.to_json());
|
||||
GJson out = GJson::object();
|
||||
out.set("events", arr);
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
// Memory Bank ------------------------------------------------------------
|
||||
|
||||
router.post("/agent/sessions/memories/generate", "agent-memories-generate",
|
||||
[routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
gs::MemoryGenerateRequest g;
|
||||
g.scope = SessionsRoutes::scope_of(in);
|
||||
if (!field(in, "session_id").empty()) {
|
||||
g.source = gs::MemoryGenerateRequest::Source::kSession;
|
||||
g.session_id = field(in, "session_id");
|
||||
} else {
|
||||
g.source = gs::MemoryGenerateRequest::Source::kContents;
|
||||
if (!field(in, "text").empty()) g.contents.push_back(google::Content::user(field(in, "text")));
|
||||
}
|
||||
GJson arr = GJson::array();
|
||||
for (const gs::GeneratedMemory& m : routes->bank(field(in, "engine")).generate(g)) {
|
||||
GJson item = GJson::object();
|
||||
item.set("memory", memory_json(m.memory));
|
||||
item.set("action", GJson(m.action));
|
||||
arr.push(item);
|
||||
}
|
||||
GJson out = GJson::object();
|
||||
out.set("generated", arr);
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/memories/retrieve", "agent-memories-retrieve",
|
||||
[routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
gs::RetrieveRequest r;
|
||||
r.scope = SessionsRoutes::scope_of(in);
|
||||
r.search_query = field(in, "query");
|
||||
if (!field(in, "top_k").empty()) r.top_k = std::atoi(field(in, "top_k").c_str());
|
||||
gs::RetrieveResult res = routes->bank(field(in, "engine")).retrieve(r);
|
||||
GJson arr = GJson::array();
|
||||
for (const gs::RetrievedMemory& m : res.memories) {
|
||||
GJson item = GJson::object();
|
||||
item.set("memory", memory_json(m.memory));
|
||||
if (m.has_distance) item.set("distance", GJson(m.distance));
|
||||
arr.push(item);
|
||||
}
|
||||
GJson out = GJson::object();
|
||||
out.set("memories", arr);
|
||||
out.set("next_page_token", GJson(res.next_page_token));
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/memories/create", "agent-memories-create",
|
||||
[routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
gs::MemorySpec spec;
|
||||
spec.memory_id = field(in, "memory_id");
|
||||
spec.fact = field(in, "fact");
|
||||
spec.scope = SessionsRoutes::scope_of(in);
|
||||
return answer(memory_json(routes->bank(field(in, "engine")).create(spec)), 201);
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/memories/get", "agent-memories-get", [routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
return answer(memory_json(routes->bank(field(in, "engine")).get(field(in, "memory_id"))));
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/memories/list", "agent-memories-list", [routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
gs::MemoryListOptions options;
|
||||
options.filter = field(in, "filter");
|
||||
GJson arr = GJson::array();
|
||||
for (const gs::Memory& m : routes->bank(field(in, "engine")).list(options))
|
||||
arr.push(memory_json(m));
|
||||
GJson out = GJson::object();
|
||||
out.set("memories", arr);
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
router.del("/agent/sessions/memories/memory", "agent-memories-delete",
|
||||
[routes](fw::Request req) {
|
||||
return guarded([&] {
|
||||
routes->bank(req.query_or("engine", "")).delete_memory(req.query_or("id", ""));
|
||||
GJson out = GJson::object();
|
||||
out.set("deleted", GJson(true));
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/memories/profiles", "agent-memories-profiles",
|
||||
[routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
GJson profiles = GJson::object();
|
||||
for (const auto& [id, p] :
|
||||
routes->bank(field(in, "engine")).retrieve_profiles(SessionsRoutes::scope_of(in)))
|
||||
profiles.set(id, p.fields);
|
||||
GJson out = GJson::object();
|
||||
out.set("profiles", profiles);
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
// Irreversible when force is true: needs confirm == engine id.
|
||||
router.post("/agent/sessions/memories/purge", "agent-memories-purge",
|
||||
[routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
gs::PurgeRequest p;
|
||||
p.filter = field(in, "filter");
|
||||
p.force = field(in, "force") == "true";
|
||||
p.confirm = field(in, "confirm");
|
||||
gs::PurgeResult r = routes->bank(field(in, "engine")).purge(p);
|
||||
GJson out = GJson::object();
|
||||
out.set("forced", GJson(r.forced));
|
||||
out.set("purge_count", GJson(static_cast<int>(r.purge_count)));
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
} // namespace molo::example::app
|
||||
|
||||
Reference in New Issue
Block a user