Provider for OpenAI's Responses API.
Normalizes OpenAI's response output items (assistant messages + function
calls) to Alloy's content-block format. Use this provider, not
Alloy.Provider.OpenAICompat, for OpenAI models: starting with GPT-5.4,
Chat Completions does not support tool calling with reasoning enabled.
Config
Required:
:api_key- OpenAI API key:model- Model name (e.g., "gpt-6-astra", "gpt-6.1-sol", "gpt-5.4")
Optional:
:max_tokens- Max output tokens, reasoning tokens included. Omitted unless set, so the model's own limit applies: a small cap can leave a reasoning model with no tokens for its answer:system_prompt- System prompt string:api_url- Base URL (default: "https://api.openai.com"). Can point to compatible Responses APIs; for xAI useAlloy.Provider.XAI:provider_state- opaque provider-owned state carried across turns. Each response's ID is recorded as%{response_id: "..."}; it is informational and never sent back automatically:store- Persist the response server-side when supported:include- Additional response fields to include:tool_choice- Provider-native tool selection mode:parallel_tool_calls- Whether the provider may issue tool calls in parallel:previous_response_id- Continue a stored response (see "Chaining responses" below):built_in_tools- provider-native tool definitions to append to custom function tools:web_search-trueor a config map to append aweb_searchtool:x_search-trueor a config map to append anx_searchtool:req_options- Additional options passed to Req
Conversation state
By default every request carries the full conversation, like every other
Alloy provider. In this stateless mode (store not true and no
:previous_response_id), Alloy requests encrypted reasoning content and
replays every output item: reasoning items are kept as
%{type: "reasoning", raw: item} blocks and other non-message items
(built-in tool calls, compaction items) as %{type: "output_item", raw: item} blocks. An assistant message's phase is kept on its text blocks
and always sent back.
Chaining responses
To continue a response stored server-side instead, pass its ID as
:previous_response_id together with only the messages added since that
response. The server prepends the stored conversation, so sending the full
history as well would duplicate it (and bill it twice). The ID of the
latest response is in result.metadata.provider_state.response_id. A
chained response must have been created with store enabled (the API's
default). Tool-loop turns within one run keep the same
:previous_response_id, so they still send only the run's new messages.
Example
Alloy.run("Summarize this code.",
provider: {Alloy.Provider.OpenAI,
api_key: System.get_env("OPENAI_API_KEY"),
model: "gpt-5.4"
}
)
Summary
Types
@type config() :: %{ :api_key => String.t(), :model => String.t(), optional(:max_tokens) => pos_integer(), optional(:system_prompt) => String.t(), optional(:api_url) => String.t(), optional(:provider_state) => map(), optional(:store) => boolean(), optional(:include) => [String.t()], optional(:tool_choice) => String.t() | map(), optional(:parallel_tool_calls) => boolean(), optional(:previous_response_id) => String.t(), optional(:built_in_tools) => [map()], optional(:web_search) => boolean() | map(), optional(:x_search) => boolean() | map(), optional(:req_options) => keyword() }
Configuration for the OpenAI provider. See the module doc for field semantics.