Skip to content

armgit / floci

Public Imported from GitHub
0

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

feat(bedrock-agentcore): implement InvokeHarness (#3557)

Ovidiu (Ovi)6f054422182a
diff --git a/docs/services/bedrock-agentcore.md b/docs/services/bedrock-agentcore.md
index d8e0dcaecd..a37d1a6c4c 100644
--- a/docs/services/bedrock-agentcore.md
+++ b/docs/services/bedrock-agentcore.md
@@ -109,8 +109,35 @@ rather than on stored events.
`POST /runtimes/{agentRuntimeArn}/invocations` returns a fixed, configurable JSON
body (default `{"output":"yes"}`) and echoes the
`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header. The request payload (opaque
-binary, up to 100 MB) is never parsed. Streaming responses are not emulated — a
-single non-streaming `200` is returned.
+binary, up to 100 MB) is never parsed. This operation returns a single non-streaming
+`200`; `InvokeHarness` below is the streaming one.
+
+## Data plane — `InvokeHarness`
+
+`POST /harnesses/invoke` returns an `application/vnd.amazon.eventstream` response, the same
+framing `ConverseStream` uses, so an SDK client's stream iterator works unchanged. The frames
+arrive in AWS's order: `messageStart`, `contentBlockStart`, one `contentBlockDelta` per chunk,
+`contentBlockStop`, `messageStop`, `metadata`.
+
+`harnessArn`, `runtimeSessionId` and `messages` are all required, and the first two are validated
+against their modelled shapes rather than merely checked for presence: a harness ARN ends in the
+same `name-<10 alphanumerics>` form AgentCore uses elsewhere, and a runtime session id is 33 to 100
+characters. `messages` may be an empty array, but omitting the member is a `ValidationException`.
+
+Note the wire bindings, which are easy to get wrong: `harnessArn` and `qualifier` are **query
+parameters**, `runtimeSessionId` and `runtimeUserId` are **headers**
+(`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` / `-User-Id`), and only `messages`, `model`,
+`tools` and friends travel in the JSON body. A missing `harnessArn` or `runtimeSessionId` is a
+`ValidationException`.
+
+There is no agent loop and no model. The assistant's reply **echoes the caller's last user
+message**, so a chat client visibly works end to end and a request that failed to parse is obvious
+rather than hidden behind a fixed string. A request whose `messages` array is present but empty, or
+carries no user turn, is legitimate and gets a canned reply rather than an error.
+
+The `harnessArn` is not resolved: the emulator models no harness resource, so there is nothing to
+look one up in. Tool execution, skills and multi-turn iteration are not emulated, so no tool-use
+block is ever produced even when a request supplies `tools`.
## Configuration
@@ -120,12 +147,15 @@ single non-streaming `200` is returned.
| `FLOCI_SERVICES_BEDROCK_AGENT_CORE_ENABLED` | `true` | Enable/disable the data plane (invoke) |
| `FLOCI_SERVICES_BEDROCK_AGENT_CORE_INVOKE_RESPONSE` | `{"output":"yes"}` | Canned `InvokeAgentRuntime` response body |
| `FLOCI_SERVICES_BEDROCK_AGENT_CORE_VALIDATE_RUNTIME_EXISTS` | `false` | When `true`, `InvokeAgentRuntime` returns `ResourceNotFoundException` for an unknown runtime ARN instead of the canned response |
+| `FLOCI_SERVICES_BEDROCK_AGENT_CORE_HARNESS_ECHO_PREFIX` | `You said: ` | Prefix on the reply `InvokeHarness` streams back |
+| `FLOCI_SERVICES_BEDROCK_AGENT_CORE_HARNESS_EMPTY_REPLY` | `No user message was supplied.` | Reply used when a request carries no user message |
> **Note on YAML config keys.** The status endpoint reports these services as
> `bedrock-agentcore-control` and `bedrock-agentcore`, but the YAML property paths
> use hyphenated words: `floci.services.bedrock-agent-core-control.enabled` and
> `floci.services.bedrock-agent-core.enabled` (and `…bedrock-agent-core.invoke-response`,
-> `…bedrock-agent-core.validate-runtime-exists`). The `FLOCI_*` environment variables
+> `…bedrock-agent-core.validate-runtime-exists`, `…bedrock-agent-core.harness-echo-prefix`,
+> `…bedrock-agent-core.harness-empty-reply`). The `FLOCI_*` environment variables
> above map to these paths directly and are the recommended way to configure the service.
## Behavior notes
diff --git a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
index 243bf9693b..13a2bcdafd 100644
--- a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
+++ b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
@@ -2564,6 +2564,18 @@ public interface EmulatorConfig {
@WithDefault("false")
boolean validateRuntimeExists();
+
+ /**
+ * Prefix on the assistant reply InvokeHarness streams back. The reply echoes the caller's
+ * last user message: there is no model, and echoing makes a chat UI visibly work while
+ * keeping a request that failed to parse obvious.
+ */
+ @WithDefault("You said: ")
+ String harnessEchoPrefix();
+
+ /** Reply used when a request carries no user message, which is a legitimate call. */
+ @WithDefault("No user message was supplied.")
+ String harnessEmptyReply();
}
/** Classic (2012-06-01) Elastic Load Balancing — a separate API from {@link ElbV2ServiceConfig}. */
diff --git a/src/main/java/io/github/hectorvent/floci/services/bedrockruntime/backend/BedrockStreamEncoder.java b/src/main/java/io/github/hectorvent/floci/core/common/AwsEventStreamWriter.java
similarity index 79%
rename from src/main/java/io/github/hectorvent/floci/services/bedrockruntime/backend/BedrockStreamEncoder.java
rename to src/main/java/io/github/hectorvent/floci/core/common/AwsEventStreamWriter.java
index e85f0d7749..dd0efae15e 100644
--- a/src/main/java/io/github/hectorvent/floci/services/bedrockruntime/backend/BedrockStreamEncoder.java
+++ b/src/main/java/io/github/hectorvent/floci/core/common/AwsEventStreamWriter.java
@@ -1,8 +1,7 @@
-package io.github.hectorvent.floci.services.bedrockruntime.backend;
+package io.github.hectorvent.floci.core.common;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
-import io.github.hectorvent.floci.core.common.AwsEventStreamEncoder;
import java.io.IOException;
import java.io.OutputStream;
@@ -10,19 +9,19 @@ import java.io.UncheckedIOException;
import java.util.LinkedHashMap;
/**
- * Frames Bedrock ConverseStream events (messageStart, contentBlockDelta, ...) as
+ * Frames streaming events (messageStart, contentBlockDelta, ...) as
* {@code application/vnd.amazon.eventstream} messages and writes each one to the response
* {@link OutputStream} as soon as it's known, so SDK clients see incremental delivery instead
* of the whole response landing at once - the same binary framing S3 Select and Kinesis
* SubscribeToShard build elsewhere in Floci, just written frame-by-frame instead of batched.
*/
-final class BedrockStreamEncoder {
+public final class AwsEventStreamWriter {
- private BedrockStreamEncoder() {
+ private AwsEventStreamWriter() {
}
/** Writes a normal event frame ({@code :message-type: event}), e.g. messageStart, contentBlockDelta. */
- static void writeEvent(ObjectMapper mapper, OutputStream out, String eventType, ObjectNode payload) {
+ public static void writeEvent(ObjectMapper mapper, OutputStream out, String eventType, ObjectNode payload) {
writeFrame(mapper, out, "event", ":event-type", eventType, payload);
}
@@ -33,7 +32,7 @@ final class BedrockStreamEncoder {
* pick the matching modeled exception class (e.g. ModelStreamErrorException), the same way
* it reads {@code x-amzn-ErrorType} for a regular non-streaming error response.
*/
- static void writeException(ObjectMapper mapper, OutputStream out, String exceptionType, ObjectNode payload) {
+ public static void writeException(ObjectMapper mapper, OutputStream out, String exceptionType, ObjectNode payload) {
writeFrame(mapper, out, "exception", ":exception-type", exceptionType, payload);
}
diff --git a/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/BedrockAgentCoreController.java b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/BedrockAgentCoreController.java
index 5569ee7328..2d6e098ea1 100644
--- a/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/BedrockAgentCoreController.java
+++ b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/BedrockAgentCoreController.java
@@ -6,6 +6,16 @@ import io.github.hectorvent.floci.core.common.RegionResolver;
import io.github.hectorvent.floci.services.bedrockagentcorecontrol.BedrockAgentCoreControlService;
import jakarta.inject.Inject;
import jakarta.ws.rs.Consumes;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import io.github.hectorvent.floci.core.common.AwsException;
+import io.smallrye.common.annotation.Blocking;
+import jakarta.ws.rs.core.GenericEntity;
+import jakarta.ws.rs.core.StreamingOutput;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.util.function.Consumer;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
@@ -36,18 +46,24 @@ public class BedrockAgentCoreController {
private static final String SESSION_HEADER = "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id";
private final BedrockAgentCoreService service;
+ private final BedrockAgentCoreHarnessService harnessService;
private final BedrockAgentCoreControlService controlService;
private final RegionResolver regionResolver;
+ private final ObjectMapper objectMapper;
private final boolean validateRuntimeExists;
@Inject
public BedrockAgentCoreController(BedrockAgentCoreService service,
+ BedrockAgentCoreHarnessService harnessService,
BedrockAgentCoreControlService controlService,
RegionResolver regionResolver,
+ ObjectMapper objectMapper,
EmulatorConfig config) {
this.service = service;
+ this.harnessService = harnessService;
this.controlService = controlService;
this.regionResolver = regionResolver;
+ this.objectMapper = objectMapper;
this.validateRuntimeExists = config.services().bedrockAgentCore().validateRuntimeExists();
}
@@ -80,4 +96,55 @@ public class BedrockAgentCoreController {
}
return builder.build();
}
+
+ /**
+ * {@code InvokeHarness}. Answers with an {@code application/vnd.amazon.eventstream} response,
+ * the same framing ConverseStream uses, so an SDK client's stream iterator works unchanged.
+ *
+ * <p>{@code harnessArn} arrives as a query parameter and {@code runtimeSessionId} as a header,
+ * which is how the SDK binds them; only {@code messages}, {@code model} and {@code tools} are in
+ * the body.
+ *
+ * <p>Request validation happens before the first frame: once the stream is committed the status
+ * is already 200 and a problem could only be reported as an in-stream exception frame.
+ */
+ @POST
+ @Blocking
+ @Path("/harnesses/invoke")
+ @Consumes(MediaType.WILDCARD)
+ public Response invokeHarness(@Context HttpHeaders headers,
+ @QueryParam("harnessArn") String harnessArn,
+ @QueryParam("qualifier") String harnessQualifier,
+ String body) {
+ ObjectNode request;
+ try {
+ JsonNode parsed = objectMapper.readTree(body != null && !body.isBlank() ? body : "{}");
+ request = parsed.isObject() ? (ObjectNode) parsed : objectMapper.createObjectNode();
+ } catch (IOException e) {
+ throw new AwsException("ValidationException", "Request body is not valid JSON", 400);
+ }
+
+ // runtimeSessionId and runtimeUserId are headers on the wire, not body fields. Only the
+ // session id is read: runtimeUserId reaches the harness on AWS but changes nothing here.
+ String runtimeSessionId = headers.getHeaderString(SESSION_HEADER);
+ Consumer<OutputStream> stream = harnessService.invokeHarness(harnessArn, runtimeSessionId, request);
+ LOG.debugv("InvokeHarness: arn={0}, qualifier={1}, session={2}",
+ harnessArn, harnessQualifier, runtimeSessionId);
+
+ Response.ResponseBuilder builder = Response.ok(streaming(stream))
+ .header("Content-Type", "application/vnd.amazon.eventstream");
+ if (runtimeSessionId != null) {
+ builder.header(SESSION_HEADER, runtimeSessionId);
+ }
+ return builder.build();
+ }
+
+ /**
+ * The explicit return type is what lets {@code GenericEntity} keep {@code StreamingOutput} as
+ * the entity type; inlining the constructor erases it to {@code Object}. Same helper as the
+ * bedrock-runtime controller.
+ */
+ private static GenericEntity<StreamingOutput> streaming(Consumer<OutputStream> stream) {
+ return new GenericEntity<>(stream::accept, StreamingOutput.class);
+ }
}
diff --git a/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/BedrockAgentCoreHarnessService.java b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/BedrockAgentCoreHarnessService.java
new file mode 100644
index 0000000000..21a32f0af7
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/services/bedrockagentcore/BedrockAgentCoreHarnessService.java
@@ -0,0 +1,168 @@
+package io.github.hectorvent.floci.services.bedrockagentcore;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import io.github.hectorvent.floci.config.EmulatorConfig;
+import io.github.hectorvent.floci.core.common.AwsEventStreamWriter;
+import io.github.hectorvent.floci.core.common.AwsException;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+import java.io.OutputStream;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.function.Consumer;
+import java.util.regex.Pattern;
+
+/**
+ * {@code InvokeHarness}: the AgentCore Harness data plane.
+ *
+ * <p>There is no agent loop here and no model. What is emulated is the wire contract an application
+ * integrates against: the event-stream framing, the event sequence and the order they arrive in.
+ * The assistant's reply echoes the caller's last user message, so a chat UI visibly works end to end
+ * locally and a request that failed to parse is obvious rather than hidden behind a fixed string.
+ *
+ * <p>Not emulated: model inference, tool execution, skills and multi-turn iteration. A request may
+ * carry {@code tools}, but no tool-use block is ever produced.
+ */
+@ApplicationScoped
+public class BedrockAgentCoreHarnessService {
+
+ private static final String ROLE_USER = "user";
+
+ /**
+ * Modelled constraints, from the service model rather than guessed. A harness ARN ends in the
+ * same {@code name-<10 alphanumerics>} shape AgentCore uses for its other resource ids, and a
+ * runtime session id has a documented minimum length that a short test value does not meet.
+ */
+ private static final Pattern HARNESS_ARN = Pattern.compile(
+ "arn:([^:]+)?:bedrock-agentcore:[a-z0-9-]+:[0-9]{12}:harness/[a-zA-Z][a-zA-Z0-9_]{0,39}-[a-zA-Z0-9]{10}");
+ private static final Pattern RUNTIME_SESSION_ID = Pattern.compile("[a-zA-Z0-9][a-zA-Z0-9-_]*");
+ private static final int RUNTIME_SESSION_ID_MIN = 33;
+ private static final int RUNTIME_SESSION_ID_MAX = 100;
+ /** Chunked so consumers exercise incremental delivery rather than one blob. */
+ private static final int CHUNK_SIZE = 24;
+
+ private final ObjectMapper objectMapper;
+ private final String echoPrefix;
+ private final String emptyReply;
+
+ @Inject
+ public BedrockAgentCoreHarnessService(ObjectMapper objectMapper, EmulatorConfig config) {
+ this.objectMapper = objectMapper;
+ this.echoPrefix = config.services().bedrockAgentCore().harnessEchoPrefix();
+ this.emptyReply = config.services().bedrockAgentCore().harnessEmptyReply();
+ }
+
+ /**
+ * Validates the request and returns the stream writer.
+ *
+ * <p>Validation happens before any frame is written: once the stream is committed the status is
+ * already 200 and the only way left to report a problem is an in-stream exception frame.
+ */
+ public Consumer<OutputStream> invokeHarness(String harnessArn, String runtimeSessionId, ObjectNode request) {
+ // harnessArn rides in the query string and runtimeSessionId in a header, so neither is
+ // read from the body. Confirmed against the SDK's own request bindings.
+ // The ARN is validated whole, shape included, before runtimeSessionId is looked at: a request
+ // wrong in both reports the ARN, as AWS does.
+ requirePresent(harnessArn, "harnessArn");
+ if (!HARNESS_ARN.matcher(harnessArn).matches()) {
+ throw new AwsException("ValidationException", "Invalid harness ARN format.", 400);
+ }
+ requirePresent(runtimeSessionId, "runtimeSessionId");
+ if (runtimeSessionId.length() < RUNTIME_SESSION_ID_MIN
+ || runtimeSessionId.length() > RUNTIME_SESSION_ID_MAX
+ || !RUNTIME_SESSION_ID.matcher(runtimeSessionId).matches()) {
+ throw new AwsException("ValidationException",
+ "runtimeSessionId must be " + RUNTIME_SESSION_ID_MIN + " to " + RUNTIME_SESSION_ID_MAX
+ + " characters and match " + RUNTIME_SESSION_ID.pattern(), 400);
+ }
+ // The ARN's shape is checked but the harness itself is not resolved: the emulator models no
+ // harness resource, so there is nothing to look it up in.
+
+ // messages is a required member. An empty array is a legitimate request, but an omitted or
+ // non-array member is not, so the two must not collapse into the same canned reply.
+ JsonNode messages = request.path("messages");
+ if (!messages.isArray()) {
+ throw new AwsException("ValidationException", "messages is required", 400);
+ }
+
+ String reply = buildReply(messages);
+ return output -> writeStream(output, reply);
+ }
+
+ private String buildReply(JsonNode messages) {
+ String lastUserText = lastUserText(messages);
+ // An empty messages array is legitimate: a caller whose memory already holds the current
+ // turn sends none. Answer rather than fail.
+ return lastUserText.isBlank() ? emptyReply : echoPrefix + lastUserText;
+ }
+
+ /** Concatenates the text blocks of the last {@code user} message. */
+ private static String lastUserText(JsonNode messages) {
+ if (!messages.isArray()) {
+ return "";
+ }
+ for (int i = messages.size() - 1; i >= 0; i--) {
+ JsonNode message = messages.get(i);
+ if (!ROLE_USER.equalsIgnoreCase(message.path("role").asText(""))) {
+ continue;
+ }
+ StringBuilder text = new StringBuilder();
+ for (JsonNode block : message.path("content")) {
+ String blockText = block.path("text").asText("");
+ if (!blockText.isEmpty()) {
+ text.append(blockText);
+ }
+ }
+ return text.toString();
+ }
+ return "";
+ }
+
+ private void writeStream(OutputStream output, String reply) {
+ AwsEventStreamWriter.writeEvent(objectMapper, output, "messageStart",
+ objectMapper.createObjectNode().put("role", "assistant"));
+
+ ObjectNode contentBlockStart = objectMapper.createObjectNode();
+ contentBlockStart.put("contentBlockIndex", 0);
+ AwsEventStreamWriter.writeEvent(objectMapper, output, "contentBlockStart", contentBlockStart);
+
+ for (String chunk : chunk(reply)) {
+ ObjectNode delta = objectMapper.createObjectNode();
+ delta.put("contentBlockIndex", 0);
+ delta.putObject("delta").put("text", chunk);
+ AwsEventStreamWriter.writeEvent(objectMapper, output, "contentBlockDelta", delta);
+ }
+
+ AwsEventStreamWriter.writeEvent(objectMapper, output, "contentBlockStop",
+ objectMapper.createObjectNode().put("contentBlockIndex", 0));
+ AwsEventStreamWriter.writeEvent(objectMapper, output, "messageStop",
+ objectMapper.createObjectNode().put("stopReason", "end_turn"));
+
+ ObjectNode metadata = objectMapper.createObjectNode();
+ // Token counts are a stand-in: nothing is tokenised, so they are derived from the text.
+ int outputTokens = Math.max(1, reply.length() / 4);
+ metadata.putObject("usage")
+ .put("inputTokens", outputTokens)
+ .put("outputTokens", outputTokens)
+ .put("totalTokens", outputTokens * 2);
+ metadata.putObject("metrics").put("latencyMs", 1);
+ AwsEventStreamWriter.writeEvent(objectMapper, output, "metadata", metadata);
+ }
+
+ private static List<String> chunk(String text) {
+ List<String> chunks = new ArrayList<>();
+ for (int i = 0; i < text.length(); i += CHUNK_SIZE) {
+ chunks.add(text.substring(i, Math.min(text.length(), i + CHUNK_SIZE)));
+ }
+ return chunks.isEmpty() ? List.of("") : chunks;
+ }
+
+ private static void requirePresent(String value, String field) {
+ if (value == null || value.isBlank()) {
+ throw new AwsException("ValidationException", field + " is required", 400);
+ }
+ }
+}
diff --git a/src/main/java/io/github/hectorvent/floci/services/bedrockruntime/backend/BedrockOpenAiTranslator.java b/src/main/java/io/github/hectorvent/floci/services/bedrockruntime/backend/BedrockOpenAiTranslator.java
index 15f1659335..fbd1bc7b7a 100644
--- a/src/main/java/io/github/hectorvent/floci/services/bedrockruntime/backend/BedrockOpenAiTranslator.java
+++ b/src/main/java/io/github/hectorvent/floci/services/bedrockruntime/backend/BedrockOpenAiTranslator.java
@@ -1,5 +1,6 @@
package io.github.hectorvent.floci.services.bedrockruntime.backend;
+import io.github.hectorvent.floci.core.common.AwsEventStreamWriter;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
@@ -280,7 +281,7 @@ final class BedrockOpenAiTranslator {
* contentBlockIndex before parsing it as JSON.
*/
static void streamBedrockEvents(ObjectMapper mapper, Stream<String> sseLines, OutputStream out, long startNanos) {
- BedrockStreamEncoder.writeEvent(mapper, out, "messageStart", mapper.createObjectNode().put("role", "assistant"));
+ AwsEventStreamWriter.writeEvent(mapper, out, "messageStart", mapper.createObjectNode().put("role", "assistant"));
boolean anyContentDeltaWritten = false;
Map<Integer, ToolCallAccumulator> toolCalls = new LinkedHashMap<>();
@@ -344,7 +345,7 @@ final class BedrockOpenAiTranslator {
}
if (anyContentDeltaWritten) {
- BedrockStreamEncoder.writeEvent(mapper, out, "contentBlockStop",
+ AwsEventStreamWriter.writeEvent(mapper, out, "contentBlockStop",
mapper.createObjectNode().put("contentBlockIndex", 0));
}
@@ -356,7 +357,7 @@ final class BedrockOpenAiTranslator {
}
boolean hasToolCalls = !validToolCalls.isEmpty();
- BedrockStreamEncoder.writeEvent(mapper, out, "messageStop",
+ AwsEventStreamWriter.writeEvent(mapper, out, "messageStop",
mapper.createObjectNode().put("stopReason", hasToolCalls ? "tool_use" : mapFinishReason(finishReason)));
writeMetadata(mapper, out, startNanos, promptTokens, completionTokens, totalTokens);
@@ -386,7 +387,7 @@ final class BedrockOpenAiTranslator {
.put("outputTokens", completionTokens)
.put("totalTokens", totalTokens);
metadata.putObject("metrics").put("latencyMs", latencyMs);
- BedrockStreamEncoder.writeEvent(mapper, out, "metadata", metadata);
+ AwsEventStreamWriter.writeEvent(mapper, out, "metadata", metadata);
}
private static void writeToolCalls(ObjectMapper mapper, OutputStream out, ToolCallAccumulator acc, int blockIndex) {
@@ -395,14 +396,14 @@ final class BedrockOpenAiTranslator {
ObjectNode toolUseStart = startEvent.putObject("start").putObject("toolUse");
toolUseStart.put("toolUseId", acc.id);
toolUseStart.put("name", acc.name);
- BedrockStreamEncoder.writeEvent(mapper, out, "contentBlockStart", startEvent);
+ AwsEventStreamWriter.writeEvent(mapper, out, "contentBlockStart", startEvent);
ObjectNode deltaEvent = mapper.createObjectNode();
deltaEvent.put("contentBlockIndex", blockIndex);
deltaEvent.putObject("delta").putObject("toolUse").put("input", acc.arguments.toString());
- BedrockStreamEncoder.writeEvent(mapper, out, "contentBlockDelta", deltaEvent);
+ AwsEventStreamWriter.writeEvent(mapper, out, "contentBlockDelta", deltaEvent);
- BedrockStreamEncoder.writeEvent(mapper, out, "contentBlockStop",
+ AwsEventStreamWriter.writeEvent(mapper, out, "contentBlockStop",
mapper.createObjectNode().put("contentBlockIndex", blockIndex));
}
@@ -430,7 +431,7 @@ final class BedrockOpenAiTranslator {
ObjectNode errorPayload = mapper.createObjectNode();
errorPayload.put("message", "Proxy backend's ConverseStream response ended without a finish_reason "
+ "or \"[DONE]\" terminator - the stream may have been truncated.");
- BedrockStreamEncoder.writeException(mapper, out, "modelStreamErrorException", errorPayload);
+ AwsEventStreamWriter.writeException(mapper, out, "modelStreamErrorException", errorPayload);
}
private static void writeToolCalls(JsonNode delta, Map<Integer, ToolCallAccumulator> toolCalls) {
@@ -466,7 +467,7 @@ final class BedrockOpenAiTranslator {
ObjectNode deltaEvent = mapper.createObjectNode();
deltaEvent.put("contentBlockIndex", 0);
deltaEvent.putObject("delta").put("text", contentDelta);
- BedrockStreamEncoder.writeEvent(mapper, out, "contentBlockDelta", deltaEvent);
+ AwsEventStreamWriter.writeEvent(mapper, out, "contentBlockDelta", deltaEvent);
return true;
}
diff --git a/src/main/java/io/github/hectorvent/floci/services/bedrockruntime/backend/StubBackend.java b/src/main/java/io/github/hectorvent/floci/services/bedrockruntime/backend/StubBackend.java
index a8126b9410..ca5e6071c3 100644
--- a/src/main/java/io/github/hectorvent/floci/services/bedrockruntime/backend/StubBackend.java
+++ b/src/main/java/io/github/hectorvent/floci/services/bedrockruntime/backend/StubBackend.java
@@ -1,5 +1,6 @@
package io.github.hectorvent.floci.services.bedrockruntime.backend;
+import io.github.hectorvent.floci.core.common.AwsEventStreamWriter;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
@@ -82,7 +83,7 @@ public class StubBackend implements BedrockBackend {
@Override
public Consumer<OutputStream> converseStream(String modelId, ObjectNode bedrockRequest) {
return output -> {
- BedrockStreamEncoder.writeEvent(objectMapper, output, "messageStart",
+ AwsEventStreamWriter.writeEvent(objectMapper, output, "messageStart",
objectMapper.createObjectNode().put("role", "assistant"));
List<String> flociStubResponse = List.of("Floci stub response", " for model=", modelId);
@@ -90,13 +91,13 @@ public class StubBackend implements BedrockBackend {
ObjectNode contentBlockDelta = objectMapper.createObjectNode();
contentBlockDelta.put("contentBlockIndex", 0);
contentBlockDelta.putObject("delta").put("text", fragment);
- BedrockStreamEncoder.writeEvent(objectMapper, output, "contentBlockDelta", contentBlockDelta);
+ AwsEventStreamWriter.writeEvent(objectMapper, output, "contentBlockDelta", contentBlockDelta);
}
- BedrockStreamEncoder.writeEvent(objectMapper, output, "contentBlockStop",
+ AwsEventStreamWriter.writeEvent(objectMapper, output, "contentBlockStop",
objectMapper.createObjectNode().put("contentBlockIndex", 0));
- BedrockStreamEncoder.writeEvent(objectMapper, output, "messageStop",
+ AwsEventStreamWriter.writeEvent(objectMapper, output, "messageStop",
objectMapper.createObjectNode().put("stopReason", "end_turn"));
ObjectNode metadata = objectMapper.createObjectNode();
@@ -105,7 +106,7 @@ public class StubBackend implements BedrockBackend {
.put("outputTokens", 12)
.put("totalTokens", 22);
metadata.putObject("metrics").put("latencyMs", 1);
- BedrockStreamEncoder.writeEvent(objectMapper, output, "metadata", metadata);
+ AwsEventStreamWriter.writeEvent(objectMapper, output, "metadata", metadata);
};
}
}
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
index 37f65fe4c4..857288cb94 100644
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -752,6 +752,8 @@ floci:
enabled: true
# invoke-response: '{"output":"yes"}' # Body returned by InvokeAgentRuntime
# validate-runtime-exists: false # true = reject unknown runtime ARNs
+ # harness-echo-prefix: 'You said: ' # Prefix on the reply InvokeHarness streams back
+ # harness-empty-reply: 'No user message was supplied.'
bedrock-agent-core-control:
enabled: true
servicequotas:
diff --git a/src/test/java/io/github/hectorvent/floci/services/bedrockagentcore/BedrockAgentCoreHarnessIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/bedrockagentcore/BedrockAgentCoreHarnessIntegrationTest.java
new file mode 100644
index 0000000000..e59522f768
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/services/bedrockagentcore/BedrockAgentCoreHarnessIntegrationTest.java
@@ -0,0 +1,199 @@
+package io.github.hectorvent.floci.services.bedrockagentcore;
+
+import io.quarkus.test.junit.QuarkusTest;
+import io.restassured.specification.RequestSpecification;
+import org.junit.jupiter.api.Test;
+
+import java.util.regex.Matcher;
+
+import java.util.regex.Pattern;
+
+import static io.restassured.RestAssured.given;
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.containsString;
+import static org.hamcrest.Matchers.lessThan;
+import static org.hamcrest.Matchers.not;
+
+/**
+ * {@code InvokeHarness} streams an event-stream response.
+ *
+ * <p>The body is binary event-stream framing rather than JSON, but the event names and the JSON
+ * payload text still appear as UTF-8 substrings between the framing bytes, which is how the
+ * bedrock-runtime streaming tests assert on the same encoding.
+ */
+@QuarkusTest
+class BedrockAgentCoreHarnessIntegrationTest {
+
+ /** Matches the modelled ARN pattern: a name then a ten character suffix. */
+ private static final String ARN =
+ "arn:aws:bedrock-agentcore:us-east-1:000000000000:harness/myHarness-abc1234567";
+ /** A runtime session id has a documented minimum of 33 characters. */
+ private static final String SESSION = "session-0123456789abcdef0123456789abcdef";
+ private static final String SESSION_HEADER = "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id";
+
+ /**
+ * Rebuilds the assistant text from the contentBlockDelta frames, the way a consumer does.
+ * Asserting on the whole phrase directly would fail: the reply is chunked, so it is split
+ * across frames and never appears contiguously in the body.
+ */
+ private static String assistantText(String eventStreamBody) {
+ Matcher matcher = Pattern.compile("\\{\"text\":\"(.*?)\"\\}").matcher(eventStreamBody);
+ StringBuilder text = new StringBuilder();
+ while (matcher.find()) {
+ text.append(matcher.group(1));
+ }
+ return text.toString();
+ }
+
+ /**
+ * Posts with the bindings the SDK uses: {@code harnessArn} is a query parameter and
+ * {@code runtimeSessionId} a header. Only messages/model/tools travel in the body.
+ */
+ private static RequestSpecification request(String harnessArn, String sessionId) {
+ RequestSpecification spec = given().contentType("application/json");
+ if (harnessArn != null) {
+ spec = spec.queryParam("harnessArn", harnessArn);
+ }
+ if (sessionId != null) {
+ spec = spec.header(SESSION_HEADER, sessionId);
+ }
+ return spec;
+ }
+
+ private static String invoke(String harnessArn, String sessionId, String body, int expectedStatus) {
+ return request(harnessArn, sessionId).body(body)
+ .when().post("/harnesses/invoke")
+ .then().statusCode(expectedStatus)
+ .extract().body().asString();
+ }
+
+ @Test
+ void theReplyEchoesTheLastUserMessage() {
+ String body = request(ARN, SESSION)
+ .body("""
+ {"messages": [{"role": "user", "content": [{"text": "what is EIDR?"}]}]}
+ """)
+ .when().post("/harnesses/invoke")
+ .then().statusCode(200)
+ .header("Content-Type", containsString("application/vnd.amazon.eventstream"))
+ .extract().body().asString();
+
+ assertThat(assistantText(body), containsString("what is EIDR?"));
+ }
+
+ @Test
+ void theStreamCarriesTheFullEventSequenceInOrder() {
+ String body = request(ARN, SESSION)
+ .body("""
+ {"messages": [{"role": "user", "content": [{"text": "hello"}]}]}
+ """)
+ .when().post("/harnesses/invoke")
+ .then().statusCode(200)
+ .extract().body().asString();
+
+ assertThat(body, containsString("messageStart"));
+ assertThat(body, containsString("assistant"));
+ assertThat(body, containsString("contentBlockStart"));
+ assertThat(body, containsString("contentBlockDelta"));
+ assertThat(body, containsString("contentBlockStop"));
+ assertThat(body, containsString("messageStop"));
+ assertThat(body, containsString("end_turn"));
+ assertThat(body, containsString("metadata"));
+
+ // Order matters to a consumer building a message from the stream.
+ assertThat(body.indexOf("messageStart"), lessThan(body.indexOf("contentBlockDelta")));
+ assertThat(body.indexOf("contentBlockDelta"), lessThan(body.indexOf("messageStop")));
+ assertThat(body.indexOf("messageStop"), lessThan(body.indexOf("metadata")));
+ }
+
+ @Test
+ void onlyTheLastUserMessageIsEchoed() {
+ String body = request(ARN, SESSION)
+ .body("""
+ {"messages": [
+ {"role": "user", "content": [{"text": "first question"}]},
+ {"role": "assistant", "content": [{"text": "an answer"}]},
+ {"role": "user", "content": [{"text": "second question"}]}]}
+ """)
+ .when().post("/harnesses/invoke")
+ .then().statusCode(200)
+ .extract().body().asString();
+
+ assertThat(assistantText(body), containsString("second question"));
+ assertThat(assistantText(body), not(containsString("first question")));
+ }
+
+ @Test
+ void anEmptyMessagesArrayStillStreamsAWellFormedResponse() {
+ // Legitimate: a caller whose memory already holds the current turn sends no messages.
+ String body = invoke(ARN, SESSION, "{\"messages\": []}", 200);
+
+ assertThat(body, containsString("messageStart"));
+ assertThat(body, containsString("messageStop"));
+ assertThat(assistantText(body), containsString("No user message was supplied."));
+ }
+
+ @Test
+ void aRequestWithoutAHarnessArnIsRejected() {
+ String body = invoke(null, SESSION, "{}", 400);
+ assertThat(body, containsString("ValidationException"));
+ assertThat(body, containsString("harnessArn"));
+ }
+
+ @Test
+ void aRequestWithoutARuntimeSessionIdIsRejected() {
+ String body = invoke(ARN, null, "{}", 400);
+ assertThat(body, containsString("ValidationException"));
+ assertThat(body, containsString("runtimeSessionId"));
+ }
+
+ @Test
+ void anUnknownHarnessArnIsAccepted() {
+ // The emulator models no harness resource, so there is nothing to resolve an ARN against.
+ // Well formed but naming no harness: the shape is checked, the resource is not resolved.
+ request("arn:aws:bedrock-agentcore:us-east-1:000000000000:harness/unknownOne-zzzz999999", SESSION)
+ .body("""
+ {"messages": [{"role": "user", "content": [{"text": "hi"}]}]}
+ """)
+ .when().post("/harnesses/invoke")
+ .then().statusCode(200);
+ }
+
+ @Test
+ void anOmittedMessagesMemberIsRejected() {
+ // messages is required. An empty array is a legitimate request; omitting the member is not,
+ // so the two must not collapse into the same canned reply.
+ String body = invoke(ARN, SESSION, "{}", 400);
+ assertThat(body, containsString("messages"));
+ }
+
+ @Test
+ void aNonArrayMessagesMemberIsRejected() {
+ invoke(ARN, SESSION, "{\"messages\": \"hello\"}", 400);
+ }
+
+ @Test
+ void aRuntimeSessionIdShorterThanTheMinimumIsRejected() {
+ String body = invoke(ARN, "short", "{\"messages\": []}", 400);
+ assertThat(body, containsString("runtimeSessionId"));
+ }
+
+ @Test
+ void aMalformedHarnessArnIsRejected() {
+ String body = invoke("anything", SESSION, "{\"messages\": []}", 400);
+ assertThat(body, containsString("harness ARN"));
+ }
+
+ @Test
+ void aMalformedArnIsReportedAheadOfAMissingRuntimeSessionId() {
+ String body = invoke("anything", null, "{\"messages\": []}", 400);
+ assertThat(body, containsString("harness ARN"));
+ assertThat(body, not(containsString("runtimeSessionId")));
+ }
+
+ @Test
+ void anArnWithoutTheTenCharacterSuffixIsRejected() {
+ invoke("arn:aws:bedrock-agentcore:us-east-1:000000000000:harness/h-1", SESSION,
+ "{\"messages\": []}", 400);
+ }
+}