# `ReqLLM.OpenAI.Responses`
[🔗](https://github.com/agentjido/req_llm/blob/main/lib/req_llm/openai/responses.ex#L1)

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.

# `close`

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

Closes the session.

# `connect`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

Queues user input for an active GPT-6 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`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*