items = createResponse.input().get().asResponse();
+ boolean needsReparse = false;
+ for (ResponseInputItem item : items) {
+ if (!item.isEasyInputMessage() && !item.isMessage()
+ && !item.isFunctionCall() && !item.isFunctionCallOutput()
+ && !item.isComputerCall() && !item.isComputerCallOutput()
+ && !item.isItemReference() && !item.isCodeInterpreterCall()
+ && item._json().isPresent()) {
+ needsReparse = true;
+ break;
+ }
+ }
+
+ if (needsReparse && node.has("input") && node.get("input").isArray()) {
+ ArrayNode inputArray = (ArrayNode) node.get("input");
+ boolean modified = false;
+ for (int i = 0; i < inputArray.size(); i++) {
+ JsonNode element = inputArray.get(i);
+ if (element.isObject() && !element.has("type")
+ && element.has("role") && element.has("content")) {
+ ((ObjectNode) element).put("type", "message");
+ modified = true;
+ }
+ }
+ if (modified) {
+ LOGGER.debug("Injected 'type: message' into input items missing type discriminator");
+ createResponse = p.getCodec().treeToValue(node, ResponseCreateParams.Body.class);
+ }
+ }
+ }
+ return createResponse;
+ }
+ }
+}
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/AgentServerResponseContext.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/AgentServerResponseContext.java
new file mode 100644
index 000000000000..f08ba31b8568
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/AgentServerResponseContext.java
@@ -0,0 +1,355 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.microsoft.agentserver.api.implementation.IdGenerator;
+import com.microsoft.agentserver.api.implementation.ItemConversion;
+import com.openai.models.responses.ResponseCreateParams;
+import com.openai.models.responses.ResponseInputItem;
+import com.openai.models.responses.ResponseItem;
+import com.openai.models.responses.ResponseOutputItem;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.atomic.AtomicReference;
+
+/**
+ * Enhanced implementation of {@link ResponseContext} that resolves input items
+ * and conversation history from the request, using lazy-cached async resolution.
+ * Inline items are converted via {@link ItemConversion}; item references are
+ * resolved via {@link ResponsesProvider#getItemsAsync}.
+ *
+ * Accepts either {@link ResponseCreateParams} or {@link ResponseCreateParams.Body}
+ * as input — both expose the same API surface ({@code input()},
+ * {@code previousResponseId()}, {@code conversation()}, etc.).
+ */
+final class AgentServerResponseContext implements ResponseContext {
+
+ /**
+ * Default maximum number of history items to fetch.
+ */
+ static final int DEFAULT_FETCH_HISTORY_COUNT = 100;
+
+ private final String responseId;
+ private final ResponsesProvider provider;
+ private final ResponseCreateParams.Body request;
+ private final JsonNode rawBody;
+ private final int historyLimit;
+ private final IsolationContext isolation;
+ private final Map clientHeaders;
+ private final Map queryParameters;
+ private final String requestId;
+ private final String sessionId;
+ // Lazy-cached async results (AtomicReference for thread-safe single-init)
+ private final AtomicReference>> inputItemsRef =
+ new AtomicReference<>();
+ private final AtomicReference>> historyItemIdsRef =
+ new AtomicReference<>();
+ private final AtomicReference>> historyRef =
+ new AtomicReference<>();
+ private volatile boolean shutdownRequested;
+ private volatile boolean cancelled;
+
+ /**
+ * Initializes a new instance of {@code AgentServerResponseContext}.
+ *
+ * Use {@link ResponseContext#builder()} to construct instances via the fluent builder API.
+ *
+ * @param responseId the unique response identifier.
+ * @param provider the responses provider for resolving item references and history.
+ * @param request the create-response request body containing input items.
+ * @param rawBody the full raw JSON request body, or {@code null} if not available.
+ * @param historyLimit maximum number of history items to fetch, or {@code null} for the default (100).
+ * @param isolation the isolation context, or {@code null} for {@link IsolationContext#EMPTY}.
+ * @param clientHeaders the forwarded client headers, or {@code null} for empty.
+ * @param queryParameters the query parameters, or {@code null} for empty.
+ * @param requestId the request ID for correlation, or {@code null}.
+ * @param sessionId the resolved session ID per {@code SessionIdResolver}, or {@code null}.
+ */
+ AgentServerResponseContext(
+ String responseId,
+ ResponsesProvider provider,
+ ResponseCreateParams.Body request,
+ JsonNode rawBody,
+ Integer historyLimit,
+ IsolationContext isolation,
+ Map clientHeaders,
+ Map queryParameters,
+ String requestId,
+ String sessionId) {
+ this.responseId = Objects.requireNonNull(responseId, "responseId must not be null");
+ this.provider = Objects.requireNonNull(provider, "provider must not be null");
+ this.request = Objects.requireNonNull(request, "request must not be null");
+ this.rawBody = rawBody;
+ this.historyLimit = historyLimit != null ? historyLimit : DEFAULT_FETCH_HISTORY_COUNT;
+ this.isolation = isolation != null ? isolation : IsolationContext.EMPTY;
+ this.clientHeaders = clientHeaders != null ? clientHeaders : Collections.emptyMap();
+ this.queryParameters = queryParameters != null ? queryParameters : Collections.emptyMap();
+ this.requestId = requestId;
+ this.sessionId = sessionId;
+ }
+
+ /**
+ * Backward-compatible constructor without platform headers.
+ */
+ AgentServerResponseContext(
+ String responseId,
+ ResponsesProvider provider,
+ ResponseCreateParams.Body request,
+ JsonNode rawBody,
+ Integer historyLimit) {
+ this(responseId, provider, request, rawBody, historyLimit, null, null, null, null, null);
+ }
+
+ /**
+ * Converts a {@link ResponseItem} back to a {@link ResponseOutputItem} for input resolution.
+ *
+ * Note: {@code FunctionCall} items cannot be converted because
+ * {@link ResponseItem#asFunctionCall()} returns {@code ResponseFunctionToolCallItem}
+ * (input variant) while {@link ResponseOutputItem#ofFunctionCall} requires
+ * {@code ResponseFunctionToolCall} (output variant).
+ */
+ private static ResponseOutputItem toOutputItem(ResponseItem item) {
+ if (item.isResponseOutputMessage()) {
+ return ResponseOutputItem.ofMessage(item.asResponseOutputMessage());
+ }
+ if (item.isFileSearchCall()) {
+ return ResponseOutputItem.ofFileSearchCall(item.asFileSearchCall());
+ }
+ if (item.isWebSearchCall()) {
+ return ResponseOutputItem.ofWebSearchCall(item.asWebSearchCall());
+ }
+ if (item.isComputerCall()) {
+ return ResponseOutputItem.ofComputerCall(item.asComputerCall());
+ }
+ if (item.isReasoning()) {
+ return ResponseOutputItem.ofReasoning(item.asReasoning());
+ }
+ if (item.isCodeInterpreterCall()) {
+ return ResponseOutputItem.ofCodeInterpreterCall(item.asCodeInterpreterCall());
+ }
+ if (item.isShellCall()) {
+ return ResponseOutputItem.ofShellCall(item.asShellCall());
+ }
+ if (item.isShellCallOutput()) {
+ return ResponseOutputItem.ofShellCallOutput(item.asShellCallOutput());
+ }
+ if (item.isApplyPatchCall()) {
+ return ResponseOutputItem.ofApplyPatchCall(item.asApplyPatchCall());
+ }
+ if (item.isApplyPatchCallOutput()) {
+ return ResponseOutputItem.ofApplyPatchCallOutput(item.asApplyPatchCallOutput());
+ }
+ return null;
+ }
+
+ /**
+ * Lazily initializes and caches a {@link CompletableFuture} in the given
+ * {@link AtomicReference}, ensuring at most one computation.
+ */
+ private static CompletableFuture getOrInit(
+ AtomicReference> ref,
+ java.util.function.Supplier> supplier) {
+ CompletableFuture existing = ref.get();
+ if (existing != null) {
+ return existing;
+ }
+ CompletableFuture created = supplier.get();
+ if (ref.compareAndSet(null, created)) {
+ return created;
+ }
+ return ref.get();
+ }
+
+ private static boolean isNullOrEmpty(String s) {
+ return s == null || s.isEmpty();
+ }
+
+ @Override
+ public String getResponseId() {
+ return responseId;
+ }
+
+ @Override
+ public boolean isShutdownRequested() {
+ return shutdownRequested;
+ }
+
+ /**
+ * Sets whether the server is shutting down.
+ * This is called by the hosting infrastructure, not by handlers.
+ */
+ public void setShutdownRequested(boolean shutdownRequested) {
+ this.shutdownRequested = shutdownRequested;
+ }
+
+ @Override
+ public boolean isCancelled() {
+ return cancelled;
+ }
+
+ @Override
+ public void cancel() {
+ this.cancelled = true;
+ }
+
+ @Override
+ public JsonNode getRawBody() {
+ return rawBody;
+ }
+
+ @Override
+ public IsolationContext getIsolation() {
+ return isolation;
+ }
+
+ @Override
+ public Map getClientHeaders() {
+ return clientHeaders;
+ }
+
+ @Override
+ public Map getQueryParameters() {
+ return queryParameters;
+ }
+
+ @Override
+ public String getRequestId() {
+ return requestId;
+ }
+
+ /**
+ * Package-private accessor for the original request body (needed by API helpers).
+ */
+ ResponseCreateParams.Body getRequestBody() {
+ return request;
+ }
+
+ @Override
+ public String getSessionId() {
+ return sessionId;
+ }
+
+ // ── Private resolution methods ──────────────────────────────
+
+ @Override
+ public CompletableFuture> getInputItemsAsync() {
+ return getOrInit(inputItemsRef, this::resolveInputItemsAsync);
+ }
+
+ @Override
+ public CompletableFuture> getHistoryAsync() {
+ return getOrInit(historyRef, this::resolveHistoryAsync);
+ }
+
+ /**
+ * Gets the cached history item IDs. Used by the orchestrator to pass IDs
+ * to the provider without duplicating storage.
+ *
+ * @return a future containing the resolved history item IDs.
+ */
+ public CompletableFuture> getHistoryItemIdsAsync() {
+ return getOrInit(historyItemIdsRef, this::resolveHistoryItemIdsAsync);
+ }
+
+ private CompletableFuture> resolveInputItemsAsync() {
+ Optional inputOpt = request.input();
+ if (inputOpt.isEmpty()) {
+ return CompletableFuture.completedFuture(Collections.emptyList());
+ }
+
+ ResponseCreateParams.Input input = inputOpt.get();
+
+ // If the input is a plain text string, there are no structured items to resolve
+ if (input.isText()) {
+ return CompletableFuture.completedFuture(Collections.emptyList());
+ }
+
+ List items = input.asResponse();
+ if (items.isEmpty()) {
+ return CompletableFuture.completedFuture(Collections.emptyList());
+ }
+
+ IdGenerator idGen = new IdGenerator(IdGenerator.extractPartitionKey(responseId));
+
+ // Separate inline items from item references
+ List results = new ArrayList<>(items.size());
+ List referenceIds = new ArrayList<>();
+ List referencePositions = new ArrayList<>();
+
+ for (ResponseInputItem item : items) {
+ if (item.isItemReference()) {
+ referenceIds.add(item.asItemReference().id());
+ referencePositions.add(results.size());
+ results.add(null); // placeholder — index matches results.size()
+ } else {
+ ResponseOutputItem output = ItemConversion.toOutputItem(item, idGen);
+ if (output != null) {
+ results.add(output);
+ }
+ // Non-convertible, non-reference items are silently skipped
+ }
+ }
+
+ // If no references, return the inline results immediately
+ if (referenceIds.isEmpty()) {
+ return CompletableFuture.completedFuture(Collections.unmodifiableList(results));
+ }
+
+ // Batch-resolve references via the provider
+ return provider.getItemsAsync(referenceIds)
+ .thenApply(resolved -> {
+ for (int i = 0; i < referencePositions.size(); i++) {
+ int pos = referencePositions.get(i);
+ if (i < resolved.size() && resolved.get(i) != null) {
+ ResponseOutputItem converted = toOutputItem(resolved.get(i));
+ if (converted != null) {
+ results.set(pos, converted);
+ }
+ }
+ }
+ // Remove unresolved placeholders (nulls remaining from failed references)
+ return results.stream()
+ .filter(Objects::nonNull)
+ .toList();
+ });
+ }
+
+ // ── Utility ─────────────────────────────────────────────────
+
+ private CompletableFuture> resolveHistoryItemIdsAsync() {
+ String previousResponseId = request.previousResponseId().orElse(null);
+ String conversationId = request.conversation()
+ .flatMap(conv -> conv.isId() ? Optional.of(conv.asId()) : Optional.empty())
+ .orElse(null);
+
+ if (isNullOrEmpty(previousResponseId) && isNullOrEmpty(conversationId)) {
+ return CompletableFuture.completedFuture(Collections.emptyList());
+ }
+
+ return provider.getHistoryItemIdsAsync(previousResponseId, conversationId, historyLimit);
+ }
+
+ private CompletableFuture> resolveHistoryAsync() {
+ return getHistoryItemIdsAsync()
+ .thenCompose(ids -> {
+ if (ids.isEmpty()) {
+ return CompletableFuture.completedFuture(Collections.emptyList());
+ }
+ return provider.getItemsAsync(ids)
+ .thenApply(items -> items.stream()
+ .filter(Objects::nonNull)
+ .toList());
+ });
+ }
+}
+
+
+
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/AgentServerResponseEventStream.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/AgentServerResponseEventStream.java
new file mode 100644
index 000000000000..064c299b67dc
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/AgentServerResponseEventStream.java
@@ -0,0 +1,1217 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import com.microsoft.agentserver.api.implementation.IdGenerator;
+import com.openai.core.JsonNull;
+import com.openai.core.http.StreamResponse;
+import com.openai.models.chat.completions.ChatCompletionChunk;
+import com.openai.models.responses.Response;
+import com.openai.models.responses.ResponseCodeInterpreterToolCall;
+import com.openai.models.responses.ResponseCompletedEvent;
+import com.openai.models.responses.ResponseContentPartAddedEvent;
+import com.openai.models.responses.ResponseContentPartDoneEvent;
+import com.openai.models.responses.ResponseCreatedEvent;
+import com.openai.models.responses.ResponseCustomToolCall;
+import com.openai.models.responses.ResponseError;
+import com.openai.models.responses.ResponseFailedEvent;
+import com.openai.models.responses.ResponseFileSearchToolCall;
+import com.openai.models.responses.ResponseFunctionCallArgumentsDeltaEvent;
+import com.openai.models.responses.ResponseFunctionCallArgumentsDoneEvent;
+import com.openai.models.responses.ResponseFunctionToolCall;
+import com.openai.models.responses.ResponseFunctionWebSearch;
+import com.openai.models.responses.ResponseInProgressEvent;
+import com.openai.models.responses.ResponseIncompleteEvent;
+import com.openai.models.responses.ResponseOutputItem;
+import com.openai.models.responses.ResponseOutputItemAddedEvent;
+import com.openai.models.responses.ResponseOutputItemDoneEvent;
+import com.openai.models.responses.ResponseOutputMessage;
+import com.openai.models.responses.ResponseOutputText;
+import com.openai.models.responses.ResponseQueuedEvent;
+import com.openai.models.responses.ResponseReasoningItem;
+import com.openai.models.responses.ResponseStatus;
+import com.openai.models.responses.ResponseStreamEvent;
+import com.openai.models.responses.ResponseTextDeltaEvent;
+import com.openai.models.responses.ResponseTextDoneEvent;
+import com.openai.models.responses.ResponseUsage;
+import com.openai.models.responses.ToolChoiceOptions;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.Flow;
+import java.util.concurrent.SubmissionPublisher;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.function.Consumer;
+
+/**
+ * Fluent builder for constructing a streaming response event sequence.
+ *
+ * Manages a global sequence counter, output index counter, and an accumulated
+ * {@link Response} snapshot. Every {@code emit*()} method appends a {@link ResponseEvent}
+ * to the internal list and returns {@code this} for chaining.
+ *
+ * Nested output-item scopes use the {@link Consumer} callback pattern so that
+ * builder lifecycles are lexically scoped and automatically finalized.
+ *
+ * Call {@link #subscribe(Consumer, Consumer, Runnable)} to receive events
+ * in real-time as they are produced — including text deltas from deeply nested builders.
+ * Events are delivered via a {@link SubmissionPublisher} from the JDK's
+ * {@link Flow} reactive-streams API.
+ *
+ *
Threading model
+ *
+ * This class is designed for a single-writer pattern: all {@code emit*()}
+ * and {@code addOutput*()} methods must be called from a single thread (or with external
+ * serialization). The {@link #subscribe(Consumer, Consumer, Runnable)} callbacks are
+ * invoked by the {@link SubmissionPublisher}'s executor. Internal synchronization ensures
+ * safe hand-off between the writer and subscriber.
+ *
+ *
Example usage (synchronous)
+ * {@code
+ * ResponseEventStream stream = ResponseEventStream.create(request, context)
+ * .emitCreated()
+ * .emitInProgress()
+ * .addOutputMessage(msg -> msg
+ * .emitAdded()
+ * .addTextPart(text -> text
+ * .emitAdded()
+ * .emitDelta("Hello!")
+ * .emitDone("Hello!"))
+ * .emitDone())
+ * .emitCompleted();
+ *
+ * List events = stream.getEvents();
+ * }
+ *
+ * Example usage (reactive streaming)
+ * {@code
+ * ResponseEventStream stream = ResponseEventStream.create(request, context);
+ * stream.subscribe(
+ * event -> System.out.println(event.eventName()),
+ * failure -> failure.printStackTrace(),
+ * () -> System.out.println("Done"));
+ *
+ * // Build on another thread — subscribers see events immediately.
+ * // awaitSubscription() blocks until subscribe() has been called,
+ * // preventing events from being emitted before a subscriber is ready.
+ * executor.submit(() -> {
+ * stream.awaitSubscription();
+ * stream.emitCreated()
+ * .emitInProgress()
+ * .addOutputMessage(msg -> msg
+ * .emitAdded()
+ * .addTextPart(text -> text
+ * .emitAdded()
+ * .emitDelta("Hello!")
+ * .emitDone("Hello!"))
+ * .emitDone())
+ * .emitCompleted();
+ * });
+ * }
+ */
+final class AgentServerResponseEventStream implements ResponseEventStream {
+
+ private final IdGenerator idGenerator;
+ private final String responseId;
+ // Accumulated events and output items.
+ private final CopyOnWriteArrayList events = new CopyOnWriteArrayList<>();
+ // Concurrent map because trackCompletedOutputItem() may be called from nested
+ // builders or forwardUpstream() while a subscriber is consuming events on a
+ // different thread (e.g., via the SubmissionPublisher executor).
+ private final Map outputItems = new java.util.concurrent.ConcurrentSkipListMap<>();
+ // JDK reactive publisher for push-based event delivery.
+ // Synchronous executor (Runnable::run) ensures events are delivered inline
+ // on the writer thread, matching the original Multi emitter semantics.
+ private final SubmissionPublisher publisher =
+ new SubmissionPublisher<>(Runnable::run, Flow.defaultBufferSize());
+ private final CountDownLatch subscriptionLatch = new CountDownLatch(1);
+ private final AtomicLong sequenceNumber = new AtomicLong();
+ private final AtomicLong outputIndex = new AtomicLong();
+ private final AtomicBoolean terminated = new AtomicBoolean();
+ // Mutable response builder – rebuilt into an immutable snapshot per event.
+ // The OpenAI SDK builder is mutable (setters return `this`), but we reassign
+ // defensively so the code also works if the builder were ever replaced with
+ // an immutable variant.
+ // THREADING: all reads/writes of responseBuilder MUST hold builderLock.
+ private Response.Builder responseBuilder;
+ private final Object builderLock = new Object();
+
+ // ── Construction ──────────────────────────────────────────
+
+ private AgentServerResponseEventStream(AgentServerCreateResponse request, ResponseContext context) {
+ Objects.requireNonNull(context, "context must not be null");
+ Objects.requireNonNull(request, "request must not be null");
+
+ this.idGenerator = new IdGenerator(IdGenerator.extractPartitionKey(context.getResponseId()));
+ this.responseId = context.getResponseId();
+
+ String conversationId = request.responseCreateParams().conversation()
+ .flatMap(conv -> {
+ if (conv.isId()) {
+ return Optional.of(conv.asId());
+ }
+ if (conv.isResponseConversationParam()) {
+ return Optional.of(conv.asResponseConversationParam().id());
+ }
+ return Optional.empty();
+ })
+ .orElse(null);
+
+ this.responseBuilder = Response.builder()
+ .id(context.getResponseId())
+ .createdAt(System.currentTimeMillis() / 1000.0)
+ .status(ResponseStatus.QUEUED)
+ .error(Optional.empty())
+ .incompleteDetails(Optional.empty())
+ .instructions(Optional.empty())
+ .metadata(Optional.empty())
+ .parallelToolCalls(false)
+ .temperature(Optional.empty())
+ .toolChoice(ToolChoiceOptions.AUTO)
+ .tools(List.of())
+ .topP(Optional.empty())
+ .output(List.of())
+ .previousResponseId(request.responseCreateParams().previousResponseId().orElse(null))
+ .background(request.responseCreateParams().background().orElse(null))
+ .putAdditionalProperty("agent_id", new JsonNull());
+
+ if (request.responseCreateParams().model().isPresent()) {
+ request.responseCreateParams().model().ifPresent(this.responseBuilder::model);
+ } else {
+ String modelName = FoundryEnvironment.AGENT_NAME != null
+ ? FoundryEnvironment.AGENT_NAME : "unknown-agent";
+ this.responseBuilder.model(modelName);
+ }
+
+ if (conversationId != null) {
+ this.responseBuilder = this.responseBuilder.conversation(
+ Response.Conversation.builder().id(conversationId).build());
+ }
+ }
+
+ /**
+ * Creates a new event stream from a request and context.
+ */
+ public static ResponseEventStream create(ResponseContext context, AgentServerCreateResponse request) {
+ return new AgentServerResponseEventStream(request, context);
+ }
+
+ // ── Results ───────────────────────────────────────────────
+
+ /**
+ * Resolves the SSE event name for a given {@link ResponseStreamEvent}.
+ * Returns {@code null} for unrecognized or lifecycle events.
+ */
+ private static String resolveEventName(ResponseStreamEvent event) {
+ if (event.isOutputItemAdded()) return "response.output_item.added";
+ if (event.isOutputItemDone()) return "response.output_item.done";
+ if (event.isOutputTextDelta()) return "response.output_text.delta";
+ if (event.isOutputTextDone()) return "response.output_text.done";
+ if (event.isContentPartAdded()) return "response.content_part.added";
+ if (event.isContentPartDone()) return "response.content_part.done";
+ if (event.isFunctionCallArgumentsDelta()) return "response.function_call_arguments.delta";
+ if (event.isFunctionCallArgumentsDone()) return "response.function_call_arguments.done";
+ // Add more as needed for reasoning, file search, etc.
+ return null;
+ }
+
+ /**
+ * Creates a default zero-usage object with all required fields populated.
+ * The OpenAI SDK requires {@code inputTokensDetails} and {@code outputTokensDetails}
+ * even when usage is not tracked.
+ */
+ private static ResponseUsage defaultUsage() {
+ return ResponseUsage.builder()
+ .inputTokens(0)
+ .outputTokens(0)
+ .totalTokens(0)
+ .inputTokensDetails(ResponseUsage.InputTokensDetails.builder()
+ .cachedTokens(0)
+ .build())
+ .outputTokensDetails(ResponseUsage.OutputTokensDetails.builder()
+ .reasoningTokens(0)
+ .build())
+ .build();
+ }
+
+ // ── Reactive Stream ───────────────────────────────────────
+
+ /**
+ * Returns an unmodifiable view of all events emitted so far.
+ */
+ @Override
+ public List getEvents() {
+ return Collections.unmodifiableList(events);
+ }
+
+ /**
+ * Returns a snapshot of the current {@link Response} being constructed.
+ */
+ @Override
+ public Response getResponse() {
+ synchronized (builderLock) {
+ return responseBuilder.build();
+ }
+ }
+
+ /**
+ * Stamps the resolved {@code agent_session_id} onto every snapshot
+ * produced by this stream from this point forward. No-op for null/empty input.
+ * Package-private — invoked by {@link AgentServerResponsesApi} once the
+ * session ID is resolved for the current request.
+ */
+ void setAgentSessionId(String sessionId) {
+ if (sessionId == null || sessionId.isEmpty()) {
+ return;
+ }
+ synchronized (builderLock) {
+ responseBuilder = responseBuilder.putAdditionalProperty(
+ "agent_session_id", com.openai.core.JsonValue.from(sessionId));
+ }
+ }
+
+ // ── Response Lifecycle Events ─────────────────────────────
+
+ /**
+ * Subscribes to this event stream with the given callbacks.
+ *
+ * Every event produced by any builder — including deeply nested text deltas —
+ * is pushed to the {@code onEvent} callback immediately. If events have already
+ * been emitted before subscription, they are replayed first.
+ *
+ * Terminal events ({@code emitCompleted}, {@code emitFailed}, {@code emitIncomplete})
+ * automatically invoke {@code onComplete}.
+ *
+ * This method is synchronized on the same monitor as {@link #addEvent} to
+ * guarantee that no events are lost between the replay loop and the
+ * {@link SubmissionPublisher} subscription.
+ *
+ * @param onEvent called for each {@link ResponseEvent} as it is produced
+ * @param onFailure called if the stream encounters an error
+ * @param onComplete called when the stream terminates normally
+ */
+ @Override
+ public synchronized void subscribe(Consumer onEvent, Consumer onFailure, Runnable onComplete) {
+ // Replay events already emitted before subscription.
+ for (ResponseEvent event : events) {
+ onEvent.accept(event);
+ }
+
+ // If the stream already terminated, signal completion immediately.
+ if (terminated.get()) {
+ subscriptionLatch.countDown();
+ onComplete.run();
+ return;
+ }
+
+ // Wire up a Flow.Subscriber that delegates to the provided callbacks.
+ // Because addEvent() is also synchronized on `this`, no submit() can
+ // happen between the replay above and the registration below.
+ publisher.subscribe(new Flow.Subscriber<>() {
+ @Override
+ public void onSubscribe(Flow.Subscription subscription) {
+ subscription.request(Long.MAX_VALUE);
+ }
+
+ @Override
+ public void onNext(ResponseEvent event) {
+ onEvent.accept(event);
+ }
+
+ @Override
+ public void onError(Throwable throwable) {
+ onFailure.accept(throwable);
+ }
+
+ @Override
+ public void onComplete() {
+ onComplete.run();
+ }
+ });
+
+ // Signal any threads waiting in awaitSubscription().
+ subscriptionLatch.countDown();
+ }
+
+ /**
+ * Blocks the calling thread until {@link #subscribe} has been called,
+ * ensuring that no events are emitted before a subscriber is ready.
+ * Times out after 30 seconds to avoid deadlocks.
+ *
+ * @throws InterruptedException if the thread is interrupted while waiting
+ */
+ @Override
+ public void awaitSubscription() throws InterruptedException {
+ if (!subscriptionLatch.await(30, TimeUnit.SECONDS)) {
+ throw new IllegalStateException(
+ "Timed out waiting for a subscriber to be registered. " +
+ "Ensure subscribe() is called within 30 seconds of stream creation.");
+ }
+ }
+
+ /**
+ * Emits a {@code response.queued} event. Sets status to {@link ResponseStatus#QUEUED}.
+ */
+ @Override
+ public ResponseEventStream emitQueued() {
+ synchronized (builderLock) {
+ responseBuilder = responseBuilder.status(ResponseStatus.QUEUED);
+ addEvent(new ResponseEvent("response.queued",
+ ResponseStreamEvent.ofQueued(new ResponseQueuedEvent.Builder()
+ .sequenceNumber(nextSequenceNumber())
+ .response(snapshot())
+ .build())));
+ }
+ return this;
+ }
+
+ /**
+ * Emits a {@code response.created} event with status {@link ResponseStatus#IN_PROGRESS}.
+ */
+ @Override
+ public ResponseEventStream emitCreated() {
+ return emitCreated(ResponseStatus.IN_PROGRESS);
+ }
+
+ /**
+ * Emits a {@code response.created} event with the given status.
+ */
+ @Override
+ public ResponseEventStream emitCreated(ResponseStatus status) {
+ synchronized (builderLock) {
+ responseBuilder = responseBuilder.status(status);
+ }
+ addEvent(new ResponseEvent("response.created",
+ ResponseStreamEvent.ofCreated(new ResponseCreatedEvent.Builder()
+ .sequenceNumber(nextSequenceNumber())
+ .response(snapshot())
+ .build())));
+ return this;
+ }
+
+ /**
+ * Emits a {@code response.in_progress} event. Sets status to {@link ResponseStatus#IN_PROGRESS}.
+ */
+ @Override
+ public ResponseEventStream emitInProgress() {
+ synchronized (builderLock) {
+ responseBuilder = responseBuilder.status(ResponseStatus.IN_PROGRESS);
+ }
+ addEvent(new ResponseEvent("response.in_progress",
+ ResponseStreamEvent.ofInProgress(new ResponseInProgressEvent.Builder()
+ .sequenceNumber(nextSequenceNumber())
+ .response(snapshot())
+ .build())));
+ return this;
+ }
+
+ /**
+ * Emits a {@code response.completed} event with no usage data.
+ */
+ @Override
+ public ResponseEventStream emitCompleted() {
+ return emitCompleted(null);
+ }
+
+ /**
+ * Emits a {@code response.completed} event with optional usage data.
+ *
+ * @throws IllegalStateException if a terminal event has already been emitted
+ */
+ @Override
+ public ResponseEventStream emitCompleted(ResponseUsage usage) {
+ guardTerminal();
+ // Default to zero-usage if none provided — clients may require the field.
+ ResponseUsage effectiveUsage = usage != null ? usage : defaultUsage();
+ synchronized (builderLock) {
+ responseBuilder = responseBuilder
+ .status(ResponseStatus.COMPLETED)
+ .completedAt(System.currentTimeMillis() / 1000.0)
+ .output(collectOutputItems())
+ .usage(effectiveUsage);
+ }
+ addEvent(new ResponseEvent("response.completed",
+ ResponseStreamEvent.ofCompleted(new ResponseCompletedEvent.Builder()
+ .sequenceNumber(nextSequenceNumber())
+ .response(snapshot())
+ .build())));
+ completeMulti();
+ return this;
+ }
+
+ /**
+ * Emits a {@code response.failed} event with a server error.
+ */
+ @Override
+ public ResponseEventStream emitFailed() {
+ return emitFailed(ResponseError.Code.SERVER_ERROR, "An internal server error occurred.", null);
+ }
+
+ /**
+ * Emits a {@code response.failed} event with the given error.
+ */
+ @Override
+ public ResponseEventStream emitFailed(ResponseError.Code code, String message) {
+ return emitFailed(code, message, null);
+ }
+
+ /**
+ * Emits a {@code response.failed} event with the given error and optional usage data.
+ *
+ * @throws IllegalStateException if a terminal event has already been emitted
+ */
+ @Override
+ public ResponseEventStream emitFailed(ResponseError.Code code, String message, ResponseUsage usage) {
+ guardTerminal();
+ ResponseUsage effectiveUsage = usage != null ? usage : defaultUsage();
+ synchronized (builderLock) {
+ responseBuilder = responseBuilder
+ .status(ResponseStatus.FAILED)
+ .completedAt(System.currentTimeMillis() / 1000.0)
+ .error(ResponseError.builder().code(code).message(message).build())
+ .output(collectOutputItems())
+ .usage(effectiveUsage);
+ }
+ addEvent(new ResponseEvent("response.failed",
+ ResponseStreamEvent.ofFailed(new ResponseFailedEvent.Builder()
+ .sequenceNumber(nextSequenceNumber())
+ .response(snapshot())
+ .build())));
+ completeMulti();
+ return this;
+ }
+
+ /**
+ * Emits a {@code response.incomplete} event with no details.
+ */
+ @Override
+ public ResponseEventStream emitIncomplete() {
+ return emitIncomplete(null, null);
+ }
+
+ // ── Output Item Scope Factories (Consumer pattern) ────────
+
+ /**
+ * Emits a {@code response.incomplete} event with the given reason.
+ */
+ @Override
+ public ResponseEventStream emitIncomplete(Response.IncompleteDetails.Reason reason) {
+ return emitIncomplete(reason, null);
+ }
+
+ /**
+ * Emits a {@code response.incomplete} event with optional reason and usage.
+ *
+ * @throws IllegalStateException if a terminal event has already been emitted
+ */
+ @Override
+ public ResponseEventStream emitIncomplete(Response.IncompleteDetails.Reason reason, ResponseUsage usage) {
+ guardTerminal();
+ ResponseUsage effectiveUsage = usage != null ? usage : defaultUsage();
+ synchronized (builderLock) {
+ responseBuilder = responseBuilder
+ .status(ResponseStatus.INCOMPLETE)
+ .completedAt(System.currentTimeMillis() / 1000.0)
+ .output(collectOutputItems())
+ .usage(effectiveUsage);
+ }
+ if (reason != null) {
+ synchronized (builderLock) {
+ responseBuilder = responseBuilder.incompleteDetails(
+ Response.IncompleteDetails.builder().reason(reason).build());
+ }
+ }
+ addEvent(new ResponseEvent("response.incomplete",
+ ResponseStreamEvent.ofIncomplete(new ResponseIncompleteEvent.Builder()
+ .sequenceNumber(nextSequenceNumber())
+ .response(snapshot())
+ .build())));
+ completeMulti();
+ return this;
+ }
+
+ /**
+ * Adds a message output item. The consumer configures the message builder
+ * (emit added/done, add text parts, etc.) within a lexically scoped block.
+ */
+ @Override
+ public ResponseEventStream addOutputMessage(Consumer config) {
+ long idx = outputIndex.getAndIncrement();
+ String itemId = idGenerator.generateMessageItemId();
+ OutputMessageBuilder builder = new OutputMessageBuilder(this, idx, itemId);
+ config.accept(builder);
+ return this;
+ }
+
+ /**
+ * Adds a function call output item. The consumer configures the function call builder
+ * (emit added/done, emit argument deltas, etc.) within a lexically scoped block.
+ */
+ @Override
+ public ResponseEventStream addOutputFunctionCall(Consumer config) {
+ long idx = outputIndex.getAndIncrement();
+ String itemId = idGenerator.generateFunctionCallItemId();
+ config.accept(new OutputFunctionCallBuilder(this, idx, itemId));
+ return this;
+ }
+
+ /**
+ * Adds a reasoning output item.
+ */
+ @Override
+ public ResponseEventStream addOutputReasoningItem(Consumer> config) {
+ long idx = outputIndex.getAndIncrement();
+ String itemId = idGenerator.generateReasoningItemId();
+ config.accept(new OutputItemBuilder<>(this, idx, itemId));
+ return this;
+ }
+
+ /**
+ * Adds a file search call output item.
+ */
+ @Override
+ public ResponseEventStream addOutputFileSearchCall(Consumer> config) {
+ long idx = outputIndex.getAndIncrement();
+ String itemId = idGenerator.generateFileSearchCallItemId();
+ config.accept(new OutputItemBuilder<>(this, idx, itemId));
+ return this;
+ }
+
+ /**
+ * Adds a web search call output item.
+ */
+ @Override
+ public ResponseEventStream addOutputWebSearchCall(Consumer> config) {
+ long idx = outputIndex.getAndIncrement();
+ String itemId = idGenerator.generateWebSearchCallItemId();
+ config.accept(new OutputItemBuilder<>(this, idx, itemId));
+ return this;
+ }
+
+ /**
+ * Adds a code interpreter call output item.
+ */
+ @Override
+ public ResponseEventStream addOutputCodeInterpreterCall(
+ Consumer> config) {
+ long idx = outputIndex.getAndIncrement();
+ String itemId = idGenerator.generateCodeInterpreterCallItemId();
+ config.accept(new OutputItemBuilder<>(this, idx, itemId));
+ return this;
+ }
+
+ /**
+ * Adds an image generation call output item.
+ */
+ @Override
+ public ResponseEventStream addOutputImageGenCall(
+ Consumer> config) {
+ long idx = outputIndex.getAndIncrement();
+ String itemId = idGenerator.generateImageGenCallItemId();
+ config.accept(new OutputItemBuilder<>(this, idx, itemId));
+ return this;
+ }
+
+ /**
+ * Adds an MCP tool call output item.
+ */
+ @Override
+ public ResponseEventStream addOutputMcpCall(Consumer> config) {
+ long idx = outputIndex.getAndIncrement();
+ String itemId = idGenerator.generateMcpCallItemId();
+ config.accept(new OutputItemBuilder<>(this, idx, itemId));
+ return this;
+ }
+
+ /**
+ * Adds an MCP list-tools output item.
+ */
+ @Override
+ public ResponseEventStream addOutputMcpListTools(
+ Consumer> config) {
+ long idx = outputIndex.getAndIncrement();
+ String itemId = idGenerator.generateMcpListToolsItemId();
+ config.accept(new OutputItemBuilder<>(this, idx, itemId));
+ return this;
+ }
+
+ /**
+ * Adds a custom tool call output item.
+ */
+ @Override
+ public ResponseEventStream addOutputCustomToolCall(Consumer> config) {
+ long idx = outputIndex.getAndIncrement();
+ String itemId = idGenerator.generateCustomToolCallItemId();
+ config.accept(new OutputItemBuilder<>(this, idx, itemId));
+ return this;
+ }
+
+ /**
+ * Adds a generic output item for types with no dedicated factory.
+ */
+ @Override
+ public ResponseEventStream addOutputItem(String itemId, Consumer> config) {
+ Objects.requireNonNull(itemId, "itemId must not be null");
+ long idx = outputIndex.getAndIncrement();
+ config.accept(new OutputItemBuilder<>(this, idx, itemId));
+ return this;
+ }
+
+ /**
+ * Appends a pre-built event directly. For advanced / interop scenarios.
+ */
+ @Override
+ public ResponseEventStream emit(ResponseEvent event) {
+ addEvent(event);
+ return this;
+ }
+
+ // ── Internal helpers ──────────────────────────────────────
+
+ /**
+ * Forwards an upstream OpenAI streaming response through this stream.
+ * All content events (output items, text deltas, function call arguments,
+ * reasoning, etc.) are forwarded directly. Upstream lifecycle events
+ * (created, in_progress, completed, queued) are skipped since this stream
+ * owns its own lifecycle.
+ *
+ * Throws {@link RuntimeException} if the upstream reports a failure event.
+ *
+ *
Example usage
+ * {@code
+ * stream.emitCreated().emitInProgress();
+ * try (var upstream = client.responses().createStreaming(params)) {
+ * stream.forwardUpstream(upstream.stream());
+ * }
+ * stream.emitCompleted();
+ * }
+ *
+ * @param upstreamEvents the stream of events from the upstream OpenAI client
+ * @return this stream for chaining
+ * @throws RuntimeException if the upstream reports a failure event
+ */
+ @Override
+ public ResponseEventStream forwardUpstream(java.util.stream.Stream upstreamEvents) {
+ upstreamEvents.forEach(event -> {
+ // Skip upstream lifecycle events — we own the response envelope.
+ if (event.isCreated() || event.isInProgress() || event.isCompleted() || event.isQueued()) {
+ return;
+ }
+
+ // Detect upstream failure.
+ if (event.isFailed()) {
+ throw new RuntimeException("Upstream request failed");
+ }
+
+ // Forward all content events (output_item.added, output_item.done,
+ // text deltas, function_call_arguments, content_part events, etc.)
+ // by determining the event name and re-emitting through our stream.
+ String eventName = resolveEventName(event);
+ if (eventName != null) {
+ // Track output items for the terminal completed event.
+ if (event.isOutputItemDone()) {
+ ResponseOutputItem item = event.asOutputItemDone().item();
+ long idx = outputIndex.getAndIncrement();
+ trackCompletedOutputItem(item, idx);
+ }
+ addEvent(new ResponseEvent(eventName, event));
+ }
+ });
+ return this;
+ }
+
+ public long nextSequenceNumber() {
+ return sequenceNumber.getAndIncrement();
+ }
+
+ public synchronized void addEvent(ResponseEvent event) {
+ events.add(event);
+ publisher.submit(event);
+ }
+
+ public void trackCompletedOutputItem(ResponseOutputItem item, long idx) {
+ outputItems.put(idx, item);
+ }
+
+ /**
+ * Returns a copy of the accumulated output items in index order.
+ */
+ private List collectOutputItems() {
+ return new ArrayList<>(outputItems.values());
+ }
+
+ private Response snapshot() {
+ synchronized (builderLock) {
+ return responseBuilder.build();
+ }
+ }
+
+ /**
+ * Atomically guards against calling a terminal method more than once.
+ *
+ * @throws IllegalStateException if a terminal event has already been emitted
+ */
+ private void guardTerminal() {
+ if (!terminated.compareAndSet(false, true)) {
+ throw new IllegalStateException(
+ "Stream has already been terminated. " +
+ "emitCompleted/emitFailed/emitIncomplete may only be called once.");
+ }
+ }
+
+ private void completeMulti() {
+ publisher.close();
+ }
+
+ // ══════════════════════════════════════════════════════════
+ // Scoped builders
+ // ══════════════════════════════════════════════════════════
+
+ /**
+ * Fluent builder for a generic output item. Returned by the various
+ * {@code addOutput*()} factory methods.
+ */
+ public static class OutputItemBuilder implements ResponseEventStream.OutputItemBuilder {
+ protected final ResponseEventStream stream;
+ protected final long outputIdx;
+ protected final String itemId;
+
+ OutputItemBuilder(ResponseEventStream stream, long outputIdx, String itemId) {
+ this.stream = stream;
+ this.outputIdx = outputIdx;
+ this.itemId = itemId;
+ }
+
+ static ResponseOutputItem toOutputItem(Object item) {
+ if (item instanceof ResponseOutputItem roi) return roi;
+ if (item instanceof ResponseOutputMessage msg) return ResponseOutputItem.ofMessage(msg);
+ if (item instanceof ResponseFunctionToolCall ftc) return ResponseOutputItem.ofFunctionCall(ftc);
+ if (item instanceof ResponseReasoningItem ri) return ResponseOutputItem.ofReasoning(ri);
+ if (item instanceof ResponseFileSearchToolCall fsc) return ResponseOutputItem.ofFileSearchCall(fsc);
+ if (item instanceof ResponseFunctionWebSearch ws) return ResponseOutputItem.ofWebSearchCall(ws);
+ if (item instanceof ResponseCodeInterpreterToolCall ci) return ResponseOutputItem.ofCodeInterpreterCall(ci);
+ if (item instanceof ResponseOutputItem.ImageGenerationCall ig)
+ return ResponseOutputItem.ofImageGenerationCall(ig);
+ if (item instanceof ResponseOutputItem.McpCall mc) return ResponseOutputItem.ofMcpCall(mc);
+ if (item instanceof ResponseOutputItem.McpListTools mlt) return ResponseOutputItem.ofMcpListTools(mlt);
+ if (item instanceof ResponseCustomToolCall ct) return ResponseOutputItem.ofCustomToolCall(ct);
+ throw new IllegalArgumentException("Unsupported output item type: " + item.getClass());
+ }
+
+ /**
+ * Emits a {@code response.output_item.added} event for this item.
+ */
+ public OutputItemBuilder emitAdded(T item) {
+ ResponseOutputItem outputItem = toOutputItem(item);
+ stream.addEvent(new ResponseEvent("response.output_item.added",
+ ResponseStreamEvent.ofOutputItemAdded(new ResponseOutputItemAddedEvent.Builder()
+ .sequenceNumber(stream.nextSequenceNumber())
+ .outputIndex(outputIdx)
+ .item(outputItem)
+ .build())));
+ return this;
+ }
+
+ /**
+ * Emits a {@code response.output_item.done} event for this item
+ * and tracks it in the parent stream's output list.
+ */
+ public OutputItemBuilder emitDone(T item) {
+ ResponseOutputItem outputItem = toOutputItem(item);
+ stream.trackCompletedOutputItem(outputItem, outputIdx);
+ stream.addEvent(new ResponseEvent("response.output_item.done",
+ ResponseStreamEvent.ofOutputItemDone(new ResponseOutputItemDoneEvent.Builder()
+ .sequenceNumber(stream.nextSequenceNumber())
+ .outputIndex(outputIdx)
+ .item(outputItem)
+ .build())));
+ return this;
+ }
+
+ /**
+ * Returns the auto-generated item ID for this output item.
+ */
+ public String getItemId() {
+ return itemId;
+ }
+ }
+
+ /**
+ * Fluent builder for a function call output item. Provides convenience methods
+ * for the common function call lifecycle: added, argument deltas, argument done,
+ * and item done — without requiring the caller to manage sequence numbers or
+ * construct raw event objects.
+ *
+ * Example usage
+ * {@code
+ * stream.addOutputFunctionCall(func -> func
+ * .emitAdded("get_weather", "call_123")
+ * .emitArgumentsDelta("{\"location\":")
+ * .emitArgumentsDelta("\"Seattle\"}")
+ * .emitArgumentsDone("get_weather", "{\"location\":\"Seattle\"}")
+ * .emitDone());
+ * }
+ */
+ public static class OutputFunctionCallBuilder implements ResponseEventStream.OutputFunctionCallBuilder {
+ private final AgentServerResponseEventStream stream;
+ private final long outputIdx;
+ private final String itemId;
+ private final StringBuilder accumulatedArguments = new StringBuilder();
+ private String name;
+ private String callId;
+
+ OutputFunctionCallBuilder(AgentServerResponseEventStream stream, long outputIdx, String itemId) {
+ this.stream = stream;
+ this.outputIdx = outputIdx;
+ this.itemId = itemId;
+ }
+
+ /**
+ * Emits a {@code response.output_item.added} event with an in-progress function call.
+ *
+ * @param name the function name (e.g. "get_weather")
+ * @param callId the call ID for this function invocation
+ */
+ public OutputFunctionCallBuilder emitAdded(String name, String callId) {
+ this.name = name;
+ this.callId = callId;
+ ResponseFunctionToolCall call = ResponseFunctionToolCall.builder()
+ .id(itemId)
+ .callId(callId)
+ .name(name)
+ .arguments("")
+ .status(ResponseFunctionToolCall.Status.IN_PROGRESS)
+ .build();
+ stream.addEvent(new ResponseEvent("response.output_item.added",
+ ResponseStreamEvent.ofOutputItemAdded(new ResponseOutputItemAddedEvent.Builder()
+ .sequenceNumber(stream.nextSequenceNumber())
+ .outputIndex(outputIdx)
+ .item(ResponseOutputItem.ofFunctionCall(call))
+ .build())));
+ return this;
+ }
+
+ /**
+ * Emits a {@code response.function_call_arguments.delta} event and accumulates
+ * the arguments text.
+ *
+ * @param delta the argument text chunk
+ */
+ public OutputFunctionCallBuilder emitArgumentsDelta(String delta) {
+ accumulatedArguments.append(delta);
+ stream.addEvent(new ResponseEvent("response.function_call_arguments.delta",
+ ResponseStreamEvent.ofFunctionCallArgumentsDelta(
+ ResponseFunctionCallArgumentsDeltaEvent.builder()
+ .sequenceNumber(stream.nextSequenceNumber())
+ .itemId(itemId)
+ .outputIndex(outputIdx)
+ .delta(delta)
+ .build())));
+ return this;
+ }
+
+ /**
+ * Emits a {@code response.function_call_arguments.done} event with the final
+ * function name and complete arguments string.
+ *
+ * @param name the function name
+ * @param arguments the complete arguments JSON string
+ */
+ public OutputFunctionCallBuilder emitArgumentsDone(String name, String arguments) {
+ accumulatedArguments.setLength(0);
+ accumulatedArguments.append(arguments);
+ stream.addEvent(new ResponseEvent("response.function_call_arguments.done",
+ ResponseStreamEvent.ofFunctionCallArgumentsDone(
+ ResponseFunctionCallArgumentsDoneEvent.builder()
+ .sequenceNumber(stream.nextSequenceNumber())
+ .itemId(itemId)
+ .outputIndex(outputIdx)
+ .name(name)
+ .arguments(arguments)
+ .build())));
+ return this;
+ }
+
+ /**
+ * Emits a {@code response.output_item.done} event with the completed function call
+ * and tracks it in the parent stream's output list. Uses the accumulated arguments
+ * and the name/callId from {@link #emitAdded(String, String)}.
+ */
+ public OutputFunctionCallBuilder emitDone() {
+ ResponseFunctionToolCall completedCall = ResponseFunctionToolCall.builder()
+ .id(itemId)
+ .callId(callId)
+ .name(name)
+ .arguments(accumulatedArguments.toString())
+ .status(ResponseFunctionToolCall.Status.COMPLETED)
+ .build();
+ ResponseOutputItem outputItem = ResponseOutputItem.ofFunctionCall(completedCall);
+ stream.trackCompletedOutputItem(outputItem, outputIdx);
+ stream.addEvent(new ResponseEvent("response.output_item.done",
+ ResponseStreamEvent.ofOutputItemDone(new ResponseOutputItemDoneEvent.Builder()
+ .sequenceNumber(stream.nextSequenceNumber())
+ .outputIndex(outputIdx)
+ .item(outputItem)
+ .build())));
+ return this;
+ }
+
+ /**
+ * Returns the auto-generated item ID for this function call.
+ */
+ public String getItemId() {
+ return itemId;
+ }
+ }
+
+ /**
+ * Fluent builder for a message output item. Provides convenience methods
+ * for the common message lifecycle and lexically scoped text-part builders.
+ */
+ public static class OutputMessageBuilder implements ResponseEventStream.OutputMessageBuilder {
+ private final AgentServerResponseEventStream stream;
+ private final long outputIdx;
+ private final String itemId;
+ private final String responseId;
+ private final List contentParts = new ArrayList<>();
+
+ OutputMessageBuilder(AgentServerResponseEventStream stream, long outputIdx, String itemId) {
+ this.stream = stream;
+ this.outputIdx = outputIdx;
+ this.itemId = itemId;
+ this.responseId = stream.responseId;
+ }
+
+ /**
+ * Emits a {@code response.output_item.added} event with an in-progress message.
+ */
+ public OutputMessageBuilder emitAdded() {
+ ResponseOutputItem outputItem = ResponseOutputItem.ofMessage(
+ buildMessage(ResponseOutputMessage.Status.IN_PROGRESS));
+ stream.addEvent(new ResponseEvent("response.output_item.added",
+ ResponseStreamEvent.ofOutputItemAdded(new ResponseOutputItemAddedEvent.Builder()
+ .sequenceNumber(stream.nextSequenceNumber())
+ .outputIndex(outputIdx)
+ .item(outputItem)
+ .build())));
+ return this;
+ }
+
+ /**
+ * Adds a text content part. The consumer configures delta emissions within
+ * a lexically scoped block.
+ *
+ * When the consumer returns, the following events are automatically emitted
+ * if the consumer did not already emit them:
+ *
+ * - {@code response.output_text.done} — if not already emitted by
+ * {@link TextPartBuilder#emitDone(String)}
+ * - {@code response.content_part.done} — always emitted
+ *
+ */
+ public OutputMessageBuilder addTextPart(Consumer config) {
+ long contentIndex = contentParts.size();
+ TextPartBuilder textBuilder = new TextPartBuilder(stream, itemId, outputIdx, contentIndex);
+ config.accept(textBuilder);
+
+ String finalTextValue = textBuilder.accumulatedText.toString();
+
+ // Auto-emit output_text.done if the consumer didn't call emitDone
+ if (!textBuilder.doneEmitted) {
+ textBuilder.emitDone(finalTextValue);
+ }
+
+ // Always emit content_part.done
+ ResponseOutputText finalText = ResponseOutputText.builder()
+ .text(finalTextValue)
+ .annotations(List.of())
+ .logprobs(List.of())
+ .build();
+ contentParts.add(ResponseOutputMessage.Content.ofOutputText(finalText));
+
+ stream.addEvent(new ResponseEvent("response.content_part.done",
+ ResponseStreamEvent.ofContentPartDone(new ResponseContentPartDoneEvent.Builder()
+ .sequenceNumber(stream.nextSequenceNumber())
+ .itemId(itemId)
+ .outputIndex(outputIdx)
+ .contentIndex(contentIndex)
+ .part(finalText)
+ .build())));
+ return this;
+ }
+
+ /**
+ * Convenience method that emits a complete text message in one call.
+ * Equivalent to:
+ * {@code
+ * msg.emitAdded()
+ * .addTextPart(text -> text.emitAdded().emitDelta(content).emitDone(content))
+ * .emitDone();
+ * }
+ *
+ * @param content The full text content to emit as a single delta and done event.
+ * @return this builder for chaining.
+ */
+ public OutputMessageBuilder outputItemMessage(String content) {
+ return emitAdded()
+ .addTextPart(text -> text
+ .emitAdded()
+ .emitDelta(content)
+ .emitDone(content))
+ .emitDone();
+ }
+
+ /**
+ * Emits a {@code response.output_item.done} event with the completed message
+ * and tracks it in the parent stream's output list.
+ */
+ public OutputMessageBuilder emitDone() {
+ ResponseOutputMessage msg = buildMessage(ResponseOutputMessage.Status.COMPLETED);
+ ResponseOutputItem outputItem = ResponseOutputItem.ofMessage(msg);
+ stream.trackCompletedOutputItem(outputItem, outputIdx);
+ stream.addEvent(new ResponseEvent("response.output_item.done",
+ ResponseStreamEvent.ofOutputItemDone(new ResponseOutputItemDoneEvent.Builder()
+ .sequenceNumber(stream.nextSequenceNumber())
+ .outputIndex(outputIdx)
+ .item(outputItem)
+ .build())));
+ return this;
+ }
+
+ /**
+ * Returns the auto-generated item ID for this message.
+ */
+ public String getItemId() {
+ return itemId;
+ }
+
+ @Override
+ public OutputMessageBuilder streamChatCompletion(StreamResponse streamResponse) {
+ return emitAdded()
+ .addTextPart(text -> text.emitAdded().streamDeltas(streamResponse))
+ .emitDone();
+ }
+
+ private ResponseOutputMessage buildMessage(ResponseOutputMessage.Status status) {
+ // Build the created_by object matching Foundry platform expectations:
+ // {"agent": {"type": "agent_id", "name": "", "version": ""}, "response_id": "..."}
+ Map agentObj = new LinkedHashMap<>();
+ agentObj.put("type", "agent_id");
+ agentObj.put("name", "");
+ agentObj.put("version", "");
+ Map createdBy = new LinkedHashMap<>();
+ createdBy.put("agent", agentObj);
+ createdBy.put("response_id", responseId);
+
+ return ResponseOutputMessage.builder()
+ .id(itemId)
+ .content(new ArrayList<>(contentParts))
+ .status(status)
+ .putAdditionalProperty("created_by", com.openai.core.JsonValue.from(createdBy))
+ .build();
+ }
+ }
+
+ /**
+ * Fluent builder for a text content part within a message.
+ * Tracks accumulated delta text for the final {@code content_part.done} event
+ * (emitted automatically by the parent {@link OutputMessageBuilder}).
+ */
+ public static class TextPartBuilder implements ResponseEventStream.TextPartBuilder {
+ final StringBuilder accumulatedText = new StringBuilder();
+ private final AgentServerResponseEventStream stream;
+ private final String itemId;
+ private final long outputIdx;
+ private final long contentIndex;
+ boolean doneEmitted;
+
+ TextPartBuilder(AgentServerResponseEventStream stream, String itemId, long outputIdx, long contentIndex) {
+ this.stream = stream;
+ this.itemId = itemId;
+ this.outputIdx = outputIdx;
+ this.contentIndex = contentIndex;
+ }
+
+ /**
+ * Emits a {@code response.content_part.added} event with an empty text part.
+ */
+ public TextPartBuilder emitAdded() {
+ ResponseOutputText empty = ResponseOutputText.builder()
+ .text("")
+ .annotations(List.of())
+ .build();
+ stream.addEvent(new ResponseEvent("response.content_part.added",
+ ResponseStreamEvent.ofContentPartAdded(new ResponseContentPartAddedEvent.Builder()
+ .sequenceNumber(stream.nextSequenceNumber())
+ .itemId(itemId)
+ .outputIndex(outputIdx)
+ .contentIndex(contentIndex)
+ .part(empty)
+ .build())));
+ return this;
+ }
+
+ /**
+ * Emits a {@code response.output_text.delta} event and accumulates the text.
+ */
+ public TextPartBuilder emitDelta(String delta) {
+ accumulatedText.append(delta);
+ stream.addEvent(new ResponseEvent("response.output_text.delta",
+ ResponseStreamEvent.ofOutputTextDelta(new ResponseTextDeltaEvent.Builder()
+ .sequenceNumber(stream.nextSequenceNumber())
+ .itemId(itemId)
+ .outputIndex(outputIdx)
+ .contentIndex(contentIndex)
+ .delta(delta)
+ .logprobs(List.of())
+ .build())));
+ return this;
+ }
+
+ /**
+ * Emits a {@code response.output_text.done} event with the final text.
+ * Also updates the accumulated text to the provided value.
+ */
+ public TextPartBuilder emitDone(String text) {
+ accumulatedText.setLength(0);
+ accumulatedText.append(text);
+ doneEmitted = true;
+ stream.addEvent(new ResponseEvent("response.output_text.done",
+ ResponseStreamEvent.ofOutputTextDone(new ResponseTextDoneEvent.Builder()
+ .sequenceNumber(stream.nextSequenceNumber())
+ .itemId(itemId)
+ .outputIndex(outputIdx)
+ .contentIndex(contentIndex)
+ .text(text)
+ .logprobs(List.of())
+ .build())));
+ return this;
+ }
+
+ @Override
+ public TextPartBuilder streamDeltas(StreamResponse streamResponse) {
+ try (streamResponse) {
+ streamResponse.stream().forEach(chunk ->
+ chunk.choices().forEach(choice ->
+ choice.delta().content().ifPresent(delta -> {
+ if (!delta.isEmpty()) {
+ emitDelta(delta);
+ }
+ })
+ )
+ );
+ }
+ return this;
+ }
+ }
+}
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/AgentServerResponseItemList.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/AgentServerResponseItemList.java
new file mode 100644
index 000000000000..fea83b682fb9
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/AgentServerResponseItemList.java
@@ -0,0 +1,17 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import com.fasterxml.jackson.annotation.JsonUnwrapped;
+import com.openai.models.responses.inputitems.ResponseItemList;
+
+/**
+ * Wraps a {@link ResponseItemList} together with an optional {@link AgentReference}
+ * for the agent server protocol's list-input-items response.
+ *
+ * @param agent the agent reference, or {@code null} if not applicable
+ * @param responseItemList the paginated list of response items
+ */
+public record AgentServerResponseItemList(AgentReference agent, @JsonUnwrapped ResponseItemList responseItemList) {
+}
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/AgentServerResponsesApi.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/AgentServerResponsesApi.java
new file mode 100644
index 000000000000..cdc9a995be74
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/AgentServerResponsesApi.java
@@ -0,0 +1,981 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import com.microsoft.agentserver.api.implementation.FoundryStorageProvider;
+import com.microsoft.agentserver.api.implementation.IdGenerator;
+import com.microsoft.agentserver.api.implementation.InMemoryResponseProvider;
+import com.microsoft.agentserver.api.implementation.ItemConversion;
+import com.openai.models.responses.Response;
+import com.openai.models.responses.ResponseCreateParams;
+import com.openai.models.responses.ResponseItem;
+import com.openai.models.responses.ResponseOutputItem;
+import com.openai.models.responses.ResponseOutputMessage;
+import com.openai.models.responses.ResponseStatus;
+import com.openai.models.responses.ToolChoiceOptions;
+import com.openai.models.responses.inputitems.ResponseItemList;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+/**
+ * Default implementation of {@link ResponsesApi} for the agent server protocol.
+ *
+ * Orchestrates request handling by delegating to a {@link ResponseHandler} for response
+ * generation, and a {@link ResponsesProvider} for state persistence. Supports both
+ * synchronous and streaming response creation.
+ *
+ * In hosted environments ({@link FoundryEnvironment#IS_HOSTED}), uses
+ * {@link FoundryStorageProvider} for persistence; otherwise falls back to
+ * {@link InMemoryResponseProvider}.
+ *
+ * Threading model: This class is a synchronous façade over the
+ * asynchronous {@link ResponsesProvider}. Methods such as {@link #getResponse},
+ * {@link #deleteResponse}, and {@link #listInputItems} block the calling thread
+ * via {@link java.util.concurrent.CompletableFuture#join()} until the provider
+ * operation completes. Callers should be aware that these methods will block and
+ * should not be invoked from async pipelines or reactive threads without offloading.
+ */
+class AgentServerResponsesApi implements ResponsesApi, AutoCloseable {
+
+ private static final Logger LOGGER = LoggerFactory.getLogger(AgentServerResponsesApi.class);
+
+ private final ResponseHandler responseHandler;
+ private final ResponsesProvider provider;
+
+ /**
+ * Executor for background ({@code background=true}) response processing. Daemon
+ * threads so the JVM is not kept alive by in-flight background work.
+ */
+ private final ExecutorService backgroundExecutor = Executors.newCachedThreadPool(r -> {
+ Thread t = new Thread(r, "agentserver-background");
+ t.setDaemon(true);
+ return t;
+ });
+
+ /**
+ * Process-scoped registry of in-flight background executions.
+ * Used to coordinate cancellation with the
+ * background finalisation so cancellation always wins.
+ */
+ private final ExecutionTracker executionTracker = new ExecutionTracker();
+
+ /**
+ * In-memory buffer of SSE events for replay via {@code GET /responses/{id}?stream=true}.
+ *
+ */
+ private final EventReplayStore eventReplayStore = new EventReplayStore();
+
+ public AgentServerResponsesApi(ResponseHandler responseHandler, ResponsesProvider provider) {
+ this.responseHandler = responseHandler;
+ this.provider = provider;
+ }
+
+ /**
+ * Tracks active background executions by response ID so that cancel/finalise
+ * can coordinate.
+ */
+ static final class ExecutionTracker {
+ private final Map executions = new ConcurrentHashMap<>();
+
+ Execution register(String responseId, boolean background, boolean store) {
+ Execution execution = new Execution(background, store);
+ executions.put(responseId, execution);
+ return execution;
+ }
+
+ Execution get(String responseId) {
+ return executions.get(responseId);
+ }
+
+ void evict(String responseId) {
+ executions.remove(responseId);
+ }
+ }
+
+ /**
+ * Coordination state for a single in-flight execution. The mutable flags
+ * ({@code cancelRequested}, {@code finalized}) are guarded by the monitor of
+ * the {@code Execution} instance itself.
+ */
+ static final class Execution {
+ final boolean background;
+ final boolean store;
+ boolean cancelRequested;
+ boolean finalized;
+
+ Execution(boolean background, boolean store) {
+ this.background = background;
+ this.store = store;
+ }
+ }
+
+ private static String extractResponseIdFromMetadata(AgentServerCreateResponse createResponse) {
+ try {
+ return createResponse.responseCreateParams().metadata()
+ .map(meta -> {
+ com.openai.core.JsonValue val = meta._additionalProperties().get("response_id");
+ if (val == null) return null;
+ @SuppressWarnings("unchecked")
+ java.util.Optional str = val.asString();
+ return str.orElse(null);
+ })
+ .orElse(null);
+ } catch (Exception e) {
+ LOGGER.debug("Could not extract response_id from metadata", e);
+ return null;
+ }
+ }
+
+ private static String extractResponseItemId(ResponseItem item) {
+ return ItemConversion.extractItemId(item);
+ }
+
+ /**
+ * Resolves the response ID for a new create request, in priority order:
+ *
+ * - {@code x-agent-response-id} HTTP header.
+ * - {@code metadata.response_id} field on the request body (legacy override).
+ * - Freshly generated via {@link IdGenerator#generateResponseId()}.
+ *
+ */
+ private static String resolveResponseId(AgentServerCreateResponse createResponse, RequestMetadata metadata) {
+ if (metadata != null) {
+ String override = metadata.getResponseIdOverride();
+ if (override != null && !override.isEmpty()) {
+ return override;
+ }
+ }
+ String fromBody = extractResponseIdFromMetadata(createResponse);
+ if (fromBody != null) {
+ return fromBody;
+ }
+ return new IdGenerator(null).generateResponseId();
+ }
+
+ /**
+ * Auto-stamps the resolved {@code agent_session_id} onto a
+ * {@link Response} by adding it to the additional-properties map. Returns the
+ * original instance unchanged when {@code sessionId} is {@code null}/empty.
+ */
+ private static Response stampSessionId(Response resp, String sessionId) {
+ if (resp == null || sessionId == null || sessionId.isEmpty()) {
+ return resp;
+ }
+ return resp.toBuilder()
+ .putAdditionalProperty("agent_session_id", com.openai.core.JsonValue.from(sessionId))
+ .build();
+ }
+
+ /**
+ * Combines (response-ID resolution) and (session-ID stamping) and
+ * normalizes all child IDs (output message ids, conversation id) to share
+ * the resolved response's partition key. The Foundry storage backend routes
+ * an envelope to a single shard by partition key, so a mix of partitions in
+ * a single envelope causes the storage create to fail with HTTP 500.
+ */
+ private static Response normalizeIdsAndStamp(Response handlerResp, String responseId, String sessionId, AgentReference agentRef) {
+ Response.Builder rebuilt = handlerResp.toBuilder();
+ if (!responseId.equals(handlerResp.id())) {
+ rebuilt.id(responseId);
+ }
+
+ // Re-partition any output message item IDs whose partition doesn't already
+ // match the resolved response. The Foundry storage backend routes envelopes
+ // by partition key; mixed partitions in a single envelope are rejected.
+ // (Streaming already produces aligned IDs; this primarily fixes the sync
+ // path where ResponseBuilder generates a fresh partition.)
+ String partitionKey;
+ try {
+ partitionKey = IdGenerator.extractPartitionKey(responseId);
+ } catch (RuntimeException e) {
+ partitionKey = null;
+ }
+
+ if (partitionKey != null) {
+ IdGenerator idGen = new IdGenerator(partitionKey);
+ List normalizedOutput = new ArrayList<>();
+ for (ResponseOutputItem item : handlerResp.output()) {
+ if (item.isMessage()) {
+ ResponseOutputMessage msg = item.asMessage();
+ if (!sharesPartition(msg.id(), partitionKey)) {
+ normalizedOutput.add(ResponseOutputItem.ofMessage(
+ msg.toBuilder().id(idGen.generateMessageItemId()).build()));
+ continue;
+ }
+ }
+ normalizedOutput.add(item);
+ }
+ rebuilt.output(normalizedOutput);
+ }
+
+ if (sessionId != null && !sessionId.isEmpty()) {
+ rebuilt.putAdditionalProperty(
+ "agent_session_id", com.openai.core.JsonValue.from(sessionId));
+ }
+
+ // echo the request's agent_reference onto the response so the
+ // platform storage backend can correlate the persisted response with the
+ // originating agent. Stored as an additional property because the openai
+ // Response model has no first-class agent_reference field.
+ if (agentRef != null) {
+ com.fasterxml.jackson.databind.node.ObjectNode refNode = com.microsoft.agentserver.api.serialization.ObjectMapperFactory
+ .getObjectMapper().createObjectNode();
+ if (agentRef.type() != null) {
+ refNode.put("type", agentRef.type().toString().toLowerCase(java.util.Locale.ROOT));
+ }
+ if (agentRef.name() != null) {
+ refNode.put("name", agentRef.name());
+ }
+ if (agentRef.version() != null) {
+ refNode.put("version", agentRef.version());
+ }
+ if (agentRef.label() != null) {
+ refNode.put("label", agentRef.label());
+ }
+ rebuilt.putAdditionalProperty("agent_reference", com.openai.core.JsonValue.from(refNode));
+ }
+
+ return rebuilt.build();
+ }
+
+ private static boolean sharesPartition(String id, String partitionKey) {
+ if (id == null) {
+ return false;
+ }
+ try {
+ return partitionKey.equals(IdGenerator.extractPartitionKey(id));
+ } catch (RuntimeException e) {
+ return false;
+ }
+ }
+
+ /**
+ * Validates a response-ID path parameter before any lookup. Malformed
+ * IDs produce HTTP 400 ({@code "Malformed identifier."}) rather than 404.
+ *
+ * @param responseId the path parameter to validate
+ * @throws ApiException 400 if the ID is not a well-formed response ID
+ */
+ private static void validateResponseId(String responseId) throws ApiException {
+ if (!IdGenerator.isValidResponseId(responseId)) {
+ // param="responseId{}" so clients can echo the offending value.
+ String param = "responseId{" + (responseId == null ? "" : responseId) + "}";
+ throw new ApiException(400,
+ ApiError.invalidRequest("Malformed identifier.", ApiError.CODE_INVALID_PARAMETERS, param));
+ }
+ }
+
+ @Override
+ public CreateResponse createResponse(AgentServerCreateResponse createResponse) throws ApiException {
+ return createResponse(createResponse, RequestMetadata.EMPTY);
+ }
+
+ @Override
+ public CreateResponse createResponse(AgentServerCreateResponse createResponse, RequestMetadata metadata) throws ApiException {
+ LOGGER.debug("createResponse called");
+
+ ResponseCreateParams.Body params = createResponse.responseCreateParams();
+ boolean background = params.background().orElse(false);
+ boolean store = params.store().orElse(true);
+
+ // background=true requires store=true.
+ if (background && !store) {
+ throw new ApiException(400, ApiError.invalidRequest("The 'background' parameter requires 'store' to be true.", ApiError.CODE_UNSUPPORTED_PARAMETER, "background"));
+ }
+
+ String responseId = resolveResponseId(createResponse, metadata);
+ // resolve the session ID once for this request; stamped on every
+ // Response object that leaves the API.
+ String sessionId = SessionIdResolver.resolve(createResponse, FoundryEnvironment.SESSION_ID);
+
+ ResponseContext context = buildContext(responseId, sessionId, createResponse, metadata);
+
+ // : emit the spec-required invoke_agent {model} span around handler
+ // execution. The span scopes everything the handler does so per-tool /
+ // per-LLM child spans (when emitted) attach to it.
+ io.opentelemetry.api.trace.Span span = Observability.startInvokeAgentSpan(
+ extractModelName(params),
+ responseId,
+ extractConversationId(params),
+ createResponse.agent() != null ? createResponse.agent().name() : null,
+ createResponse.agent() != null ? createResponse.agent().version() : null,
+ false);
+ try (io.opentelemetry.context.Scope ignored = span.makeCurrent()) {
+ if (background) {
+ CreateResponse bg = createBackgroundResponse(responseId, sessionId, context, createResponse);
+ return bg;
+ }
+
+ CreateResponse response;
+ try {
+ response = responseHandler.createResponse(context, createResponse);
+ } catch (RuntimeException e) {
+ String code = e.getClass().getSimpleName();
+ String msg = e.getMessage();
+ if (e.getCause() instanceof ApiException ae) {
+ code = ae.getError() != null ? ae.getError().code() : code;
+ msg = ae.getMessage();
+ }
+ Observability.recordInvokeAgentError(span, code, msg, e);
+ throw e;
+ }
+
+ // ensure the resolved response ID (which may have come from the
+ // x-agent-response-id header or `metadata.response_id`) is the one that
+ // both the client sees and storage uses — even when handlers build their
+ // own ID internally via ResponseBuilder. Also stamp the session ID,
+ // and re-partition child IDs (msg_, conv_) to match the resolved response's
+ // partition key (required by Foundry storage so the envelope routes to a
+ // single shard).
+ Response handlerResp = response.response();
+ if (handlerResp != null) {
+ handlerResp = normalizeIdsAndStamp(handlerResp, responseId, sessionId, createResponse.agent());
+ response = new CreateResponse(response.agent(), handlerResp);
+ }
+
+ persistResponse(context, response);
+
+ return response;
+ } finally {
+ span.end();
+ }
+ }
+
+ /**
+ * Handles {@code background=true}, non-streaming creation (matrix C3 / Rules
+ * ). Persists an initial {@code in_progress} snapshot so the
+ * response is immediately retrievable via GET, returns that snapshot to the
+ * caller right away, and processes the handler asynchronously, persisting the
+ * terminal result when done. Cancellation always wins.
+ */
+ private CreateResponse createBackgroundResponse(
+ String responseId, String sessionId, ResponseContext context, AgentServerCreateResponse createResponse) {
+
+ // Phase 1: persist the in_progress snapshot (with input items) so GET works
+ // while processing runs in the background. stamp the resolved session ID.
+ Response initial = stampSessionId(
+ buildInitialResponse(responseId, createResponse, ResponseStatus.IN_PROGRESS),
+ sessionId);
+ persistStreamingResponse(context, initial);
+
+ Execution execution = executionTracker.register(responseId, true, true);
+ final String finalResponseId = responseId;
+ final String finalSessionId = sessionId;
+
+ backgroundExecutor.submit(() -> {
+ try {
+ CreateResponse result = responseHandler.createResponse(context, createResponse);
+ // Re-stamp the terminal response with the response ID we already handed
+ // to the client (Phase 1), the background flag, and the session ID, so
+ // GET on that ID observes a coherent completed background response.
+ Response terminal = result.response();
+ if (terminal != null) {
+ Response.Builder rebuilt = terminal.toBuilder().background(true);
+ if (!finalResponseId.equals(terminal.id())) {
+ rebuilt.id(finalResponseId);
+ }
+ rebuilt.putAdditionalProperty(
+ "agent_session_id", com.openai.core.JsonValue.from(finalSessionId));
+ terminal = rebuilt.build();
+ }
+ final Response finalTerminal = terminal;
+ synchronized (execution) {
+ if (!execution.cancelRequested && !execution.finalized && finalTerminal != null) {
+ persistStreamingResponse(context, finalTerminal);
+ execution.finalized = true;
+ }
+ }
+ } catch (Exception e) {
+ LOGGER.error("Background response {} processing failed", finalResponseId, e);
+ synchronized (execution) {
+ if (!execution.cancelRequested && !execution.finalized) {
+ Response failed = stampSessionId(
+ buildInitialResponse(finalResponseId, createResponse, ResponseStatus.FAILED),
+ finalSessionId);
+ persistStreamingResponse(context, failed);
+ execution.finalized = true;
+ }
+ }
+ } finally {
+ executionTracker.evict(finalResponseId);
+ }
+ });
+
+ // return immediately with the in_progress snapshot.
+ return new CreateResponse(null, initial);
+ }
+
+ /**
+ * Builds a minimal {@link Response} snapshot for a background response in the
+ * given lifecycle {@code status} (used for the initial {@code in_progress}
+ * persistence and for failure fallback).
+ */
+ private Response buildInitialResponse(
+ String responseId, AgentServerCreateResponse createResponse, ResponseStatus status) {
+
+ ResponseCreateParams.Body params = createResponse.responseCreateParams();
+
+ String conversationId = params.conversation()
+ .flatMap(conv -> {
+ if (conv.isId()) {
+ return Optional.of(conv.asId());
+ }
+ if (conv.isResponseConversationParam()) {
+ return Optional.of(conv.asResponseConversationParam().id());
+ }
+ return Optional.empty();
+ })
+ .orElse(null);
+
+ Response.Builder builder = Response.builder()
+ .id(responseId)
+ .createdAt(System.currentTimeMillis() / 1000.0)
+ .status(status)
+ .background(true)
+ .output(List.of())
+ .error(Optional.empty())
+ .incompleteDetails(Optional.empty())
+ .instructions(Optional.empty())
+ .metadata(Optional.empty())
+ .parallelToolCalls(false)
+ .temperature(Optional.empty())
+ .toolChoice(ToolChoiceOptions.AUTO)
+ .tools(List.of())
+ .topP(Optional.empty())
+ .previousResponseId(params.previousResponseId().orElse(null));
+
+ if (params.model().isPresent()) {
+ params.model().ifPresent(builder::model);
+ } else {
+ builder.model(FoundryEnvironment.AGENT_NAME != null ? FoundryEnvironment.AGENT_NAME : "unknown-agent");
+ }
+
+ if (conversationId != null) {
+ builder.conversation(Response.Conversation.builder().id(conversationId).build());
+ }
+
+ return builder.build();
+ }
+
+ @Override
+ public ResponseEventStream createStreamingResponse(AgentServerCreateResponse createResponse) throws ApiException {
+ return createStreamingResponse(createResponse, RequestMetadata.EMPTY);
+ }
+
+ @Override
+ public ResponseEventStream createStreamingResponse(AgentServerCreateResponse createResponse, RequestMetadata metadata) throws ApiException {
+ LOGGER.debug("createStreamingResponse called");
+
+ ResponseCreateParams.Body params = createResponse.responseCreateParams();
+ boolean background = params.background().orElse(false);
+ boolean store = params.store().orElse(true);
+
+ // background=true requires store=true (matrix C8).
+ if (background && !store) {
+ throw new ApiException(400, ApiError.invalidRequest("The 'background' parameter requires 'store' to be true.", ApiError.CODE_UNSUPPORTED_PARAMETER, "background"));
+ }
+
+ String responseId = resolveResponseId(createResponse, metadata);
+ // resolve the session ID once for this request.
+ String sessionId = SessionIdResolver.resolve(createResponse, FoundryEnvironment.SESSION_ID);
+
+ ResponseContext context = buildContext(responseId, sessionId, createResponse, metadata);
+
+ // : emit the spec-required invoke_agent {model} span. For streaming the
+ // span lives until the stream terminates (completion or failure), so the
+ // handler's tool/LLM child spans (when emitted) attach to it.
+ io.opentelemetry.api.trace.Span invokeSpan = Observability.startInvokeAgentSpan(
+ extractModelName(params),
+ responseId,
+ extractConversationId(params),
+ createResponse.agent() != null ? createResponse.agent().name() : null,
+ createResponse.agent() != null ? createResponse.agent().version() : null,
+ true);
+ ResponseEventStream stream;
+ try (io.opentelemetry.context.Scope ignored = invokeSpan.makeCurrent()) {
+ stream = responseHandler.createAsync(context, createResponse);
+ } catch (RuntimeException e) {
+ Observability.recordInvokeAgentError(invokeSpan,
+ e.getClass().getSimpleName(), e.getMessage(), e);
+ invokeSpan.end();
+ throw e;
+ }
+
+ // stamp the resolved session ID on every snapshot the stream produces.
+ if (stream instanceof AgentServerResponseEventStream impl) {
+ impl.setAgentSessionId(sessionId);
+ }
+
+ // C4 (background+stream): persist an initial in_progress snapshot so GET
+ // works immediately while the response streams in the background.
+ if (background) {
+ Response initial = stampSessionId(
+ buildInitialResponse(responseId, createResponse, ResponseStatus.IN_PROGRESS),
+ sessionId);
+ persistStreamingResponse(context, initial);
+ }
+
+ // For stored responses, init the replay buffer so a mid-stream replay
+ // request sees `hasBuffer()==true` (avoiding a false "not stream=true"
+ // rejection) and gets whatever has been emitted so far.
+ if (store) {
+ eventReplayStore.initBuffer(responseId);
+ // Capture any events the handler emitted synchronously before we wired
+ // up the subscriber below.
+ for (ResponseEvent existing : stream.getEvents()) {
+ eventReplayStore.append(responseId, existing);
+ }
+ }
+
+ // Register the in-flight execution so cancel/disconnect can coordinate with
+ // the terminal persistence. Background streams are tagged as background so
+ // signalClientDisconnected is a no-op for them; explicit cancel
+ // remains supported. Non-background streams enable.
+ final Execution execution = executionTracker.register(responseId, background, store);
+
+ final String finalResponseId = responseId;
+ final boolean storeEnabled = store;
+ final boolean isBackground = background;
+ // Track the count of events we already appended above so we don't
+ // double-buffer those when the subscribe callback fires.
+ final int alreadyBuffered = store ? stream.getEvents().size() : 0;
+ final java.util.concurrent.atomic.AtomicInteger seenCount =
+ new java.util.concurrent.atomic.AtomicInteger(0);
+ stream.subscribe(
+ event -> {
+ // Live mid-stream buffering: append each new event
+ // so a concurrent replay request observes it. Skip the prefix the
+ // synchronous handler already emitted before subscribe attached.
+ if (storeEnabled && seenCount.getAndIncrement() >= alreadyBuffered) {
+ eventReplayStore.append(finalResponseId, event);
+ }
+ },
+ failure -> {
+ LOGGER.error("Stream failed for response {}", finalResponseId, failure);
+ Observability.recordInvokeAgentError(invokeSpan,
+ failure.getClass().getSimpleName(), failure.getMessage(), failure);
+ invokeSpan.end();
+ },
+ () -> {
+ LOGGER.debug("Stream completed for response {}", finalResponseId);
+ try {
+ synchronized (execution) {
+ if (execution.cancelRequested || execution.finalized) {
+ // Cancellation won the race; do not overwrite
+ // the cancelled snapshot with the natural terminal state.
+ return;
+ }
+ Response resp = stream.getResponse();
+ if (resp != null) {
+ if (isBackground) {
+ // C4: re-stamp background=true so GET on the terminal
+ // observes a coherent background response (mirroring C3).
+ resp = resp.toBuilder().background(true).build();
+ }
+ // Match the sync path: normalize child IDs to the resolved
+ // response's partition, stamp agent_reference and
+ // agent_session_id. Without these the storage POST
+ // fails (envelope partition mismatch, missing agent_reference).
+ resp = normalizeIdsAndStamp(resp, finalResponseId, sessionId, createResponse.agent());
+ persistStreamingResponse(context, resp);
+ }
+ execution.finalized = true;
+ }
+ } catch (Exception e) {
+ LOGGER.error("Failed to persist streaming response", e);
+ } finally {
+ executionTracker.evict(finalResponseId);
+ invokeSpan.end();
+ }
+ }
+ );
+
+ return stream;
+ }
+
+ private static String extractModelName(ResponseCreateParams.Body params) {
+ try {
+ if (params.model().isPresent()) {
+ var model = params.model().get();
+ if (model._json().isPresent() && model._json().get().asString().isPresent()) {
+ return model._json().get().asString().get().toString();
+ }
+ }
+ } catch (Exception ignored) {
+ // fall through
+ }
+ return null;
+ }
+
+ private static String extractConversationId(ResponseCreateParams.Body params) {
+ try {
+ return params.conversation()
+ .flatMap(c -> c.isId() ? java.util.Optional.of(c.asId()) : java.util.Optional.empty())
+ .orElse(null);
+ } catch (Exception ignored) {
+ return null;
+ }
+ }
+
+ @Override
+ public com.openai.models.responses.Response getResponse(String responseId, List include) throws ApiException {
+ return getResponse(responseId, include, RequestMetadata.EMPTY);
+ }
+
+ @Override
+ public com.openai.models.responses.Response getResponse(String responseId, List include, RequestMetadata metadata) throws ApiException {
+ LOGGER.debug("getResponse called for responseId={}", responseId);
+ validateResponseId(responseId);
+ com.openai.models.responses.Response resp = provider.getResponseAsync(responseId, metadata.getIsolation())
+ .join()
+ .orElse(null);
+
+ if (resp == null) {
+ throw new ApiException(404, ApiError.invalidRequest(responseId + " not found"));
+ }
+
+ return resp;
+ }
+
+ @Override
+ public ResponseStreamReplay replayResponseStream(String responseId, Integer startingAfter) throws ApiException {
+ LOGGER.debug("replayResponseStream called for responseId={}, startingAfter={}", responseId, startingAfter);
+ validateResponseId(responseId);
+
+ // Not found / store=false → 404.
+ com.openai.models.responses.Response resp = provider.getResponseAsync(responseId)
+ .join()
+ .orElse(null);
+ if (resp == null) {
+ throw new ApiException(404, ApiError.invalidRequest(responseId + " not found"));
+ }
+
+ // SSE replay requires background=true (checked before stream).
+ if (!resp.background().orElse(false)) {
+ throw new ApiException(400, ApiError.invalidRequest(
+ "This response cannot be streamed because it was not created with background=true.",
+ ApiError.CODE_INVALID_REQUEST, "stream"));
+ }
+
+ // SSE replay requires stream=true at creation. The presence of a replay
+ // buffer indicates the response was created streaming.
+ if (!eventReplayStore.hasBuffer(responseId)) {
+ throw new ApiException(400, ApiError.invalidRequest(
+ "This response cannot be streamed because it was not created with stream=true.",
+ ApiError.CODE_INVALID_REQUEST, "stream"));
+ }
+
+ List events = eventReplayStore.replay(responseId, startingAfter)
+ .orElseGet(List::of);
+ return new ResponseStreamReplay(events);
+ }
+
+ @Override
+ public com.openai.models.responses.Response cancelResponse(String responseId) throws ApiException {
+ LOGGER.debug("cancelResponse called for responseId={}", responseId);
+ validateResponseId(responseId);
+
+ com.openai.models.responses.Response resp = provider.getResponseAsync(responseId)
+ .join()
+ .orElse(null);
+
+ // (not found) → 404. Non-background in-flight responses are also not findable.
+ if (resp == null) {
+ throw new ApiException(404, ApiError.invalidRequest(responseId + " not found"));
+ }
+
+ // the background check happens first, regardless of status.
+ boolean background = resp.background().orElse(false);
+ if (!background) {
+ throw new ApiException(400, ApiError.invalidRequest("Cannot cancel a synchronous response."));
+ }
+
+ com.openai.models.responses.ResponseStatus status = resp.status().orElse(null);
+
+ // cancelling an already-cancelled response is idempotent.
+ if (com.openai.models.responses.ResponseStatus.CANCELLED.equals(status)) {
+ return resp;
+ }
+
+ // terminal states cannot be cancelled.
+ if (com.openai.models.responses.ResponseStatus.COMPLETED.equals(status)) {
+ throw new ApiException(400, ApiError.invalidRequest("Cannot cancel a completed response."));
+ }
+ if (com.openai.models.responses.ResponseStatus.FAILED.equals(status)) {
+ throw new ApiException(400, ApiError.invalidRequest("Cannot cancel a failed response."));
+ }
+ if (com.openai.models.responses.ResponseStatus.INCOMPLETE.equals(status)) {
+ throw new ApiException(400, ApiError.invalidRequest("Cannot cancel a response in terminal state."));
+ }
+
+ // queued or in_progress → wind down to cancelled with output cleared.
+ com.openai.models.responses.Response cancelled = resp.toBuilder()
+ .status(com.openai.models.responses.ResponseStatus.CANCELLED)
+ .output(Collections.emptyList())
+ .build();
+
+ // Coordinate with any in-flight background execution so the background
+ // finaliser does not overwrite the cancelled state.
+ Execution execution = executionTracker.get(responseId);
+ if (execution != null) {
+ synchronized (execution) {
+ execution.cancelRequested = true;
+ provider.saveResponseAsync(responseId, cancelled, null, null).join();
+ }
+ } else {
+ provider.saveResponseAsync(responseId, cancelled, null, null).join();
+ }
+ LOGGER.debug("Response {} cancelled (output cleared)", responseId);
+ return cancelled;
+ }
+
+ @Override
+ public void signalClientDisconnected(String responseId) {
+ // only non-background responses are affected by client disconnect.
+ // Background responses outlive the connection — no-op there.
+ Execution execution = executionTracker.get(responseId);
+ if (execution == null || execution.background) {
+ return;
+ }
+ synchronized (execution) {
+ if (execution.cancelRequested || execution.finalized) {
+ return;
+ }
+ execution.cancelRequested = true;
+ // Persist the cancelled snapshot only when store=true; per, store=false
+ // disconnects produce no retrievable response (GET → 404).
+ if (execution.store) {
+ try {
+ com.openai.models.responses.Response existing =
+ provider.getResponseAsync(responseId).join().orElse(null);
+ com.openai.models.responses.Response.Builder builder = existing != null
+ ? existing.toBuilder()
+ : com.openai.models.responses.Response.builder()
+ .id(responseId)
+ .createdAt(System.currentTimeMillis() / 1000.0)
+ .model("")
+ .parallelToolCalls(false)
+ .tools(java.util.List.of())
+ .error(java.util.Optional.empty())
+ .incompleteDetails(java.util.Optional.empty())
+ .instructions(java.util.Optional.empty())
+ .metadata(java.util.Optional.empty())
+ .temperature(java.util.Optional.empty())
+ .topP(java.util.Optional.empty())
+ .toolChoice(com.openai.models.responses.ToolChoiceOptions.AUTO);
+ com.openai.models.responses.Response cancelled = builder
+ .status(com.openai.models.responses.ResponseStatus.CANCELLED)
+ .output(java.util.Collections.emptyList())
+ .build();
+ provider.saveResponseAsync(responseId, cancelled, null, null).join();
+ } catch (Exception e) {
+ LOGGER.warn("Failed to persist cancelled-on-disconnect snapshot for {}", responseId, e);
+ }
+ }
+ LOGGER.debug("Response {} cancelled on client disconnect", responseId);
+ }
+ }
+
+ // ── Private helpers ─────────────────────────────────────────
+
+ private ResponseContext buildContext(String responseId, String sessionId, AgentServerCreateResponse createResponse, RequestMetadata metadata) {
+ return ResponseContext.builder()
+ .responseId(responseId)
+ .provider(provider)
+ .request(createResponse.responseCreateParams())
+ .isolation(metadata.getIsolation())
+ .clientHeaders(metadata.getClientHeaders())
+ .queryParameters(metadata.getQueryParameters())
+ .requestId(metadata.getRequestId())
+ .sessionId(sessionId)
+ .build();
+ }
+
+ @Override
+ public void deleteResponse(String responseId) throws ApiException {
+ LOGGER.debug("deleteResponse called for responseId={}", responseId);
+ validateResponseId(responseId);
+ provider.deleteResponseAsync(responseId).join();
+ // Best-effort removal of any buffered SSE events so replay is no longer possible.
+ eventReplayStore.delete(responseId);
+ }
+
+ @Override
+ public AgentServerResponseItemList listInputItems(String responseId, Integer limit, String order, String after, String before, List include) throws ApiException {
+ LOGGER.debug("listInputItems called for responseId={}", responseId);
+ validateResponseId(responseId);
+
+ // Verify the response exists
+ com.openai.models.responses.Response resp = provider.getResponseAsync(responseId)
+ .join()
+ .orElse(null);
+
+ if (resp == null) {
+ throw new ApiException(404, ApiError.invalidRequest(responseId + " not found"));
+ }
+
+ // Retrieve the stored input items (not output items)
+ List allItems = provider.getInputItemsForResponseAsync(responseId)
+ .join();
+
+ int effectiveLimit = (limit != null) ? limit : 20;
+ boolean descending = "desc".equalsIgnoreCase(order);
+
+
+ // Apply cursor-based pagination. `after` slices off everything up to and including
+ // that item; `before` slices off everything from that item onward; both combine
+ // as an exclusive range. Items always operate on the underlying stored order
+ // (i.e. cursor semantics are positional and order-independent, per ).
+ int fromIdx = 0;
+ int toIdx = allItems.size();
+ if (after != null && !after.isEmpty()) {
+ for (int i = 0; i < allItems.size(); i++) {
+ if (after.equals(extractResponseItemId(allItems.get(i)))) {
+ fromIdx = Math.max(fromIdx, i + 1);
+ break;
+ }
+ }
+ }
+ if (before != null && !before.isEmpty()) {
+ for (int i = 0; i < allItems.size(); i++) {
+ if (before.equals(extractResponseItemId(allItems.get(i)))) {
+ toIdx = Math.min(toIdx, i);
+ break;
+ }
+ }
+ }
+ List windowed = fromIdx < toIdx
+ ? allItems.subList(fromIdx, toIdx)
+ : List.of();
+
+ // Apply ordering
+ List ordered;
+ if (descending) {
+ ordered = new ArrayList<>(windowed);
+ Collections.reverse(ordered);
+ } else {
+ ordered = windowed;
+ }
+
+ // Apply limit
+ List page = ordered.size() > effectiveLimit
+ ? ordered.subList(0, effectiveLimit)
+ : ordered;
+
+ boolean hasMore = ordered.size() > effectiveLimit;
+ String firstId = page.isEmpty() ? null : extractResponseItemId(page.get(0));
+ String lastId = page.isEmpty() ? null : extractResponseItemId(page.get(page.size() - 1));
+
+ ResponseItemList itemList = ResponseItemList.builder()
+ .data(page)
+ .firstId(firstId != null ? firstId : "")
+ .lastId(lastId != null ? lastId : "")
+ .hasMore(hasMore)
+ .build();
+
+ return new AgentServerResponseItemList(null, itemList);
+ }
+
+ private void persistResponse(ResponseContext context, CreateResponse response) {
+ if (response.response() != null) {
+ com.openai.models.responses.Response resp = response.response();
+ persistStreamingResponse(context, resp);
+ }
+ }
+
+ private void persistStreamingResponse(ResponseContext context, com.openai.models.responses.Response resp) {
+ String previousResponseId = resp.previousResponseId().orElse(null);
+ String conversationId = resp.conversation()
+ .map(com.openai.models.responses.Response.Conversation::id)
+ .orElse(null);
+
+ // Build role-preserving input_items directly from the raw request body.
+ // The context.getInputItemsAsync() path returns ResponseOutputItems which
+ // are hardcoded to role=assistant — wrong for stored conversation history.
+ List inputItems = Collections.emptyList();
+ try {
+ ResponseCreateParams.Body body = context instanceof AgentServerResponseContext c
+ ? c.getRequestBody() : null;
+ if (body != null && body.input().isPresent()) {
+ ResponseCreateParams.Input in = body.input().get();
+ if (in.isResponse()) {
+ IdGenerator idGen = new IdGenerator(IdGenerator.extractPartitionKey(resp.id()));
+ List items = new ArrayList<>();
+ for (com.openai.models.responses.ResponseInputItem raw : in.asResponse()) {
+ ResponseItem converted = ItemConversion.toResponseItem(raw, idGen);
+ if (converted != null) {
+ items.add(converted);
+ }
+ }
+ inputItems = items;
+ } else if (in.isText() && !in.asText().isEmpty()) {
+ // Plain-text input — synthesize a single user message.
+ IdGenerator idGen = new IdGenerator(IdGenerator.extractPartitionKey(resp.id()));
+ inputItems = List.of(ItemConversion.toResponseItem(
+ com.openai.models.responses.ResponseInputItem.ofEasyInputMessage(
+ com.openai.models.responses.EasyInputMessage.builder()
+ .role(com.openai.models.responses.EasyInputMessage.Role.USER)
+ .content(com.openai.models.responses.EasyInputMessage.Content.ofTextInput(in.asText()))
+ .build()),
+ idGen));
+ }
+ }
+ } catch (Exception e) {
+ LOGGER.warn("Failed to gather input items for response {}", resp.id(), e);
+ }
+
+ // Get history item IDs if there's a previous response
+ List historyItemIds = Collections.emptyList();
+ if (previousResponseId != null) {
+ try {
+ historyItemIds = provider.getHistoryItemIdsAsync(previousResponseId, conversationId, 100).join();
+ } catch (Exception e) {
+ LOGGER.warn("Failed to get history item IDs for response {}", resp.id(), e);
+ }
+ }
+
+ // Single envelope call: POST /responses with {response, input_items, history_item_ids}
+ try {
+ // Pass isolation context so storage API receives platform isolation headers
+ IsolationContext isolation = context.getIsolation();
+ if (provider instanceof FoundryStorageProvider foundryProvider) {
+ foundryProvider.createResponseAsync(resp.id(), resp, inputItems, historyItemIds, isolation).join();
+ } else {
+ provider.createResponseAsync(resp.id(), resp, inputItems, historyItemIds).join();
+ }
+ } catch (Exception e) {
+ LOGGER.error("Failed to persist response {} to Foundry storage", resp.id(), e);
+ }
+ }
+
+ /**
+ * Shuts down the background executor, waiting up to 5 seconds for in-flight
+ * tasks to complete. Should be called when the hosting container is stopping
+ * (e.g. via a JVM shutdown hook or framework lifecycle callback).
+ */
+ @Override
+ public void close() {
+ backgroundExecutor.shutdown();
+ try {
+ if (!backgroundExecutor.awaitTermination(5, java.util.concurrent.TimeUnit.SECONDS)) {
+ LOGGER.warn("Background executor did not terminate within 5s; forcing shutdown");
+ backgroundExecutor.shutdownNow();
+ }
+ } catch (InterruptedException e) {
+ LOGGER.warn("Interrupted while awaiting background executor shutdown");
+ backgroundExecutor.shutdownNow();
+ Thread.currentThread().interrupt();
+ }
+ }
+}
+
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/AgentServerVersion.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/AgentServerVersion.java
new file mode 100644
index 000000000000..180f954c9752
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/AgentServerVersion.java
@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+/**
+ * Provides the {@code x-platform-server} header value identifying this library.
+ *
+ * The header value is computed once at class initialization from the library version
+ * and the current JVM version, e.g.:
+ * {@code azure-ai-agentserver-java/1.0.0 (java/21)}
+ */
+public final class AgentServerVersion {
+
+ private static final AgentServerVersion INSTANCE = new AgentServerVersion();
+
+ private final String composedHeader;
+
+ private AgentServerVersion() {
+ String javaVersion = System.getProperty("java.version", "unknown");
+ composedHeader = "azure-ai-agentserver-java/" + getLibraryVersion() + " (java/" + javaVersion + ")";
+ }
+
+ /**
+ * Returns the singleton instance.
+ */
+ public static AgentServerVersion getInstance() {
+ return INSTANCE;
+ }
+
+ /**
+ * Returns the {@code x-platform-server} header value for this library.
+ */
+ public String getHeaderValue() {
+ return composedHeader;
+ }
+
+ private static String getLibraryVersion() {
+ Package pkg = AgentServerVersion.class.getPackage();
+ if (pkg != null && pkg.getImplementationVersion() != null) {
+ return pkg.getImplementationVersion();
+ }
+ return "1.0.0-SNAPSHOT";
+ }
+}
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ApiError.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ApiError.java
new file mode 100644
index 000000000000..91cebc0e7ac6
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ApiError.java
@@ -0,0 +1,97 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Structured HTTP error body as defined by the API spec.
+ * Serialised inside an outer envelope: {@code { "error": ApiError }}.
+ *
+ * Required fields: {@link #message}, {@link #type}, {@link #code} (which may be
+ * {@code null} but is always present). Optional fields ({@link #param},
+ * {@link #details}, {@link #additionalInfo}) are omitted when {@code null}.
+ *
+ * @param message human-readable description (always present)
+ * @param type error category, e.g. {@code "invalid_request_error"}, {@code "server_error"} (always present)
+ * @param code sub-code such as {@code "invalid_parameters"}, {@code "unsupported_parameter"};
+ * always serialised, may be {@code null}
+ * @param param the offending request parameter, JSON-path or path-param name; optional
+ * @param details nested error objects for multi-error validation; optional
+ * @param additionalInfo arbitrary supplemental key/value context; optional
+ */
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public record ApiError(
+ @JsonProperty("message") String message,
+ @JsonProperty("type") String type,
+ // `code` is always serialised (may be null) per the envelope spec.
+ @JsonInclude(JsonInclude.Include.ALWAYS) @JsonProperty("code") String code,
+ @JsonProperty("param") String param,
+ @JsonProperty("details") List details,
+ @JsonProperty("additionalInfo") Map additionalInfo) {
+
+ /**
+ * Standard error type for client-side / 4xx errors.
+ */
+ public static final String TYPE_INVALID_REQUEST = "invalid_request_error";
+ /**
+ * Standard error type for unhandled server errors (500).
+ */
+ public static final String TYPE_SERVER_ERROR = "server_error";
+
+ /**
+ * Generic 4xx sub-code used when no more specific code applies.
+ */
+ public static final String CODE_INVALID_REQUEST = "invalid_request_error";
+ /**
+ * Malformed path identifier.
+ */
+ public static final String CODE_INVALID_PARAMETERS = "invalid_parameters";
+ /**
+ * Parameter present but unsupported in this combination.
+ */
+ public static final String CODE_UNSUPPORTED_PARAMETER = "unsupported_parameter";
+ /**
+ * Required parameter missing from the request.
+ */
+ public static final String CODE_MISSING_REQUIRED_PARAMETER = "missing_required_parameter";
+ /**
+ * Unknown / unrecognised parameter on the request.
+ */
+ public static final String CODE_UNKNOWN_PARAMETER = "unknown_parameter";
+ /**
+ * A generic field-level validation failure inside a {@code details[]} entry.
+ */
+ public static final String CODE_INVALID_VALUE = "invalid_value";
+ /**
+ * Unhandled server-side failure.
+ */
+ public static final String CODE_SERVER_ERROR = "server_error";
+
+ /**
+ * Convenience for the common 4xx case with no offending parameter.
+ */
+ public static ApiError invalidRequest(String message) {
+ return new ApiError(message, TYPE_INVALID_REQUEST, CODE_INVALID_REQUEST, null, null, null);
+ }
+
+ /**
+ * Convenience for a 4xx case with a specific sub-code and offending parameter.
+ */
+ public static ApiError invalidRequest(String message, String code, String param) {
+ return new ApiError(message, TYPE_INVALID_REQUEST, code, param, null, null);
+ }
+
+ /**
+ * Convenience for a 500.
+ */
+ public static ApiError serverError(String message) {
+ return new ApiError(message, TYPE_SERVER_ERROR, CODE_SERVER_ERROR, null, null, null);
+ }
+}
+
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ApiException.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ApiException.java
new file mode 100644
index 000000000000..58dc85a29e6f
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ApiException.java
@@ -0,0 +1,50 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import java.util.Objects;
+
+/**
+ * Exception thrown when an API operation fails.
+ *
+ * Carries an HTTP status code and a structured {@link ApiError} body that the
+ * hosting framework adapter serialises as the standard error envelope
+ * ({@code { "error": { "message", "type", "code", "param"?, "details"?, "additionalInfo"? } }})
+ * per the API spec.
+ */
+public class ApiException extends Exception {
+
+ private final int statusCode;
+ private final ApiError error;
+
+ /**
+ * Creates an {@code ApiException} with the given status code and structured error body.
+ *
+ * @param statusCode the HTTP status code representing the error
+ * @param error the structured error body (required)
+ */
+ public ApiException(int statusCode, ApiError error) {
+ super("API error: HTTP " + statusCode + " — " + Objects.requireNonNull(error, "error").message());
+ this.statusCode = statusCode;
+ this.error = error;
+ }
+
+ /**
+ * Returns the HTTP status code associated with this exception.
+ *
+ * @return the status code
+ */
+ public int getStatusCode() {
+ return statusCode;
+ }
+
+ /**
+ * Returns the structured error body, never {@code null}.
+ *
+ * @return the structured {@link ApiError}
+ */
+ public ApiError getError() {
+ return error;
+ }
+}
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/CreateResponse.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/CreateResponse.java
new file mode 100644
index 000000000000..b1e8873b8cb1
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/CreateResponse.java
@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import com.fasterxml.jackson.annotation.JsonUnwrapped;
+import com.openai.models.responses.Response;
+
+/**
+ * Wraps an OpenAI {@link Response} together with an optional {@link AgentReference}
+ * for the agent server protocol's create-response endpoint.
+ *
+ * The {@code response} field is serialized unwrapped (its properties merge into
+ * the top-level JSON object), while the {@code agent} field is a nested object.
+ *
+ * @param agent the agent that produced this response, or {@code null}
+ * @param response the OpenAI Response object
+ */
+public record CreateResponse(AgentReference agent, @JsonUnwrapped Response response) {
+}
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/EventReplayStore.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/EventReplayStore.java
new file mode 100644
index 000000000000..80c467685d4b
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/EventReplayStore.java
@@ -0,0 +1,164 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.microsoft.agentserver.api.serialization.ObjectMapperFactory;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CopyOnWriteArrayList;
+
+/**
+ * Process-scoped, in-memory buffer of serialized SSE events keyed by response ID,
+ * used to support SSE replay via {@code GET /responses/{id}?stream=true}.
+ *
+ *
+ * Each event is retained for a minimum of {@code ttl} from when it was buffered
+ * (default 10 minutes). The per-event TTL means individual events may be
+ * evicted independently — JSON GET is unaffected by replay-buffer eviction.
+ *
+ * Events may be appended {@linkplain #append(String, ResponseEvent) one at a time}
+ * (live, while the response is still streaming — supports mid-stream replay) or in
+ * a single batch via {@linkplain #store(String, List)}. {@linkplain #initBuffer(String)}
+ * registers an empty buffer so {@linkplain #hasBuffer(String)} returns {@code true}
+ * even before the first event arrives — required so a replay request that races
+ * the first emission is not mis-classified as "not created with stream=true".
+ */
+final class EventReplayStore {
+
+ private static final Logger LOGGER = LoggerFactory.getLogger(EventReplayStore.class);
+
+ /**
+ * Default per-event replay retention.
+ */
+ static final Duration DEFAULT_TTL = Duration.ofMinutes(10);
+
+ private final Duration ttl;
+ private final Map> buffers = new ConcurrentHashMap<>();
+
+ EventReplayStore() {
+ this(DEFAULT_TTL);
+ }
+
+ EventReplayStore(Duration ttl) {
+ this.ttl = ttl;
+ }
+
+ /**
+ * A single buffered event: its sequence number, name, JSON payload, and expiry.
+ */
+ record StoredEvent(long sequenceNumber, String eventName, String data, long expiresAtMillis) {
+ }
+
+ /**
+ * Registers an empty replay buffer for a response. Used by the streaming
+ * create path so {@link #hasBuffer(String)} reflects "was created with
+ * stream=true" before any event has been appended.
+ */
+ void initBuffer(String responseId) {
+ buffers.computeIfAbsent(responseId, k -> new CopyOnWriteArrayList<>());
+ }
+
+ /**
+ * Appends a single event to the replay buffer (used for live mid-stream
+ * buffering of background streaming responses). Idempotent on the buffer
+ * existence — if no buffer was {@linkplain #initBuffer(String) initialised}
+ * first, one is created on demand.
+ */
+ void append(String responseId, ResponseEvent event) {
+ if (event == null) {
+ return;
+ }
+ StoredEvent stored = toStoredEvent(event, buffers.getOrDefault(responseId, List.of()).size());
+ if (stored == null) {
+ return;
+ }
+ buffers.computeIfAbsent(responseId, k -> new CopyOnWriteArrayList<>()).add(stored);
+ }
+
+ /**
+ * Replaces the buffer for {@code responseId} with the supplied events.
+ * Convenience for the "buffer at terminal" pattern.
+ */
+ void store(String responseId, List events) {
+ if (events == null || events.isEmpty()) {
+ buffers.put(responseId, new CopyOnWriteArrayList<>());
+ return;
+ }
+ List stored = new CopyOnWriteArrayList<>();
+ long index = 0;
+ for (ResponseEvent event : events) {
+ StoredEvent s = toStoredEvent(event, index);
+ if (s != null) {
+ stored.add(s);
+ }
+ index++;
+ }
+ buffers.put(responseId, stored);
+ }
+
+ private StoredEvent toStoredEvent(ResponseEvent event, long fallbackIndex) {
+ ObjectMapper mapper = ObjectMapperFactory.getObjectMapper();
+ try {
+ String data = mapper.writeValueAsString(event.streamEvent());
+ long seq = fallbackIndex;
+ JsonNode node = mapper.readTree(data);
+ if (node.hasNonNull("sequence_number")) {
+ seq = node.get("sequence_number").asLong(fallbackIndex);
+ }
+ long expiresAt = System.currentTimeMillis() + ttl.toMillis();
+ return new StoredEvent(seq, event.eventName(), data, expiresAt);
+ } catch (Exception e) {
+ LOGGER.warn("Failed to serialize replay event {}", fallbackIndex, e);
+ return null;
+ }
+ }
+
+ /**
+ * Returns {@code true} if a replay buffer exists for the response — i.e. it was
+ * created with {@code stream=true} (even if all its events have since expired).
+ */
+ boolean hasBuffer(String responseId) {
+ return buffers.containsKey(responseId);
+ }
+
+ /**
+ * Returns the non-expired events for a response with {@code sequence_number}
+ * greater than {@code startingAfter} (when provided), in order.
+ */
+ Optional> replay(String responseId, Integer startingAfter) {
+ List all = buffers.get(responseId);
+ if (all == null) {
+ return Optional.empty();
+ }
+ long now = System.currentTimeMillis();
+ long after = startingAfter != null ? startingAfter : Long.MIN_VALUE;
+ List live = new ArrayList<>();
+ for (StoredEvent e : all) {
+ if (e.expiresAtMillis() <= now) {
+ continue; // per-event TTL eviction
+ }
+ if (e.sequenceNumber() <= after) {
+ continue; // starting_after cursor
+ }
+ live.add(new ResponseStreamReplay.ReplayEvent(e.sequenceNumber(), e.eventName(), e.data()));
+ }
+ return Optional.of(live);
+ }
+
+ /**
+ * Removes any buffered events for a response (best-effort, on delete).
+ */
+ void delete(String responseId) {
+ buffers.remove(responseId);
+ }
+}
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/FoundryEnvironment.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/FoundryEnvironment.java
new file mode 100644
index 000000000000..70a3b15c4711
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/FoundryEnvironment.java
@@ -0,0 +1,167 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import com.azure.core.credential.TokenCredential;
+import com.azure.identity.DefaultAzureCredentialBuilder;
+import com.azure.identity.ManagedIdentityCredentialBuilder;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.net.URI;
+
+/**
+ * Provides strongly-typed access to Foundry platform environment variables
+ * injected by the Azure AI Foundry hosting infrastructure.
+ *
+ * All values are read once at class load and cached for the lifetime of the process.
+ * This class is a static utility and cannot be instantiated.
+ *
+ * Equivalent to the C# {@code FoundryEnvironment}.
+ */
+public final class FoundryEnvironment {
+
+ /**
+ * The agent name. Sourced from {@code FOUNDRY_AGENT_NAME}.
+ */
+ public static final String AGENT_NAME = System.getenv("FOUNDRY_AGENT_NAME");
+ /**
+ * The agent version. Sourced from {@code FOUNDRY_AGENT_VERSION}.
+ */
+ public static final String AGENT_VERSION = System.getenv("FOUNDRY_AGENT_VERSION");
+ /**
+ * The Foundry project endpoint. Sourced from {@code FOUNDRY_PROJECT_ENDPOINT},
+ * with fallback to {@code AZURE_AI_PROJECT_ENDPOINT}.
+ */
+ public static final String PROJECT_ENDPOINT = resolveProjectEndpoint();
+ /**
+ * The full ARM ID of the Foundry project. Sourced from {@code FOUNDRY_PROJECT_ARM_ID}.
+ */
+ public static final String PROJECT_ARM_ID = System.getenv("FOUNDRY_PROJECT_ARM_ID");
+ /**
+ * The session ID. Sourced from {@code FOUNDRY_AGENT_SESSION_ID}.
+ */
+ public static final String SESSION_ID = System.getenv("FOUNDRY_AGENT_SESSION_ID");
+ /**
+ * The model deployment name. Sourced from {@code MODEL_DEPLOYMENT_NAME}.
+ * Default: {@code "gpt-4.1-mini"}.
+ */
+ public static final String MODEL_DEPLOYMENT_NAME = resolveWithDefault("MODEL_DEPLOYMENT_NAME", "gpt-4.1-mini");
+ /**
+ * The Azure managed identity client ID. Sourced from {@code AZURE_CLIENT_ID}.
+ *
+ * When set, prefer {@code ManagedIdentityCredential} with this client ID.
+ * When absent, {@code DefaultAzureCredential} should be used.
+ */
+ public static final String AZURE_CLIENT_ID = System.getenv("AZURE_CLIENT_ID");
+ /**
+ * The Azure OpenAI endpoint derived from the project endpoint (scheme + host),
+ * with fallback to {@code AZURE_OPENAI_ENDPOINT} or {@code AZURE_ENDPOINT}.
+ *
+ * For example, if {@link #PROJECT_ENDPOINT} is
+ * {@code "https://account.services.ai.azure.com/api/projects/proj"},
+ * this resolves to {@code "https://account.services.ai.azure.com"}.
+ */
+ public static final String OPENAI_ENDPOINT = resolveOpenAiEndpoint();
+ /**
+ * The HTTP listen port. Sourced from {@code PORT}. Default: 8088.
+ */
+ public static final int PORT = resolvePort();
+ /**
+ * The OTLP exporter endpoint. Sourced from {@code OTEL_EXPORTER_OTLP_ENDPOINT}.
+ */
+ public static final String OTLP_ENDPOINT = System.getenv("OTEL_EXPORTER_OTLP_ENDPOINT");
+ /**
+ * The Application Insights connection string. Sourced from {@code APPLICATIONINSIGHTS_CONNECTION_STRING}.
+ *
+ * Security note: This value is a credential. Avoid logging or exposing it in diagnostics.
+ */
+ public static final String APP_INSIGHTS_CONNECTION_STRING = System.getenv("APPLICATIONINSIGHTS_CONNECTION_STRING");
+ /**
+ * Indicates whether the process is running in a Foundry hosted environment.
+ * Returns {@code true} when the {@code FOUNDRY_HOSTING_ENVIRONMENT} environment variable
+ * is set to a non-empty value.
+ */
+ public static final boolean IS_HOSTED = isNonEmpty(System.getenv("FOUNDRY_HOSTING_ENVIRONMENT"));
+ private static final Logger LOGGER = LoggerFactory.getLogger(FoundryEnvironment.class);
+
+ private FoundryEnvironment() {
+ // Static utility class
+ }
+
+ /**
+ * Resolves the appropriate {@link TokenCredential} for the current environment.
+ *
+ * When {@link #AZURE_CLIENT_ID} is set (typical in hosted environments with managed identity),
+ * returns a {@code ManagedIdentityCredential} scoped to that client ID.
+ * Otherwise, returns a {@code DefaultAzureCredential} for local development and
+ * environments without an explicit managed identity.
+ *
+ * @return a {@link TokenCredential} suitable for authenticating with Azure services
+ */
+ public static TokenCredential resolveCredential() {
+ if (isNonEmpty(AZURE_CLIENT_ID)) {
+ LOGGER.debug("Using ManagedIdentityCredential with client ID: {}", AZURE_CLIENT_ID);
+ return new ManagedIdentityCredentialBuilder()
+ .clientId(AZURE_CLIENT_ID)
+ .build();
+ }
+ LOGGER.debug("Using DefaultAzureCredential");
+ return new DefaultAzureCredentialBuilder().build();
+ }
+
+ private static String resolveProjectEndpoint() {
+ String endpoint = System.getenv("FOUNDRY_PROJECT_ENDPOINT");
+ if (isNonEmpty(endpoint)) {
+ return endpoint;
+ }
+ return System.getenv("AZURE_AI_PROJECT_ENDPOINT");
+ }
+
+ private static String resolveOpenAiEndpoint() {
+ // Derive from project endpoint (scheme + host)
+ if (isNonEmpty(PROJECT_ENDPOINT)) {
+ try {
+ URI uri = URI.create(PROJECT_ENDPOINT);
+ return uri.getScheme() + "://" + uri.getHost();
+ } catch (IllegalArgumentException ignored) {
+ // fall through to explicit env vars
+ }
+ }
+ // Fallback to explicit env vars
+ String explicit = System.getenv("AZURE_OPENAI_ENDPOINT");
+ if (isNonEmpty(explicit)) {
+ return explicit;
+ }
+ return System.getenv("AZURE_ENDPOINT");
+ }
+
+ private static String resolveWithDefault(String envVar, String defaultValue) {
+ String value = System.getenv(envVar);
+ return isNonEmpty(value) ? value : defaultValue;
+ }
+
+ private static int resolvePort() {
+ String portEnv = System.getenv("PORT");
+ if (portEnv == null || portEnv.isEmpty()) {
+ return 8088;
+ }
+ try {
+ int port = Integer.parseInt(portEnv);
+ if (port < 1 || port > 65535) {
+ throw new IllegalStateException(
+ "The PORT environment variable value '" + portEnv + "' is not a valid port number (1–65535).");
+ }
+ return port;
+ } catch (NumberFormatException e) {
+ throw new IllegalStateException(
+ "The PORT environment variable value '" + portEnv + "' is not a valid port number (1–65535).", e);
+ }
+ }
+
+ private static boolean isNonEmpty(String value) {
+ return value != null && !value.isEmpty();
+ }
+}
+
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/HealthApi.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/HealthApi.java
new file mode 100644
index 000000000000..beaf47206b67
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/HealthApi.java
@@ -0,0 +1,41 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+/**
+ * Interface for Kubernetes-style health probe endpoints.
+ *
+ * Implementations indicate whether the application is ready to serve traffic
+ * (readiness) and whether the process is alive (liveness).
+ *
+ * The default implementation always returns {@code true} for both probes.
+ * Override to add custom health checks (e.g., database connectivity, downstream
+ * service availability).
+ */
+public interface HealthApi {
+
+ /**
+ * Returns whether the application is ready to serve requests.
+ *
+ * A {@code false} return value causes the orchestrator to stop routing traffic
+ * to this instance until it becomes ready again.
+ *
+ * @return {@code true} if ready, {@code false} otherwise
+ */
+ default boolean isReady() {
+ return true;
+ }
+
+ /**
+ * Returns whether the application process is alive and responsive.
+ *
+ * A {@code false} return value causes the orchestrator to restart the container.
+ *
+ * @return {@code true} if alive, {@code false} otherwise
+ */
+ default boolean isAlive() {
+ return true;
+ }
+}
+
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/IsolationContext.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/IsolationContext.java
new file mode 100644
index 000000000000..a20d9e93d407
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/IsolationContext.java
@@ -0,0 +1,131 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * Carries the platform-injected isolation keys for a single request.
+ * The Foundry platform sets {@code x-agent-user-isolation-key} and
+ * {@code x-agent-chat-isolation-key} headers on every protocol request.
+ * These opaque partition keys let handlers scope user-private and
+ * conversation-shared state without inspecting user identity.
+ *
+ * User isolation key — the partition for data that belongs to the
+ * individual who initiated the request (e.g., OAuth tokens, personal memory,
+ * per-user preferences, cache entries). Stable for a given user across sessions.
+ *
+ * Chat isolation key — the partition for conversation-scoped state
+ * (e.g., conversation history, turn state, shared files). In a 1:1 user↔agent
+ * chat this equals the user isolation key. It differs only in shared-surface
+ * scenarios (e.g., a Teams group chat) where it represents the common partition
+ * all participants write to.
+ *
+ * Both keys are opaque, platform-generated, and scoped to the agent — data
+ * cannot leak between agents. Neither key is guaranteed to be present when
+ * running locally (outside the platform); handlers should handle {@code null}
+ * values gracefully (e.g., fall back to a default partition).
+ */
+public record IsolationContext(String userIsolationKey, String chatIsolationKey) {
+
+ /**
+ * An empty {@link IsolationContext} with both keys {@code null}.
+ * Used when the platform headers are absent (e.g., local development).
+ */
+ public static final IsolationContext EMPTY = new IsolationContext(null, null);
+
+ /**
+ * Creates a new {@link IsolationContext} with the given keys.
+ *
+ * @param userIsolationKey the value of the {@code x-agent-user-isolation-key} header,
+ * or {@code null} if the header was absent.
+ * @param chatIsolationKey the value of the {@code x-agent-chat-isolation-key} header,
+ * or {@code null} if the header was absent.
+ */
+ public IsolationContext {
+ }
+
+ /**
+ * Extracts isolation keys from a map of HTTP headers (case-insensitive lookup).
+ * Returns {@link #EMPTY} when neither platform header is present.
+ *
+ * @param headers a map of header name → value (case-insensitive keys recommended).
+ * @return an {@link IsolationContext} with the extracted keys.
+ */
+ public static IsolationContext fromHeaders(Map headers) {
+ if (headers == null || headers.isEmpty()) {
+ return EMPTY;
+ }
+ String userKey = normalizeHeaderValue(headers.get(PlatformHeaders.USER_ISOLATION_KEY));
+ String chatKey = normalizeHeaderValue(headers.get(PlatformHeaders.CHAT_ISOLATION_KEY));
+
+ if (userKey == null && chatKey == null) {
+ return EMPTY;
+ }
+ return new IsolationContext(userKey, chatKey);
+ }
+
+ /**
+ * Extracts client headers (those prefixed with {@code x-client-}) from a map of
+ * HTTP request headers. The prefix is preserved in the returned keys.
+ *
+ * @param headers a map of all request headers.
+ * @return an unmodifiable map of client headers (may be empty, never null).
+ */
+ public static Map extractClientHeaders(Map headers) {
+ if (headers == null || headers.isEmpty()) {
+ return Collections.emptyMap();
+ }
+ Map clientHeaders = new LinkedHashMap<>();
+ for (Map.Entry entry : headers.entrySet()) {
+ String key = entry.getKey();
+ if (key != null && key.toLowerCase().startsWith(PlatformHeaders.CLIENT_HEADER_PREFIX)) {
+ clientHeaders.put(key.toLowerCase(), entry.getValue());
+ }
+ }
+ return Collections.unmodifiableMap(clientHeaders);
+ }
+
+ /**
+ * Gets the user isolation key — the partition under which
+ * user-private state should be stored.
+ *
+ * @return an opaque string from {@code x-agent-user-isolation-key},
+ * or {@code null} when running outside the platform.
+ */
+ @Override
+ public String userIsolationKey() {
+ return userIsolationKey;
+ }
+
+ /**
+ * Gets the chat isolation key — the partition under which
+ * conversation / shared state should be stored.
+ *
+ * @return an opaque string from {@code x-agent-chat-isolation-key},
+ * or {@code null} when running outside the platform.
+ * In a 1:1 user↔agent chat this equals {@link #userIsolationKey ()}.
+ */
+ @Override
+ public String chatIsolationKey() {
+ return chatIsolationKey;
+ }
+
+ /**
+ * Returns {@code true} if both isolation keys are absent.
+ */
+ public boolean isEmpty() {
+ return userIsolationKey == null && chatIsolationKey == null;
+ }
+
+ private static String normalizeHeaderValue(String value) {
+ if (value == null || value.isBlank()) {
+ return null;
+ }
+ return value.trim();
+ }
+}
+
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/Observability.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/Observability.java
new file mode 100644
index 000000000000..a8aaa5b0e6da
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/Observability.java
@@ -0,0 +1,404 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import io.opentelemetry.api.GlobalOpenTelemetry;
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.api.trace.SpanKind;
+import io.opentelemetry.api.trace.StatusCode;
+import io.opentelemetry.api.trace.Tracer;
+import io.opentelemetry.context.Context;
+import io.opentelemetry.context.propagation.TextMapGetter;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.Map;
+
+/**
+ * Provides OpenTelemetry instrumentation for the Azure AI Foundry Agent Server server.
+ *
+ * This class uses the OpenTelemetry API which is a no-op by default. It becomes active when:
+ *
+ * - The OpenTelemetry Java Agent is attached via {@code javaagent:} JVM flag
+ * - The OpenTelemetry SDK is programmatically configured (e.g., via {@code opentelemetry-sdk-extension-autoconfigure})
+ * - The Application Insights Java Agent is attached
+ *
+ *
+ * The instrumentation scope is {@code "Azure.AI.AgentServer.Responses"}, matching the.NET convention.
+ *
+ * Environment variables (used by OTel SDK/Agent when present):
+ *
+ * - {@code OTEL_EXPORTER_OTLP_ENDPOINT} — OTLP exporter endpoint
+ * - {@code OTEL_SERVICE_NAME} — service name (defaults to agent name)
+ * - {@code APPLICATIONINSIGHTS_CONNECTION_STRING} — enables Application Insights export
+ *
+ */
+public final class Observability {
+
+ private static final Logger LOGGER = LoggerFactory.getLogger(Observability.class);
+
+ /**
+ * Instrumentation scope name for the protocol, matching.NET convention.
+ */
+ public static final String SCOPE_RESPONSES = "Azure.AI.AgentServer.Responses";
+
+ /**
+ * Instrumentation scope name for the core hosting layer.
+ */
+ public static final String SCOPE_CORE = "Azure.AI.AgentServer.Core";
+
+ private static volatile Tracer responsesTracer;
+ private static volatile Tracer coreTracer;
+
+ private Observability() {
+ // Static utility class
+ }
+
+ /**
+ * Gets the tracer for the protocol scope.
+ * Uses {@link GlobalOpenTelemetry} which is auto-configured by the OTel Java Agent
+ * or SDK autoconfigure module.
+ *
+ * @return the protocol tracer.
+ */
+ public static Tracer getResponsesTracer() {
+ if (responsesTracer == null) {
+ responsesTracer = GlobalOpenTelemetry.getTracer(SCOPE_RESPONSES);
+ }
+ return responsesTracer;
+ }
+
+ /**
+ * Gets the tracer for the core hosting scope.
+ *
+ * @return the Core hosting tracer.
+ */
+ public static Tracer getCoreTracer() {
+ if (coreTracer == null) {
+ coreTracer = GlobalOpenTelemetry.getTracer(SCOPE_CORE);
+ }
+ return coreTracer;
+ }
+
+ /**
+ * Starts a new SERVER span for an incoming HTTP request.
+ * Extracts trace context from request headers (W3C traceparent) using
+ * the global propagator.
+ *
+ * @param spanName the span name (e.g., "POST /responses").
+ * @param headers the request headers for context propagation.
+ * @return the started span (caller must close/end it).
+ */
+ public static Span startServerSpan(String spanName, Map headers) {
+ OpenTelemetry otel = GlobalOpenTelemetry.get();
+ Context extractedContext = otel.getPropagators()
+ .getTextMapPropagator()
+ .extract(Context.current(), headers, MapTextMapGetter.INSTANCE);
+
+ return getCoreTracer()
+ .spanBuilder(spanName)
+ .setSpanKind(SpanKind.SERVER)
+ .setParent(extractedContext)
+ .startSpan();
+ }
+
+ /**
+ * Records standard HTTP attributes on a span.
+ *
+ * @param span the span to set attributes on.
+ * @param method the HTTP method (GET, POST, etc.).
+ * @param path the request path.
+ * @param statusCode the HTTP response status code.
+ */
+ public static void setHttpAttributes(Span span, String method, String path, int statusCode) {
+ span.setAttribute("http.request.method", method);
+ span.setAttribute("url.path", path);
+ span.setAttribute("http.response.status_code", statusCode);
+
+ if (statusCode >= 500) {
+ span.setStatus(StatusCode.ERROR, "HTTP " + statusCode);
+ }
+ }
+
+ /**
+ * Starts the spec-required {@code invoke_agent {model}} span.
+ *
+ * Sets all required GenAI semantic-convention tags and namespaced
+ * {@code azure.ai.agentserver.responses.*} tags so the platform's
+ * trajectory UI can render the response in context.
+ *
+ * @param model resolved model name (may be {@code null} or empty)
+ * @param responseId the response id (e.g. {@code caresp_…}); never null/empty
+ * @param conversationId conversation id, or {@code null} if absent
+ * @param agentName agent name, or {@code null}
+ * @param agentVersion agent version, or {@code null}
+ * @param streaming whether this is a streaming invocation
+ * @return the started span; caller is responsible for ending it
+ */
+ public static Span startInvokeAgentSpan(
+ String model,
+ String responseId,
+ String conversationId,
+ String agentName,
+ String agentVersion,
+ boolean streaming) {
+
+ String spanName = (model != null && !model.isEmpty())
+ ? "invoke_agent " + model
+ : "invoke_agent";
+
+ Span span = getResponsesTracer()
+ .spanBuilder(spanName)
+ .setSpanKind(SpanKind.SERVER)
+ .startSpan();
+
+ // GenAI semantic-convention identity tags
+ span.setAttribute("service.name", "azure.ai.agentserver");
+ span.setAttribute("gen_ai.provider.name", "AzureAI Hosted Agents");
+ span.setAttribute("gen_ai.operation.name", "invoke_agent");
+ span.setAttribute("gen_ai.response.id", responseId);
+ if (model != null && !model.isEmpty()) {
+ span.setAttribute("gen_ai.request.model", model);
+ }
+ if (conversationId != null && !conversationId.isEmpty()) {
+ span.setAttribute("gen_ai.conversation.id", conversationId);
+ }
+
+ String agentId;
+ if (agentName != null && !agentName.isEmpty()) {
+ agentId = agentName + ":" + (agentVersion != null ? agentVersion : "");
+ span.setAttribute("gen_ai.agent.name", agentName);
+ if (agentVersion != null && !agentVersion.isEmpty()) {
+ span.setAttribute("gen_ai.agent.version", agentVersion);
+ }
+ } else {
+ agentId = "";
+ }
+ span.setAttribute("gen_ai.agent.id", agentId);
+
+ // Namespaced tags for dashboards / correlation
+ span.setAttribute("azure.ai.agentserver.responses.response_id", responseId);
+ span.setAttribute("azure.ai.agentserver.responses.conversation_id",
+ conversationId != null ? conversationId : "");
+ span.setAttribute("azure.ai.agentserver.responses.streaming", streaming);
+
+ String projectArmId = FoundryEnvironment.PROJECT_ARM_ID;
+ if (projectArmId != null && !projectArmId.isEmpty()) {
+ span.setAttribute("microsoft.foundry.project.id", projectArmId);
+ }
+
+ return span;
+ }
+
+ /**
+ * Records an error on an {@code invoke_agent} span per
+ * the spec (error tags). Sets the status to ERROR
+ * and adds the recommended namespaced + OTel exception tags.
+ */
+ public static void recordInvokeAgentError(Span span, String code, String message, Throwable t) {
+ if (span == null) {
+ return;
+ }
+ if (code != null) {
+ span.setAttribute("azure.ai.agentserver.responses.error.code", code);
+ span.setAttribute("error.type", code);
+ }
+ if (message != null) {
+ span.setAttribute("azure.ai.agentserver.responses.error.message", message);
+ span.setAttribute("otel.status_description", message);
+ }
+ if (t != null) {
+ span.recordException(t);
+ }
+ span.setStatus(StatusCode.ERROR, message != null ? message : "");
+ maybeLogRbacGuidance(t);
+ }
+
+ /**
+ * Pattern matching a missing data-action message of the form:
+ * "The principal `` lacks the required data action `/`..."
+ * emitted by Azure Cognitive Services / OpenAI on 401 PermissionDenied.
+ */
+ private static final java.util.regex.Pattern PRINCIPAL_LACKS_ACTION = java.util.regex.Pattern.compile(
+ "principal\\s+`?([0-9a-fA-F-]{36})`?\\s+lacks the required data action\\s+`?([^`\\s\"]+)`?",
+ java.util.regex.Pattern.CASE_INSENSITIVE);
+
+ /**
+ * Backstop: catches the generic "Principal does not have access to API/Operation."
+ */
+ private static final java.util.regex.Pattern GENERIC_PRINCIPAL_DENIED = java.util.regex.Pattern.compile(
+ "Principal does not have access to API/Operation",
+ java.util.regex.Pattern.CASE_INSENSITIVE);
+
+ private static final java.util.Set RBAC_GUIDANCE_PRINCIPALS =
+ java.util.Collections.synchronizedSet(new java.util.HashSet<>());
+
+ /**
+ * Detects Azure RBAC-related authentication failures from an exception
+ * chain and prints a one-time human-readable remediation message that
+ * includes the exact {@code az role assignment create} command to run.
+ */
+ public static void maybeLogRbacGuidance(Throwable t) {
+ if (t == null) {
+ return;
+ }
+
+ Throwable cur = t;
+ for (int depth = 0; cur != null && depth < 8; depth++, cur = cur.getCause()) {
+ String msg = cur.getMessage();
+ if (msg == null) {
+ continue;
+ }
+ java.util.regex.Matcher m = PRINCIPAL_LACKS_ACTION.matcher(msg);
+ if (m.find()) {
+ String principalId = m.group(1);
+ String action = m.group(2);
+ if (RBAC_GUIDANCE_PRINCIPALS.add("data-action:" + principalId + ":" + action)) {
+ logDataActionGuidance(principalId, action);
+ }
+ return;
+ }
+ if (GENERIC_PRINCIPAL_DENIED.matcher(msg).find()) {
+ if (RBAC_GUIDANCE_PRINCIPALS.add("generic:" + System.identityHashCode(cur))) {
+ logGenericPrincipalDeniedGuidance();
+ }
+ return;
+ }
+ }
+ }
+
+ private static void logDataActionGuidance(String principalId, String action) {
+ String role = guessRoleForAction(action);
+ StringBuilder sb = new StringBuilder();
+ sb.append("\n");
+ sb.append("==============================================================================\n");
+ sb.append(" AZURE RBAC: The agent's managed identity is missing a required role.\n");
+ sb.append("==============================================================================\n");
+ sb.append(" Principal id : ").append(principalId).append("\n");
+ sb.append(" Missing action : ").append(action).append("\n");
+ if (role != null) {
+ sb.append(" Suggested role : \"").append(role).append("\"\n");
+ }
+ sb.append("\n");
+ sb.append(" Run the following to grant access (replace with the resource id of\n");
+ sb.append(" the Cognitive Services / Foundry account the request was made against):\n");
+ sb.append("\n");
+ sb.append(" az role assignment create \\\n");
+ sb.append(" --assignee ").append(principalId).append(" \\\n");
+ sb.append(" --role \"").append(role != null ? role : "Cognitive Services OpenAI User").append("\" \\\n");
+ sb.append(" --scope \n");
+ sb.append("\n");
+ sb.append(" Allow ~30s for the assignment to propagate, then retry.\n");
+ sb.append("==============================================================================");
+ LOGGER.error(sb.toString());
+ }
+
+ private static void logGenericPrincipalDeniedGuidance() {
+ LOGGER.error("""
+ ==============================================================================
+ AZURE RBAC: The agent's managed identity is missing a required role.
+ ==============================================================================
+ The platform returned: "Principal does not have access to API/Operation."
+ The principal id is not in the message, but it is the agent's instance
+ identity (visible via `az agentservers show` or in the agent metadata).
+
+ For Azure OpenAI calls against a Foundry project, the agent typically needs:
+ - "Cognitive Services OpenAI User" on the Cognitive Services account, AND
+ - "Azure AI User" on the project (scope ending in /projects/)
+
+ Use:
+ az role assignment create --assignee \\
+ --role "Azure AI User" --scope
+ ==============================================================================""");
+ }
+
+ private static String guessRoleForAction(String action) {
+ if (action == null) {
+ return null;
+ }
+ String lower = action.toLowerCase(java.util.Locale.ROOT);
+ if (lower.contains("openai") && lower.contains("chat")) {
+ return "Cognitive Services OpenAI User";
+ }
+ if (lower.contains("openai")) {
+ return "Cognitive Services OpenAI Contributor";
+ }
+ if (lower.contains("cognitiveservices")) {
+ return "Cognitive Services User";
+ }
+ return null;
+ }
+
+ /**
+ * Starts the spec-required {@code tools/call {tool_name}} span
+ * for outbound calls to the Foundry
+ * Toolboxes (MCP) proxy. Use {@link #recordToolboxResult} to set the
+ * success/failure tags before ending the span.
+ *
+ * @param toolboxName the toolbox name used for this invocation
+ * @param fullToolName fully-qualified tool name, e.g. {@code everything.echo}
+ * @param serverLabel server-label prefix, e.g. {@code everything}
+ * @return the started span; caller is responsible for ending it
+ */
+ public static Span startToolboxCallSpan(String toolboxName, String fullToolName, String serverLabel) {
+ Span span = getResponsesTracer()
+ .spanBuilder("tools/call " + fullToolName)
+ .setSpanKind(SpanKind.CLIENT)
+ .startSpan();
+ if (toolboxName != null) {
+ span.setAttribute("azure.ai.agentserver.toolbox.name", toolboxName);
+ }
+ if (fullToolName != null) {
+ span.setAttribute("azure.ai.agentserver.toolbox.tool_name", fullToolName);
+ }
+ if (serverLabel != null) {
+ span.setAttribute("azure.ai.agentserver.toolbox.server_label", serverLabel);
+ }
+ return span;
+ }
+
+ /**
+ * Records the success/failure outcome and latency on a {@link
+ * #startToolboxCallSpan} span.
+ */
+ public static void recordToolboxResult(Span span, boolean success, long latencyMs,
+ String errorCode, String errorMessage, Throwable t) {
+ if (span == null) {
+ return;
+ }
+ span.setAttribute("azure.ai.agentserver.toolbox.success", success);
+ span.setAttribute("azure.ai.agentserver.toolbox.latency_ms", latencyMs);
+ if (!success) {
+ if (errorCode != null) {
+ span.setAttribute("azure.ai.agentserver.toolbox.error.code", errorCode);
+ }
+ if (errorMessage != null) {
+ span.setAttribute("azure.ai.agentserver.toolbox.error.message", errorMessage);
+ }
+ if (t != null) {
+ span.recordException(t);
+ }
+ span.setStatus(StatusCode.ERROR, errorMessage != null ? errorMessage : "");
+ }
+ }
+
+ /**
+ * TextMapGetter for extracting trace context from a {@code Map}.
+ */
+ private enum MapTextMapGetter implements TextMapGetter> {
+ INSTANCE;
+
+ @Override
+ public Iterable keys(Map carrier) {
+ return carrier.keySet();
+ }
+
+ @Override
+ public String get(Map carrier, String key) {
+ return carrier == null ? null : carrier.get(key);
+ }
+ }
+}
+
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/PlatformHeaders.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/PlatformHeaders.java
new file mode 100644
index 000000000000..72870a9ca697
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/PlatformHeaders.java
@@ -0,0 +1,90 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+/**
+ * Defines the HTTP header names used across the AgentServer platform.
+ * These headers form the wire contract between the Foundry platform,
+ * agent containers, and downstream storage services.
+ *
+ * Response headers (set by the server on every response):
+ *
+ * - {@link #REQUEST_ID} — request correlation ID.
+ * - {@link #SERVER_VERSION} — server SDK identity.
+ * - {@link #SESSION_ID} — resolved session ID (when applicable).
+ *
+ * Request headers (set by the platform or client):
+ *
+ * - {@link #REQUEST_ID} — client-provided correlation ID (echoed back on response).
+ * - {@link #USER_ISOLATION_KEY} / {@link #CHAT_ISOLATION_KEY} — platform isolation keys.
+ * - {@link #CLIENT_HEADER_PREFIX} — prefix for pass-through client headers.
+ * - {@link #TRACE_PARENT} — W3C Trace Context propagation header.
+ * - {@link #CLIENT_REQUEST_ID} — Azure SDK client correlation header.
+ *
+ */
+public final class PlatformHeaders {
+
+ /**
+ * The {@code x-request-id} header — carries the request correlation ID.
+ * On responses, the server always sets this header.
+ * On requests, clients may set it to provide their own correlation ID.
+ */
+ public static final String REQUEST_ID = "x-request-id";
+
+ /**
+ * The {@code x-platform-server} header — identifies the server SDK stack
+ * (hosting version, protocol versions, language, and runtime).
+ * Set on every response by the platform header filter.
+ */
+ public static final String SERVER_VERSION = "x-platform-server";
+
+ /**
+ * The {@code x-agent-session-id} header — the resolved session ID for the request.
+ * Set on responses by protocol-specific session resolution logic.
+ */
+ public static final String SESSION_ID = "x-agent-session-id";
+
+ /**
+ * The {@code x-agent-response-id} request header — when present and non-empty,
+ * the container MUST use this value as the response ID instead of generating
+ * one.
+ */
+ public static final String RESPONSE_ID_OVERRIDE = "x-agent-response-id";
+
+ /**
+ * The {@code x-agent-user-isolation-key} header — the platform-injected
+ * partition key for user-private state.
+ */
+ public static final String USER_ISOLATION_KEY = "x-agent-user-isolation-key";
+
+ /**
+ * The {@code x-agent-chat-isolation-key} header — the platform-injected
+ * partition key for conversation-scoped state.
+ */
+ public static final String CHAT_ISOLATION_KEY = "x-agent-chat-isolation-key";
+
+ /**
+ * The prefix {@code x-client-} for pass-through client headers.
+ * All request headers starting with this prefix are extracted and forwarded
+ * to the handler via the response context.
+ */
+ public static final String CLIENT_HEADER_PREFIX = "x-client-";
+
+ /**
+ * The {@code traceparent} header — W3C Trace Context propagation header.
+ * Used for distributed tracing correlation on outbound storage requests.
+ */
+ public static final String TRACE_PARENT = "traceparent";
+
+ /**
+ * The {@code x-ms-client-request-id} header — Azure SDK client correlation header.
+ * Logged for diagnostic correlation with upstream Azure SDK callers.
+ */
+ public static final String CLIENT_REQUEST_ID = "x-ms-client-request-id";
+
+ private PlatformHeaders() {
+ // Static constants class
+ }
+}
+
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/RequestMetadata.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/RequestMetadata.java
new file mode 100644
index 000000000000..ed5338ba96a5
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/RequestMetadata.java
@@ -0,0 +1,107 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import java.util.Collections;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * Carries HTTP-level metadata extracted from the incoming request that should be
+ * propagated to the {@link ResponseContext}. This includes platform headers
+ * (isolation keys, client headers), query parameters, and request ID.
+ *
+ * Framework adapters (Spring, JAX-RS) create instances from the HTTP request
+ * and pass them to the API layer via {@link ResponsesApi} methods.
+ */
+public final class RequestMetadata {
+
+ /**
+ * Empty metadata instance with no headers or parameters.
+ * Used when no HTTP context is available (e.g., unit tests, direct API calls).
+ */
+ public static final RequestMetadata EMPTY = new RequestMetadata(
+ IsolationContext.EMPTY, Collections.emptyMap(), Collections.emptyMap(), null, null);
+
+ private final IsolationContext isolation;
+ private final Map clientHeaders;
+ private final Map queryParameters;
+ private final String requestId;
+ private final String responseIdOverride;
+
+ /**
+ * Creates a new {@link RequestMetadata} instance.
+ *
+ * @param isolation the isolation context (non-null).
+ * @param clientHeaders the forwarded {@code x-client-*} headers (non-null).
+ * @param queryParameters the query parameters (non-null).
+ * @param requestId the request ID for correlation, or {@code null}.
+ * @param responseIdOverride the value of the {@code x-agent-response-id} request
+ * header, or {@code null} when absent / empty.
+ */
+ public RequestMetadata(
+ IsolationContext isolation,
+ Map clientHeaders,
+ Map queryParameters,
+ String requestId,
+ String responseIdOverride) {
+ this.isolation = Objects.requireNonNull(isolation, "isolation must not be null");
+ this.clientHeaders = Objects.requireNonNull(clientHeaders, "clientHeaders must not be null");
+ this.queryParameters = Objects.requireNonNull(queryParameters, "queryParameters must not be null");
+ this.requestId = requestId;
+ this.responseIdOverride = (responseIdOverride == null || responseIdOverride.isEmpty())
+ ? null : responseIdOverride;
+ }
+
+ /**
+ * Backwards-compatible 4-arg constructor for callers that do not carry an
+ * {@code x-agent-response-id} override (e.g. direct API tests).
+ */
+ public RequestMetadata(
+ IsolationContext isolation,
+ Map clientHeaders,
+ Map queryParameters,
+ String requestId) {
+ this(isolation, clientHeaders, queryParameters, requestId, null);
+ }
+
+ /**
+ * Gets the platform-injected isolation keys.
+ */
+ public IsolationContext getIsolation() {
+ return isolation;
+ }
+
+ /**
+ * Gets the forwarded client headers (prefixed with {@code x-client-}).
+ */
+ public Map getClientHeaders() {
+ return clientHeaders;
+ }
+
+ /**
+ * Gets the query parameters from the HTTP request.
+ */
+ public Map getQueryParameters() {
+ return queryParameters;
+ }
+
+ /**
+ * Gets the request ID for correlation.
+ */
+ public String getRequestId() {
+ return requestId;
+ }
+
+ /**
+ * Gets the value of the {@code x-agent-response-id} request header — when
+ * non-null/non-empty, this overrides the generated response ID.
+ *
+ * @return the override, or {@code null} when the header was absent or empty.
+ */
+ public String getResponseIdOverride() {
+ return responseIdOverride;
+ }
+}
+
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseBuilder.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseBuilder.java
new file mode 100644
index 000000000000..cc46e751b2af
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseBuilder.java
@@ -0,0 +1,105 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import com.microsoft.agentserver.api.implementation.IdGenerator;
+import com.openai.core.JsonMissing;
+import com.openai.models.responses.Response;
+import com.openai.models.responses.ResponseCreateParams;
+import com.openai.models.responses.ResponseOutputItem;
+import com.openai.models.responses.ResponseOutputMessage;
+import com.openai.models.responses.ResponseOutputText;
+import com.openai.models.responses.ResponseStatus;
+import com.openai.models.responses.ToolChoiceOptions;
+
+import java.util.List;
+
+/**
+ * Utility class for constructing {@link Response} objects from output content.
+ *
+ * Uses {@link IdGenerator} for consistent Foundry-format IDs across the codebase.
+ */
+public final class ResponseBuilder {
+
+ private static final String DEFAULT_MODEL = "gpt-4o";
+
+ private ResponseBuilder() {
+ // Static utility class — do not instantiate.
+ }
+
+ /**
+ * Extracts the model name from the request.
+ * Returns the model specified in the request, or {@value #DEFAULT_MODEL} as a default fallback.
+ *
+ * @param request the create response request
+ * @return the model name
+ */
+ public static String getModelName(AgentServerCreateResponse request) {
+ try {
+ ResponseCreateParams.Body body = request.responseCreateParams();
+ if (body.model().isPresent() &&
+ body.model().get()._json().isPresent() &&
+ body.model().get()._json().get().asString().isPresent()) {
+ return body.model().get()._json().get().asString().get().toString();
+ }
+ } catch (Exception e) {
+ // Fall through to default
+ }
+ return DEFAULT_MODEL;
+ }
+
+ /**
+ * Constructs a complete {@link Response} wrapping the given output text.
+ *
+ * @param createResponse the original create request (used to extract model name)
+ * @param responseOutputText the text content to include in the response
+ * @return a fully-formed Response object
+ */
+ public static Response convertOutputToResponse(
+ AgentServerCreateResponse createResponse,
+ ResponseOutputText responseOutputText) {
+ // IDs use a fresh partition key here; the API layer
+ // (AgentServerResponsesApi.normalizeIdsAndStamp) re-partitions all
+ // child IDs to match the resolved response ID before persistence.
+ IdGenerator idGen = new IdGenerator(null);
+ String responseId = idGen.generateResponseId();
+ String messageId = idGen.generateMessageItemId();
+
+ ResponseOutputMessage.Content responseOutputMessage = ResponseOutputMessage.Content.ofOutputText(responseOutputText);
+
+ ResponseOutputMessage message = ResponseOutputMessage.builder()
+ .addContent(responseOutputMessage)
+ .id(messageId)
+ .status(ResponseOutputMessage.Status.COMPLETED)
+ .build();
+
+ Response.Builder builder = Response.builder()
+ .id(responseId)
+ .createdAt(System.currentTimeMillis() / 1000.0)
+ .addOutput(ResponseOutputItem.ofMessage(message))
+ .model(getModelName(createResponse))
+ .parallelToolCalls(false)
+ .tools(List.of())
+ .status(ResponseStatus.COMPLETED)
+ .toolChoice(ToolChoiceOptions.AUTO)
+ .error(JsonMissing.of())
+ .incompleteDetails(JsonMissing.of())
+ .instructions(JsonMissing.of())
+ .metadata(JsonMissing.of())
+ .temperature(JsonMissing.of())
+ .topP(JsonMissing.of());
+
+ // Only echo a conversation id when the client supplied one. The platform
+ // storage backend rejects responses that reference a conversation_id it
+ // does not already know about ("conv_… not found").
+ createResponse.responseCreateParams().conversation().ifPresent(conv -> {
+ if (conv.isId()) {
+ builder.conversation(Response.Conversation.builder().id(conv.asId()).build());
+ }
+ });
+
+ return builder.build();
+ }
+
+}
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseContext.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseContext.java
new file mode 100644
index 000000000000..b2fcd351c6d7
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseContext.java
@@ -0,0 +1,325 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.openai.models.responses.ResponseCreateParams;
+import com.openai.models.responses.ResponseItem;
+import com.openai.models.responses.ResponseOutputItem;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.concurrent.CompletableFuture;
+
+public interface ResponseContext {
+ /**
+ * Creates a new {@link Builder} for constructing {@link ResponseContext} instances.
+ *
+ * @return a new builder instance.
+ */
+ static Builder builder() {
+ return new Builder();
+ }
+
+ /**
+ * Gets the unique response identifier.
+ */
+ String getResponseId();
+
+ /**
+ * Gets whether the server is shutting down.
+ * Handlers can use this to distinguish shutdown from explicit cancel or client disconnect.
+ */
+ boolean isShutdownRequested();
+
+ /**
+ * Gets whether this request has been cancelled (e.g., client disconnected).
+ * Handlers should poll this periodically during long-running operations
+ * and abort gracefully when it returns {@code true}.
+ *
+ * @return {@code true} if the request has been cancelled.
+ */
+ boolean isCancelled();
+
+ /**
+ * Requests cancellation of this response context.
+ * Called by the hosting infrastructure when the client disconnects
+ * or an explicit cancel is received.
+ */
+ void cancel();
+
+
+ /**
+ * Gets the full raw JSON request body.
+ * Allows handlers to access custom or extension fields that are not part of the typed model.
+ * Returns {@code null} when no raw body is available (e.g., test-constructed contexts).
+ */
+ JsonNode getRawBody();
+
+ /**
+ * Resolves and returns the input items for the current request.
+ * Inline items are converted to {@link ResponseOutputItem} instances;
+ * item references are resolved via the provider. Results are cached
+ * after the first call.
+ *
+ * @return a future containing the resolved input items.
+ */
+ CompletableFuture> getInputItemsAsync();
+
+ /**
+ * Resolves and returns the conversation history items for the current request.
+ * History is fetched from the provider using {@code previous_response_id} and/or
+ * {@code conversation} context. Items are returned as {@link ResponseItem} in
+ * ascending (chronological) order, naturally carrying role information.
+ * Results are cached after the first call.
+ *
+ * @return a future containing the resolved history items, or an empty list if no conversation context exists.
+ */
+ CompletableFuture> getHistoryAsync();
+
+ /**
+ * Gets the platform-injected isolation keys for this request.
+ * Handlers use these opaque partition keys to scope user-private and
+ * conversation-shared state. Returns {@link IsolationContext#EMPTY}
+ * when the platform headers are absent (e.g., local development).
+ *
+ * @return the isolation context for this request.
+ */
+ default IsolationContext getIsolation() {
+ return IsolationContext.EMPTY;
+ }
+
+ /**
+ * Gets the forwarded client headers (those prefixed with {@code x-client-})
+ * from the original HTTP request.
+ *
+ * @return an unmodifiable map of client header name → value (may be empty, never null).
+ */
+ default Map getClientHeaders() {
+ return Collections.emptyMap();
+ }
+
+ /**
+ * Gets the query parameters from the original HTTP request.
+ *
+ * @return an unmodifiable map of parameter name → value (may be empty, never null).
+ */
+ default Map getQueryParameters() {
+ return Collections.emptyMap();
+ }
+
+ /**
+ * Gets the request ID for this request (from the {@code x-request-id} header
+ * or auto-generated). Useful for correlation in logs and downstream calls.
+ *
+ * @return the request ID, or {@code null} if not set.
+ */
+ default String getRequestId() {
+ return null;
+ }
+
+ /**
+ * Gets the resolved session ID for this request, per the Responses Protocol
+ * Spec.
+ *
+ * Priority chain:
+ *
+ * - {@code request.agent_session_id} payload field (client-supplied).
+ * - {@code FOUNDRY_AGENT_SESSION_ID} environment variable (platform-supplied
+ * when running in a Foundry hosted container).
+ * - Deterministic SHA-256 derivation from agent identity + partition source
+ * ({@code conversation_id} or {@code previous_response_id}), or a random
+ * value when no conversational context exists.
+ *
+ * Handlers should prefer this value over reading
+ * {@code FoundryEnvironment.SESSION_ID} directly: it is request-scoped (so it
+ * stays correct if the hosting model ever supports multiple sessions per
+ * container) and honors client-supplied {@code agent_session_id} overrides.
+ *
+ * @return the resolved session ID (never null/empty when the context was
+ * created by the platform; may be {@code null} for test-constructed
+ * contexts that did not supply one).
+ */
+ default String getSessionId() {
+ return null;
+ }
+
+ /**
+ * Builder for constructing {@link ResponseContext} instances.
+ *
+ * All parameters are set via fluent setters. Required parameters
+ * ({@code responseId}, {@code provider}, {@code request}) are validated
+ * when {@link #build()} is called.
+ *
+ *
{@code
+ * ResponseContext ctx = ResponseContext.builder()
+ * .responseId(responseId)
+ * .provider(provider)
+ * .request(params)
+ * .rawBody(jsonNode)
+ * .historyLimit(50)
+ * .build();
+ * }
+ */
+ final class Builder {
+ private String responseId;
+ private ResponsesProvider provider;
+ private ResponseCreateParams.Body request;
+ private JsonNode rawBody;
+ private Integer historyLimit;
+ private IsolationContext isolation;
+ private Map clientHeaders;
+ private Map queryParameters;
+ private String requestId;
+ private String sessionId;
+
+ Builder() {
+ }
+
+ /**
+ * Sets the unique response identifier (required).
+ *
+ * @param responseId the response identifier.
+ * @return this builder.
+ */
+ public Builder responseId(String responseId) {
+ this.responseId = responseId;
+ return this;
+ }
+
+ /**
+ * Sets the responses provider for resolving item references and history (required).
+ *
+ * @param provider the responses' provider.
+ * @return this builder.
+ */
+ public Builder provider(ResponsesProvider provider) {
+ this.provider = provider;
+ return this;
+ }
+
+ /**
+ * Sets the create-response request body containing input items (required).
+ *
+ * @param request the request body.
+ * @return this builder.
+ */
+ public Builder request(ResponseCreateParams.Body request) {
+ this.request = request;
+ return this;
+ }
+
+ /**
+ * Sets the create-response request, extracting its body (required).
+ *
+ * @param request the create-response request.
+ * @return this builder.
+ */
+ public Builder request(ResponseCreateParams request) {
+ Objects.requireNonNull(request, "request must not be null");
+ this.request = request._body();
+ return this;
+ }
+
+ /**
+ * Sets the full raw JSON request body.
+ *
+ * @param rawBody the raw JSON body, or {@code null} if not available.
+ * @return this builder.
+ */
+ public Builder rawBody(JsonNode rawBody) {
+ this.rawBody = rawBody;
+ return this;
+ }
+
+ /**
+ * Sets the maximum number of history items to fetch.
+ * Defaults to {@link AgentServerResponseContext#DEFAULT_FETCH_HISTORY_COUNT} if not set.
+ *
+ * @param historyLimit the maximum number of history items.
+ * @return this builder.
+ */
+ public Builder historyLimit(int historyLimit) {
+ this.historyLimit = historyLimit;
+ return this;
+ }
+
+ /**
+ * Sets the platform-injected isolation context (optional).
+ * Defaults to {@link IsolationContext#EMPTY} if not set.
+ *
+ * @param isolation the isolation context.
+ * @return this builder.
+ */
+ public Builder isolation(IsolationContext isolation) {
+ this.isolation = isolation;
+ return this;
+ }
+
+ /**
+ * Sets the forwarded client headers (optional).
+ * These are headers prefixed with {@code x-client-} from the HTTP request.
+ *
+ * @param clientHeaders the client headers map.
+ * @return this builder.
+ */
+ public Builder clientHeaders(Map clientHeaders) {
+ this.clientHeaders = clientHeaders;
+ return this;
+ }
+
+ /**
+ * Sets the query parameters from the HTTP request (optional).
+ *
+ * @param queryParameters the query parameter map.
+ * @return this builder.
+ */
+ public Builder queryParameters(Map queryParameters) {
+ this.queryParameters = queryParameters;
+ return this;
+ }
+
+ /**
+ * Sets the request ID for correlation (optional).
+ *
+ * @param requestId the request ID.
+ * @return this builder.
+ */
+ public Builder requestId(String requestId) {
+ this.requestId = requestId;
+ return this;
+ }
+
+ /**
+ * Sets the resolved session ID for this request (optional).
+ *
+ * Typically set by the API layer from {@code SessionIdResolver}. Handlers
+ * read it back via {@link ResponseContext#getSessionId()}.
+ *
+ * @param sessionId the resolved session ID, or {@code null} if not available.
+ * @return this builder.
+ */
+ public Builder sessionId(String sessionId) {
+ this.sessionId = sessionId;
+ return this;
+ }
+
+ /**
+ * Builds and returns a new {@link ResponseContext} instance.
+ *
+ * @return the constructed {@link ResponseContext}.
+ * @throws NullPointerException if {@code responseId}, {@code provider}, or {@code request} is null.
+ */
+ public ResponseContext build() {
+ Objects.requireNonNull(responseId, "responseId must not be null");
+ Objects.requireNonNull(provider, "provider must not be null");
+ Objects.requireNonNull(request, "request must not be null");
+ return new AgentServerResponseContext(
+ responseId, provider, request, rawBody, historyLimit,
+ isolation, clientHeaders, queryParameters, requestId, sessionId);
+ }
+ }
+}
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseEvent.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseEvent.java
new file mode 100644
index 000000000000..00c8a933b872
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseEvent.java
@@ -0,0 +1,16 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import com.openai.models.responses.ResponseStreamEvent;
+
+/**
+ * Wraps a {@link ResponseStreamEvent} together with its SSE event name.
+ * Produced by {@link AgentServerResponseEventStream} emit methods and consumed by the SSE transport layer.
+ *
+ * @param eventName the SSE event name, e.g. {@code "response.created"}, {@code "response.output_text.delta"}
+ * @param streamEvent the wrapped OpenAI SDK stream event union
+ */
+public record ResponseEvent(String eventName, ResponseStreamEvent streamEvent) {
+}
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseEventStream.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseEventStream.java
new file mode 100644
index 000000000000..7f3930e40469
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseEventStream.java
@@ -0,0 +1,381 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import com.openai.core.http.StreamResponse;
+import com.openai.models.chat.completions.ChatCompletionChunk;
+import com.openai.models.responses.Response;
+import com.openai.models.responses.ResponseCodeInterpreterToolCall;
+import com.openai.models.responses.ResponseCustomToolCall;
+import com.openai.models.responses.ResponseError;
+import com.openai.models.responses.ResponseFileSearchToolCall;
+import com.openai.models.responses.ResponseFunctionWebSearch;
+import com.openai.models.responses.ResponseOutputItem;
+import com.openai.models.responses.ResponseReasoningItem;
+import com.openai.models.responses.ResponseStatus;
+import com.openai.models.responses.ResponseStreamEvent;
+import com.openai.models.responses.ResponseUsage;
+
+import java.util.List;
+import java.util.Objects;
+import java.util.function.Consumer;
+
+public interface ResponseEventStream {
+
+ /**
+ * Creates a new {@link Builder} for constructing {@link ResponseEventStream} instances.
+ *
+ * @return a new builder instance.
+ */
+ static Builder builder() {
+ return new Builder();
+ }
+
+ /**
+ * Creates a new event stream from a request and context.
+ *
+ * @param context the response context (required).
+ * @param request the create-response request (required).
+ * @return a new {@link ResponseEventStream}.
+ */
+ static ResponseEventStream create(ResponseContext context, AgentServerCreateResponse request) {
+ return AgentServerResponseEventStream.create(context, request);
+ }
+
+ List getEvents();
+
+ Response getResponse();
+
+ void subscribe(Consumer onEvent, Consumer onFailure, Runnable onComplete);
+
+ void awaitSubscription() throws InterruptedException;
+
+ ResponseEventStream emitQueued();
+
+ ResponseEventStream emitCreated();
+
+ ResponseEventStream emitCreated(ResponseStatus status);
+
+ ResponseEventStream emitInProgress();
+
+ ResponseEventStream emitCompleted();
+
+ ResponseEventStream emitCompleted(ResponseUsage usage);
+
+ ResponseEventStream emitFailed();
+
+ ResponseEventStream emitFailed(ResponseError.Code code, String message);
+
+ ResponseEventStream emitFailed(ResponseError.Code code, String message, ResponseUsage usage);
+
+ ResponseEventStream emitIncomplete();
+
+ ResponseEventStream emitIncomplete(Response.IncompleteDetails.Reason reason);
+
+ ResponseEventStream emitIncomplete(Response.IncompleteDetails.Reason reason, ResponseUsage usage);
+
+ ResponseEventStream addOutputMessage(Consumer config);
+
+ ResponseEventStream addOutputFunctionCall(Consumer config);
+
+ ResponseEventStream addOutputReasoningItem(Consumer> config);
+
+ ResponseEventStream addOutputFileSearchCall(Consumer> config);
+
+ ResponseEventStream addOutputWebSearchCall(Consumer> config);
+
+ ResponseEventStream addOutputCodeInterpreterCall(
+ Consumer> config);
+
+ ResponseEventStream addOutputImageGenCall(
+ Consumer> config);
+
+ ResponseEventStream addOutputMcpCall(Consumer> config);
+
+ ResponseEventStream addOutputMcpListTools(
+ Consumer> config);
+
+ ResponseEventStream addOutputCustomToolCall(Consumer> config);
+
+ ResponseEventStream addOutputItem(String itemId, Consumer> config);
+
+ ResponseEventStream emit(ResponseEvent event);
+
+ ResponseEventStream forwardUpstream(java.util.stream.Stream upstreamEvents);
+
+ void trackCompletedOutputItem(ResponseOutputItem outputItem, long outputIdx);
+
+ void addEvent(ResponseEvent responseEvent);
+
+ long nextSequenceNumber();
+
+ // ── Nested builder interfaces ───────────────────────────────
+
+ /**
+ * Fluent builder for a generic output item. Provides methods to emit
+ * {@code output_item.added} and {@code output_item.done} events.
+ *
+ * @param the output item model type
+ */
+ interface OutputItemBuilder {
+
+ /**
+ * Emits a {@code response.output_item.added} event for this item.
+ *
+ * @param item the output item to emit.
+ * @return this builder.
+ */
+ OutputItemBuilder emitAdded(T item);
+
+ /**
+ * Emits a {@code response.output_item.done} event for this item
+ * and tracks it in the parent stream's output list.
+ *
+ * @param item the completed output item.
+ * @return this builder.
+ */
+ OutputItemBuilder emitDone(T item);
+
+ /**
+ * Returns the auto-generated item ID for this output item.
+ */
+ String getItemId();
+ }
+
+ /**
+ * Fluent builder for a function call output item. Provides convenience methods
+ * for the common function call lifecycle: added, argument deltas, argument done,
+ * and item done.
+ *
+ * {@code
+ * stream.addOutputFunctionCall(func -> func
+ * .emitAdded("get_weather", "call_123")
+ * .emitArgumentsDelta("{\"location\":")
+ * .emitArgumentsDelta("\"Seattle\"}")
+ * .emitArgumentsDone("get_weather", "{\"location\":\"Seattle\"}")
+ * .emitDone());
+ * }
+ */
+ interface OutputFunctionCallBuilder {
+
+ /**
+ * Emits a {@code response.output_item.added} event with an in-progress function call.
+ *
+ * @param name the function name (e.g. "get_weather").
+ * @param callId the call ID for this function invocation.
+ * @return this builder.
+ */
+ OutputFunctionCallBuilder emitAdded(String name, String callId);
+
+ /**
+ * Emits a {@code response.function_call_arguments.delta} event and accumulates
+ * the arguments text.
+ *
+ * @param delta the argument text chunk.
+ * @return this builder.
+ */
+ OutputFunctionCallBuilder emitArgumentsDelta(String delta);
+
+ /**
+ * Emits a {@code response.function_call_arguments.done} event with the final
+ * function name and complete arguments string.
+ *
+ * @param name the function name.
+ * @param arguments the complete arguments JSON string.
+ * @return this builder.
+ */
+ OutputFunctionCallBuilder emitArgumentsDone(String name, String arguments);
+
+ /**
+ * Emits a {@code response.output_item.done} event with the completed function call
+ * and tracks it in the parent stream's output list.
+ *
+ * @return this builder.
+ */
+ OutputFunctionCallBuilder emitDone();
+
+ /**
+ * Returns the auto-generated item ID for this function call.
+ */
+ String getItemId();
+ }
+
+ /**
+ * Fluent builder for a message output item. Provides convenience methods
+ * for the common message lifecycle and lexically scoped text-part builders.
+ */
+ interface OutputMessageBuilder {
+
+ /**
+ * Emits a {@code response.output_item.added} event with an in-progress message.
+ *
+ * @return this builder.
+ */
+ OutputMessageBuilder emitAdded();
+
+ /**
+ * Adds a text content part. The consumer configures delta emissions within
+ * a lexically scoped block.
+ *
+ * @param config consumer that configures the text part builder.
+ * @return this builder.
+ */
+ OutputMessageBuilder addTextPart(Consumer config);
+
+ /**
+ * Convenience method that emits a complete text message in one call.
+ * Equivalent to:
+ * {@code
+ * msg.emitAdded()
+ * .addTextPart(text -> text.emitAdded().emitDelta(content).emitDone(content))
+ * .emitDone();
+ * }
+ *
+ * @param content the full text content to emit as a single delta and done event.
+ * @return this builder.
+ */
+ OutputMessageBuilder outputItemMessage(String content);
+
+ /**
+ * Emits a {@code response.output_item.done} event with the completed message
+ * and tracks it in the parent stream's output list.
+ *
+ * @return this builder.
+ */
+ OutputMessageBuilder emitDone();
+
+ /**
+ * Convenience method that streams a chat completion response as a single text
+ * message. Equivalent to:
+ * {@code
+ * emitAdded()
+ * .addTextPart(text -> text.emitAdded().streamDeltas(streamResponse))
+ * .emitDone();
+ * }
+ *
+ * Each token from the LLM is forwarded as a {@code response.output_text.delta}
+ * event in real time, giving callers a true streaming experience.
+ *
+ * @param streamResponse the streaming response from
+ * {@code client.chat().completions().createStreaming(params)}.
+ * @return this builder for chaining.
+ */
+ OutputMessageBuilder streamChatCompletion(StreamResponse streamResponse);
+
+ /**
+ * Returns the auto-generated item ID for this message.
+ */
+ String getItemId();
+ }
+
+ /**
+ * Fluent builder for a text content part within a message.
+ * Tracks accumulated delta text for the final {@code content_part.done} event.
+ */
+ interface TextPartBuilder {
+
+ /**
+ * Emits a {@code response.content_part.added} event with an empty text part.
+ *
+ * @return this builder.
+ */
+ TextPartBuilder emitAdded();
+
+ /**
+ * Emits a {@code response.output_text.delta} event and accumulates the text.
+ *
+ * @param delta the text chunk.
+ * @return this builder.
+ */
+ TextPartBuilder emitDelta(String delta);
+
+ /**
+ * Emits a {@code response.output_text.done} event with the final text.
+ *
+ * @param text the final text value.
+ * @return this builder.
+ */
+ TextPartBuilder emitDone(String text);
+
+ /**
+ * Consumes a streaming chat completion response and pipes each token into
+ * {@link #emitDelta(String)}. The stream is fully consumed (and closed) before
+ * this method returns, so callers should not close the {@link StreamResponse}
+ * themselves. {@link #emitDone} is not called by this method; the
+ * auto-done logic in {@code addTextPart} handles it, or the caller may chain
+ * {@code .emitDone(...)} explicitly.
+ *
+ * {@code
+ * stream.addOutputMessage(msg -> msg
+ * .emitAdded()
+ * .addTextPart(text -> text
+ * .emitAdded()
+ * .streamDeltas(chatCompletionStreamResponse))
+ * .emitDone());
+ * }
+ *
+ * @param streamResponse the streaming response from
+ * {@code client.chat().completions().createStreaming(params)}.
+ * @return this builder for chaining.
+ */
+ TextPartBuilder streamDeltas(StreamResponse streamResponse);
+ }
+
+ // ── ResponseEventStream.Builder ─────────────────────────────
+
+ /**
+ * Builder for constructing {@link ResponseEventStream} instances.
+ *
+ * All parameters are set via fluent setters. Required parameters
+ * ({@code context}, {@code request}) are validated when {@link #build()} is called.
+ *
+ *
{@code
+ * ResponseEventStream stream = ResponseEventStream.builder()
+ * .context(responseContext)
+ * .request(createResponse)
+ * .build();
+ * }
+ */
+ final class Builder {
+ private ResponseContext context;
+ private AgentServerCreateResponse request;
+
+ Builder() {
+ }
+
+ /**
+ * Sets the response context (required).
+ *
+ * @param context the response context.
+ * @return this builder.
+ */
+ public Builder context(ResponseContext context) {
+ this.context = context;
+ return this;
+ }
+
+ /**
+ * Sets the create-response request (required).
+ *
+ * @param request the create-response request.
+ * @return this builder.
+ */
+ public Builder request(AgentServerCreateResponse request) {
+ this.request = request;
+ return this;
+ }
+
+ /**
+ * Builds and returns a new {@link ResponseEventStream} instance.
+ *
+ * @return the constructed {@link ResponseEventStream}.
+ * @throws NullPointerException if {@code context} or {@code request} is null.
+ */
+ public ResponseEventStream build() {
+ Objects.requireNonNull(context, "context must not be null");
+ Objects.requireNonNull(request, "request must not be null");
+ return AgentServerResponseEventStream.create(context, request);
+ }
+ }
+}
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseHandler.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseHandler.java
new file mode 100644
index 000000000000..0299215bd4e3
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseHandler.java
@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+/**
+ * Handler interface for processing incoming response requests.
+ *
+ * Implementors must override at least one of the two methods:
+ *
+ * - {@link #createAsync} — for streaming responses (SSE)
+ * - {@link #createResponse} — for non-streaming (synchronous) responses
+ *
+ */
+public interface ResponseHandler {
+
+ /**
+ * Creates a streaming response from a {@link AgentServerCreateResponse}.
+ * Used by the server adapter when dispatching incoming streaming HTTP requests.
+ *
+ * @param responseContext the context for this response (ID, provider, history)
+ * @param request the deserialized create-response request
+ * @return an event stream that produces SSE events as the response is generated
+ * @throws UnsupportedOperationException if the handler does not support streaming
+ */
+ default ResponseEventStream createAsync(
+ ResponseContext responseContext,
+ AgentServerCreateResponse request
+ ) {
+ throw new UnsupportedOperationException(
+ "Streaming responses (createAsync) are not implemented by this handler. "
+ + "Override createAsync() to support streaming.");
+ }
+
+ /**
+ * Creates a synchronous (non-streaming) response from a {@link AgentServerCreateResponse}.
+ * Used by the server adapter when dispatching incoming non-streaming HTTP requests.
+ *
+ * @param responseContext the context for this response (ID, provider, history)
+ * @param request the deserialized create-response request
+ * @return the completed response
+ * @throws UnsupportedOperationException if the handler does not support synchronous responses
+ */
+ default CreateResponse createResponse(
+ ResponseContext responseContext,
+ AgentServerCreateResponse request
+ ) {
+ throw new UnsupportedOperationException(
+ "Synchronous responses (createResponse) are not implemented by this handler. "
+ + "Override createResponse() to support non-streaming.");
+ }
+}
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseStreamReplay.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseStreamReplay.java
new file mode 100644
index 000000000000..8a0788af7032
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponseStreamReplay.java
@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import java.util.List;
+
+/**
+ * The result of replaying the stored Server-Sent Events for a background
+ * streaming response.
+ *
+ * Each {@link ReplayEvent} carries the SSE event name and the JSON payload exactly
+ * as it was emitted (including the {@code sequence_number} field). The adapter
+ * writes them to the wire as {@code event: {name}\ndata: {data}\n\n}.
+ *
+ * @param events the ordered list of replayable events (already filtered by the
+ * {@code starting_after} cursor when provided)
+ */
+public record ResponseStreamReplay(List events) {
+
+ /**
+ * A single replayable SSE event.
+ *
+ * @param sequenceNumber the 0-based monotonically increasing sequence number
+ * @param eventName the SSE event name, e.g. {@code "response.created"}
+ * @param data the JSON payload (includes {@code sequence_number})
+ */
+ public record ReplayEvent(long sequenceNumber, String eventName, String data) {
+ }
+}
+
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponsesApi.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponsesApi.java
new file mode 100644
index 000000000000..6f8162692370
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponsesApi.java
@@ -0,0 +1,292 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import com.microsoft.agentserver.api.implementation.FoundryStorageProvider;
+import com.microsoft.agentserver.api.implementation.InMemoryResponseProvider;
+import com.openai.models.responses.Response;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * Defines the contract for the OpenAI Responses API as hosted by the
+ * Azure AI Foundry agent server infrastructure.
+ *
+ * This interface is framework-agnostic — it uses only domain types and can be
+ * implemented without any dependency on a specific HTTP framework (JAX-RS, Spring, etc.).
+ * Framework-specific adapters (e.g., {@code java-agent-server-api-jaxrs}) provide
+ * the HTTP transport layer on top of this interface.
+ */
+public interface ResponsesApi {
+
+ /**
+ * Creates a new {@link Builder} for constructing {@link ResponsesApi} instances.
+ *
+ * @return a new builder instance.
+ */
+ static Builder builder() {
+ return new Builder();
+ }
+
+ static ResponsesApi create(ResponseHandler handler) {
+ return ResponsesApi.builder().responseHandler(handler).build();
+ }
+
+ /**
+ * Creates a synchronous (non-streaming) model response.
+ *
+ * @param createResponse the create-response request
+ * @return the completed response
+ * @throws ApiException if the request is invalid or processing fails
+ */
+ CreateResponse createResponse(AgentServerCreateResponse createResponse) throws ApiException;
+
+ /**
+ * Creates a synchronous (non-streaming) model response with HTTP request metadata.
+ * The metadata (isolation keys, client headers, query parameters, request ID) is
+ * propagated to the {@link ResponseContext} available to handlers.
+ *
+ * @param createResponse the create-response request
+ * @param metadata the HTTP request metadata
+ * @return the completed response
+ * @throws ApiException if the request is invalid or processing fails
+ */
+ default CreateResponse createResponse(AgentServerCreateResponse createResponse, RequestMetadata metadata) throws ApiException {
+ return createResponse(createResponse);
+ }
+
+ /**
+ * Creates a streaming model response, returning an event stream that produces
+ * Server-Sent Events as the response is generated.
+ *
+ * @param createResponse the create-response request
+ * @return the event stream for streaming delivery
+ * @throws ApiException if the request is invalid or processing fails
+ */
+ ResponseEventStream createStreamingResponse(AgentServerCreateResponse createResponse) throws ApiException;
+
+ /**
+ * Creates a streaming model response with HTTP request metadata.
+ * The metadata (isolation keys, client headers, query parameters, request ID) is
+ * propagated to the {@link ResponseContext} available to handlers.
+ *
+ * @param createResponse the create-response request
+ * @param metadata the HTTP request metadata
+ * @return the event stream for streaming delivery
+ * @throws ApiException if the request is invalid or processing fails
+ */
+ default ResponseEventStream createStreamingResponse(AgentServerCreateResponse createResponse, RequestMetadata metadata) throws ApiException {
+ return createStreamingResponse(createResponse);
+ }
+
+ /**
+ * Retrieves a previously stored response by ID.
+ *
+ * @param responseId the response identifier
+ * @param include optional list of fields to include
+ * @return the stored response
+ * @throws ApiException if the response is not found or retrieval fails
+ */
+ Response getResponse(String responseId, List include) throws ApiException;
+
+ /**
+ * Variant that accepts the inbound {@link RequestMetadata} so the API layer
+ * can forward platform isolation headers to the storage backend. Required
+ * for {@code FoundryStorageProvider}, which partitions stored responses by
+ * isolation key — a GET without the matching headers returns 404 even when
+ * the response exists.
+ *
+ * @param responseId the response identifier
+ * @param include optional list of fields to include
+ * @param metadata the inbound request metadata (may be {@link RequestMetadata#EMPTY})
+ * @return the stored response
+ * @throws ApiException if the response is not found or retrieval fails
+ */
+ default Response getResponse(String responseId, List include, RequestMetadata metadata) throws ApiException {
+ return getResponse(responseId, include);
+ }
+
+ /**
+ * Cancels a background response that is still queued or in progress.
+ *
+ * Behaviour follows the API spec:
+ *
+ * - If the response does not exist (or was never persisted) → {@link ApiException} 404.
+ * - If the response was not created with {@code background=true} → {@link ApiException}
+ * 400 ({@code "Cannot cancel a synchronous response."}). The background check happens
+ * first, before status checks.
+ * - If the response is already {@code cancelled} → returns it unchanged (idempotent).
+ * - If the response is in a terminal state ({@code completed}/{@code failed}/{@code incomplete})
+ * → {@link ApiException} 400 with the corresponding message.
+ * - If the response is {@code queued} or {@code in_progress} → it winds down to
+ * {@code cancelled} with its output cleared and the cancelled
+ * {@link Response} is returned.
+ *
+ *
+ * @param responseId the response identifier
+ * @return the cancelled (or already-cancelled) response
+ * @throws ApiException with status 404 if not found, or 400 if the response cannot be cancelled
+ */
+ Response cancelResponse(String responseId) throws ApiException;
+
+ /**
+ * Signals that the HTTP client disconnected from a non-background response
+ * before processing completed. For non-background responses the
+ * implementation winds down to {@code cancelled} (output cleared,
+ * cancelled snapshot persisted if {@code store=true}) and prevents the
+ * normal terminal persistence from overwriting it. For background responses
+ * this is a no-op.
+ *
+ * Safe to call unconditionally from the adapter on disconnect detection —
+ * if no in-flight execution matches the ID, the call is a no-op.
+ *
+ * @param responseId the in-flight response identifier whose client disconnected
+ */
+ default void signalClientDisconnected(String responseId) {
+ // No-op default keeps the interface backward compatible for custom impls.
+ }
+
+ /**
+ * Replays the stored SSE event sequence for a background streaming response.
+ * Triggered by
+ * {@code GET /responses/{id}?stream=true}.
+ *
+ * Preconditions: the response must have been created with
+ * {@code store=true}, {@code background=true} and {@code stream=true}.
+ *
+ * - Not found / {@code store=false} → {@link ApiException} 404.
+ * - {@code background=false} → {@link ApiException} 400
+ * ({@code "This response cannot be streamed because it was not created with background=true."}).
+ * - {@code stream=false} → {@link ApiException} 400
+ * ({@code "This response cannot be streamed because it was not created with stream=true."}).
+ *
+ * Otherwise returns the events with {@code sequence_number > startingAfter};
+ * if {@code startingAfter} is at or beyond the last sequence number,
+ * the returned list is empty.
+ *
+ * @param responseId the response identifier
+ * @param startingAfter replay only events with a greater sequence number, or {@code null} for all
+ * @return the (possibly empty) replay event sequence
+ * @throws ApiException 404 if not found/not stored, 400 if not replayable
+ */
+ ResponseStreamReplay replayResponseStream(String responseId, Integer startingAfter) throws ApiException;
+
+ /**
+ * Deletes a previously stored response by ID.
+ *
+ * @param responseId the response identifier
+ * @throws ApiException if deletion fails
+ */
+ void deleteResponse(String responseId) throws ApiException;
+
+ /**
+ * Returns a paginated list of input items for a given response.
+ *
+ * @param responseId the response identifier
+ * @param limit maximum number of items to return (default 20, range 1-100)
+ * @param order sort order ({@code "asc"} or {@code "desc"})
+ * @param after cursor for forward pagination — return items after this item ID
+ * @param before cursor for backward pagination — return items before this item ID
+ * @param include optional list of fields to include
+ * @return the paginated item list
+ * @throws ApiException if the response is not found or retrieval fails
+ */
+ AgentServerResponseItemList listInputItems(
+ String responseId,
+ Integer limit,
+ String order,
+ String after,
+ String before,
+ List include) throws ApiException;
+
+ /**
+ * Builder for constructing {@link ResponsesApi} instances backed by
+ * {@link AgentServerResponsesApi}.
+ *
+ * All parameters are set via fluent setters. The {@code responseHandler} is required
+ * and validated when {@link #build()} is called. The {@code provider} is optional —
+ * if not set, an appropriate provider is resolved automatically based on the
+ * hosting environment.
+ *
+ *
{@code
+ * ResponsesApi api = ResponsesApi.builder()
+ * .responseHandler(myHandler)
+ * .provider(myProvider)
+ * .build();
+ * }
+ */
+ final class Builder {
+ private static final Logger LOGGER = LoggerFactory.getLogger(ResponsesApi.class);
+
+ private ResponseHandler responseHandler;
+ private ResponsesProvider provider;
+
+ Builder() {
+ }
+
+ private static ResponsesProvider resolveProvider() {
+ // : when FOUNDRY_HOSTING_ENVIRONMENT is set, the SDK MUST auto-activate
+ // the Foundry state provider for durable, multi-instance persistence.
+ if (FoundryEnvironment.IS_HOSTED) {
+ try {
+ FoundryStorageProvider provider = FoundryStorageProvider.fromEnvironment();
+ LOGGER.info("Hosted environment detected (FOUNDRY_HOSTING_ENVIRONMENT set). "
+ + "Using FoundryStorageProvider.");
+ return provider;
+ } catch (RuntimeException e) {
+ // Hosted but FOUNDRY_PROJECT_ENDPOINT is missing/invalid — log and fall
+ // back to in-memory rather than failing startup, so the container can
+ // still serve health probes for diagnosis.
+ LOGGER.error("Failed to initialise FoundryStorageProvider in hosted mode; "
+ + "falling back to InMemoryResponseProvider. Cause: {}", e.getMessage());
+ }
+ } else {
+ LOGGER.debug("Local environment detected. Using InMemoryResponseProvider.");
+ }
+ return new InMemoryResponseProvider();
+ }
+
+ /**
+ * Sets the response handler that generates responses (required).
+ *
+ * @param responseHandler the response handler.
+ * @return this builder.
+ */
+ public Builder responseHandler(ResponseHandler responseHandler) {
+ this.responseHandler = responseHandler;
+ return this;
+ }
+
+ /**
+ * Sets the responses provider for state persistence (optional).
+ *
+ * If not set, a provider is resolved automatically based on the hosting
+ * environment (Foundry storage in hosted environments, in-memory locally).
+ *
+ * @param provider the responses' provider.
+ * @return this builder.
+ */
+ public Builder provider(ResponsesProvider provider) {
+ this.provider = provider;
+ return this;
+ }
+
+ /**
+ * Builds and returns a new {@link ResponsesApi} instance.
+ *
+ * @return the constructed {@link ResponsesApi}.
+ * @throws NullPointerException if {@code responseHandler} is null.
+ */
+ public ResponsesApi build() {
+ Objects.requireNonNull(responseHandler, "responseHandler must not be null");
+ if (provider == null) {
+ provider = resolveProvider();
+ }
+ return new AgentServerResponsesApi(responseHandler, provider);
+ }
+ }
+}
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponsesProvider.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponsesProvider.java
new file mode 100644
index 000000000000..b4a7dd1e85d4
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/ResponsesProvider.java
@@ -0,0 +1,147 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import com.microsoft.agentserver.api.implementation.InMemoryResponseProvider;
+import com.openai.models.responses.ResponseItem;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Provides pluggable response state persistence for the Responses API server.
+ *
+ * Items are stored as {@link ResponseItem}, a union type that naturally carries
+ * role information: {@code ResponseInputMessageItem} (user/system/developer) vs
+ * {@code ResponseOutputMessage} (assistant), plus tool calls and other item types.
+ *
+ * When no custom implementation is registered, the SDK provides an in-memory default.
+ */
+public interface ResponsesProvider {
+
+ static ResponsesProvider inMemory() {
+ return new InMemoryResponseProvider();
+ }
+
+ /**
+ * Retrieves items by their identifiers (batch lookup).
+ * Items not found are returned as {@code null} entries.
+ *
+ * @param itemIds the item identifiers to look up.
+ * @return a future containing items matching the requested IDs
+ * ({@code null} for missing entries).
+ */
+ CompletableFuture> getItemsAsync(List itemIds);
+
+ /**
+ * Retrieves the list of history item IDs for a conversation chain,
+ * starting from a previous response and/or conversation ID.
+ *
+ * @param previousResponseId the previous response ID to look up history from, or {@code null}.
+ * @param conversationId the conversation ID to scope history, or {@code null}.
+ * @param limit maximum number of history item IDs to return.
+ * @return a future containing an ordered list of history item IDs.
+ */
+ CompletableFuture> getHistoryItemIdsAsync(
+ String previousResponseId,
+ String conversationId,
+ int limit);
+
+ /**
+ * Persists a completed response and its output items.
+ *
+ * @param responseId the response ID.
+ * @param response the full response object.
+ * @param previousResponseId the previous response ID, or {@code null}.
+ * @param conversationId the conversation ID, or {@code null}.
+ * @return a future that completes when persistence is done.
+ */
+ CompletableFuture saveResponseAsync(
+ String responseId,
+ com.openai.models.responses.Response response,
+ String previousResponseId,
+ String conversationId);
+
+ /**
+ * Persists the resolved input items for a response, so they appear
+ * in conversation history before the output items.
+ *
+ * @param responseId the response ID these input items belong to.
+ * @param inputItems the resolved input items as {@link ResponseItem}s.
+ * @return a future that completes when persistence is done.
+ */
+ default CompletableFuture saveInputItemsAsync(
+ String responseId,
+ List inputItems) {
+ return CompletableFuture.completedFuture(null);
+ }
+
+ /**
+ * Creates a response in storage with its input items and history in a single
+ * atomic operation (envelope format). This matches the Foundry storage API
+ * contract used by the C# and Python SDKs.
+ *
+ * The default implementation delegates to {@link #saveResponseAsync} for
+ * backward compatibility with in-memory providers.
+ *
+ * @param responseId the response ID.
+ * @param response the full response object.
+ * @param inputItems the resolved input items.
+ * @param historyItemIds the history item IDs from prior conversation turns.
+ * @return a future that completes when persistence is done.
+ */
+ default CompletableFuture createResponseAsync(
+ String responseId,
+ com.openai.models.responses.Response response,
+ List inputItems,
+ List historyItemIds) {
+ // Default: delegate to the legacy separate-call pattern
+ return saveResponseAsync(responseId, response, null, null);
+ }
+
+ /**
+ * Retrieves the stored input items for a given response.
+ * These are the items that were sent as input when the response was created.
+ *
+ * @param responseId the response ID.
+ * @return a future containing the input items, or an empty list if not found.
+ */
+ default CompletableFuture> getInputItemsForResponseAsync(String responseId) {
+ return CompletableFuture.completedFuture(List.of());
+ }
+
+ /**
+ * Retrieves a previously stored response by its ID.
+ *
+ * @param responseId the response ID.
+ * @return a future containing the response, or empty if not found.
+ */
+ CompletableFuture> getResponseAsync(String responseId);
+
+ /**
+ * Retrieves a previously stored response by its ID, forwarding the inbound
+ * request's platform isolation headers to the backend (required by Foundry
+ * storage, which partitions responses by isolation key — a GET without the
+ * matching headers returns 404 even though the response exists).
+ *
+ * Default implementation ignores isolation for in-memory providers.
+ *
+ * @param responseId the response ID.
+ * @param isolation the inbound isolation context (may be {@code null} for tests / local runs).
+ * @return a future containing the response, or empty if not found.
+ */
+ default CompletableFuture> getResponseAsync(
+ String responseId, IsolationContext isolation) {
+ return getResponseAsync(responseId);
+ }
+
+ /**
+ * Deletes a previously stored response by its ID.
+ *
+ * @param responseId the response ID.
+ * @return a future that completes when deletion is done.
+ */
+ CompletableFuture deleteResponseAsync(String responseId);
+}
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/SessionIdResolver.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/SessionIdResolver.java
new file mode 100644
index 000000000000..03ed5da92b3d
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/SessionIdResolver.java
@@ -0,0 +1,184 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api;
+
+import com.microsoft.agentserver.api.implementation.IdGenerator;
+import com.openai.core.JsonValue;
+import com.openai.models.responses.ResponseCreateParams;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.security.SecureRandom;
+import java.util.Locale;
+import java.util.Optional;
+
+/**
+ * Resolves the {@code agent_session_id} for a response, per the Responses
+ * the protocol spec and.
+ *
+ * Priority chain:
+ *
+ * - {@code request.agent_session_id} — payload-level client-supplied affinity.
+ * - {@code FOUNDRY_AGENT_SESSION_ID} environment variable — platform-supplied.
+ * - Deterministic derivation — SHA-256 of {@code "agentName:agentVersion:partitionHint"},
+ * first 63 lowercase hex characters. Falls back to a random 63-char lowercase
+ * hex when no conversational context (no {@code conversation_id} /
+ * {@code previous_response_id}) is present.
+ *
+ * The resolved value is always 63 lowercase hex characters (or whatever the
+ * client supplied at tier 1 — that string is returned unchanged).
+ */
+final class SessionIdResolver {
+
+ /**
+ * Output length of the deterministic derivation.
+ */
+ private static final int HEX_LENGTH = 63;
+
+ /**
+ * Default agent name when {@code agent_reference.name} is absent or empty.
+ */
+ private static final String DEFAULT_AGENT_NAME = "server-default-agent";
+
+ private static final SecureRandom RANDOM = new SecureRandom();
+
+ private SessionIdResolver() {
+ }
+
+ /**
+ * Resolves the session ID for the given request.
+ *
+ * @param request the create-response request (non-null)
+ * @param envSessionId the value of {@code FOUNDRY_AGENT_SESSION_ID}, or {@code null}/empty
+ * @return the resolved session ID (never null/empty)
+ */
+ static String resolve(AgentServerCreateResponse request, String envSessionId) {
+ // Tier 1: client-supplied payload field.
+ String fromPayload = extractPayloadSessionId(request);
+ if (isNonEmpty(fromPayload)) {
+ return fromPayload;
+ }
+ // Tier 2: platform-supplied environment variable.
+ if (isNonEmpty(envSessionId)) {
+ return envSessionId;
+ }
+ // Tier 3: deterministic derivation (or random if no context).
+ return derive(request);
+ }
+
+ /**
+ * Returns the {@code agent_session_id} value from the request body's top-level
+ * additional properties, or {@code null} when absent / wrong type / empty.
+ */
+ private static String extractPayloadSessionId(AgentServerCreateResponse request) {
+ try {
+ ResponseCreateParams.Body body = request.responseCreateParams();
+ if (body == null) {
+ return null;
+ }
+ JsonValue val = body._additionalProperties().get("agent_session_id");
+ if (val == null) {
+ return null;
+ }
+ @SuppressWarnings("unchecked")
+ Optional str = val.asString();
+ return str.filter(SessionIdResolver::isNonEmpty).orElse(null);
+ } catch (Exception e) {
+ return null;
+ }
+ }
+
+ /**
+ * Computes the deterministic session ID per Tier 3 of the algorithm.
+ */
+ private static String derive(AgentServerCreateResponse request) {
+ ResponseCreateParams.Body body = request.responseCreateParams();
+
+ // Select partition source: conversation_id wins, then previous_response_id,
+ // else random.
+ String partitionSource = null;
+ if (body != null) {
+ Optional convId = body.conversation().flatMap(c -> {
+ if (c.isId()) {
+ return Optional.of(c.asId());
+ }
+ if (c.isResponseConversationParam()) {
+ return Optional.of(c.asResponseConversationParam().id());
+ }
+ return Optional.empty();
+ }).filter(SessionIdResolver::isNonEmpty);
+
+ if (convId.isPresent()) {
+ partitionSource = convId.get();
+ } else {
+ Optional prev = body.previousResponseId().filter(SessionIdResolver::isNonEmpty);
+ if (prev.isPresent()) {
+ partitionSource = prev.get();
+ }
+ }
+ }
+
+ if (partitionSource == null) {
+ return randomHex();
+ }
+
+ // Extract the 18-char partition key if the source is a well-formed Foundry ID;
+ // otherwise use the raw value as the hint.
+ String partitionHint;
+ try {
+ partitionHint = IdGenerator.extractPartitionKey(partitionSource);
+ } catch (RuntimeException ex) {
+ partitionHint = partitionSource;
+ }
+
+ // Agent identity.
+ String agentName = DEFAULT_AGENT_NAME;
+ String agentVersion = "";
+ AgentReference ref = request.agent();
+ if (ref != null) {
+ if (isNonEmpty(ref.name())) {
+ agentName = ref.name();
+ }
+ if (ref.version() != null) {
+ agentVersion = ref.version();
+ }
+ }
+
+ String seed = agentName + ":" + agentVersion + ":" + partitionHint;
+ return sha256Hex(seed).substring(0, HEX_LENGTH);
+ }
+
+ private static String randomHex() {
+ // 63 chars → 32 bytes (we'll truncate the trailing nibble).
+ byte[] bytes = new byte[(HEX_LENGTH + 1) / 2];
+ RANDOM.nextBytes(bytes);
+ return toHex(bytes).substring(0, HEX_LENGTH);
+ }
+
+ private static String sha256Hex(String input) {
+ try {
+ byte[] digest = MessageDigest.getInstance("SHA-256")
+ .digest(input.getBytes(StandardCharsets.UTF_8));
+ return toHex(digest);
+ } catch (NoSuchAlgorithmException e) {
+ throw new IllegalStateException("SHA-256 not available", e);
+ }
+ }
+
+ private static String toHex(byte[] bytes) {
+ StringBuilder sb = new StringBuilder(bytes.length * 2);
+ for (byte b : bytes) {
+ sb.append(Character.forDigit((b >> 4) & 0xF, 16));
+ sb.append(Character.forDigit(b & 0xF, 16));
+ }
+ // Already lowercase via Character.forDigit.
+ return sb.toString().toLowerCase(Locale.ROOT);
+ }
+
+ private static boolean isNonEmpty(String s) {
+ return s != null && !s.isEmpty();
+ }
+}
+
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/TrustStoreInstaller.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/TrustStoreInstaller.java
new file mode 100644
index 000000000000..9e706981ccdf
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/TrustStoreInstaller.java
@@ -0,0 +1,635 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.agentserver.api;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.SSLEngine;
+import javax.net.ssl.TrustManager;
+import javax.net.ssl.TrustManagerFactory;
+import javax.net.ssl.X509ExtendedTrustManager;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.net.InetSocketAddress;
+import java.net.Socket;
+import java.net.SocketAddress;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.security.GeneralSecurityException;
+import java.security.KeyStore;
+import java.security.MessageDigest;
+import java.security.cert.CertPathBuilder;
+import java.security.cert.CertStore;
+import java.security.cert.Certificate;
+import java.security.cert.CertificateException;
+import java.security.cert.CertificateFactory;
+import java.security.cert.CollectionCertStoreParameters;
+import java.security.cert.PKIXBuilderParameters;
+import java.security.cert.PKIXCertPathBuilderResult;
+import java.security.cert.TrustAnchor;
+import java.security.cert.X509CertSelector;
+import java.security.cert.X509Certificate;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Enumeration;
+import java.util.HashSet;
+import java.util.HexFormat;
+import java.util.List;
+import java.util.Locale;
+import java.util.Objects;
+import java.util.Set;
+import java.util.function.Predicate;
+
+/**
+ * Utility for installing additional trusted CA certificates into the JVM at runtime without
+ * mutating the JDK's {@code cacerts} file or the OS certificate bundle.
+ *
+ * Two layers are available, configurable independently per call:
+ *
+ * - Merged keystore install. The JDK default {@code cacerts} is loaded
+ * into memory, the supplied certificate(s) are added, the merged keystore is written
+ * to a temporary file, and the JVM system properties {@code javax.net.ssl.trustStore}
+ * / {@code javax.net.ssl.trustStorePassword} / {@code javax.net.ssl.trustStoreType}
+ * are pointed at it. HTTP clients that consult these properties (notably reactor-netty
+ * inside {@code azure-core-http-netty}) will then trust the added cert globally.
+ * - Host-scoped JVM-default {@link SSLContext}. When a host predicate
+ * is supplied, a composite trust manager is built that consults the added cert only
+ * for hosts matched by the predicate (the JDK default trust set applies to every other
+ * host) and is registered via {@link SSLContext#setDefault(SSLContext)}. Code paths
+ * using the JVM-default {@code SSLContext} pick it up automatically; reactor-netty's
+ * default {@code HttpClient} does not — see the caveat on
+ * {@link #installAdcEgressProxyCertificate(Logger, Predicate)}.
+ *
+ *
+ * This must be invoked before any code triggers initialization of the
+ * default {@link SSLContext} (i.e. before the first outbound HTTPS call), otherwise the
+ * change will not take effect for the current JVM.
+ *
+ *
For every certificate added, the installer logs an audit line capturing subject DN,
+ * issuer DN, validity window, serial number, SHA-256 fingerprint, and a PKIX chain summary.
+ *
+ *
Primary use case — ADC egress proxy CA
+ * In the Azure AI Foundry vNext ("ADC") hosting environment, traffic to the Foundry project
+ * endpoint (matching {@link #defaultAdcProxiedHosts()}) is TLS-terminated by an egress proxy
+ * whose CA cert is mounted at {@link #ADC_EGRESS_PROXY_CA_CERT}. The recommended bootstrap
+ * is a single call from {@code main()}:
+ * {@code
+ * TrustStoreInstaller.installAdcEgressProxyCertificate();
+ * }
+ * This performs both layers above against the mounted proxy CA, with host-scoping defaulted
+ * to {@link #defaultAdcProxiedHosts()}. Use {@link #installAdcEgressProxyCertificate(Logger)}
+ * to route the audit log through your application logger, or
+ * {@link #installAdcEgressProxyCertificate(Logger, Predicate)} to override the host-scoping
+ * predicate. To install an arbitrary (non-ADC) proxy CA, use
+ * {@link #installProxyCertificate(Logger, Predicate, Path, String)}.
+ */
+public final class TrustStoreInstaller {
+
+ private static final Logger LOGGER = LoggerFactory.getLogger(TrustStoreInstaller.class);
+ private static final String DEFAULT_CACERTS_PASSWORD = "changeit";
+
+ /**
+ * Well-known path at which the Azure Agent Server (vNext "ADC" hosting environment) mounts
+ * the egress proxy CA certificate required for outbound HTTPS calls to Foundry endpoints.
+ * Absent when running locally.
+ */
+ public static final Path ADC_EGRESS_PROXY_CA_CERT =
+ Paths.get("/etc/ssl/certs/adc-egress-proxy-ca.crt");
+
+ private TrustStoreInstaller() {
+ }
+
+ /**
+ * Returns the caller-supplied logger when non-null, otherwise the class-static logger.
+ * Used so that callers may opt-in to routing lifecycle messages through their own
+ * application-configured SLF4J logger while still getting sensible defaults when they
+ * pass {@code null}.
+ *
+ * @param logger optional caller-supplied logger; may be {@code null}.
+ * @return {@code logger} when non-null, otherwise the class-static logger.
+ */
+ private static Logger logger(Logger logger) {
+ return logger != null ? logger : LOGGER;
+ }
+
+ /**
+ * Installs the Azure Agent Server (ADC) egress proxy CA certificate from the well-known
+ * mount path {@code /etc/ssl/certs/adc-egress-proxy-ca.crt}, applying both layers documented
+ * on the class JavaDoc: the merged-keystore install and a host-scoped JVM-default
+ * {@link SSLContext} scoped to {@link #defaultAdcProxiedHosts()}. This is the recommended
+ * one-line bootstrap from {@code main()}. Uses the class-static SLF4J logger for lifecycle
+ * messages — call {@link #installAdcEgressProxyCertificate(Logger)} to route them through
+ * your own application logger instead.
+ *
+ * No-op when the certificate file is not present (e.g. when running locally outside
+ * the ADC hosting environment), so it is safe to call unconditionally during startup.
+ *
+ * @return {@code true} if the certificate was found and installed, {@code false} otherwise.
+ * @throws IOException if reading the cert or default cacerts fails.
+ * @throws GeneralSecurityException if the keystore cannot be loaded or the certificate parsed.
+ */
+ public static boolean installAdcEgressProxyCertificate()
+ throws IOException, GeneralSecurityException {
+ return installAdcEgressProxyCertificate(null, defaultAdcProxiedHosts());
+ }
+
+ /**
+ * Variant of {@link #installAdcEgressProxyCertificate()} that routes lifecycle messages
+ * through the caller's SLF4J logger. Applies both layers (merged-keystore install plus
+ * host-scoping to {@link #defaultAdcProxiedHosts()}). Pass {@code null} for {@code logger}
+ * to fall back to the class-static logger.
+ */
+ public static boolean installAdcEgressProxyCertificate(Logger logger)
+ throws IOException, GeneralSecurityException {
+ return installAdcEgressProxyCertificate(logger, defaultAdcProxiedHosts());
+ }
+
+ /**
+ * Variant that lets the caller override the host-scoping predicate (or disable
+ * host-scoping entirely by passing {@code null}). Equivalent to the no-arg / one-arg
+ * overloads when {@code adcHosts == defaultAdcProxiedHosts()}.
+ *
+ *
Caveat. Some HTTP clients (notably reactor-netty's default
+ * {@code HttpClient}, used by {@code azure-core-http-netty}) build their own
+ * {@code SslContext} from the {@code javax.net.ssl.trustStore} system property and do
+ * not consult {@link SSLContext#getDefault()}. For those clients the
+ * merged-keystore install still makes the proxy CA trusted globally, but the
+ * host-scoping enforcement does not apply.
+ *
+ * @param logger optional SLF4J logger; {@code null} uses the class-static logger.
+ * @param adcHosts predicate evaluated against {@code SSLEngine.getPeerHost()} /
+ * {@code Socket.getRemoteSocketAddress()}; only matching hosts will see
+ * the proxy CA in their trust set. Pass {@code null} to disable
+ * host-scoping entirely (merged-keystore install only).
+ */
+ public static boolean installAdcEgressProxyCertificate(Logger logger, Predicate adcHosts)
+ throws IOException, GeneralSecurityException {
+ return installProxyCertificate(logger, adcHosts, ADC_EGRESS_PROXY_CA_CERT, "adc-egress-proxy");
+ }
+
+ /**
+ * Generic variant for installing any proxy CA certificate file with optional host-scoping.
+ * Equivalent to {@link #installAdcEgressProxyCertificate(Logger, Predicate)} but
+ * parameterised by certificate path and alias prefix instead of using the ADC defaults.
+ *
+ * Performs the two layers documented on the class JavaDoc — the merged-keystore
+ * install always; the host-scoped {@link SSLContext} only when {@code adcHosts} is
+ * non-{@code null}.
+ *
+ *
No-op if {@code certPath} does not exist (returns {@code false}), making it safe to
+ * call unconditionally during application startup.
+ *
+ * @param logger optional SLF4J logger; {@code null} uses the class-static logger.
+ * @param adcHosts optional host predicate; {@code null} disables host-scoping. The
+ * parameter name reflects the primary ADC use case, but the predicate
+ * may match any host pattern relevant to the supplied cert.
+ * @param certPath path to a PEM- or DER-encoded X.509 certificate file (may contain
+ * multiple PEM-encoded certificates concatenated together).
+ * @param aliasPrefix prefix used to derive unique aliases ({@code aliasPrefix-N}) for the
+ * imported certificates in the merged keystore.
+ */
+ public static boolean installProxyCertificate(
+ Logger logger, Predicate adcHosts, Path certPath, String aliasPrefix)
+ throws IOException, GeneralSecurityException {
+ boolean installed = installIntoMergedKeystore(certPath, aliasPrefix, logger);
+ if (installed && adcHosts != null && Files.isRegularFile(certPath)) {
+ installHostScopedDefaultSslContext(logger, adcHosts, certPath);
+ }
+ return installed;
+ }
+
+ /**
+ * Merged-keystore install: parses certs from {@code certPath}, adds them to a copy of
+ * the JDK {@code cacerts} under {@code aliasPrefix-N}, writes the merged keystore to a
+ * temp file, and points the JVM at it via the {@code javax.net.ssl.trustStore} system
+ * properties. No-op if {@code certPath} does not exist.
+ */
+ private static boolean installIntoMergedKeystore(Path certPath, String aliasPrefix, Logger logger)
+ throws IOException, GeneralSecurityException {
+ Objects.requireNonNull(certPath, "certPath");
+ Objects.requireNonNull(aliasPrefix, "aliasPrefix");
+
+ Logger log = logger(logger);
+
+ if (!Files.isRegularFile(certPath)) {
+ log.debug("No CA cert found at {}; skipping truststore install.", certPath);
+ return false;
+ }
+
+ KeyStore merged = loadDefaultCacerts(logger);
+
+ CertificateFactory cf = CertificateFactory.getInstance("X.509");
+ Collection certs;
+ try (InputStream in = Files.newInputStream(certPath)) {
+ certs = cf.generateCertificates(in);
+ }
+ if (certs.isEmpty()) {
+ log.warn("No certificates were parsed from {}.", certPath);
+ return false;
+ }
+
+ // Build the candidate pool used during chain-building so that intermediates shipped
+ // alongside the leaf certificate in the same file are discoverable.
+ List intermediates = new ArrayList<>();
+ for (Certificate c : certs) {
+ if (c instanceof X509Certificate x) {
+ intermediates.add(x);
+ }
+ }
+
+ int added = 0;
+ int i = 0;
+ for (Certificate cert : certs) {
+ String alias = aliasPrefix + "-" + i++;
+ ChainInfo chain = (cert instanceof X509Certificate x)
+ ? buildChain(x, intermediates, merged)
+ : ChainInfo.NONE;
+
+ logCertificateDetails(log, alias, cert, chain);
+
+ merged.setCertificateEntry(alias, cert);
+ added++;
+ }
+
+ if (added == 0) {
+ log.warn("No certificates from {} were added to the truststore.", certPath);
+ return false;
+ }
+
+ Path mergedFile = Files.createTempFile("cacerts-with-" + aliasPrefix + "-", ".jks");
+ mergedFile.toFile().deleteOnExit();
+ try (OutputStream out = Files.newOutputStream(mergedFile)) {
+ merged.store(out, DEFAULT_CACERTS_PASSWORD.toCharArray());
+ }
+
+ System.setProperty("javax.net.ssl.trustStore", mergedFile.toAbsolutePath().toString());
+ System.setProperty("javax.net.ssl.trustStorePassword", DEFAULT_CACERTS_PASSWORD);
+ System.setProperty("javax.net.ssl.trustStoreType", merged.getType());
+
+ log.info("Installed {} CA certificate(s) from {} into merged truststore {}.",
+ added, certPath, mergedFile);
+ return true;
+ }
+
+ private static KeyStore loadDefaultCacerts(Logger logger) throws IOException, GeneralSecurityException {
+ Logger log = logger(logger);
+ Path cacerts = Paths.get(System.getProperty("java.home"), "lib", "security", "cacerts");
+ KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType());
+ if (Files.isRegularFile(cacerts)) {
+ try (InputStream in = Files.newInputStream(cacerts)) {
+ ks.load(in, DEFAULT_CACERTS_PASSWORD.toCharArray());
+ }
+ } else {
+ log.warn("Default JDK cacerts not found at {}; starting from an empty truststore.", cacerts);
+ ks.load(null, DEFAULT_CACERTS_PASSWORD.toCharArray());
+ }
+ return ks;
+ }
+
+ /**
+ * Emits an INFO line describing the certificate being trusted: alias, subject DN,
+ * issuer DN, validity window, serial number, SHA-256 fingerprint, and trust chain
+ * (root subject + fingerprint, whether the chain validates against the JDK cacerts).
+ */
+ private static void logCertificateDetails(Logger log, String alias, Certificate cert, ChainInfo chain) {
+ if (cert instanceof X509Certificate x509) {
+ log.info(
+ "Adding CA certificate [alias={}] subject=\"{}\" issuer=\"{}\" "
+ + "notBefore={} notAfter={} serial={} sha256={} chain={}",
+ alias,
+ x509.getSubjectX500Principal().getName(),
+ x509.getIssuerX500Principal().getName(),
+ x509.getNotBefore().toInstant(),
+ x509.getNotAfter().toInstant(),
+ x509.getSerialNumber().toString(16),
+ sha256Fingerprint(x509),
+ chain.summary());
+ } else {
+ log.info("Adding CA certificate [alias={}] type={}", alias, cert.getType());
+ }
+ }
+
+ private static String sha256Fingerprint(X509Certificate cert) {
+ try {
+ byte[] digest = MessageDigest.getInstance("SHA-256").digest(cert.getEncoded());
+ return HexFormat.of().withUpperCase().withDelimiter(":").formatHex(digest);
+ } catch (GeneralSecurityException e) {
+ return "";
+ }
+ }
+
+ /**
+ * Attempts to build a PKIX trust chain from {@code target} to a trust anchor in
+ * {@code trustAnchors} (typically the JDK's cacerts), using {@code intermediates} as a
+ * candidate pool. Returns a {@link ChainInfo} that captures the outcome — whether the
+ * chain is trusted, the root certificate (if any), and a short human-readable summary.
+ *
+ * Self-signed certificates are handled as a special case: the cert is treated as its
+ * own root and reported as "self-signed (not anchored)" unless an equal cert already
+ * exists in {@code trustAnchors}, in which case it is reported as "self-signed (anchored)".
+ */
+ private static ChainInfo buildChain(X509Certificate target,
+ Collection intermediates,
+ KeyStore trustAnchors) {
+ boolean selfSigned = target.getSubjectX500Principal().equals(target.getIssuerX500Principal());
+ if (selfSigned) {
+ boolean anchored = trustAnchorsContain(trustAnchors, target);
+ String summary = "self-signed root sha256=" + sha256Fingerprint(target)
+ + (anchored ? " (anchored in cacerts)" : " (not anchored in cacerts)");
+ return new ChainInfo(anchored, target, summary);
+ }
+
+ try {
+ Set anchors = new HashSet<>();
+ Enumeration aliases = trustAnchors.aliases();
+ while (aliases.hasMoreElements()) {
+ String a = aliases.nextElement();
+ if (trustAnchors.isCertificateEntry(a)) {
+ Certificate c = trustAnchors.getCertificate(a);
+ if (c instanceof X509Certificate x) {
+ anchors.add(new TrustAnchor(x, null));
+ }
+ }
+ }
+ if (anchors.isEmpty()) {
+ return new ChainInfo(false, null, "no trust anchors available");
+ }
+
+ X509CertSelector sel = new X509CertSelector();
+ sel.setCertificate(target);
+
+ PKIXBuilderParameters params = new PKIXBuilderParameters(anchors, sel);
+ params.setRevocationEnabled(false);
+ params.addCertStore(CertStore.getInstance("Collection",
+ new CollectionCertStoreParameters(intermediates)));
+
+ CertPathBuilder builder = CertPathBuilder.getInstance("PKIX");
+ PKIXCertPathBuilderResult result = (PKIXCertPathBuilderResult) builder.build(params);
+ X509Certificate root = result.getTrustAnchor().getTrustedCert();
+ String summary = "trusted via PKIX: root subject=\""
+ + root.getSubjectX500Principal().getName()
+ + "\" root sha256=" + sha256Fingerprint(root);
+ return new ChainInfo(true, root, summary);
+ } catch (GeneralSecurityException e) {
+ return new ChainInfo(false, null, "no trusted chain (" + e.getMessage() + ")");
+ }
+ }
+
+ private static boolean trustAnchorsContain(KeyStore trustAnchors, X509Certificate cert) {
+ try {
+ Enumeration aliases = trustAnchors.aliases();
+ while (aliases.hasMoreElements()) {
+ String a = aliases.nextElement();
+ if (trustAnchors.isCertificateEntry(a) && cert.equals(trustAnchors.getCertificate(a))) {
+ return true;
+ }
+ }
+ } catch (GeneralSecurityException ignored) {
+ // fall through
+ }
+ return false;
+ }
+
+ /**
+ * Result of a single chain-building attempt against the JDK cacerts.
+ */
+ private record ChainInfo(boolean trusted, X509Certificate root, String summary) {
+ static final ChainInfo NONE = new ChainInfo(false, null, "n/a");
+ }
+
+ // ──────────────────────────────────────────────────────────────────
+ // Host-scoped trust manager
+ // ──────────────────────────────────────────────────────────────────
+
+ /**
+ * Default predicate matching the host pattern empirically observed to be MITM'd by the
+ * ADC egress proxy in Azure AI Foundry vNext: *.services.ai.azure.com (the
+ * unified Foundry project / storage / OpenAI endpoint pattern).
+ */
+ public static Predicate defaultAdcProxiedHosts() {
+ return host -> {
+ if (host == null) return false;
+ String h = host.toLowerCase(Locale.ROOT);
+ return h.endsWith(".services.ai.azure.com");
+ };
+ }
+
+ /**
+ * Builds a host-scoped trust manager set: certificates loaded from {@code certPath} are
+ * trusted only when validating server certificates for hosts matched by {@code adcHosts}.
+ * For all other hosts — and as a fall-through for matched hosts whose server cert was not
+ * signed by the scoped CA — the JDK default trust set is used.
+ *
+ * @param certPath path to PEM/DER cert file to install under scoped trust.
+ * @param adcHosts host predicate; only matching hosts will see the scoped CA.
+ * @param logger optional SLF4J logger; {@code null} uses the class-static logger.
+ */
+ private static TrustManager[] hostScopedTrustManagers(
+ Path certPath, Predicate adcHosts, Logger logger)
+ throws IOException, GeneralSecurityException {
+
+ Objects.requireNonNull(certPath, "certPath");
+ Objects.requireNonNull(adcHosts, "adcHosts");
+ Logger log = logger(logger);
+
+ TrustManagerFactory defaultTmf = TrustManagerFactory.getInstance(
+ TrustManagerFactory.getDefaultAlgorithm());
+ defaultTmf.init((KeyStore) null);
+ X509ExtendedTrustManager defaultTm = firstX509Extended(defaultTmf,
+ "JDK default trust manager");
+
+ KeyStore scopedOnly = KeyStore.getInstance(KeyStore.getDefaultType());
+ scopedOnly.load(null, null);
+
+ int added = 0;
+ if (Files.isRegularFile(certPath)) {
+ CertificateFactory cf = CertificateFactory.getInstance("X.509");
+ Collection certs;
+ try (InputStream in = Files.newInputStream(certPath)) {
+ certs = cf.generateCertificates(in);
+ }
+ List intermediates = new ArrayList<>();
+ for (Certificate c : certs) {
+ if (c instanceof X509Certificate x) {
+ intermediates.add(x);
+ }
+ }
+ KeyStore cacertsForChainBuild = loadDefaultCacerts(log);
+ int i = 0;
+ for (Certificate cert : certs) {
+ String alias = "host-scoped-" + i++;
+ if (!(cert instanceof X509Certificate x)) continue;
+ buildChain(x, intermediates, cacertsForChainBuild); // populates chain context for log
+ scopedOnly.setCertificateEntry(alias, x);
+ added++;
+ }
+ } else {
+ log.debug("Host-scoped trust manager: cert file {} not present; scoped trust set is empty "
+ + "and will always fall through to JDK default.", certPath);
+ }
+
+ TrustManagerFactory scopedTmf = TrustManagerFactory.getInstance(
+ TrustManagerFactory.getDefaultAlgorithm());
+ scopedTmf.init(scopedOnly);
+ X509ExtendedTrustManager scopedTm = firstX509Extended(scopedTmf,
+ "Scoped trust manager");
+
+ log.info("Host-scoped trust manager built: {} cert(s) trusted for predicate-matched hosts; "
+ + "JDK default trust applies to all other hosts.", added);
+
+ return new TrustManager[]{
+ new HostScopedTrustManager(scopedTm, defaultTm, adcHosts)
+ };
+ }
+
+ /**
+ * Builds a host-scoped {@link SSLContext} via {@link #hostScopedTrustManagers} and registers
+ * it as the JVM default via {@link SSLContext#setDefault(SSLContext)}. See the caveat on
+ * {@link #installAdcEgressProxyCertificate(Logger, Predicate)} about HTTP clients that
+ * bypass the JVM-default {@link SSLContext}.
+ */
+ private static void installHostScopedDefaultSslContext(
+ Logger logger, Predicate adcHosts, Path certPath)
+ throws IOException, GeneralSecurityException {
+ Logger log = logger(logger);
+ TrustManager[] tms = hostScopedTrustManagers(certPath, adcHosts, log);
+ SSLContext ctx;
+ try {
+ ctx = SSLContext.getInstance("TLS");
+ ctx.init(null, tms, null);
+ } catch (GeneralSecurityException e) {
+ log.warn("Failed to construct host-scoped SSLContext; default SSLContext unchanged.", e);
+ return;
+ }
+ SSLContext.setDefault(ctx);
+ log.info("Installed host-scoped SSLContext as the JVM default; scoped CA is trusted "
+ + "only for hosts matching the supplied predicate.");
+ }
+
+ private static X509ExtendedTrustManager firstX509Extended(TrustManagerFactory tmf, String label) {
+ for (TrustManager tm : tmf.getTrustManagers()) {
+ if (tm instanceof X509ExtendedTrustManager x) {
+ return x;
+ }
+ }
+ throw new IllegalStateException(label + " did not provide an X509ExtendedTrustManager");
+ }
+
+ /**
+ * Composite {@link X509ExtendedTrustManager} that consults a scoped trust manager
+ * (containing only the explicitly-added CA(s)) for hosts matched by a predicate and the
+ * JDK default trust manager for everything else.
+ *
+ * Behaviour:
+ *
+ * - For matched hosts: the scoped trust manager validates first; on failure the JDK
+ * default is consulted as a fall-back (so direct connections to the real service
+ * endpoint, not through the proxy, still work when the platform-mounted proxy CA
+ * is absent).
+ * - For unmatched hosts: only the JDK default applies — the scoped CA is
+ * never consulted, so a compromised proxy CA cannot impersonate
+ * public-internet hosts.
+ * - For the legacy {@code checkServerTrusted(chain, authType)} overload (no peer
+ * host available): only the JDK default applies (fail-safe).
+ *
+ */
+ private static final class HostScopedTrustManager extends X509ExtendedTrustManager {
+
+ private final X509ExtendedTrustManager scopedTm;
+ private final X509ExtendedTrustManager defaultTm;
+ private final Predicate scopedHosts;
+
+ HostScopedTrustManager(X509ExtendedTrustManager scopedTm,
+ X509ExtendedTrustManager defaultTm,
+ Predicate scopedHosts) {
+ this.scopedTm = Objects.requireNonNull(scopedTm, "scopedTm");
+ this.defaultTm = Objects.requireNonNull(defaultTm, "defaultTm");
+ this.scopedHosts = Objects.requireNonNull(scopedHosts, "scopedHosts");
+ }
+
+ @Override
+ public X509Certificate[] getAcceptedIssuers() {
+ X509Certificate[] scoped = scopedTm.getAcceptedIssuers();
+ X509Certificate[] def = defaultTm.getAcceptedIssuers();
+ X509Certificate[] all = new X509Certificate[scoped.length + def.length];
+ System.arraycopy(scoped, 0, all, 0, scoped.length);
+ System.arraycopy(def, 0, all, scoped.length, def.length);
+ return all;
+ }
+
+ // ── client trust (rare; defer to default) ─────────────────────
+ @Override
+ public void checkClientTrusted(X509Certificate[] chain, String authType) throws CertificateException {
+ defaultTm.checkClientTrusted(chain, authType);
+ }
+
+ @Override
+ public void checkClientTrusted(X509Certificate[] chain, String authType, Socket socket) throws CertificateException {
+ defaultTm.checkClientTrusted(chain, authType, socket);
+ }
+
+ @Override
+ public void checkClientTrusted(X509Certificate[] chain, String authType, SSLEngine engine) throws CertificateException {
+ defaultTm.checkClientTrusted(chain, authType, engine);
+ }
+
+ // ── server trust (the host-scoping decision lives here) ───────
+ @Override
+ public void checkServerTrusted(X509Certificate[] chain, String authType) throws CertificateException {
+ // No peer-host information on this overload — fail-safe to JDK default only.
+ defaultTm.checkServerTrusted(chain, authType);
+ }
+
+ @Override
+ public void checkServerTrusted(X509Certificate[] chain, String authType, Socket socket) throws CertificateException {
+ checkServerTrustedForPeer(chain, authType, peerHost(socket), socket, null);
+ }
+
+ @Override
+ public void checkServerTrusted(X509Certificate[] chain, String authType, SSLEngine engine) throws CertificateException {
+ String peer = engine == null ? null : engine.getPeerHost();
+ checkServerTrustedForPeer(chain, authType, peer, null, engine);
+ }
+
+ private void checkServerTrustedForPeer(X509Certificate[] chain, String authType,
+ String peer, Socket socket, SSLEngine engine)
+ throws CertificateException {
+
+ if (peer != null && scopedHosts.test(peer)) {
+ try {
+ if (socket != null) {
+ scopedTm.checkServerTrusted(chain, authType, socket);
+ } else if (engine != null) {
+ scopedTm.checkServerTrusted(chain, authType, engine);
+ } else {
+ scopedTm.checkServerTrusted(chain, authType);
+ }
+ return;
+ } catch (CertificateException ignored) {
+ // fall through to default
+ }
+ }
+
+ if (socket != null) {
+ defaultTm.checkServerTrusted(chain, authType, socket);
+ } else if (engine != null) {
+ defaultTm.checkServerTrusted(chain, authType, engine);
+ } else {
+ defaultTm.checkServerTrusted(chain, authType);
+ }
+ }
+
+ private static String peerHost(Socket socket) {
+ if (socket == null) return null;
+ SocketAddress addr = socket.getRemoteSocketAddress();
+ if (addr instanceof InetSocketAddress isa) {
+ return isa.getHostString();
+ }
+ return null;
+ }
+ }
+}
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/implementation/FoundryStorageException.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/implementation/FoundryStorageException.java
new file mode 100644
index 000000000000..ebb09c429f37
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/implementation/FoundryStorageException.java
@@ -0,0 +1,59 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api.implementation;
+
+/**
+ * Exception thrown when a Foundry storage API operation fails.
+ *
+ * Contains the HTTP status code and response body for diagnostic purposes.
+ */
+public final class FoundryStorageException extends RuntimeException {
+
+ private final int statusCode;
+ private final String responseBody;
+
+ /**
+ * Creates a new {@code FoundryStorageException}.
+ *
+ * @param message the exception message
+ * @param statusCode the HTTP status code returned by the storage API
+ * @param responseBody the response body, or empty string if unavailable
+ */
+ public FoundryStorageException(String message, int statusCode, String responseBody) {
+ super(message);
+ this.statusCode = statusCode;
+ this.responseBody = responseBody != null ? responseBody : "";
+ }
+
+ /**
+ * Creates a new {@code FoundryStorageException} with a cause.
+ *
+ * @param message the exception message
+ * @param cause the underlying cause
+ */
+ public FoundryStorageException(String message, Throwable cause) {
+ super(message, cause);
+ this.statusCode = 0;
+ this.responseBody = "";
+ }
+
+ /**
+ * Returns the HTTP status code from the failed storage API call.
+ *
+ * @return the status code, or 0 if not applicable
+ */
+ public int getStatusCode() {
+ return statusCode;
+ }
+
+ /**
+ * Returns the response body from the failed storage API call.
+ *
+ * @return the response body, or an empty string
+ */
+ public String getResponseBody() {
+ return responseBody;
+ }
+}
+
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/implementation/FoundryStorageProvider.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/implementation/FoundryStorageProvider.java
new file mode 100644
index 000000000000..36a1872cc128
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/implementation/FoundryStorageProvider.java
@@ -0,0 +1,656 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api.implementation;
+
+import com.azure.core.credential.TokenCredential;
+import com.azure.core.http.HttpHeaderName;
+import com.azure.core.http.HttpMethod;
+import com.azure.core.http.HttpPipeline;
+import com.azure.core.http.HttpPipelineBuilder;
+import com.azure.core.http.HttpRequest;
+import com.azure.core.http.HttpResponse;
+import com.azure.core.http.policy.BearerTokenAuthenticationPolicy;
+import com.azure.core.http.policy.HttpLogOptions;
+import com.azure.core.http.policy.HttpLoggingPolicy;
+import com.azure.core.http.policy.RetryPolicy;
+import com.azure.core.util.BinaryData;
+import com.azure.identity.DefaultAzureCredentialBuilder;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ArrayNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.microsoft.agentserver.api.IsolationContext;
+import com.microsoft.agentserver.api.PlatformHeaders;
+import com.microsoft.agentserver.api.ResponsesProvider;
+import com.microsoft.agentserver.api.serialization.ObjectMapperFactory;
+import com.openai.models.responses.Response;
+import com.openai.models.responses.ResponseItem;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.net.URI;
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+/**
+ * HTTP-backed implementation of {@link ResponsesProvider} that persists
+ * state to the Azure AI Foundry storage API using an Azure Core
+ * {@link HttpPipeline} for retry, authentication, telemetry, and tracing.
+ *
+ * Equivalent to the C# {@code FoundryStorageProvider}.
+ */
+public final class FoundryStorageProvider implements ResponsesProvider, AutoCloseable {
+ private static final Logger LOGGER = LoggerFactory.getLogger(FoundryStorageProvider.class);
+ private static final String API_VERSION = "v1";
+ private static final String JSON_CONTENT_TYPE = "application/json; charset=utf-8";
+ private static final String FOUNDRY_STORAGE_SCOPE = "https://ai.azure.com/.default";
+ private static final ObjectMapper MAPPER = ObjectMapperFactory.getObjectMapper();
+
+ private final HttpPipeline pipeline;
+ private final URI storageBaseUri;
+ private final ExecutorService ioExecutor;
+
+ /**
+ * Creates a new FoundryStorageProvider with a pre-built HttpPipeline and a custom executor
+ * for async I/O operations.
+ *
+ * @param pipeline the Azure Core HTTP pipeline (includes retry, auth, telemetry)
+ * @param storageBaseUri the base URI for the Foundry storage API (e.g. "...")
+ * @param ioExecutor the executor for async I/O operations
+ */
+ public FoundryStorageProvider(HttpPipeline pipeline, URI storageBaseUri, ExecutorService ioExecutor) {
+ this.pipeline = pipeline;
+ this.storageBaseUri = storageBaseUri.toString().endsWith("/")
+ ? storageBaseUri
+ : URI.create(storageBaseUri + "/");
+ this.ioExecutor = ioExecutor;
+ LOGGER.debug("Initialized FoundryStorageProvider with base URI: {}", this.storageBaseUri);
+ }
+
+ /**
+ * Creates a new FoundryStorageProvider with a pre-built HttpPipeline and the
+ * {@linkplain #defaultIoExecutor() default I/O executor}.
+ *
+ * @param pipeline the Azure Core HTTP pipeline (includes retry, auth, telemetry)
+ * @param storageBaseUri the base URI for the Foundry storage API (e.g. "https://host/storage/")
+ */
+ public FoundryStorageProvider(HttpPipeline pipeline, URI storageBaseUri) {
+ this(pipeline, storageBaseUri, defaultIoExecutor());
+ }
+
+ /**
+ * Creates a new FoundryStorageProvider with DefaultAzureCredential and the
+ * {@linkplain #defaultIoExecutor() default I/O executor}.
+ *
+ * @param storageBaseUri the base URI for the Foundry storage API
+ */
+ public FoundryStorageProvider(URI storageBaseUri) {
+ this(storageBaseUri, new DefaultAzureCredentialBuilder().build());
+ }
+
+ /**
+ * Creates a new FoundryStorageProvider with a custom TokenCredential and the
+ * {@linkplain #defaultIoExecutor() default I/O executor}.
+ *
+ * @param storageBaseUri the base URI for the Foundry storage API
+ * @param credential the Azure token credential for authentication
+ */
+ public FoundryStorageProvider(URI storageBaseUri, TokenCredential credential) {
+ this(buildPipeline(credential), storageBaseUri);
+ }
+
+ /**
+ * Creates a default {@link ExecutorService} for blocking HTTP I/O operations.
+ *
+ * Uses a cached thread pool with daemon threads to prevent thread starvation
+ * of the {@code ForkJoinPool.commonPool()}, which is designed for CPU-bound work.
+ *
+ * @return a new cached thread pool with daemon threads named {@code "foundry-storage-io"}
+ */
+ private static ExecutorService defaultIoExecutor() {
+ return Executors.newCachedThreadPool(r -> {
+ Thread t = new Thread(r, "foundry-storage-io");
+ t.setDaemon(true);
+ return t;
+ });
+ }
+
+ private static HttpPipeline buildPipeline(TokenCredential credential) {
+ return new HttpPipelineBuilder()
+ .policies(
+ new BearerTokenAuthenticationPolicy(credential, FOUNDRY_STORAGE_SCOPE),
+ new RetryPolicy(),
+ new HttpLoggingPolicy(new HttpLogOptions()))
+ .build();
+ }
+
+ // ── Request building ──────────────────────────────────────
+
+ private static String encode(String value) {
+ return URLEncoder.encode(value, StandardCharsets.UTF_8);
+ }
+
+ /**
+ * Creates a FoundryStorageProvider from environment variables.
+ * Requires FOUNDRY_PROJECT_ENDPOINT to be set.
+ * Uses DefaultAzureCredential for authentication (managed identity in hosted environments).
+ *
+ * @return a configured FoundryStorageProvider
+ * @throws IllegalStateException if FOUNDRY_PROJECT_ENDPOINT is not set
+ */
+ public static FoundryStorageProvider fromEnvironment() {
+ String endpoint = System.getenv("FOUNDRY_PROJECT_ENDPOINT");
+ if (endpoint == null || endpoint.isBlank()) {
+ LOGGER.error("FOUNDRY_PROJECT_ENDPOINT environment variable is not set");
+ throw new IllegalStateException(
+ "FOUNDRY_PROJECT_ENDPOINT environment variable is required for FoundryStorageProvider.");
+ }
+
+ String baseUri = endpoint.endsWith("/") ? endpoint + "storage/" : endpoint + "/storage/";
+ LOGGER.debug("Creating FoundryStorageProvider from environment with base URI: {}", baseUri);
+ return new FoundryStorageProvider(URI.create(baseUri));
+ }
+
+ private String buildUrl(String path, String extraQuery) {
+ String base = storageBaseUri.toString() + path + "?api-version=" + API_VERSION;
+ if (extraQuery != null && !extraQuery.isEmpty()) {
+ base += "&" + extraQuery;
+ }
+ return base;
+ }
+
+ // ── ResponsesProvider implementation ──────────────────────
+
+ private HttpResponse sendRequest(HttpMethod method, String path, String extraQuery, BinaryData body) {
+ return sendRequest(method, path, extraQuery, body, null);
+ }
+
+ private HttpResponse sendRequest(HttpMethod method, String path, String extraQuery, BinaryData body, IsolationContext isolation) {
+ String url = buildUrl(path, extraQuery);
+ LOGGER.debug("Sending {} request to {}", method, url);
+ HttpRequest request = new HttpRequest(method, url);
+
+ if (body != null) {
+ request.setBody(body);
+ request.setHeader(HttpHeaderName.CONTENT_TYPE, JSON_CONTENT_TYPE);
+ }
+ request.setHeader(HttpHeaderName.ACCEPT, "application/json");
+
+ // Apply platform isolation headers (required by Foundry storage API)
+ if (isolation != null) {
+ if (isolation.userIsolationKey() != null) {
+ request.setHeader(HttpHeaderName.fromString(PlatformHeaders.USER_ISOLATION_KEY),
+ isolation.userIsolationKey());
+ }
+ if (isolation.chatIsolationKey() != null) {
+ request.setHeader(HttpHeaderName.fromString(PlatformHeaders.CHAT_ISOLATION_KEY),
+ isolation.chatIsolationKey());
+ }
+ }
+
+ HttpResponse response = pipeline.sendSync(request, com.azure.core.util.Context.NONE);
+ LOGGER.debug("{} {} returned status {}", method, path, response.getStatusCode());
+ throwIfError(response);
+ return response;
+ }
+
+ private void throwIfError(HttpResponse response) {
+ int status = response.getStatusCode();
+ if (status >= 200 && status < 300) {
+ return;
+ }
+ String responseBody = response.getBodyAsBinaryData() != null
+ ? response.getBodyAsBinaryData().toString() : "";
+ LOGGER.warn("Foundry storage API error: HTTP {} - {}", status, responseBody);
+ if (status == 404) {
+ throw new FoundryStorageException("Resource not found", status, responseBody);
+ }
+ throw new FoundryStorageException(
+ "Foundry storage API error: HTTP " + status, status, responseBody);
+ }
+
+ @Override
+ public CompletableFuture> getItemsAsync(List itemIds) {
+ LOGGER.debug("getItemsAsync called with {} item IDs", itemIds.size());
+ return CompletableFuture.supplyAsync(() -> {
+ try {
+ ObjectNode body = MAPPER.createObjectNode();
+ ArrayNode idsArray = body.putArray("item_ids");
+ for (String id : itemIds) {
+ idsArray.add(id);
+ }
+
+ try (HttpResponse response = sendRequest(
+ HttpMethod.POST, "items/batch/retrieve", null,
+ BinaryData.fromString(MAPPER.writeValueAsString(body)))) {
+
+ JsonNode root = MAPPER.readTree(response.getBodyAsBinaryData().toString());
+ List result = new ArrayList<>();
+ if (root.isArray()) {
+ for (JsonNode node : root) {
+ if (node.isNull()) {
+ result.add(null);
+ } else {
+ result.add(MAPPER.treeToValue(node, ResponseItem.class));
+ }
+ }
+ }
+ LOGGER.debug("getItemsAsync returning {} items ({} requested)", result.size(), itemIds.size());
+ return result;
+ }
+ } catch (IOException e) {
+ LOGGER.error("Failed to get items from Foundry storage for {} IDs", itemIds.size(), e);
+ throw new FoundryStorageException("Failed to get items from Foundry storage", e);
+ }
+ }, ioExecutor);
+ }
+
+ @Override
+ public CompletableFuture> getHistoryItemIdsAsync(
+ String previousResponseId,
+ String conversationId,
+ int limit) {
+ LOGGER.debug("getHistoryItemIdsAsync called with previousResponseId={}, conversationId={}, limit={}",
+ previousResponseId, conversationId, limit);
+ return CompletableFuture.supplyAsync(() -> {
+ try {
+ StringBuilder query = new StringBuilder("limit=" + limit);
+ if (previousResponseId != null && !previousResponseId.isEmpty()) {
+ query.append("&previous_response_id=")
+ .append(URLEncoder.encode(previousResponseId, StandardCharsets.UTF_8));
+ }
+ if (conversationId != null && !conversationId.isEmpty()) {
+ query.append("&conversation_id=")
+ .append(URLEncoder.encode(conversationId, StandardCharsets.UTF_8));
+ }
+
+ // Use the low-level send so we can treat 404 as "no history yet"
+ // (a brand-new conversation or response) without logging a warning.
+ String url = buildUrl("history/item_ids", query.toString());
+ LOGGER.debug("Sending GET request to {}", url);
+ HttpRequest request = new HttpRequest(HttpMethod.GET, url);
+ request.setHeader(HttpHeaderName.ACCEPT, "application/json");
+ try (HttpResponse response = pipeline.sendSync(request, com.azure.core.util.Context.NONE)) {
+ int status = response.getStatusCode();
+ if (status == 404) {
+ LOGGER.debug("No prior history for previousResponseId={} / conversationId={} (404 from storage)",
+ previousResponseId, conversationId);
+ return List.of();
+ }
+ throwIfError(response);
+ JsonNode root = MAPPER.readTree(response.getBodyAsBinaryData().toString());
+ List ids = new ArrayList<>();
+ if (root.isArray()) {
+ for (JsonNode node : root) {
+ ids.add(node.asText());
+ }
+ }
+ LOGGER.debug("getHistoryItemIdsAsync returning {} IDs", ids.size());
+ return ids;
+ }
+ } catch (IOException e) {
+ LOGGER.error("Failed to get history item IDs from Foundry storage", e);
+ throw new FoundryStorageException("Failed to get history item IDs from Foundry storage", e);
+ }
+ }, ioExecutor);
+ }
+
+ @Override
+ public CompletableFuture saveResponseAsync(
+ String responseId,
+ Response response,
+ String previousResponseId,
+ String conversationId) {
+ LOGGER.debug("saveResponseAsync called for responseId={}, previousResponseId={}, conversationId={}",
+ responseId, previousResponseId, conversationId);
+ // Note: input items are included via createResponseAsync; this is now only used
+ // as a fallback or for update-only scenarios.
+ return createResponseAsync(responseId, response, List.of(), List.of());
+ }
+
+ @Override
+ public CompletableFuture saveInputItemsAsync(
+ String responseId,
+ List inputItems) {
+ // Input items are now sent as part of the create envelope in createResponseAsync.
+ // This method is kept for interface compatibility but is effectively a no-op
+ // when called after createResponseAsync has already included the items.
+ LOGGER.debug("saveInputItemsAsync called for responseId={} with {} items (no-op, items sent in envelope)",
+ responseId, inputItems != null ? inputItems.size() : 0);
+ return CompletableFuture.completedFuture(null);
+ }
+
+ /**
+ * Creates a response in Foundry storage using the envelope format.
+ * Sends POST /responses with body: {"response": {...}, "input_items": [...], "history_item_ids": [...]}
+ * This matches the C# and Python SDK CreateResponseAsync contract.
+ *
+ * @param responseId the response ID
+ * @param response the response object
+ * @param inputItems the resolved input items
+ * @param historyItemIds the history item IDs from prior conversation turns
+ * @return a future that completes when persistence is done
+ */
+ public CompletableFuture createResponseAsync(
+ String responseId,
+ Response response,
+ List inputItems,
+ List historyItemIds) {
+ return createResponseAsync(responseId, response, inputItems, historyItemIds, null);
+ }
+
+ /**
+ * Creates a response in Foundry storage using the envelope format,
+ * forwarding platform isolation headers to the storage API.
+ *
+ * @param responseId the response ID
+ * @param response the response object
+ * @param inputItems the resolved input items
+ * @param historyItemIds the history item IDs from prior conversation turns
+ * @param isolation the isolation context from the inbound request (may be null)
+ * @return a future that completes when persistence is done
+ */
+ public CompletableFuture createResponseAsync(
+ String responseId,
+ Response response,
+ List inputItems,
+ List historyItemIds,
+ IsolationContext isolation) {
+ LOGGER.debug("createResponseAsync called for responseId={} with {} input items and {} history IDs",
+ responseId, inputItems != null ? inputItems.size() : 0,
+ historyItemIds != null ? historyItemIds.size() : 0);
+ return CompletableFuture.runAsync(() -> {
+ try {
+ // Build the envelope: {"response": {...}, "input_items": [...], "history_item_ids": [...]}
+ ObjectNode envelope = MAPPER.createObjectNode();
+
+ // Serialize the response and sanitize it
+ JsonNode responseNode = MAPPER.valueToTree(response);
+ ObjectNode sanitized = sanitizeResponseForStorage((ObjectNode) responseNode);
+ envelope.set("response", sanitized);
+
+ // Serialize input items
+ ArrayNode itemsArray = MAPPER.createArrayNode();
+ if (inputItems != null) {
+ for (ResponseItem item : inputItems) {
+ JsonNode itemNode = MAPPER.valueToTree(item);
+ itemsArray.add(itemNode);
+ }
+ }
+ envelope.set("input_items", itemsArray);
+
+ // Serialize history item IDs
+ ArrayNode historyArray = MAPPER.createArrayNode();
+ if (historyItemIds != null) {
+ for (String id : historyItemIds) {
+ historyArray.add(id);
+ }
+ }
+ envelope.set("history_item_ids", historyArray);
+
+ String jsonBody = MAPPER.writeValueAsString(envelope);
+ LOGGER.debug("Storage request body (create envelope): {}", jsonBody);
+
+ // POST to /responses (no ID in path!) - this is the create endpoint
+ try (HttpResponse ignored = sendRequest(HttpMethod.POST, "responses", null,
+ BinaryData.fromString(jsonBody), isolation)) {
+ LOGGER.debug("Successfully created response {} in storage", responseId);
+ }
+ } catch (IOException e) {
+ LOGGER.error("Failed to create response {} in Foundry storage", responseId, e);
+ throw new FoundryStorageException("Failed to create response in Foundry storage", e);
+ }
+ }, ioExecutor);
+ }
+
+ // ── Helpers ───────────────────────────────────────────────
+
+ @Override
+ public CompletableFuture> getResponseAsync(String responseId) {
+ return getResponseAsync(responseId, null);
+ }
+
+ @Override
+ public CompletableFuture> getResponseAsync(String responseId, IsolationContext isolation) {
+ LOGGER.debug("getResponseAsync called for responseId={}", responseId);
+ return CompletableFuture.supplyAsync(() -> {
+ try {
+ String url = buildUrl("responses/" + encode(responseId), null);
+ HttpRequest request = new HttpRequest(HttpMethod.GET, url);
+ request.setHeader(HttpHeaderName.ACCEPT, "application/json");
+ applyIsolationHeaders(request, isolation);
+
+ try (HttpResponse response = pipeline.sendSync(request, com.azure.core.util.Context.NONE)) {
+ if (response.getStatusCode() == 404) {
+ LOGGER.debug("Response {} not found in Foundry storage", responseId);
+ return Optional.empty();
+ }
+ throwIfError(response);
+
+ String json = response.getBodyAsBinaryData().toString();
+ Response result = MAPPER.readValue(json, Response.class);
+ LOGGER.debug("Successfully retrieved response {}", responseId);
+ return Optional.of(result);
+ }
+ } catch (IOException e) {
+ LOGGER.error("Failed to get response {} from Foundry storage", responseId, e);
+ throw new FoundryStorageException("Failed to get response from Foundry storage", e);
+ }
+ }, ioExecutor);
+ }
+
+ private static void applyIsolationHeaders(HttpRequest request, IsolationContext isolation) {
+ if (isolation == null) {
+ return;
+ }
+ if (isolation.userIsolationKey() != null) {
+ request.setHeader(HttpHeaderName.fromString(PlatformHeaders.USER_ISOLATION_KEY),
+ isolation.userIsolationKey());
+ }
+ if (isolation.chatIsolationKey() != null) {
+ request.setHeader(HttpHeaderName.fromString(PlatformHeaders.CHAT_ISOLATION_KEY),
+ isolation.chatIsolationKey());
+ }
+ }
+
+ @Override
+ public CompletableFuture deleteResponseAsync(String responseId) {
+ LOGGER.debug("deleteResponseAsync called for responseId={}", responseId);
+ return CompletableFuture.runAsync(() -> {
+ try (HttpResponse ignored = sendRequest(HttpMethod.DELETE, "responses/" + encode(responseId), null, null)) {
+ LOGGER.debug("Successfully deleted response {}", responseId);
+ }
+ }, ioExecutor);
+ }
+
+ @Override
+ public CompletableFuture> getInputItemsForResponseAsync(String responseId) {
+ LOGGER.debug("getInputItemsForResponseAsync called for responseId={}", responseId);
+ return CompletableFuture.supplyAsync(() -> {
+ try {
+ String url = buildUrl("responses/" + encode(responseId) + "/input_items", null);
+ HttpRequest request = new HttpRequest(HttpMethod.GET, url);
+ request.setHeader(HttpHeaderName.ACCEPT, "application/json");
+
+ try (HttpResponse response = pipeline.sendSync(request, com.azure.core.util.Context.NONE)) {
+ if (response.getStatusCode() == 404) {
+ LOGGER.debug("Input items for response {} not found", responseId);
+ return List.of();
+ }
+ throwIfError(response);
+
+ String json = response.getBodyAsBinaryData().toString();
+ JsonNode root = MAPPER.readTree(json);
+ JsonNode dataNode = root.has("data") ? root.get("data") : root;
+ List result = new ArrayList<>();
+ if (dataNode.isArray()) {
+ for (JsonNode node : dataNode) {
+ if (!node.isNull()) {
+ result.add(MAPPER.treeToValue(node, ResponseItem.class));
+ }
+ }
+ }
+ LOGGER.debug("getInputItemsForResponseAsync returning {} items for response {}",
+ result.size(), responseId);
+ return result;
+ }
+ } catch (IOException e) {
+ LOGGER.error("Failed to get input items for response {} from Foundry storage", responseId, e);
+ throw new FoundryStorageException("Failed to get input items from Foundry storage", e);
+ }
+ }, ioExecutor);
+ }
+
+ // ── Sanitization ─────────────────────────────────────────
+
+ /**
+ * Sanitizes a response JSON object for storage API compatibility.
+ * The OpenAI Java SDK serializes extra fields (agent_id, created_by, logprobs)
+ * and uses floating-point for timestamps. This method produces a body that
+ * matches the C#/.NET ResponseObject schema exactly.
+ */
+ private ObjectNode sanitizeResponseForStorage(ObjectNode node) {
+ // Remove fields not in the storage schema
+ node.remove("agent_id");
+ node.remove("created_by");
+ node.remove("logprobs");
+ node.remove("service_tier");
+ node.remove("metadata");
+
+ // Remove camelCase duplicates (OpenAI Java SDK serializes both snake_case and camelCase)
+ node.remove("createdAt");
+ node.remove("completedAt");
+ node.remove("cancelledAt");
+ node.remove("failedAt");
+ node.remove("parallelToolCalls");
+ node.remove("toolChoice");
+ node.remove("previousResponseId");
+ node.remove("maxOutputTokens");
+ node.remove("incompleteDetails");
+ node.remove("topP");
+
+ // Ensure timestamps are integers (SDK may serialize as floats)
+ ensureIntTimestamp(node, "created_at");
+ ensureIntTimestamp(node, "completed_at");
+ ensureIntTimestamp(node, "cancelled_at");
+ ensureIntTimestamp(node, "failed_at");
+
+ // Remove fields that should not be present if null (C#/Python omit nulls)
+ // Only add these if they have real values; the storage API doesn't expect explicit nulls
+ // Storage backend (C# reference impl) writes these as explicit `null` when
+ // unset rather than omitting them. Ensure they are always present so
+ // the platform deserializer doesn't 500 on a missing required key.
+ ensureNullIfAbsent(node, "instructions");
+ ensureNullIfAbsent(node, "error");
+ ensureNullIfAbsent(node, "incomplete_details");
+ // agent_reference is always set by AgentServerResponsesApi.normalizeIdsAndStamp;
+ // if it's missing on the way in, default to null to match the
+ // C# WriteNull behavior.
+ ensureNullIfAbsent(node, "agent_reference");
+
+ // These are truly optional in the C# schema (Optional.IsDefined wraps with no else)
+ // — omit when null/missing.
+ removeIfNull(node, "previous_response_id");
+ removeIfNull(node, "cancelled_at");
+ removeIfNull(node, "failed_at");
+
+ // Sanitize output items (remove openai-java-only extras; ensure schema fields)
+ if (node.has("output") && node.get("output").isArray()) {
+ for (JsonNode outputItem : node.get("output")) {
+ if (outputItem.isObject()) {
+ ObjectNode itemObj = (ObjectNode) outputItem;
+ itemObj.remove("created_by");
+ itemObj.remove("logprobs");
+ // Sanitize content parts within output items
+ if (itemObj.has("content") && itemObj.get("content").isArray()) {
+ for (JsonNode contentPart : itemObj.get("content")) {
+ if (contentPart.isObject()) {
+ ObjectNode partObj = (ObjectNode) contentPart;
+ // C# OutputMessageContentOutputTextContent always writes
+ // logprobs as an array (defaults to []). The platform
+ // deserializer 500s when this field is absent.
+ if ("output_text".equals(partObj.path("type").asText())) {
+ if (!partObj.has("logprobs") || partObj.get("logprobs").isNull()) {
+ partObj.set("logprobs", MAPPER.createArrayNode());
+ }
+ if (!partObj.has("annotations") || partObj.get("annotations").isNull()) {
+ partObj.set("annotations", MAPPER.createArrayNode());
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+
+ // Ensure usage has required sub-objects
+ if (node.has("usage") && !node.get("usage").isNull()) {
+ ObjectNode usage = (ObjectNode) node.get("usage");
+ if (!usage.has("input_tokens_details") || usage.get("input_tokens_details").isNull()) {
+ ObjectNode inputDetails = MAPPER.createObjectNode();
+ inputDetails.put("cached_tokens", 0);
+ usage.set("input_tokens_details", inputDetails);
+ }
+ if (!usage.has("output_tokens_details") || usage.get("output_tokens_details").isNull()) {
+ ObjectNode outputDetails = MAPPER.createObjectNode();
+ outputDetails.put("reasoning_tokens", 0);
+ usage.set("output_tokens_details", outputDetails);
+ }
+ }
+
+ return node;
+ }
+
+ /**
+ * Ensures a timestamp field is an integer (not a float like 1.778771021E9).
+ */
+ private void ensureIntTimestamp(ObjectNode node, String field) {
+ if (node.has(field) && !node.get(field).isNull()) {
+ JsonNode val = node.get(field);
+ if (val.isDouble() || val.isFloat()) {
+ node.put(field, val.longValue());
+ }
+ }
+ }
+
+ /**
+ * Removes a field from the node if it is null or missing.
+ * The storage API expects fields to be omitted rather than explicitly null.
+ */
+ private void removeIfNull(ObjectNode node, String field) {
+ if (node.has(field) && node.get(field).isNull()) {
+ node.remove(field);
+ }
+ }
+
+ /**
+ * Ensures the field is present in the object, set to JSON null if it was
+ * missing. The C# reference serializer writes these keys as explicit nulls
+ * rather than omitting them, and the storage backend deserializer rejects
+ * envelopes where they are absent.
+ */
+ private void ensureNullIfAbsent(ObjectNode node, String field) {
+ if (!node.has(field)) {
+ node.putNull(field);
+ }
+ }
+
+ /**
+ * Shuts down the I/O executor used for async HTTP operations.
+ * Outstanding tasks are allowed to complete, but no new tasks will be accepted.
+ */
+ @Override
+ public void close() {
+ ioExecutor.shutdown();
+ }
+}
+
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/implementation/IdGenerator.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/implementation/IdGenerator.java
new file mode 100644
index 000000000000..9b85c636a7c3
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/implementation/IdGenerator.java
@@ -0,0 +1,155 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api.implementation;
+
+import java.security.SecureRandom;
+import java.util.Base64;
+import java.util.regex.Pattern;
+
+/**
+ * Generates unique IDs with a category prefix, matching the Foundry ID format:
+ * {@code {prefix}_{partitionKey}{entropy}}.
+ */
+public final class IdGenerator {
+
+ private static final SecureRandom RANDOM = new SecureRandom();
+ private static final int PARTITION_KEY_LENGTH = 18;
+ private static final int ENTROPY_LENGTH = 32;
+
+ /**
+ * Prefix for Response resource IDs, per the protocol prefix table.
+ * Response IDs have the form {@code caresp_{partitionKey}{entropy}}.
+ */
+ static final String RESPONSE_PREFIX = "caresp";
+
+ /**
+ * Pattern for a well-formed response ID: the {@code caresp} prefix, a separator,
+ * and a 50-character Base62 body (18-char partition key + 32-char entropy), per
+ * the protocol ID format.
+ */
+ private static final Pattern RESPONSE_ID_PATTERN =
+ Pattern.compile(RESPONSE_PREFIX + "_[A-Za-z0-9]{" + (PARTITION_KEY_LENGTH + ENTROPY_LENGTH) + "}");
+
+ /**
+ * Returns {@code true} if {@code id} is a well-formed response ID
+ * ({@code caresp_} + 50 Base62 characters). Used to validate path parameters
+ * before lookup.
+ *
+ * @param id the candidate response ID
+ * @return whether the ID is well-formed
+ */
+ public static boolean isValidResponseId(String id) {
+ return id != null && RESPONSE_ID_PATTERN.matcher(id).matches();
+ }
+
+ private final String partitionKey;
+
+ public IdGenerator(String partitionKey) {
+ this.partitionKey = partitionKey != null ? partitionKey : secureEntropy(PARTITION_KEY_LENGTH);
+ }
+
+ /**
+ * Extracts the partition key from an existing Foundry-format ID.
+ *
+ * @param id the existing ID (e.g. "caresp_AbCdEf...")
+ * @return the partition key portion
+ */
+ public static String extractPartitionKey(String id) {
+ if (id == null || id.isEmpty()) {
+ throw new IllegalArgumentException("ID cannot be null or empty");
+ }
+ int underscoreIdx = id.indexOf('_');
+ if (underscoreIdx < 0 || id.length() < underscoreIdx + 1 + PARTITION_KEY_LENGTH) {
+ throw new IllegalArgumentException("ID '" + id + "' does not contain a valid partition key");
+ }
+ return id.substring(underscoreIdx + 1, underscoreIdx + 1 + PARTITION_KEY_LENGTH);
+ }
+
+ private static String secureEntropy(int length) {
+ byte[] bytes = new byte[length];
+ RANDOM.nextBytes(bytes);
+ String base64 = Base64.getUrlEncoder().withoutPadding().encodeToString(bytes);
+ // Keep only alphanumeric characters and truncate to desired length
+ StringBuilder sb = new StringBuilder(length);
+ for (int i = 0; i < base64.length() && sb.length() < length; i++) {
+ char c = base64.charAt(i);
+ if (Character.isLetterOrDigit(c)) {
+ sb.append(c);
+ }
+ }
+ // If not enough chars (unlikely), pad with more random
+ while (sb.length() < length) {
+ RANDOM.nextBytes(bytes);
+ base64 = Base64.getUrlEncoder().withoutPadding().encodeToString(bytes);
+ for (int i = 0; i < base64.length() && sb.length() < length; i++) {
+ char c = base64.charAt(i);
+ if (Character.isLetterOrDigit(c)) {
+ sb.append(c);
+ }
+ }
+ }
+ return sb.toString();
+ }
+
+ /**
+ * Generates a new ID with the given category prefix.
+ *
+ * @param category the prefix, e.g. "msg", "resp", "conv", "func"
+ * @return a new unique ID string
+ */
+ public String generate(String category) {
+ String prefix = (category == null || category.isEmpty()) ? "id" : category;
+ return prefix + "_" + partitionKey + secureEntropy(ENTROPY_LENGTH);
+ }
+
+ /**
+ * Generates a new Response resource ID using the {@code caresp} prefix.
+ *
+ * @return a new unique response ID string, e.g. {@code caresp_...}
+ */
+ public String generateResponseId() {
+ return generate(RESPONSE_PREFIX);
+ }
+
+ public String generateMessageItemId() {
+ return generate("msg");
+ }
+
+ public String generateFunctionCallItemId() {
+ return generate("fc");
+ }
+
+ public String generateReasoningItemId() {
+ return generate("rs");
+ }
+
+ public String generateFileSearchCallItemId() {
+ return generate("fs");
+ }
+
+ public String generateWebSearchCallItemId() {
+ return generate("ws");
+ }
+
+ public String generateCodeInterpreterCallItemId() {
+ return generate("ci");
+ }
+
+ public String generateImageGenCallItemId() {
+ return generate("ig");
+ }
+
+ public String generateMcpCallItemId() {
+ return generate("mcp");
+ }
+
+ public String generateMcpListToolsItemId() {
+ return generate("mcplt");
+ }
+
+ public String generateCustomToolCallItemId() {
+ return generate("ct");
+ }
+}
+
diff --git a/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/implementation/InMemoryResponseProvider.java b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/implementation/InMemoryResponseProvider.java
new file mode 100644
index 000000000000..9fb870ec6c65
--- /dev/null
+++ b/sdk/agentserver/azure-agentserver-api/src/main/java/com/microsoft/agentserver/api/implementation/InMemoryResponseProvider.java
@@ -0,0 +1,333 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.agentserver.api.implementation;
+
+import com.microsoft.agentserver.api.ResponsesProvider;
+import com.openai.models.responses.ResponseItem;
+import com.openai.models.responses.ResponseOutputItem;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentLinkedDeque;
+import java.util.concurrent.CopyOnWriteArrayList;
+
+/**
+ * Thread-safe, in-memory implementation of {@link ResponsesProvider}.
+ *
+ * Stores items as {@link ResponseItem} — a union type that naturally carries
+ * role information ({@code ResponseInputMessageItem} for user/system/developer,
+ * {@code ResponseOutputMessage} for assistant). No separate tracking of
+ * input vs output items is needed.
+ *
+ * Suitable for single-instance / development use; for production multi-instance
+ * deployments, implement a durable backend instead.
+ */
+public final class InMemoryResponseProvider implements ResponsesProvider {
+
+ /**
+ * Default maximum number of responses to retain. When exceeded, the oldest
+ * response (by insertion order) is evicted to prevent unbounded memory growth.
+ * Set to 0 for unlimited (not recommended in production).
+ */
+ static final int DEFAULT_MAX_RESPONSES = 10_000;
+
+ private final int maxResponses;
+
+ /**
+ * Insertion-order tracker for LRU eviction when {@link #maxResponses} is reached.
+ */
+ private final ConcurrentLinkedDeque insertionOrder = new ConcurrentLinkedDeque<>();
+
+ /**
+ * Item ID → stored item (input or output).
+ */
+ private final Map items = new ConcurrentHashMap<>();
+
+ /**
+ * Response ID → full Response object.
+ */
+ private final Map responses = new ConcurrentHashMap<>();
+
+ /**
+ * Response ID → ordered list of item IDs belonging to that response.
+ */
+ private final Map> responseItemIds = new ConcurrentHashMap<>();
+
+ /**
+ * Response ID → its previous response ID (for chaining).
+ */
+ private final Map responsePreviousId = new ConcurrentHashMap<>();
+
+ /**
+ * Conversation ID → ordered list of response IDs in that conversation.
+ */
+ private final Map> conversationResponses = new ConcurrentHashMap<>();
+
+ /**
+ * Response ID → ordered list of input item IDs for that response.
+ */
+ private final Map> responseInputItemIds = new ConcurrentHashMap<>();
+
+ /**
+ * Extracts the item ID from a {@link ResponseItem} union type.
+ */
+ static String extractItemId(ResponseItem item) {
+ return ItemConversion.extractItemId(item);
+ }
+
+ /**
+ * Creates an in-memory provider with the default max-responses cap
+ * ({@value #DEFAULT_MAX_RESPONSES}).
+ */
+ public InMemoryResponseProvider() {
+ this(DEFAULT_MAX_RESPONSES);
+ }
+
+ /**
+ * Creates an in-memory provider with a custom max-responses cap.
+ *
+ * @param maxResponses the maximum number of responses to retain (0 = unlimited)
+ */
+ public InMemoryResponseProvider(int maxResponses) {
+ this.maxResponses = maxResponses;
+ }
+
+ /**
+ * Extracts the item ID from a {@link ResponseOutputItem}.
+ */
+ static String extractOutputItemId(ResponseOutputItem item) {
+ return ItemConversion.extractOutputItemId(item);
+ }
+
+ @Override
+ public CompletableFuture> getItemsAsync(List itemIds) {
+ List result = new ArrayList<>(itemIds.size());
+ for (String id : itemIds) {
+ result.add(items.get(id)); // null if not found, per contract
+ }
+ return CompletableFuture.completedFuture(result);
+ }
+
+ @Override
+ public CompletableFuture> getHistoryItemIdsAsync(
+ String previousResponseId,
+ String conversationId,
+ int limit) {
+
+ List allItemIds = new ArrayList<>();
+
+ if (previousResponseId != null && !previousResponseId.isEmpty()) {
+ collectResponseChain(previousResponseId, allItemIds, limit);
+ } else if (conversationId != null && !conversationId.isEmpty()) {
+ List responseIds = conversationResponses.get(conversationId);
+ if (responseIds != null) {
+ for (String respId : responseIds) {
+ List ids = responseItemIds.get(respId);
+ if (ids != null) {
+ allItemIds.addAll(ids);
+ if (allItemIds.size() >= limit) {
+ break;
+ }
+ }
+ }
+ }
+ }
+
+ if (allItemIds.size() > limit) {
+ allItemIds = allItemIds.subList(allItemIds.size() - limit, allItemIds.size());
+ }
+
+ return CompletableFuture.completedFuture(Collections.unmodifiableList(allItemIds));
+ }
+
+ /**
+ * Persists a completed response and its output items.
+ * Output items are converted to {@link ResponseItem} for uniform storage.
+ */
+ public void saveResponse(
+ String responseId,
+ com.openai.models.responses.Response response,
+ String previousResponseId,
+ String conversationId) {
+
+ // Track insertion order and evict the oldest when the cap is reached.
+ if (maxResponses > 0 && !responses.containsKey(responseId)) {
+ insertionOrder.addLast(responseId);
+ while (responses.size() >= maxResponses) {
+ String oldest = insertionOrder.pollFirst();
+ if (oldest != null) {
+ evictResponse(oldest);
+ }
+ }
+ }
+
+ responses.put(responseId, response);
+
+ List itemIdList = new ArrayList<>(response.output().size());
+
+ for (ResponseOutputItem outputItem : response.output()) {
+ ResponseItem item = ItemConversion.toResponseItem(outputItem);
+ String itemId = extractOutputItemId(outputItem);
+ if (item != null && itemId != null) {
+ items.put(itemId, item);
+ itemIdList.add(itemId);
+ }
+ }
+
+ responseItemIds.merge(responseId, itemIdList, (existing, newIds) -> {
+ // If input items were already stored, append output items after them
+ List combined = new ArrayList<>(existing.size() + newIds.size());
+ combined.addAll(existing);
+ combined.addAll(newIds);
+ return combined;
+ });
+
+ if (previousResponseId != null && !previousResponseId.isEmpty()) {
+ responsePreviousId.put(responseId, previousResponseId);
+ }
+
+ if (conversationId != null && !conversationId.isEmpty()) {
+ conversationResponses
+ .computeIfAbsent(conversationId, k -> new CopyOnWriteArrayList<>())
+ .add(responseId);
+ }
+ }
+
+ @Override
+ public CompletableFuture saveResponseAsync(
+ String responseId,
+ com.openai.models.responses.Response response,
+ String previousResponseId,
+ String conversationId) {
+ saveResponse(responseId, response, previousResponseId, conversationId);
+ return CompletableFuture.completedFuture(null);
+ }
+
+ // ── Private helpers ─────────────────────────────────────────
+
+ @Override
+ public CompletableFuture saveInputItemsAsync(
+ String responseId,
+ List inputItems) {
+ if (inputItems == null || inputItems.isEmpty()) {
+ return CompletableFuture.completedFuture(null);
+ }
+
+ List inputItemIds = new ArrayList<>();
+ for (ResponseItem item : inputItems) {
+ String itemId = extractItemId(item);
+ if (itemId != null) {
+ items.put(itemId, item);
+ inputItemIds.add(itemId);
+ }
+ }
+
+ if (!inputItemIds.isEmpty()) {
+ // Track input item IDs separately for getInputItemsForResponseAsync
+ responseInputItemIds.put(responseId, Collections.unmodifiableList(inputItemIds));
+
+ // Store input item IDs first; output items will be appended by saveResponse
+ responseItemIds.merge(responseId, inputItemIds, (existing, newIds) -> {
+ List combined = new ArrayList<>(newIds.size() + existing.size());
+ combined.addAll(newIds);
+ combined.addAll(existing);
+ return combined;
+ });
+ }
+
+ return CompletableFuture.completedFuture(null);
+ }
+
+ @Override
+ public CompletableFuture> getResponseAsync(String responseId) {
+ return CompletableFuture.completedFuture(Optional.ofNullable(responses.get(responseId)));
+ }
+
+ @Override
+ public CompletableFuture> getInputItemsForResponseAsync(String responseId) {
+ List inputIds = responseInputItemIds.get(responseId);
+ if (inputIds == null || inputIds.isEmpty()) {
+ return CompletableFuture.completedFuture(Collections.emptyList());
+ }
+ List result = new ArrayList<>(inputIds.size());
+ for (String id : inputIds) {
+ ResponseItem item = items.get(id);
+ if (item != null) {
+ result.add(item);
+ }
+ }
+ return CompletableFuture.completedFuture(Collections.unmodifiableList(result));
+ }
+
+ @Override
+ public CompletableFuture deleteResponseAsync(String responseId) {
+ com.openai.models.responses.Response removed = responses.remove(responseId);
+ if (removed != null) {
+ List