Responses protocol methods (#49244)

* Add protocol methods to ResponsesClient and ResponsesAsyncClient

Adds BinaryData + com.openai.core.RequestOptions protocol-style methods on the Responses sync and async clients that delegate to the openai-java ResponseService.withRawResponse() / ResponseServiceAsync.withRawResponse() surface and return the openai-java raw HTTP response types directly. Specifically:

- createResponseWithResponse / createResponseStreamWithResponse

- getResponseWithResponse

- deleteResponseWithResponse

- cancelResponseWithResponse

The async variants wrap the underlying CompletableFuture in Mono.fromFuture(...). All methods continue to flow through the Azure HTTP pipeline via HttpClientHelper.mapToOpenAIHttpClient. Adds OpenAIJsonHelper.jsonBodyToValueMap(BinaryData) helper used by the create methods to forward the raw JSON body verbatim through ResponseCreateParams.Builder.additionalBodyProperties.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add protocol-method tests for ResponsesClient and ResponsesAsyncClient

Mirrors the existing basicCRUDOperations tests against the new createResponseWithResponse protocol methods (BinaryData + RequestOptions), parses the returned HttpResponseFor<Response>, and asserts on the same shape (non-null Response with an id) as the typed-method tests. Tests remain @disabled pending public preview recordings, consistent with the existing typed tests.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Enable Responses tests with full create/retrieve/delete/cancel/input-items coverage

Cleanup, expansion, and enablement of ResponsesTests and ResponsesAsyncTests:

1. Removed the stale '// currently returning 500' comments and the orphan getOpenAIClient() pseudo-code blocks from the initial Agents V2 commit (PR #47134). Live calls against the service confirmed all four previously-flagged endpoints (retrieve, delete, cancel, input_items) now return 200.

2. Expanded both typed and protocol-method tests to actually exercise the full surface: create -> retrieve -> input_items -> delete in basicCRUDOperations, plus a separate cancelBackgroundResponse / cancelBackgroundResponseWithResponse that creates a background:true response and cancels it (asserting CANCELLED or COMPLETED, since the response may finish before cancel hits). 4 test methods per class (sync + async) x 2 surfaces = 8 tests total.

3. Dropped the class-level @disabled annotations now that recordings exist. Captured live recordings via AZURE_TEST_MODE=RECORD against the Foundry endpoint, pushed via 'test-proxy push -a assets.json' to Azure/azure-sdk-assets, and bumped the assets.json Tag to java/ai/azure-ai-agents_7a1b5ec037. Verified by re-running in default (playback) mode: all 8 tests pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Narrow Responses protocol-methods scope to create + createStream only

Drop the getResponseWithResponse, deleteResponseWithResponse, and
cancelResponseWithResponse protocol methods added previously. The
ResponsesClient/ResponsesAsyncClient surface now exposes protocol-method
variants only for createAzureResponse and createStreamingAzureResponse,
matching the original typed surface.

Tests:
- Trim basicCRUDOperationsWithResponse to exercise createResponseWithResponse only.
- Add basicStreamingOperationsWithResponse to cover createResponseStreamWithResponse.
- Drop cancelBackgroundResponseWithResponse.
- Re-recorded affected sessions; bumped assets.json tag.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Use OpenAI client directly for response get/delete/cancel in tests

ResponsesClient and ResponsesAsyncClient are thin Azure-aware wrappers,
so non-Azure operations (retrieve, delete, cancel) should go through the
underlying com.openai client directly rather than the wrappers' service
getters. Adds getResponseServiceSyncClient/getResponseServiceAsyncClient
helpers in ClientTestBase that build the OpenAIClient/OpenAIClientAsync
and expose .responses(). Updates basicCRUDOperations and
cancelBackgroundResponse in both test classes to use the new helpers
for retrieve/delete/cancel; create still flows through ResponsesClient.

Recordings unchanged (the OpenAI client built by AgentsClientBuilder
shares the same Azure HTTP pipeline as the wrappers' service).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address PR review feedback on Responses protocol methods

- Reword JavaDoc on createResponseWithResponse in both clients to
  clarify the JSON body is forwarded semantically (parsed and
  re-serialized via additionalBodyProperties), not byte-for-byte, since
  property ordering may change and duplicate top-level keys are not
  preserved.
- Apply the same clarification to the streaming variant JavaDoc.
- Wrap HttpResponseFor<Response> in try-with-resources in
  basicCRUDOperationsWithResponse for both sync and async test classes
  so the response is reliably closed.
- Remove unused CREATE_BACKGROUND_RESPONSE_BODY constant in both test
  classes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jpalvarezl

sdk/ai/azure-ai-agents/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 ### Features Added
 
+- Added protocol-style methods on `ResponsesClient` and `ResponsesAsyncClient` that accept a raw JSON request body (`BinaryData`) and a `com.openai.core.RequestOptions`, and return the openai-java raw HTTP response. These mirror the existing `createAzureResponse` and `createStreamingAzureResponse` typed surface: `createResponseWithResponse` (returns `HttpResponseFor<Response>`) and `createResponseStreamWithResponse` (returns `HttpResponseFor<StreamResponse<ResponseStreamEvent>>`). They delegate to the underlying openai-java `ResponseService.withRawResponse()` surface and continue to flow through the Azure HTTP pipeline.
+
+### Other Changes
+
+- Enabled `ResponsesTests` and `ResponsesAsyncTests` (previously `@Disabled`) with create/retrieve/delete/input-items and background-cancel coverage for the typed (`ResponseService` / `ResponseServiceAsync`) surface, plus coverage for the new protocol-method surface. Recordings published to `Azure/azure-sdk-assets` and referenced from `assets.json`.
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/ai/azure-ai-agents/assets.json

@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "java",
   "TagPrefix": "java/ai/azure-ai-agents",
-  "Tag": "java/ai/azure-ai-agents_69308f6d56"
+  "Tag": "java/ai/azure-ai-agents_a3142fe843"
 }

sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/ResponsesAsyncClient.java

@@ -10,8 +10,12 @@
 import com.azure.core.annotation.ReturnType;
 import com.azure.core.annotation.ServiceClient;
 import com.azure.core.annotation.ServiceMethod;
+import com.azure.core.util.BinaryData;
 import com.openai.client.OpenAIClientAsync;
 import com.openai.core.JsonValue;
+import com.openai.core.RequestOptions;
+import com.openai.core.http.HttpResponseFor;
+import com.openai.core.http.StreamResponse;
 import com.openai.models.responses.Response;
 import com.openai.models.responses.ResponseCreateParams;
 import com.openai.models.responses.ResponseStreamEvent;
@@ -84,4 +88,74 @@ public Flux<ResponseStreamEvent> createStreamingAzureResponse(AzureCreateRespons
         params.additionalBodyProperties(additionalBodyProperties);
         return StreamingUtils.toFlux(this.responseServiceAsync.createStreaming(params.build()));
     }
+
+    /**
+     * Creates a response from a raw JSON request body and returns the raw HTTP response.
+     *
+     * <p>This protocol method delegates to the OpenAI Java SDK's
+     * {@link ResponseServiceAsync.WithRawResponse#create(ResponseCreateParams, RequestOptions)}. The
+     * {@code createResponseRequest} payload is forwarded as the request body (semantically, not
+     * byte-for-byte: the JSON is parsed and re-serialized via {@code additionalBodyProperties},
+     * so property ordering and exact formatting may change and duplicate top-level keys are not
+     * preserved), so callers can include Azure-specific extensions (such as
+     * {@link com.azure.ai.agents.models.AgentReference}) without going through the strongly-typed
+     * {@link ResponseCreateParams.Builder}.</p>
+     *
+     * <p>The returned {@link HttpResponseFor} exposes the status code, headers, and the raw
+     * response stream via {@code body()}, or the typed {@link Response} via {@code parse()}. Only
+     * one of {@code body()} or {@code parse()} may be invoked per response, and the caller must
+     * close the response (e.g. via try-with-resources) to release the underlying connection.</p>
+     *
+     * <p>Note: the second parameter is the openai-java {@link RequestOptions} (not the azure-core
+     * type) so that the OpenAI-supported options (timeout, response validation) translate
+     * faithfully. Additional headers or query parameters must be supplied via the OpenAI request
+     * builder pattern (e.g. by using {@link #createAzureResponse} for fully-typed requests).</p>
+     *
+     * @param createResponseRequest the JSON body representing the create-response request; must be a JSON object.
+     * @param requestOptions optional OpenAI request options; pass {@code null} to use the defaults.
+     * @return a {@link Mono} emitting the raw HTTP response, parseable as a {@link Response}.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public Mono<HttpResponseFor<Response>> createResponseWithResponse(BinaryData createResponseRequest,
+        RequestOptions requestOptions) {
+        Objects.requireNonNull(createResponseRequest, "createResponseRequest cannot be null");
+
+        ResponseCreateParams params = ResponseCreateParams.builder()
+            .additionalBodyProperties(OpenAIJsonHelper.jsonBodyToValueMap(createResponseRequest))
+            .build();
+        return Mono.fromFuture(this.responseServiceAsync.withRawResponse()
+            .create(params, requestOptions == null ? RequestOptions.none() : requestOptions));
+    }
+
+    /**
+     * Creates a streaming response from a raw JSON request body and returns the raw HTTP response.
+     *
+     * <p>Delegates to the OpenAI Java SDK's
+     * {@link ResponseServiceAsync.WithRawResponse#createStreaming(ResponseCreateParams, RequestOptions)}.
+     * The {@code createResponseRequest} payload is forwarded as the request body (semantically,
+     * not byte-for-byte: the JSON is parsed and re-serialized, so property ordering and exact
+     * formatting may change and duplicate top-level keys are not preserved).</p>
+     *
+     * <p>The returned {@link HttpResponseFor} wraps a {@link StreamResponse} of
+     * {@link ResponseStreamEvent} items, which the caller iterates via {@link HttpResponseFor#parse()}.
+     * Note that the underlying stream produced by the openai-java SDK's raw async streaming API is
+     * iterator-based and blocking; for a Reactor-friendly streaming surface use
+     * {@link #createStreamingAzureResponse(AzureCreateResponseOptions, ResponseCreateParams.Builder)}
+     * instead.</p>
+     *
+     * @param createResponseRequest the JSON body representing the create-response request; must be a JSON object.
+     * @param requestOptions optional OpenAI request options; pass {@code null} to use the defaults.
+     * @return a {@link Mono} emitting the raw HTTP response, parseable as a {@link StreamResponse} of {@link ResponseStreamEvent}.
+     */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
+    public Mono<HttpResponseFor<StreamResponse<ResponseStreamEvent>>>
+        createResponseStreamWithResponse(BinaryData createResponseRequest, RequestOptions requestOptions) {
+        Objects.requireNonNull(createResponseRequest, "createResponseRequest cannot be null");
+
+        ResponseCreateParams params = ResponseCreateParams.builder()
+            .additionalBodyProperties(OpenAIJsonHelper.jsonBodyToValueMap(createResponseRequest))
+            .build();
+        return Mono.fromFuture(this.responseServiceAsync.withRawResponse()
+            .createStreaming(params, requestOptions == null ? RequestOptions.none() : requestOptions));
+    }
 }

sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/ResponsesClient.java

@@ -11,9 +11,13 @@
 import com.azure.core.annotation.ServiceClient;
 import com.azure.core.annotation.ServiceMethod;
 import com.azure.core.annotation.ReturnType;
+import com.azure.core.util.BinaryData;
 import com.azure.core.util.IterableStream;
 import com.openai.client.OpenAIClient;
 import com.openai.core.JsonValue;
+import com.openai.core.RequestOptions;
+import com.openai.core.http.HttpResponseFor;
+import com.openai.core.http.StreamResponse;
 import com.openai.models.responses.Response;
 import com.openai.models.responses.ResponseCreateParams;
 import com.openai.models.responses.ResponseStreamEvent;
@@ -97,4 +101,72 @@ public static AzureCreateResponseDetails getAzureFields(Response response) {
             AzureCreateResponseDetails::fromJson);
     }
 
+    /**
+     * Creates a response from a raw JSON request body and returns the raw HTTP response.
+     *
+     * <p>This protocol method delegates to the OpenAI Java SDK's
+     * {@link ResponseService.WithRawResponse#create(ResponseCreateParams, RequestOptions)}. The
+     * {@code createResponseRequest} payload is forwarded as the request body (semantically, not
+     * byte-for-byte: the JSON is parsed and re-serialized via {@code additionalBodyProperties},
+     * so property ordering and exact formatting may change and duplicate top-level keys are not
+     * preserved), so callers can include Azure-specific extensions (such as
+     * {@link com.azure.ai.agents.models.AgentReference}) without going through the strongly-typed
+     * {@link ResponseCreateParams.Builder}.</p>
+     *
+     * <p>The returned {@link HttpResponseFor} exposes the status code, headers, and the raw
+     * response stream via {@code body()}, or the typed {@link Response} via {@code parse()}. Only
+     * one of {@code body()} or {@code parse()} may be invoked per response, and the caller must
+     * close the response (e.g. via try-with-resources) to release the underlying connection.</p>
+     *
+     * <p>Note: the second parameter is the openai-java {@link RequestOptions} (not the azure-core
+     * type) so that the OpenAI-supported options (timeout, response validation) translate
+     * faithfully. Additional headers or query parameters must be supplied via the OpenAI request
+     * builder pattern (e.g. by using {@link #createAzureResponse} for fully-typed requests).</p>
+     *
+     * @param createResponseRequest the JSON body representing the create-response request; must be a JSON object.
+     * @param requestOptions optional OpenAI request options; pass {@code null} to use the defaults.
+     * @return the raw HTTP response, parseable as a {@link Response}.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public HttpResponseFor<Response> createResponseWithResponse(BinaryData createResponseRequest,
+        RequestOptions requestOptions) {
+        Objects.requireNonNull(createResponseRequest, "createResponseRequest cannot be null");
+
+        ResponseCreateParams params = ResponseCreateParams.builder()
+            .additionalBodyProperties(OpenAIJsonHelper.jsonBodyToValueMap(createResponseRequest))
+            .build();
+        return this.responseService.withRawResponse()
+            .create(params, requestOptions == null ? RequestOptions.none() : requestOptions);
+    }
+
+    /**
+     * Creates a streaming response from a raw JSON request body and returns the raw HTTP response.
+     *
+     * <p>Delegates to the OpenAI Java SDK's
+     * {@link ResponseService.WithRawResponse#createStreaming(ResponseCreateParams, RequestOptions)}.
+     * The {@code createResponseRequest} payload is forwarded as the request body (semantically,
+     * not byte-for-byte: the JSON is parsed and re-serialized, so property ordering and exact
+     * formatting may change and duplicate top-level keys are not preserved).</p>
+     *
+     * <p>The returned {@link HttpResponseFor} wraps a {@link StreamResponse} of
+     * {@link ResponseStreamEvent} items, which the caller iterates via {@link HttpResponseFor#parse()}.
+     * The underlying stream must be closed when iteration completes; the typical pattern is
+     * try-with-resources on either the {@link HttpResponseFor} or the parsed {@link StreamResponse}.</p>
+     *
+     * @param createResponseRequest the JSON body representing the create-response request; must be a JSON object.
+     * @param requestOptions optional OpenAI request options; pass {@code null} to use the defaults.
+     * @return the raw HTTP response, parseable as a {@link StreamResponse} of {@link ResponseStreamEvent}.
+     */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
+    public HttpResponseFor<StreamResponse<ResponseStreamEvent>>
+        createResponseStreamWithResponse(BinaryData createResponseRequest, RequestOptions requestOptions) {
+        Objects.requireNonNull(createResponseRequest, "createResponseRequest cannot be null");
+
+        ResponseCreateParams params = ResponseCreateParams.builder()
+            .additionalBodyProperties(OpenAIJsonHelper.jsonBodyToValueMap(createResponseRequest))
+            .build();
+        return this.responseService.withRawResponse()
+            .createStreaming(params, requestOptions == null ? RequestOptions.none() : requestOptions);
+    }
+
 }

sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/implementation/OpenAIJsonHelper.java

@@ -160,18 +160,43 @@ public static <T extends JsonSerializable<T>> Map<String, JsonValue> toJsonValue
         }
         try {
             String json = BinaryData.fromObject(obj).toString();
-            Map<String, Object> map = MAPPER.readValue(json, new TypeReference<Map<String, Object>>() {
-            });
-            Map<String, JsonValue> result = new HashMap<>();
-            for (Map.Entry<String, Object> entry : map.entrySet()) {
-                result.put(entry.getKey(), JsonValue.from(entry.getValue()));
-            }
-            return result;
+            return jsonStringToJsonValueMap(json);
         } catch (IOException e) {
             throw new RuntimeException("Failed to flatten JsonSerializable to JsonValue map", e);
         }
     }
 
+    /**
+     * Parses raw JSON bytes representing a top-level JSON object into a map of property names to
+     * {@link JsonValue} entries, suitable for placing on an openai-java request builder via
+     * {@code additionalBodyProperties(Map)}. The strongly-typed builder fields remain unset, so
+     * the serialized output of the resulting params matches the original JSON.
+     *
+     * @param body the JSON body bytes; the content must represent a JSON object.
+     * @return a map of property names to {@link JsonValue} entries, or an empty map if the input is null.
+     * @throws RuntimeException if the input is not a valid JSON object.
+     */
+    public static Map<String, JsonValue> jsonBodyToValueMap(BinaryData body) {
+        if (body == null) {
+            return new HashMap<>();
+        }
+        try {
+            return jsonStringToJsonValueMap(body.toString());
+        } catch (IOException e) {
+            throw new RuntimeException("Failed to parse JSON body to JsonValue map", e);
+        }
+    }
+
+    private static Map<String, JsonValue> jsonStringToJsonValueMap(String json) throws IOException {
+        Map<String, Object> map = MAPPER.readValue(json, new TypeReference<Map<String, Object>>() {
+        });
+        Map<String, JsonValue> result = new HashMap<>();
+        for (Map.Entry<String, Object> entry : map.entrySet()) {
+            result.put(entry.getKey(), JsonValue.from(entry.getValue()));
+        }
+        return result;
+    }
+
     /**
      * Deserializes a map of {@link JsonValue} entries (typically from
      * {@code response._additionalProperties()}) into an Azure SDK type that implements

sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/ClientTestBase.java

@@ -15,7 +15,9 @@
 import com.azure.core.util.Configuration;
 import com.azure.identity.DefaultAzureCredentialBuilder;
 import com.openai.services.async.ConversationServiceAsync;
+import com.openai.services.async.ResponseServiceAsync;
 import com.openai.services.blocking.ConversationService;
+import com.openai.services.blocking.ResponseService;
 
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -84,6 +86,16 @@ protected ResponsesAsyncClient getResponsesAsyncClient(HttpClient httpClient,
         return getClientBuilder(httpClient, agentsServiceVersion).buildResponsesAsyncClient();
     }
 
+    protected ResponseService getResponseServiceSyncClient(HttpClient httpClient,
+        AgentsServiceVersion agentsServiceVersion) {
+        return getClientBuilder(httpClient, agentsServiceVersion).buildOpenAIClient().responses();
+    }
+
+    protected ResponseServiceAsync getResponseServiceAsyncClient(HttpClient httpClient,
+        AgentsServiceVersion agentsServiceVersion) {
+        return getClientBuilder(httpClient, agentsServiceVersion).buildOpenAIAsyncClient().responses();
+    }
+
     protected MemoryStoresClient getMemoryStoresSyncClient(HttpClient httpClient,
         AgentsServiceVersion agentsServiceVersion) {
         return getClientBuilder(httpClient, agentsServiceVersion).buildMemoryStoresClient();