Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

feat(bedrock-agentcore): implement AgentCore Memory events (#3556)

Ovidiu (Ovi)3003f059531e
diff --git a/docs/services/bedrock-agentcore.md b/docs/services/bedrock-agentcore.md
index 384e33c5d9..d8e0dcaecd 100644
--- a/docs/services/bedrock-agentcore.md
+++ b/docs/services/bedrock-agentcore.md
@@ -55,6 +55,10 @@ runtimes reach `READY` immediately and hold metadata only. See
| `UpdateMemory` | Updates a memory resource |
| `DeleteMemory` | Deletes a memory resource |
| `ListMemories` | Lists memory resources |
+| `CreateEvent` | Appends an event to a memory. `sessionId` is optional and generated when omitted |
+| `ListEvents` | Lists a session's events, newest first. `POST` to the session path, not `GET` |
+| `GetEvent` | Returns one event |
+| `DeleteEvent` | Deletes one event and echoes its id |
| `CreateBrowser` | Creates a custom browser |
| `GetCodeInterpreter` | Returns a custom or system code interpreter |
| `DeleteCodeInterpreter` | Deletes a custom code interpreter |
@@ -80,6 +84,26 @@ runtimes reach `READY` immediately and hold metadata only. See
A `DEFAULT` endpoint is created automatically with each runtime, and each runtime
is associated with an auto-created, resolvable workload identity.
+## Memory events
+
+The event data plane is backed by real storage, so what a read returns is what was written rather
+than a fixed answer. Behaviour measured against real AgentCore:
+
+- events come back **newest first**, and the event id embeds a zero-padded timestamp so ids sort
+ chronologically as plain strings
+- `includePayloads: false` omits the `payload` key entirely rather than emptying it
+- `maxResults` accepts 1 to 100
+- a **malformed** memory id is a `ValidationException`, while a **well-formed but unknown** one is a
+ `ResourceNotFoundException`. A memory id is a name followed by exactly ten alphanumerics
+- an unknown actor or session is an empty list, not an error
+- a new event lands on the `main` branch, and an empty payload is accepted, though `payload` is a
+ required member: omitting it is a `ValidationException` while `[]` is valid
+- `CreateEvent` answers `201`, not `200`
+- `ListEvents` pages with `nextToken` and defaults to 20 events when a caller names no `maxResults`
+
+Memory *records* (extraction and retrieval) are not emulated: they depend on an extraction engine
+rather than on stored events.
+
## Data plane — `InvokeAgentRuntime`
`POST /runtimes/{agentRuntimeArn}/invocations` returns a fixed, configurable JSON
diff --git a/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/BedrockAgentCoreEventService.java b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/BedrockAgentCoreEventService.java
new file mode 100644
index 0000000000..76b70dfe83
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/BedrockAgentCoreEventService.java
@@ -0,0 +1,253 @@
+package io.github.hectorvent.floci.services.bedrockagentcore;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import io.github.hectorvent.floci.core.common.AwsException;
+import io.github.hectorvent.floci.core.storage.StorageBackend;
+import io.github.hectorvent.floci.core.storage.StorageFactory;
+import io.github.hectorvent.floci.services.bedrockagentcore.model.Branch;
+import io.github.hectorvent.floci.services.bedrockagentcore.model.MemoryEvent;
+import io.github.hectorvent.floci.services.bedrockagentcore.model.PayloadType;
+import io.github.hectorvent.floci.services.bedrockagentcorecontrol.BedrockAgentCoreMemoryService;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import org.jboss.logging.Logger;
+
+import java.security.SecureRandom;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.List;
+import java.util.UUID;
+import java.util.regex.Pattern;
+
+/**
+ * AgentCore Memory events: the data plane behind {@code CreateEvent}, {@code ListEvents},
+ * {@code GetEvent} and {@code DeleteEvent}.
+ *
+ * <p>Behaviour measured against real AgentCore in us-west-2, including the parts that are easy to
+ * assume wrongly: a malformed memory id is a {@code ValidationException} while a well-formed but
+ * unknown one is {@code ResourceNotFoundException}; an unknown actor or session is simply an empty
+ * list rather than an error; events come back newest first; and {@code sessionId} is optional on
+ * create, with the service generating a UUID when it is omitted.
+ */
+@ApplicationScoped
+public class BedrockAgentCoreEventService {
+
+ private static final Logger LOG = Logger.getLogger(BedrockAgentCoreEventService.class);
+
+ /**
+ * A memory id is a name followed by exactly ten alphanumerics. Measured: a nine or eleven
+ * character suffix is rejected as malformed before the resource is ever looked up.
+ */
+ private static final Pattern MEMORY_ID = Pattern.compile("^.+-[A-Za-z0-9]{10}$");
+
+ private static final int MAX_RESULTS_LIMIT = 100;
+ /** Documented default when a caller names no page size. */
+ private static final int DEFAULT_MAX_RESULTS = 20;
+ private static final int MAX_PAYLOAD_ITEMS = 100;
+ private static final String DEFAULT_BRANCH = "main";
+ private static final SecureRandom RANDOM = new SecureRandom();
+
+ private final StorageBackend<String, MemoryEvent> eventStore;
+ private final BedrockAgentCoreMemoryService memoryService;
+
+ @Inject
+ public BedrockAgentCoreEventService(StorageFactory storageFactory,
+ BedrockAgentCoreMemoryService memoryService) {
+ this(storageFactory.create("bedrockagentcore", "bedrock-agentcore-events.json",
+ new TypeReference<>() {}), memoryService);
+ }
+
+ BedrockAgentCoreEventService(StorageBackend<String, MemoryEvent> eventStore,
+ BedrockAgentCoreMemoryService memoryService) {
+ this.eventStore = eventStore;
+ this.memoryService = memoryService;
+ }
+
+ public MemoryEvent createEvent(String memoryId, String actorId, String sessionId,
+ Double eventTimestamp, List<PayloadType> payload, boolean payloadPresent,
+ Branch branch, String region) {
+ requireMemory(memoryId, region);
+ requireField(actorId, "actorId");
+ if (eventTimestamp == null) {
+ throw new AwsException("ValidationException", "eventTimestamp is required", 400);
+ }
+ // payload is a required member whose valid values include the empty list, so an omitted
+ // member and an empty array are different requests and only the first is an error.
+ if (!payloadPresent) {
+ throw new AwsException("ValidationException", "payload is required", 400);
+ }
+ List<PayloadType> resolvedPayload = payload == null ? List.of() : payload;
+ if (resolvedPayload.size() > MAX_PAYLOAD_ITEMS) {
+ throw new AwsException("ValidationException",
+ "payload must have at most " + MAX_PAYLOAD_ITEMS + " items", 400);
+ }
+
+ // sessionId is optional: AgentCore assigns a UUID when the caller omits it.
+ String resolvedSession = (sessionId == null || sessionId.isBlank())
+ ? UUID.randomUUID().toString()
+ : sessionId;
+
+ MemoryEvent event = new MemoryEvent();
+ event.setMemoryId(memoryId);
+ event.setActorId(actorId);
+ event.setSessionId(resolvedSession);
+ event.setEventId(nextEventId(eventTimestamp));
+ event.setEventTimestamp(eventTimestamp);
+ event.setPayload(resolvedPayload);
+ event.setBranch(branch != null ? branch : new Branch(DEFAULT_BRANCH));
+
+ eventStore.put(eventKey(memoryId, actorId, resolvedSession, event.getEventId()), event);
+ LOG.debugv("CreateEvent: memory={0} actor={1} session={2} event={3}",
+ memoryId, actorId, resolvedSession, event.getEventId());
+ return event;
+ }
+
+ /**
+ * Lists a session's events, newest first.
+ *
+ * <p>The id embeds a zero-padded timestamp, so ordering by id descending is the same as
+ * ordering by time descending, which is what AgentCore returns.
+ */
+ public EventPage listEvents(String memoryId, String actorId, String sessionId,
+ Boolean includePayloads, Integer maxResults, String nextToken, String region) {
+ requireMemory(memoryId, region);
+ int limit = resolveMaxResults(maxResults);
+
+ String prefix = eventKeyPrefix(memoryId, actorId, sessionId);
+ List<MemoryEvent> events = new ArrayList<>(eventStore.scan(k -> k.startsWith(prefix)));
+ events.sort(Comparator.comparing(MemoryEvent::getEventId).reversed());
+
+ // The token is the last event id of the previous page. Ids sort with time, and the order
+ // is stable, so resuming is "everything after that id" rather than a positional offset
+ // that a concurrent write could shift.
+ if (nextToken != null && !nextToken.isBlank()) {
+ int resumeAt = -1;
+ for (int i = 0; i < events.size(); i++) {
+ if (nextToken.equals(events.get(i).getEventId())) {
+ resumeAt = i;
+ break;
+ }
+ }
+ if (resumeAt < 0) {
+ throw new AwsException("ValidationException", "nextToken is not valid", 400);
+ }
+ events = events.subList(resumeAt + 1, events.size());
+ }
+
+ boolean more = events.size() > limit;
+ List<MemoryEvent> page = more ? new ArrayList<>(events.subList(0, limit)) : events;
+ if (Boolean.FALSE.equals(includePayloads)) {
+ // Measured: the payload key is absent entirely, not an empty list.
+ page = page.stream().map(BedrockAgentCoreEventService::withoutPayload).toList();
+ }
+ // A token only when another page exists; an absent token is what stops a caller's loop.
+ String token = more && !page.isEmpty() ? page.get(page.size() - 1).getEventId() : null;
+ return new EventPage(List.copyOf(page), token);
+ }
+
+ /** One page of events plus the token to continue with, or {@code null} at the end. */
+ public record EventPage(List<MemoryEvent> events, String nextToken) {}
+
+ public MemoryEvent getEvent(String memoryId, String actorId, String sessionId,
+ String eventId, String region) {
+ requireMemory(memoryId, region);
+ return eventStore.get(eventKey(memoryId, actorId, sessionId, eventId))
+ .orElseThrow(() -> new AwsException("ResourceNotFoundException",
+ "Unable to find event with id " + eventId, 404));
+ }
+
+ public String deleteEvent(String memoryId, String actorId, String sessionId,
+ String eventId, String region) {
+ requireMemory(memoryId, region);
+ String key = eventKey(memoryId, actorId, sessionId, eventId);
+ if (eventStore.get(key).isEmpty()) {
+ throw new AwsException("ResourceNotFoundException",
+ "Unable to find event with id " + eventId, 404);
+ }
+ eventStore.delete(key);
+ LOG.debugv("DeleteEvent: memory={0} event={1}", memoryId, eventId);
+ return eventId;
+ }
+
+ // ── validation ───────────────────────────────────────────────
+
+ /**
+ * A malformed id never reaches a lookup: AgentCore answers {@code ValidationException} for one
+ * that cannot be an id at all, and {@code ResourceNotFoundException} only for a well-formed id
+ * that does not resolve.
+ */
+ private void requireMemory(String memoryId, String region) {
+ if (memoryId == null || !MEMORY_ID.matcher(memoryId).matches()) {
+ throw new AwsException("ValidationException",
+ "Invalid memoryId: not a valid memory ID or ARN", 400);
+ }
+ try {
+ memoryService.get(memoryId, region);
+ } catch (AwsException e) {
+ throw new AwsException("ResourceNotFoundException", "Memory not found: " + memoryId, 404);
+ }
+ }
+
+ private static void requireField(String value, String field) {
+ if (value == null || value.isBlank()) {
+ throw new AwsException("ValidationException", field + " is required", 400);
+ }
+ }
+
+ private static int resolveMaxResults(Integer maxResults) {
+ if (maxResults == null) {
+ return DEFAULT_MAX_RESULTS;
+ }
+ if (maxResults < 1) {
+ throw new AwsException("ValidationException", rangeViolation(maxResults,
+ "Member must have value greater than or equal to 1"), 400);
+ }
+ if (maxResults > MAX_RESULTS_LIMIT) {
+ throw new AwsException("ValidationException", rangeViolation(maxResults,
+ "Member must have value less than or equal to " + MAX_RESULTS_LIMIT), 400);
+ }
+ return maxResults;
+ }
+
+ /** AWS quotes the submitted value and cites only the bound that was actually breached. */
+ private static String rangeViolation(int value, String constraint) {
+ return "1 validation error detected: Value '" + value + "' at 'maxResults' "
+ + "failed to satisfy constraint: " + constraint;
+ }
+
+ // ── helpers ──────────────────────────────────────────────────
+
+ /**
+ * AgentCore event ids are a zero-padded epoch-millisecond prefix, a {@code #}, then a random
+ * suffix, which makes them sort chronologically as plain strings.
+ */
+ private static String nextEventId(double eventTimestampSeconds) {
+ long millis = Math.round(eventTimestampSeconds * 1000d);
+ byte[] suffix = new byte[4];
+ RANDOM.nextBytes(suffix);
+ StringBuilder hex = new StringBuilder();
+ for (byte b : suffix) {
+ hex.append(String.format("%02x", b));
+ }
+ return String.format("%019d", millis) + "#" + hex;
+ }
+
+ private static MemoryEvent withoutPayload(MemoryEvent source) {
+ MemoryEvent copy = new MemoryEvent();
+ copy.setMemoryId(source.getMemoryId());
+ copy.setActorId(source.getActorId());
+ copy.setSessionId(source.getSessionId());
+ copy.setEventId(source.getEventId());
+ copy.setEventTimestamp(source.getEventTimestamp());
+ copy.setBranch(source.getBranch());
+ return copy;
+ }
+
+ private static String eventKeyPrefix(String memoryId, String actorId, String sessionId) {
+ return memoryId + "::" + actorId + "::" + sessionId + "::";
+ }
+
+ private static String eventKey(String memoryId, String actorId, String sessionId, String eventId) {
+ return eventKeyPrefix(memoryId, actorId, sessionId) + eventId;
+ }
+}
diff --git a/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/model/Branch.java b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/model/Branch.java
new file mode 100644
index 0000000000..d8d90129ec
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/model/Branch.java
@@ -0,0 +1,23 @@
+package io.github.hectorvent.floci.services.bedrockagentcore.model;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.quarkus.runtime.annotations.RegisterForReflection;
+
+/** The branch an event belongs to. AWS defaults a new event to the {@code main} branch. */
+@RegisterForReflection
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class Branch {
+ @JsonProperty("name")
+ private String name;
+ @JsonProperty("rootEventId")
+ private String rootEventId;
+
+ public Branch() {}
+ public Branch(String name) { this.name = name; }
+
+ public String getName() { return name; }
+ public void setName(String name) { this.name = name; }
+ public String getRootEventId() { return rootEventId; }
+ public void setRootEventId(String rootEventId) { this.rootEventId = rootEventId; }
+}
diff --git a/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/model/Content.java b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/model/Content.java
new file mode 100644
index 0000000000..09fd553eec
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/model/Content.java
@@ -0,0 +1,18 @@
+package io.github.hectorvent.floci.services.bedrockagentcore.model;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.quarkus.runtime.annotations.RegisterForReflection;
+
+/** The text of a conversational payload part. */
+@RegisterForReflection
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class Content {
+ @JsonProperty("text")
+ private String text;
+
+ public Content() {}
+
+ public String getText() { return text; }
+ public void setText(String text) { this.text = text; }
+}
diff --git a/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/model/Conversational.java b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/model/Conversational.java
new file mode 100644
index 0000000000..67c3028531
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/model/Conversational.java
@@ -0,0 +1,22 @@
+package io.github.hectorvent.floci.services.bedrockagentcore.model;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.quarkus.runtime.annotations.RegisterForReflection;
+
+/** One conversational turn: a role and its content. */
+@RegisterForReflection
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class Conversational {
+ @JsonProperty("content")
+ private Content content;
+ @JsonProperty("role")
+ private String role;
+
+ public Conversational() {}
+
+ public Content getContent() { return content; }
+ public void setContent(Content content) { this.content = content; }
+ public String getRole() { return role; }
+ public void setRole(String role) { this.role = role; }
+}
diff --git a/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/model/MemoryEvent.java b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/model/MemoryEvent.java
new file mode 100644
index 0000000000..292d627c3d
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/model/MemoryEvent.java
@@ -0,0 +1,53 @@
+package io.github.hectorvent.floci.services.bedrockagentcore.model;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.quarkus.runtime.annotations.RegisterForReflection;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * One AgentCore Memory event.
+ *
+ * <p>Named {@code MemoryEvent} rather than {@code Event} to keep it distinct from the many other
+ * event types in this codebase. The wire name is {@code Event}.
+ *
+ * <p>{@code eventTimestamp} is carried as epoch milliseconds and serialised as epoch seconds with a
+ * fractional part, which is the restJson1 default the SDK expects.
+ */
+@RegisterForReflection
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class MemoryEvent {
+ @JsonProperty("memoryId")
+ private String memoryId;
+ @JsonProperty("actorId")
+ private String actorId;
+ @JsonProperty("sessionId")
+ private String sessionId;
+ @JsonProperty("eventId")
+ private String eventId;
+ @JsonProperty("eventTimestamp")
+ private Double eventTimestamp;
+ @JsonProperty("payload")
+ private List<PayloadType> payload;
+ @JsonProperty("branch")
+ private Branch branch;
+
+ public MemoryEvent() {}
+
+ public String getMemoryId() { return memoryId; }
+ public void setMemoryId(String memoryId) { this.memoryId = memoryId; }
+ public String getActorId() { return actorId; }
+ public void setActorId(String actorId) { this.actorId = actorId; }
+ public String getSessionId() { return sessionId; }
+ public void setSessionId(String sessionId) { this.sessionId = sessionId; }
+ public String getEventId() { return eventId; }
+ public void setEventId(String eventId) { this.eventId = eventId; }
+ public Double getEventTimestamp() { return eventTimestamp; }
+ public void setEventTimestamp(Double eventTimestamp) { this.eventTimestamp = eventTimestamp; }
+ public List<PayloadType> getPayload() { return payload == null ? null : new ArrayList<>(payload); }
+ public void setPayload(List<PayloadType> payload) { this.payload = payload == null ? null : new ArrayList<>(payload); }
+ public Branch getBranch() { return branch; }
+ public void setBranch(Branch branch) { this.branch = branch; }
+}
diff --git a/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/model/PayloadType.java b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/model/PayloadType.java
new file mode 100644
index 0000000000..f17c33e6b4
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/model/PayloadType.java
@@ -0,0 +1,25 @@
+package io.github.hectorvent.floci.services.bedrockagentcore.model;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.quarkus.runtime.annotations.RegisterForReflection;
+
+/**
+ * One part of an event payload. AWS models this as a union of {@code conversational} and
+ * {@code blob}; exactly one is set, and the other stays absent from the wire.
+ */
+@RegisterForReflection
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class PayloadType {
+ @JsonProperty("conversational")
+ private Conversational conversational;
+ @JsonProperty("blob")
+ private Object blob;
+
+ public PayloadType() {}
+
+ public Conversational getConversational() { return conversational; }
+ public void setConversational(Conversational conversational) { this.conversational = conversational; }
+ public Object getBlob() { return blob; }
+ public void setBlob(Object blob) { this.blob = blob; }
+}
diff --git a/src/main/java/io/github/hectorvent/floci/services/bedrockagentcorecontrol/BedrockAgentCoreMemoryController.java b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcorecontrol/BedrockAgentCoreMemoryController.java
index 7402a0f635..224e6ad807 100644
--- a/src/main/java/io/github/hectorvent/floci/services/bedrockagentcorecontrol/BedrockAgentCoreMemoryController.java
+++ b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcorecontrol/BedrockAgentCoreMemoryController.java
@@ -17,6 +17,13 @@ import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.PUT;
import jakarta.ws.rs.Path;
+import io.github.hectorvent.floci.services.bedrockagentcore.BedrockAgentCoreEventService;
+import io.github.hectorvent.floci.services.bedrockagentcore.model.Branch;
+import io.github.hectorvent.floci.services.bedrockagentcore.model.MemoryEvent;
+import io.github.hectorvent.floci.services.bedrockagentcore.model.PayloadType;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
@@ -40,13 +47,16 @@ public class BedrockAgentCoreMemoryController {
private static final Logger LOG = Logger.getLogger(BedrockAgentCoreMemoryController.class);
private final BedrockAgentCoreMemoryService service;
+ private final BedrockAgentCoreEventService eventService;
private final RegionResolver regionResolver;
private final ObjectMapper objectMapper;
@Inject
public BedrockAgentCoreMemoryController(BedrockAgentCoreMemoryService service,
+ BedrockAgentCoreEventService eventService,
RegionResolver regionResolver, ObjectMapper objectMapper) {
this.service = service;
+ this.eventService = eventService;
this.regionResolver = regionResolver;
this.objectMapper = objectMapper;
}
@@ -198,4 +208,118 @@ public class BedrockAgentCoreMemoryController {
.entity(new AwsErrorResponse("ValidationException", e.getMessage()))
.build();
}
+
+ // ── AgentCore Memory events (data plane) ─────────────────────
+ //
+ // These are data-plane operations, but they live under /memories, and a JAX-RS request is
+ // matched against one root resource class only: a class rooted at "/" never gets a look in
+ // once this class claims the subtree. So the endpoints sit here while the behaviour stays in
+ // BedrockAgentCoreEventService.
+
+ @POST
+ @Path("/{memoryId}/events")
+ @Consumes(MediaType.APPLICATION_JSON)
+ @Produces(MediaType.APPLICATION_JSON)
+ public Response createEvent(@Context HttpHeaders headers,
+ @PathParam("memoryId") String memoryId,
+ CreateEventRequest request) {
+ String region = regionResolver.resolveRegion(headers);
+ try {
+ CreateEventRequest body = request == null ? new CreateEventRequest() : request;
+ // payload is required but may legitimately be empty, so presence is passed separately
+ // from the value: null means the member was omitted, not that it was an empty list.
+ MemoryEvent event = eventService.createEvent(memoryId, body.actorId(), body.sessionId(),
+ body.eventTimestamp(), body.payload(), body.payload() != null, body.branch(), region);
+ // AWS answers CreateEvent with 201, not 200.
+ return Response.status(201).entity(Map.of("event", event)).build();
+ } catch (AwsException e) {
+ return awsError(e);
+ }
+ }
+
+ /** ListEvents is a POST to the session path, not a GET. That is the real wire shape. */
+ @POST
+ @Path("/{memoryId}/actor/{actorId}/sessions/{sessionId}")
+ @Consumes(MediaType.APPLICATION_JSON)
+ @Produces(MediaType.APPLICATION_JSON)
+ public Response listEvents(@Context HttpHeaders headers,
+ @PathParam("memoryId") String memoryId,
+ @PathParam("actorId") String actorId,
+ @PathParam("sessionId") String sessionId,
+ ListEventsRequest request) {
+ String region = regionResolver.resolveRegion(headers);
+ try {
+ ListEventsRequest body = request == null ? new ListEventsRequest() : request;
+ BedrockAgentCoreEventService.EventPage page = eventService.listEvents(memoryId, actorId, sessionId,
+ body.includePayloads(), body.maxResults(), body.nextToken(), region);
+ Map<String, Object> response = new LinkedHashMap<>();
+ response.put("events", page.events());
+ // Only present when another page exists: an absent token ends a caller's loop.
+ if (page.nextToken() != null) {
+ response.put("nextToken", page.nextToken());
+ }
+ return Response.ok(response).build();
+ } catch (AwsException e) {
+ return awsError(e);
+ }
+ }
+
+ @GET
+ @Path("/{memoryId}/actor/{actorId}/sessions/{sessionId}/events/{eventId}")
+ @Produces(MediaType.APPLICATION_JSON)
+ public Response getEvent(@Context HttpHeaders headers,
+ @PathParam("memoryId") String memoryId,
+ @PathParam("actorId") String actorId,
+ @PathParam("sessionId") String sessionId,
+ @PathParam("eventId") String eventId) {
+ String region = regionResolver.resolveRegion(headers);
+ try {
+ return Response.ok(Map.of("event",
+ eventService.getEvent(memoryId, actorId, sessionId, eventId, region))).build();
+ } catch (AwsException e) {
+ return awsError(e);
+ }
+ }
+
+ @DELETE
+ @Path("/{memoryId}/actor/{actorId}/sessions/{sessionId}/events/{eventId}")
+ @Produces(MediaType.APPLICATION_JSON)
+ public Response deleteEvent(@Context HttpHeaders headers,
+ @PathParam("memoryId") String memoryId,
+ @PathParam("actorId") String actorId,
+ @PathParam("sessionId") String sessionId,
+ @PathParam("eventId") String eventId) {
+ String region = regionResolver.resolveRegion(headers);
+ try {
+ // DeleteEvent echoes the id rather than answering with an empty body.
+ return Response.ok(Map.of("eventId",
+ eventService.deleteEvent(memoryId, actorId, sessionId, eventId, region))).build();
+ } catch (AwsException e) {
+ return awsError(e);
+ }
+ }
+
+ /**
+ * Renders an {@link AwsException} the way this protocol needs it: the SDK maps the error by the
+ * {@code X-Amzn-Errortype} header, which the shared exception mapper does not set.
+ */
+ private static Response awsError(AwsException e) {
+ return Response.status(e.getHttpStatus())
+ .type(MediaType.APPLICATION_JSON)
+ .header("X-Amzn-Errortype", e.getErrorCode())
+ .entity(new AwsErrorResponse(e.getErrorCode(), e.getMessage()))
+ .build();
+ }
+
+ /** Request body of {@code CreateEvent}; {@code sessionId} and {@code branch} are optional. */
+ public record CreateEventRequest(String actorId, String sessionId, Double eventTimestamp,
+ List<PayloadType> payload, Branch branch) {
+ public CreateEventRequest() { this(null, null, null, null, null); }
+ }
+
+ /** Request body of {@code ListEvents}. */
+ public record ListEventsRequest(Boolean includePayloads, Integer maxResults, String nextToken) {
+ public ListEventsRequest() { this(null, null, null); }
+ }
+
}
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
index ef94a2b86d..bae0e9db5d 100644
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -92,6 +92,7 @@ quarkus:
- --initialize-at-run-time=io.github.hectorvent.floci.services.cognito.CognitoSrpHelper
- --initialize-at-run-time=io.github.hectorvent.floci.services.route53.Route53Service
- --initialize-at-run-time=io.github.hectorvent.floci.services.kms.KmsService
+ - --initialize-at-run-time=io.github.hectorvent.floci.services.bedrockagentcore.BedrockAgentCoreEventService
- --initialize-at-run-time=io.github.hectorvent.floci.services.cloudfront.CloudFrontService
- --initialize-at-run-time=io.github.hectorvent.floci.services.emr.EmrService
- --initialize-at-run-time=io.github.hectorvent.floci.services.elasticbeanstalk.ElasticBeanstalkService
diff --git a/src/test/java/io/github/hectorvent/floci/services/bedrockagentcore/BedrockAgentCoreEventIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/bedrockagentcore/BedrockAgentCoreEventIntegrationTest.java
new file mode 100644
index 0000000000..88a99228be
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/services/bedrockagentcore/BedrockAgentCoreEventIntegrationTest.java
@@ -0,0 +1,249 @@
+package io.github.hectorvent.floci.services.bedrockagentcore;
+
+import io.quarkus.test.junit.QuarkusTest;
+import io.restassured.http.ContentType;
+import org.junit.jupiter.api.Test;
+
+import static io.restassured.RestAssured.given;
+import static org.hamcrest.Matchers.containsString;
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.hasSize;
+import static org.hamcrest.Matchers.notNullValue;
+import static org.hamcrest.Matchers.nullValue;
+import static org.hamcrest.Matchers.startsWith;
+
+/**
+ * AgentCore Memory events.
+ *
+ * <p>Every expectation here was measured against real AgentCore in us-west-2. The ones worth
+ * naming, because they are easy to assume wrongly: a malformed memory id is a
+ * {@code ValidationException} while a well-formed but unknown one is
+ * {@code ResourceNotFoundException}; an unknown actor or session is an empty list rather than an
+ * error; events come back newest first; {@code sessionId} is optional and generated when omitted;
+ * and {@code includePayloads=false} drops the key rather than emptying it.
+ */
+@QuarkusTest
+class BedrockAgentCoreEventIntegrationTest {
+
+ private static String createMemory(String name) {
+ return given().contentType(ContentType.JSON)
+ .body("{\"name\":\"" + name + "\",\"eventExpiryDuration\":7}")
+ .when().post("/memories/create")
+ .then().statusCode(202)
+ .extract().path("memory.id");
+ }
+
+ private static String createEvent(String memoryId, String actorId, String sessionId,
+ double timestamp, String text) {
+ String session = sessionId == null ? "" : "\"sessionId\":\"" + sessionId + "\",";
+ return given().contentType(ContentType.JSON)
+ .body("{\"actorId\":\"" + actorId + "\"," + session
+ + "\"eventTimestamp\":" + timestamp + ","
+ + "\"payload\":[{\"conversational\":{\"role\":\"USER\","
+ + "\"content\":{\"text\":\"" + text + "\"}}}]}")
+ .when().post("/memories/" + memoryId + "/events")
+ .then().statusCode(201)
+ .extract().path("event.eventId");
+ }
+
+ @Test
+ void createdEventIsListedWithItsPayload() {
+ String memoryId = createMemory("evtList");
+ createEvent(memoryId, "actor1", "sess1", 1789300800d, "hello");
+
+ given().contentType(ContentType.JSON).body("{}")
+ .when().post("/memories/" + memoryId + "/actor/actor1/sessions/sess1")
+ .then().statusCode(200)
+ .body("events", hasSize(1))
+ .body("events[0].payload[0].conversational.content.text", equalTo("hello"))
+ .body("events[0].payload[0].conversational.role", equalTo("USER"))
+ // AgentCore puts a new event on the main branch when the caller names none.
+ .body("events[0].branch.name", equalTo("main"));
+ }
+
+ @Test
+ void eventsAreListedNewestFirst() {
+ String memoryId = createMemory("evtOrder");
+ createEvent(memoryId, "actor1", "sess1", 1789300800d, "older");
+ createEvent(memoryId, "actor1", "sess1", 1789301400d, "newer");
+
+ given().contentType(ContentType.JSON).body("{}")
+ .when().post("/memories/" + memoryId + "/actor/actor1/sessions/sess1")
+ .then().statusCode(200)
+ .body("events", hasSize(2))
+ .body("events[0].payload[0].conversational.content.text", equalTo("newer"))
+ .body("events[1].payload[0].conversational.content.text", equalTo("older"));
+ }
+
+ @Test
+ void excludingPayloadsOmitsTheKeyEntirely() {
+ String memoryId = createMemory("evtNoPayload");
+ createEvent(memoryId, "actor1", "sess1", 1789300800d, "hello");
+
+ given().contentType(ContentType.JSON).body("{\"includePayloads\":false}")
+ .when().post("/memories/" + memoryId + "/actor/actor1/sessions/sess1")
+ .then().statusCode(200)
+ .body("events", hasSize(1))
+ .body("events[0].eventId", notNullValue())
+ .body("events[0].payload", nullValue());
+ }
+
+ @Test
+ void aSessionIdIsGeneratedWhenTheCallerOmitsIt() {
+ String memoryId = createMemory("evtNoSession");
+
+ given().contentType(ContentType.JSON)
+ .body("{\"actorId\":\"actor1\",\"eventTimestamp\":1789300800,\"payload\":[]}")
+ .when().post("/memories/" + memoryId + "/events")
+ .then().statusCode(201)
+ // Measured: AgentCore assigns a UUID rather than rejecting the request.
+ .body("event.sessionId", notNullValue())
+ .body("event.eventId", notNullValue());
+ }
+
+ @Test
+ void anEmptyPayloadIsAccepted() {
+ String memoryId = createMemory("evtEmptyPayload");
+
+ given().contentType(ContentType.JSON)
+ .body("{\"actorId\":\"a\",\"sessionId\":\"s\",\"eventTimestamp\":1789300800,\"payload\":[]}")
+ .when().post("/memories/" + memoryId + "/events")
+ .then().statusCode(201);
+ }
+
+ @Test
+ void anUnknownActorOrSessionIsAnEmptyListRatherThanAnError() {
+ String memoryId = createMemory("evtUnknownActor");
+
+ given().contentType(ContentType.JSON).body("{}")
+ .when().post("/memories/" + memoryId + "/actor/nobody/sessions/nosuch")
+ .then().statusCode(200)
+ .body("events", hasSize(0));
+ }
+
+ @Test
+ void aMalformedMemoryIdIsAValidationError() {
+ // The suffix must be exactly ten alphanumerics; this never reaches a lookup.
+ given().contentType(ContentType.JSON).body("{}")
+ .when().post("/memories/nope-1234/actor/a/sessions/s")
+ .then().statusCode(400)
+ .body("__type", equalTo("ValidationException"))
+ .body("message", startsWith("Invalid memoryId"));
+ }
+
+ @Test
+ void aWellFormedButUnknownMemoryIdIsNotFound() {
+ given().contentType(ContentType.JSON).body("{}")
+ .when().post("/memories/absent-AAAAAAAAAA/actor/a/sessions/s")
+ .then().statusCode(404)
+ .body("__type", equalTo("ResourceNotFoundException"))
+ .body("message", startsWith("Memory not found"));
+ }
+
+ @Test
+ void maxResultsAboveTheLimitIsRejected() {
+ String memoryId = createMemory("evtMaxResults");
+
+ given().contentType(ContentType.JSON).body("{\"maxResults\":101}")
+ .when().post("/memories/" + memoryId + "/actor/a/sessions/s")
+ .then().statusCode(400)
+ .body("__type", equalTo("ValidationException"))
+ .body("message", equalTo("1 validation error detected: Value '101' at 'maxResults' "
+ + "failed to satisfy constraint: Member must have value less than or equal to 100"));
+ }
+
+ @Test
+ void maxResultsBelowOneIsRejectedWithTheLowerBound() {
+ String memoryId = createMemory("evtMaxResultsLow");
+
+ given().contentType(ContentType.JSON).body("{\"maxResults\":0}")
+ .when().post("/memories/" + memoryId + "/actor/a/sessions/s")
+ .then().statusCode(400)
+ .body("__type", equalTo("ValidationException"))
+ .body("message", equalTo("1 validation error detected: Value '0' at 'maxResults' "
+ + "failed to satisfy constraint: Member must have value greater than or equal to 1"));
+ }
+
+ @Test
+ void gettingAnUnknownEventIsNotFound() {
+ String memoryId = createMemory("evtGetMissing");
+
+ given()
+ .when().get("/memories/" + memoryId + "/actor/a/sessions/s/events/0000000000000000000#deadbeef")
+ .then().statusCode(404)
+ .body("__type", equalTo("ResourceNotFoundException"));
+ }
+
+ @Test
+ void deletingAnEventEchoesItsIdAndRemovesIt() {
+ String memoryId = createMemory("evtDelete");
+ String eventId = createEvent(memoryId, "actor1", "sess1", 1789300800d, "hello");
+
+ given()
+ .when().delete("/memories/" + memoryId + "/actor/actor1/sessions/sess1/events/" + eventId)
+ .then().statusCode(200)
+ // DeleteEvent echoes the id rather than answering with an empty body.
+ .body("eventId", equalTo(eventId));
+
+ given().contentType(ContentType.JSON).body("{}")
+ .when().post("/memories/" + memoryId + "/actor/actor1/sessions/sess1")
+ .then().statusCode(200)
+ .body("events", hasSize(0));
+ }
+
+ @Test
+ void createEventAnswersWith201() {
+ String memoryId = createMemory("evtCreated");
+
+ given().contentType(ContentType.JSON)
+ .body("{\"actorId\":\"a\",\"sessionId\":\"s\",\"eventTimestamp\":1789300800,\"payload\":[]}")
+ .when().post("/memories/" + memoryId + "/events")
+ .then().statusCode(201)
+ .body("event.eventId", notNullValue());
+ }
+
+ @Test
+ void anOmittedPayloadIsRejectedEvenThoughAnEmptyOneIsValid() {
+ String memoryId = createMemory("evtNoPayload2");
+
+ // payload is a required member, so its absence is an error while [] is accepted.
+ given().contentType(ContentType.JSON)
+ .body("{\"actorId\":\"a\",\"sessionId\":\"s\",\"eventTimestamp\":1789300800}")
+ .when().post("/memories/" + memoryId + "/events")
+ .then().statusCode(400)
+ .body("message", containsString("payload"));
+ }
+
+ @Test
+ void listingPagesThroughWithANextToken() {
+ String memoryId = createMemory("evtPaged");
+ for (int i = 0; i < 3; i++) {
+ createEvent(memoryId, "actor1", "sess1", 1789300800d + (i * 60), "m" + i);
+ }
+
+ String firstPage = given().contentType(ContentType.JSON).body("{\"maxResults\":2}")
+ .when().post("/memories/" + memoryId + "/actor/actor1/sessions/sess1")
+ .then().statusCode(200)
+ .body("events", hasSize(2))
+ .body("nextToken", notNullValue())
+ .extract().path("nextToken");
+
+ given().contentType(ContentType.JSON)
+ .body("{\"maxResults\":2,\"nextToken\":\"" + firstPage + "\"}")
+ .when().post("/memories/" + memoryId + "/actor/actor1/sessions/sess1")
+ .then().statusCode(200)
+ .body("events", hasSize(1))
+ // No token on the last page: that is what ends a caller's loop.
+ .body("nextToken", nullValue());
+ }
+
+ @Test
+ void anInvalidNextTokenIsRejected() {
+ String memoryId = createMemory("evtBadToken");
+ createEvent(memoryId, "actor1", "sess1", 1789300800d, "hello");
+
+ given().contentType(ContentType.JSON).body("{\"nextToken\":\"not-a-real-token\"}")
+ .when().post("/memories/" + memoryId + "/actor/actor1/sessions/sess1")
+ .then().statusCode(400);
+ }
+}