feat(openai-official): add OpenAI Responses API module - #3078

🟡 Changes recommended

There are correctness/usability issues in provider configuration and connection-field validation (env base URL resolution and blank-value normalization) that should be fixed before merging.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

        String effectiveBaseUrl = effectiveOptions.getBaseUrl();
        if (effectiveBaseUrl != null && !Objects.equals(effectiveBaseUrl, baseUrl)) {
            throw new OpenAIOfficialModelException(

    /** GPT-5.4-mini with Multi-Agent Formatter. */

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

已审。重点检查了新增 openai-official Responses 模块的请求映射、非流式解析、流式事件拼装、usage/metadata/finishReason、工具调用回放、错误转换、provider SPI、BOM/distribution 接入和相关测试覆盖。\n\n本地验证：mvn -pl agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-openai-official -am test -DskipITs 通过，274 tests, 0 failures/errors, 2 skipped。\n\n未发现需要阻塞合并的问题。

Requesting changes after re-checking PR head 0bcf019. I found release-blocking correctness issues that should be fixed before merge.

[HIGH] Multi-agent formatter drops encrypted reasoning replay

OpenAIResponsesChatModel sends all history through formatter::formatHistory when a ResponsesMultiAgentFormatter is configured (OpenAIResponsesChatModel.java:112-122). In that path, ordinary assistant messages are classified as AGENT_CONVERSATION unless they contain tool blocks (ResponsesMultiAgentFormatter.java:172-181), and mergeAgentConversation rewrites them into a user <history> message (ResponsesMultiAgentFormatter.java:209-237). processMessage then serializes ThinkingBlock as visible text (ResponsesMultiAgentFormatter.java:305-312) and never delegates to ResponsesRequestMapper.mapAssistantMessage, which is the only code path that emits the Responses reasoning replay item from openai.reasoning.encrypted_content metadata (ResponsesRequestMapper.java:433-445, ResponsesRequestMapper.java:477-493).

This breaks stateless reasoning replay exactly for the documented reasoning + multi-agent formatter usage. Please preserve assistant messages with encrypted reasoning metadata as Responses reasoning input items, or route them through a passthrough/delegation path, and add a regression test that configures OpenAIResponsesChatModel with new ResponsesMultiAgentFormatter() and asserts second-turn input contains the encrypted ResponseReasoningItem.

[MEDIUM] Schema-level strict mode is ignored for JSON schema structured output

JsonSchema exposes strict (JsonSchema.java:91-96), but ResponsesRequestMapper only writes schemaBuilder.strict(...) from the model-level strictJsonSchema flag (ResponsesRequestMapper.java:178-187). A caller setting ResponseFormat.json_schema with JsonSchema.strict(true) silently gets a request without strict: true unless they also configure the model builder flag.

Please resolve strict as schema-level first, then builder-level fallback, e.g. schema.getStrict() != null ? schema.getStrict() : strictJsonSchema, and add tests for schema-level override plus builder-level fallback.

[HIGH] all-in-one shaded artifact can lose ModelProvider service registration

The new module is added to agentscope-all (agentscope-all/pom.xml:111-116) and has its own SPI file (agentscope-extensions-model-openai-official/src/main/resources/META-INF/services/io.agentscope.core.model.spi.ModelProvider:1). But the shade config only includes artifacts and has no ServicesResourceTransformer or equivalent service merge (agentscope-all/pom.xml:449-466). There are multiple model-provider service descriptors across extension modules, so the shaded jar can keep only one descriptor and drop OpenAIOfficialModelProvider, making ModelRegistry discovery fail for users depending on the all-in-one agentscope artifact.

Please add a service resource transformer to the shade plugin and a packaging regression check that the shaded jar's META-INF/services/io.agentscope.core.model.spi.ModelProvider contains io.agentscope.extensions.model.openaiofficial.OpenAIOfficialModelProvider.

CI is green, but these are behavioral/package correctness issues not covered by the current checks.

One additional blocking issue affects the default formatter path as well.

[HIGH] The production ReActAgent path discards encrypted reasoning metadata before the next turn

ResponsesResponseParser stores openai.reasoning.encrypted_content only in the terminal ChatResponse.metadata (lines 105-106), and the streaming path does the same in ResponsesStreamingAssembler (lines 261-263). However, the production consumer, ReasoningContext.processChunk, never reads chunk.getMetadata(); buildFinalMessage() creates a fresh metadata map containing only MessageMetadataKeys.CHAT_USAGE. The resulting assistant Msg therefore cannot contain the key that ResponsesRequestMapper.mapAssistantMessage looks up at lines 434-444.

As a result, encrypted reasoning replay is unreachable through a normal ReActAgent call even without ResponsesMultiAgentFormatter. This is particularly important for stateless reasoning/tool-call loops, where the reasoning item from the prior response must be sent back with the function-call output. The current cross-turn tests miss this because they manually construct an AssistantMessage with openai.reasoning.encrypted_content already present instead of exercising ChatResponse -> ReasoningContext -> Msg -> next request.

Please preserve the terminal response metadata in the final assistant message (or place the replay data on a content block and ensure its accumulator preserves it), and add a ReActAgent-level two-iteration regression test that captures the second ResponseCreateParams and asserts it contains the prior encrypted reasoning item.

Summary

Introduces a new agentscope-extensions-model-openai-official module implementing the OpenAI Responses API (as distinct from the existing chat-completions extension): SDK-backed client factory, request mapper, response parser, a streaming assembler over the SDK's StreamResponse, an error translator, credential type, ModelProvider SPI registration, an e2e ProviderFactory provider, and docs in both locales. 46 files, ~9.3k diff lines, of which the substantive new module is roughly 1.6k lines of main and the rest tests and docs.

This is a strong, unusually careful module. I specifically checked the areas this repo's review guidance calls out and they hold up:

• Credential handling — OpenAIOfficialCredential.toString() redacts the key to apiKey=***, and per-request apiKey overrides are explicitly rejected rather than silently honoured, which closes the usual leak-into-logs path.
• Streaming reliability — doFinally(signal -> closeQuietly(streamResponse)) covers complete/error/cancel, terminal failed/error/incomplete events are translated rather than swallowed, and maxRetries(0) delegates retry to AgentScope with a moduleRetryOn() predicate rather than double-retrying.
• Plugin isolation — SPI registration via META-INF/services plus aggregation/BOM wiring, and Check Module Sync is green.

The one real defect is a narrow stream-leak path; the rest is a scoping question about core.

Findings

• [Warning] OpenAIResponsesChatModel.java:154 — StreamResponse is not closed if assemble(...) throws before its doFinally guard is attached (see inline comment for the mechanism and a fix).
• [Warning] ModelContextWindows.java:72 — seven new model→context-window entries are added to agentscope-core, but they describe models served by this new extension and the same OPENAI table is consumed by the existing OpenAI extension. Core changes cascade to harness/distribution/extensions, so an inflated value mis-sizes compaction silently. A citable source per value plus a resolution test would make the table trustworthy.
• [Info] ModelContextWindows.java:87 — the glm-5.3 entry is unrelated to this feature and would be easier to review and revert as its own change.

Suggestions

The stream cleanup is the only thing I would fix before merge; it is a few lines. If you prefer to keep the provider's model metadata with the provider, a per-extension context-window table that core consults through the SPI would also avoid the core edit entirely — not something to change in this PR, just worth a follow-up issue since every new provider module currently has to touch core.

Tests

Coverage is comprehensive (error translation, credential, SDK client factory, request mapper, response parser, streaming assembler, cross-turn, plus e2e wiring), and CI is green on ubuntu-latest with 8 checks passing. Note that a 9.3k-line diff means I reviewed the new module's main sources and the core/pom edits closely and sampled the tests and docs rather than auditing every assertion — the maintainers should still read the assembler state machine end to end.

Automated review by github-manager-bot

Summary

Re-review of bb20ab81 (delta against b51a889d; the earlier reviewed commit 24f3b42b is gone from the branch). The one defect I had gated on is fixed, and the reasoning-metadata move is coherent end to end.

StreamResponse leak — fixed. streamResponse is hoisted out of the try in buildStreamingFlux and closed in the catch, so the window where assemble threw before its doFinally guard was attached is covered, and streamThrowsInAssembleClosesSdkStream asserts it by making stream() throw and waiting on the close latch. closeQuietly was widened to package-private for exactly this, which is the narrower of the two options I suggested.

Reasoning metadata onto ThinkingBlock — verified against core, and it holds. ThinkingAccumulator does metadata.putAll(block.getMetadata()) and rebuilds the block with that metadata, so encrypted_content now survives aggregation into the stored assistant message and is read back by mapAssistantMessage — the previous ChatResponse.metadata location was the one that got dropped on aggregation. I also checked the empty-text case: ReActAgent's block emitter skips deltas when getThinking() is empty and AguiStreamContext.closeReasoningMessage no-ops for a message id that was never started, so a metadata-only ThinkingBlock does not surface as an empty reasoning message to AG-UI clients. Good.

The schema-level strict precedence (schema.getStrict() overriding the builder default) and its two tests look correct.

Still open from the previous round (unchanged by this commit): the seven gpt-5.x context-window entries plus glm-5.3 are still added to agentscope-core's ModelContextWindows, still with no citable source per value and no resolution test. I am not re-flagging it inline because it is a scoping call for the maintainers, but it was my last substantive Warning and it has not moved.

Findings

• [Info] ResponsesMultiAgentFormatter.java:183 — reusing GroupType.TOOL_SEQUENCE where GroupType.BYPASS is the type that means "mapped individually, never merged"; current behaviour is correct but relies on the tool-branch role filter.
• [Info] ResponsesMultiAgentFormatter.java:204 — first-ThinkingBlock-only assumption shared with ResponsesRequestMapper.mapAssistantMessage.

Compatibility note

Dropping MD_REASONING_SUMMARY removes openai.reasoning.summary from parsed-response metadata. Nothing in this repo reads it, and the module is unreleased, so this is fine — but it is a silent output-shape change for anyone already coding against the Responses module, so it is worth one line in the module's docs/changelog.

CI / CLA / why not approving

All checks pass on bb20ab81 (build ubuntu-latest, build windows-latest, Check License, Check Module Sync, codecov/patch, validate) and CLA is signed. I am deliberately not approving: Aias00's CHANGES_REQUESTED is still the most recent review state on the PR, and the ServicesResourceTransformer addition to the agentscope-all shade config is the response to it — that resolution needs the requesting maintainer's re-review, not mine. Nothing here blocks them; both inline notes are non-blocking.

Automated review by github-manager-bot