ReqLLM.OpenAI.Responses (ReqLLM v1.22.0)

Experimental OpenAI Responses helpers and persistent WebSocket sessions.

Use with_reasoning_effort/2 with a user message to change Astra reasoning effort within a conversation. The Responses encoder places the update just before that message. Keep the request-level :reasoning_effort unchanged.

A session exposes raw provider events across response boundaries. The caller tracks response IDs, accepted steer IDs, and pending tool calls. An accepted steer is queued; it does not confirm that the steer was applied. Continue to read events after response.completed or response.incomplete to receive the automatic successor response.

If steering requires tool results, send a new response_create/2 with those results and the pending event's response ID on the same session. Include the instructions and tools again. Do not repeat the steer input. The client does not execute tools, reconnect, or retry events after a connection failure.

Summary

Functions

close(session)

Closes the session.

connect(model_spec, opts \\ [])

Connects to the Responses WebSocket endpoint and waits for the connection.

next_event(session, timeout \\ 30000)

Receives one raw event. Response completion does not close the session.

response_create(session, payload)

Starts or continues a response using a native Responses request map.

steer(session, previous_response_id, input)

Queues user input for an active Astra response.

with_reasoning_effort(message, effort)

Adds a reasoning update to an Astra user message.

Functions

close(session)

@spec close(ReqLLM.OpenAI.Responses.Session.t()) :: :ok

Closes the session.

connect(model_spec, opts \\ [])

@spec connect(
  ReqLLM.model_input(),
  keyword()
) :: {:ok, ReqLLM.OpenAI.Responses.Session.t()} | {:error, term()}

Connects to the Responses WebSocket endpoint and waits for the connection.

next_event(session, timeout \\ 30000)

@spec next_event(ReqLLM.OpenAI.Responses.Session.t(), timeout()) ::
  {:ok, map()} | :halt | {:error, term()}

Receives one raw event. Response completion does not close the session.

response_create(session, payload)

@spec response_create(ReqLLM.OpenAI.Responses.Session.t(), map()) ::
  :ok | {:error, term()}

Starts or continues a response using a native Responses request map.

Map keys must be strings. The session supplies model and type. stream and background are not valid WebSocket request fields. This low-level API accepts provider options, not ReqLLM generation options.

steer(session, previous_response_id, input)

@spec steer(ReqLLM.OpenAI.Responses.Session.t(), String.t(), String.t() | [map()]) ::
  :ok | {:error, term()}

Queues user input for an active Astra response.

Wait for response.created before sending its ID. Input can be a nonempty string or a list of native user messages. Read all response.steer.* events with next_event/2; a successful send alone does not mean acceptance.

with_reasoning_effort(message, effort)

@spec with_reasoning_effort(ReqLLM.Message.t(), atom() | String.t()) ::
  ReqLLM.Message.t()

Adds a reasoning update to an Astra user message.

Accepts low, medium, high, xhigh, or max as an atom or string. Raises ReqLLM.Error.Invalid.Parameter for other values or message roles. The message metadata retains the update's position when the context grows. This feature requires standard single-agent mode without automatic context compaction or truncation. After explicit compaction, add a fresh update.