Alloy.Provider.OpenAI (alloy v0.13.0)

Copy Markdown View Source

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 use Alloy.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 - true or a config map to append a web_search tool
  • :x_search - true or a config map to append an x_search tool
  • :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

Configuration for the OpenAI provider. See the module doc for field semantics.

Types

config()

@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.