Alloy.Provider.OpenAI (alloy v0.12.4)

Provider for OpenAI's Responses API.

Normalizes OpenAI's response output items (assistant messages + function calls) to Alloy's content-block format.

Config

Required:

:api_key - OpenAI API key
:model - Model name (e.g., "gpt-5.4", "gpt-5.1", "o3-pro")

Optional:

:max_tokens - Max output tokens (default: 4096)
:system_prompt - System prompt string
:api_url - Base URL (default: "https://api.openai.com"). Can point to compatible Responses APIs such as xAI's "https://api.x.ai"
:provider_state - opaque provider-owned state carried across turns. For Responses APIs Alloy uses %{response_id: "..."}
: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 - Explicit Responses continuation ID. Overrides provider_state.response_id when both are present
: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

In stateless mode (store not true with no previous response ID), Alloy automatically requests encrypted reasoning content and round-trips opaque reasoning output items between tool calls.

Example

Alloy.run("Summarize this code.",
  provider: {Alloy.Provider.OpenAI,
    api_key: System.get_env("OPENAI_API_KEY"),
    model: "gpt-5.4"
  }
)

Alloy.run("Review this repo",
  provider: {Alloy.Provider.OpenAI,
    api_key: System.get_env("XAI_API_KEY"),
    api_url: "https://api.x.ai",
    model: "grok-4"
  }
)

Summary

Types

config()

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.