feat(responses api): add responses api support by lynx009 · Pull Request #1454 · agentscope-ai/agentscope-java

lynx009 · 2026-05-21T06:20:59Z

AgentScope-Java Version

1.1.0

Description

This PR adds OpenAI Responses API style support to AgentScope Java.

It introduces a new Responses web extension, a Spring Boot starter, an example application, and documentation for using AgentScope Java through /v1/responses and /v1/conversations compatible HTTP endpoints.

Main changes:

Added agentscope-extensions-responses-web
- Converts Responses API request input into AgentScope internal messages.
- Builds Responses API compatible response objects.
- Supports non-streaming and streaming Responses API output.
- Supports JSON Schema structured output in both non-streaming and streaming modes.
- Supports function tool schemas, function call output items, multimodal/file-like input item shapes, and official-style response/conversation objects.
Added agentscope-responses-web-starter
- Exposes POST /v1/responses.
- Exposes response retrieval, deletion, cancellation, input item listing, token count, and compact endpoints.
- Exposes conversation creation, retrieval, update, deletion, and item management endpoints.
- Provides in-memory state support for previous_response_id, conversation, store, and background=true.
Added agentscope-examples/responses-web
- Provides a runnable Spring Boot example for manual testing.
- Prints useful curl examples at startup.
Updated documentation
- Added English and Chinese Responses API docs.
- Added installation references for the new starter.
- Added manual verification examples for non-streaming, streaming, structured output, background responses, cancellation, conversations, and input items.

How to test:

mvn -pl agentscope-extensions/agentscope-extensions-responses-web,agentscope-extensions/agentscope-spring-boot-starters/agentscope-responses-web-starter spotless:apply
mvn -pl agentscope-extensions/agentscope-extensions-responses-web,agentscope-extensions/agentscope-spring-boot-starters/agentscope-responses-web-starter -am -Dtest='io.agentscope.core.responses.**,io.agentscope.spring.boot.responses.**' -DfailIfNoTests=false -DfailIfNoSpecifiedTests=false test
mvn -pl agentscope-examples/responses-web -am -DskipTests package
Manual test example:

curl -s -X POST http://localhost:8080/v1/responses \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3-max",
    "input": "Hello, briefly introduce AgentScope Java.",
    "store": true
  }'
Streaming test example:

curl -N -X POST http://localhost:8080/v1/responses \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{
    "model": "qwen3-max",
    "input": "Please stream three short sentences.",
    "stream": true
  }'

Checklist
Please check the following items before code is ready to be reviewed.

Code has been formatted with mvn spotless:apply
All tests are passing (mvn test)
Javadoc comments are complete and follow project conventions
Related documentation has been updated (e.g. links, examples, etc.)
Code is ready for review

Copilot

Pull request overview

This PR introduces OpenAI Responses API-compatible HTTP support to AgentScope Java by adding a new Responses web extension, a Spring Boot starter exposing /v1/responses and /v1/conversations, a runnable example app, and corresponding English/Chinese documentation.

Changes:

Added agentscope-extensions-responses-web for converting Responses requests into AgentScope messages and producing Responses-style non-streaming/streaming outputs (including JSON Schema structured output).
Added agentscope-responses-web-starter with Spring Boot auto-configuration, controllers, streaming service, and an in-memory state backend for stored responses/background/conversations.
Added a responses-web example module plus docs + TOC + BOM/distribution wiring.

Reviewed changes

Copilot reviewed 55 out of 55 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/zh/task/responses-api.md	New Chinese Responses API usage guide and curl examples.
docs/zh/quickstart/installation.md	Adds the new Responses starter to the starter list (ZH).
docs/en/task/responses-api.md	New English Responses API usage guide and curl examples.
docs/en/quickstart/installation.md	Adds the new Responses starter to the starter list (EN).
docs/_toc.yml	Adds Responses API docs pages to EN/ZH TOC.
agentscope-extensions/pom.xml	Registers the new `agentscope-extensions-responses-web` module.
agentscope-extensions/agentscope-spring-boot-starters/pom.xml	Registers the new `agentscope-responses-web-starter` module.
agentscope-extensions/agentscope-spring-boot-starters/agentscope-responses-web-starter/pom.xml	New starter module dependencies (Spring MVC + validation + tests).
agentscope-extensions/agentscope-spring-boot-starters/agentscope-responses-web-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports	Enables auto-configuration discovery for the starter.
agentscope-extensions/agentscope-spring-boot-starters/agentscope-responses-web-starter/src/main/java/io/agentscope/spring/boot/responses/config/ResponsesWebAutoConfiguration.java	Auto-configures controllers, converters, streaming, and state beans.
agentscope-extensions/agentscope-spring-boot-starters/agentscope-responses-web-starter/src/main/java/io/agentscope/spring/boot/responses/config/ResponsesProperties.java	Adds `agentscope.responses.*` configuration properties.
agentscope-extensions/agentscope-spring-boot-starters/agentscope-responses-web-starter/src/main/java/io/agentscope/spring/boot/responses/web/ResponsesController.java	Implements `/v1/responses` endpoints incl. streaming/background/stateful operations.
agentscope-extensions/agentscope-spring-boot-starters/agentscope-responses-web-starter/src/main/java/io/agentscope/spring/boot/responses/web/ConversationsController.java	Implements `/v1/conversations` CRUD and items endpoints.
agentscope-extensions/agentscope-spring-boot-starters/agentscope-responses-web-starter/src/main/java/io/agentscope/spring/boot/responses/service/ResponsesStreamingService.java	Converts core Responses stream events to Spring `ServerSentEvent`.
agentscope-extensions/agentscope-spring-boot-starters/agentscope-responses-web-starter/src/main/java/io/agentscope/spring/boot/responses/service/ResponsesStateService.java	In-memory state backend for responses, background tasks, and conversations.
agentscope-extensions/agentscope-spring-boot-starters/agentscope-responses-web-starter/src/test/java/io/agentscope/spring/boot/responses/config/ResponsesWebAutoConfigurationTest.java	Verifies auto-configured beans and property binding.
agentscope-extensions/agentscope-spring-boot-starters/agentscope-responses-web-starter/src/test/java/io/agentscope/spring/boot/responses/web/ResponsesControllerTest.java	Tests create/retrieve/store/background/streaming and error behavior.
agentscope-extensions/agentscope-spring-boot-starters/agentscope-responses-web-starter/src/test/java/io/agentscope/spring/boot/responses/web/ConversationsControllerTest.java	Tests conversation CRUD and item lifecycle.
agentscope-extensions/agentscope-extensions-responses-web/pom.xml	New core extension module for Responses protocol support.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/converter/ResponsesInputConverter.java	Converts Responses input shapes to AgentScope `Msg` + system fragments + schema metadata.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/converter/ResponsesToolConverter.java	Converts function tools + `tool_choice` into AgentScope tool schemas/choices.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/converter/ResponsesGenerationOptionsConverter.java	Maps Responses generation fields to AgentScope `GenerateOptions`.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/converter/ResponsesConversionResult.java	Record encapsulating conversion outputs.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/converter/ResponsesValidationException.java	Carries Responses-style validation error metadata.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/hook/ResponsesRequestHook.java	Applies system fragments + per-request generation options via hooks.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/builder/ResponsesResponseBuilder.java	Builds Responses non-streaming/structured/stream-terminal payloads and errors.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/streaming/ResponsesStreamingAdapter.java	Core choreography converting AgentScope stream events into Responses stream events.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesRequest.java	DTO for `/v1/responses` request payload.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesResponse.java	DTO for Responses non-streaming response object.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesStreamEvent.java	DTO for streaming event payloads.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesOutputItem.java	Models message/function_call output items.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesContentPart.java	Models content parts like `output_text`.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesTool.java	Models function tool declarations.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesTextConfig.java	Models `text.format` configuration (incl. schema).
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesReasoningConfig.java	Models `reasoning.effort` config.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesUsage.java	Models token usage in Responses shape.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesTokenCount.java	Models token count endpoint response.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesList.java	Generic list wrapper for Responses/Conversations endpoints.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesConversation.java	Models conversation resource.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesConversationRequest.java	Models conversation create/update request payload.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesConversationItemsRequest.java	Models conversation items create request payload.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesDeletionStatus.java	Models delete confirmation payload.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesError.java	Models error payload shape.
agentscope-extensions/agentscope-extensions-responses-web/src/main/java/io/agentscope/core/responses/model/ResponsesErrorResponse.java	Models error wrapper returned for 4xx validation errors.
agentscope-extensions/agentscope-extensions-responses-web/src/test/java/io/agentscope/core/responses/converter/ResponsesInputConverterTest.java	Unit tests for input conversion (multimodal, tools, stateful fields).
agentscope-extensions/agentscope-extensions-responses-web/src/test/java/io/agentscope/core/responses/converter/ResponsesToolConverterTest.java	Unit tests for tool schema + tool_choice conversion.
agentscope-extensions/agentscope-extensions-responses-web/src/test/java/io/agentscope/core/responses/converter/ResponsesGenerationOptionsConverterTest.java	Unit tests for generation option mapping.
agentscope-extensions/agentscope-extensions-responses-web/src/test/java/io/agentscope/core/responses/builder/ResponsesResponseBuilderTest.java	Unit tests for non-streaming + structured + error payload building.
agentscope-extensions/agentscope-extensions-responses-web/src/test/java/io/agentscope/core/responses/streaming/ResponsesStreamingAdapterTest.java	Unit tests for streaming event choreography and structured streaming.
agentscope-examples/pom.xml	Adds the new `responses-web` example module.
agentscope-examples/responses-web/pom.xml	New example Spring Boot app module wiring.
agentscope-examples/responses-web/src/main/resources/application.yml	Example configuration enabling responses/conversations endpoints.
agentscope-examples/responses-web/src/main/java/io/agentscope/examples/responses/ResponsesWebApplication.java	Sample app entrypoint that prints curl-based manual verification instructions.
agentscope-distribution/agentscope-bom/pom.xml	Adds new extension + starter to the BOM.
agentscope-distribution/agentscope-all/pom.xml	Adds new extension to the “all” distribution artifact.

+        StringBuilder builder = new StringBuilder();
+        for (ContentBlock block : content) {
+            if (block instanceof TextBlock textBlock) {
+                if (!builder.isEmpty()) {


+        response.setStatus(status);
+        response.setModel(request != null ? request.getModel() : null);
+        response.setInstructions(request != null ? request.getInstructions() : null);
+        response.setStore(request == null || !Boolean.FALSE.equals(request.getStore()));


+            return createNonStreamingResponse(prepared.request(), conversion, responseId)
+                    .map(response -> stateService.save(response, prepared));
+        } catch (ResponsesValidationException e) {
+            return ResponseEntity.badRequest().body(responseBuilder.buildErrorResponse(e));
+        } catch (IllegalArgumentException e) {
+            return ResponseEntity.badRequest().body(responseBuilder.buildInvalidRequestError(e));
+        }


+        // Store the subscription separately so /cancel can dispose it while the model call is still
+        // running.
+        Disposable task =
+                createNonStreamingResponse(request, conversion, responseId)
+                        .map(response -> stateService.save(response, prepared))
+                        .subscribe();
+        stateService.attachBackgroundTask(responseId, task);


+    private ServerSentEvent<String> toSse(ResponsesStreamEvent event) {
+        try {
+            return ServerSentEvent.<String>builder()
+                    .event(event.getType())
+                    .data(OBJECT_MAPPER.writeValueAsString(event))
+                    .build();
+        } catch (JsonProcessingException e) {
+            return ServerSentEvent.<String>builder()
+                    .event("error")
+                    .data("{\"error\":\"Serialization error\"}")
+                    .build();
+        }


codecov · 2026-05-21T06:32:25Z

Codecov Report

❌ Patch coverage is 64.25703% with 534 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...e/responses/converter/ResponsesInputConverter.java	53.30%	59 Missing and 40 partials ⚠️
.../boot/responses/service/ResponsesStateService.java	58.29%	60 Missing and 28 partials ⚠️
...spring/boot/responses/web/ResponsesController.java	62.87%	44 Missing and 5 partials ⚠️
...re/responses/builder/ResponsesResponseBuilder.java	65.83%	16 Missing and 25 partials ⚠️
...responses/streaming/ResponsesStreamingAdapter.java	81.44%	19 Missing and 22 partials ⚠️
...agentscope/core/responses/model/ResponsesList.java	0.00%	37 Missing ⚠️
...re/responses/converter/ResponsesToolConverter.java	57.69%	8 Missing and 14 partials ⚠️
...ng/boot/responses/web/ConversationsController.java	42.42%	18 Missing and 1 partial ⚠️
...cope/core/responses/hook/ResponsesRequestHook.java	0.00%	18 Missing ⚠️
...pe/core/responses/model/ResponsesConversation.java	0.00%	15 Missing ⚠️
... and 16 more

📢 Thoughts on this report? Let us know!

lynx009 added 4 commits May 20, 2026 19:08

feat: add responses api support

eeac443

fix: fix warnings

69c8009

fix: fix warnings and errors

00b2ed7

Merge branch 'main' into feat/responses-api-support

5d61a62

lynx009 requested review from a team and Copilot May 21, 2026 06:21

Copilot started reviewing on behalf of lynx009 May 21, 2026 06:21 View session

Copilot AI reviewed May 21, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(responses api): add responses api support#1454

feat(responses api): add responses api support#1454
lynx009 wants to merge 4 commits into
agentscope-ai:mainfrom
lynx009:feat/responses-api-support

lynx009 commented May 21, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

codecov Bot commented May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

lynx009 commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

AgentScope-Java Version

Description

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

codecov Bot commented May 21, 2026

Codecov Report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lynx009 commented May 21, 2026 •

edited

Loading