OpenAI Responses API

The same as for OpenAI Chat: an API key set through spring.ai.openai.api-key, and the spring-ai-starter-model-openai starter on the classpath.

OpenAI is Spring AI’s default chat provider, and ChatClient auto-configuration requires exactly one ChatModel bean, so the two OpenAI endpoints are mutually exclusive rather than both configured. One property picks which one you get:

With responses, the auto-configuration creates a single OpenAiResponsesChatModel bean and no OpenAiChatModel bean. Connection settings stay where they are, under spring.ai.openai.

If you genuinely want both - say Chat Completions for cheap classification and Responses for an agent - leave the property at its default and declare the second model yourself:

Note that a second ChatModel bean makes ChatClient auto-configuration ambiguous, so mark one @Primary or build your ChatClient instances explicitly.

The spring.ai.openai.responses prefix configures the model.

Connection properties (api-key, base-url, timeout, max-retries, proxy, custom-headers, Microsoft Foundry and GitHub Models flags) are shared with the other OpenAI models under spring.ai.openai, and can be overridden per model under spring.ai.openai.responses.

All of these can also be set per request through OpenAiResponsesChatOptions:

Spring AI currently implements only the stateless mode of Responses API

Consequently store: false is sent on every request, and is not configurable. Two reasons, both correctness rather than preference:

Responses are therefore not retained by OpenAI on Spring AI’s behalf; your organization’s data-retention settings still apply to the request itself.

A reasoning model returns its chain of thought as an opaque encrypted blob, that you cannot read. To keep the model’s train of thought across a tool call or a follow-up turn, that exact blob has to be handed back on the next request. Dropping it produces no error - just worse answers, more tokens and repeated work.

A whole assistant turn is therefore not one message but a transcript of typed items - a reasoning item, then the function calls it produced, then a text message. That transcript is the assistant message’s ordered List<MessagePart>, one part per item, so the interleaving survives and the encrypted blob travels with the reasoning it belongs to:

On the next request each part is turned back into the item it came from, in part order. The item id, the item status and the assistant message phase ride along in the part’s attributes(), because an item cannot be rebuilt without them.

Two things are deliberately not replayed: citation annotations on a previous assistant turn, which stay readable on the generation metadata but are of no use to the model, and generated media, for which the API has no input item.

A reasoning part is replayed only when its payload came from this provider, which ReasoningPart.replayableTo("openai.responses") reports. The Responses API rejects reasoning without its own encrypted content, so a reasoning part produced by Anthropic or Bedrock, or one whose payload was lost on the way through, is skipped with a DEBUG log rather than sent and refused. The turn still goes through; the model simply reasons from scratch.

Application-side tools work exactly as they do with OpenAiChatModel, through ToolCallingAdvisor. The model runs no tool loop of its own.

Two behaviours are specific to this endpoint:

These run inside OpenAI’s request; there is nothing for your application to execute.

HostedTool.Raw is the escape hatch for tools OpenAI ships before Spring AI types them:

Citations from web and file search land under the annotations key on the generation metadata. Generated images arrive as Media on the assistant message, labelled with the output_format the item reports.

The MCP approval round-trip is not implemented, so HostedTool.Mcp rejects requireApproval = "always" at construction: an mcp_approval_request would end the turn without the tool running. Use never.

OpenAI never returns raw reasoning text - only summaries and the encrypted blob. Reasoning token counts are available through the native usage object, response.getMetadata().getUsage().getNativeUsage().

Spring AI always adds include: ["reasoning.encrypted_content"] to the request. This is one of only two framework-level defaults on this model, and it is there for correctness: without the blob coming back, replaying a reasoning turn is impossible rather than merely degraded. The other is the non-strict tool schema described above.

ChatClient.entity() works unchanged. Underneath, response_format becomes text.format.

Images (by URL or bytes) and PDFs are supported.

Audio input and output are not supported by this endpoint and are rejected with a clear message; use OpenAiChatModel for audio.

For the cases where you want the transcript rather than the flattened message, read the parts:

getReasoning(), getToolCalls(), getMedia() and getText() are views over the same list, so the familiar accessors keep working. There is no OpenAI-specific AssistantMessage subclass: the parts are provider-neutral, which is what lets replay keep working after streaming aggregation or a chat memory round-trip.

The assistant message carries no metadata. Everything a turn reports beyond its parts describes one response rather than the message, so it lives on the generation and response metadata; message metadata is persisted by some chat memory repositories and dropped by others, which makes it the wrong place for anything that matters. This differs from OpenAiChatModel, which publishes id, role, finishReason, refusal, annotations and reasoningContent on the message. The keys below keep those names where they apply, so swapping the bean only changes where you read them.

On the generation metadata, read with response.getResult().getMetadata():

reasoningContent is a flattened view, published under the key OpenAiChatModel and DeepSeek use. The authoritative form is the `ReasoningPart`s, which keep each reasoning item separate, in place among the tool calls it justified, and carry the encrypted content needed to replay it.

openai.responses.hosted_tool_calls summarizes activity inside a single request, so there is nothing to replay on the next turn; the authoritative copy of each item is the UnknownPart it was mapped to, which holds the item verbatim.

The annotations key matches OpenAiChatModel by name only. This model publishes List<Map<String, Object>>; OpenAiChatModel publishes the OpenAI SDK’s own annotation objects. Code that casts the entries needs adjusting when you swap one bean for the other.

On the response metadata, read with response.getMetadata():

Note that response.getMetadata() is rebuilt from a fixed field set during streaming aggregation, so the openai.responses.* keys are present on each streamed chunk but not on the aggregated response. getId(), getModel() and getUsage() survive aggregation.

Finish reasons: STOP, TOOL_CALLS, LENGTH (incomplete because of max_output_tokens) and CONTENT_FILTER. A failed response raises OpenAiResponsesException rather than returning an empty answer.