openai.ResponsesClient

The OpenAI Responses API client (POST {base_url}/responses).

Reference version

Signature

class openai.ResponsesClient

The OpenAI Responses API client (POST {base_url}/responses).

Options come in three groups:

credentials/endpoint — api_key/base_url (or the *_env names read at request time);
first-class typed request parameters — temperature, top_p, max_output_tokens, reasoning_effort, reasoning_summary, verbosity, parallel_tool_calls, store. Each one is lowered into the typed request class only when it is non-null;
passthrough — request_body (deep-merged over the serialized typed request as the LAST step, null deletes a key), headers and query_params.

By default the output schema rides in the prompt text and the answer is parsed with SAP. structured_output sends OpenAI Structured Outputs instead (text.format), and reads the answer strictly.

Deliberately not provided: the engine's finish_reason_allow_list and finish_reason_deny_list. There is no config surface for them here and none is planned — the typed ai.content.StopReason plus the runner's Refused / MaxTokens enforcement covers what the lists were used for, and a caller who wants a stricter policy writes it over the returned turn (or wraps the client) rather than configuring a string list of provider finish reasons.

Source:<builtin>/openai/responses.bamlbytes 1353–8940

Fields

model

string

api_key

ai.Credential | null

base_url

ai.Credential | null

timeout

baml.time.Duration | ai.LlmTimeoutOptions | null

temperature

float | null

top_p

float | null

max_output_tokens

int | null

reasoning_effort

string | null

reasoning_summary

string | null

verbosity

string | null

parallel_tool_calls

bool | null

store

bool

request_body

baml.json.json | null

Deep-merged over the serialized typed request as the last step before the body is stringified. A null value DELETES that key, so {"store": null} drops the store: false this client sends.

headers

map<string, string> | null

Extra request headers, applied (lowercased) before authorization.

query_params

map<string, string> | null

Extra URL query parameters, percent-encoded onto the endpoint.

capture_wire

bool

structured_output

bool

Hold the model to the output type with OpenAI Structured Outputs: the request carries a strict JSON Schema of the type as text.format, and the answer is read strictly as JSON rather than parsed leniently.

The model sees that schema, with every @description and /// on the type's classes, fields and enum variants, so the prompt need not include ${ctx.output_format()}. A prompt that keeps it sends the schema twice, which is harmless but costs tokens.

An output type strict mode cannot describe (a map, media, a type with no JSON form) is rejected before the request is sent, and so is a call that streams: streaming does not support it yet.

Static methods

function

new

(

model: string = …,

api_key: ai.Credential | null = …,

base_url: ai.Credential | null = …,

timeout: baml.time.Duration | ai.LlmTimeoutOptions | null = …,

temperature: float | null = …,

top_p: float | null = …,

max_output_tokens: int | null = …,

reasoning_effort: string | null = …,

reasoning_summary: string | null = …,

verbosity: string | null = …,

parallel_tool_calls: bool | null = …,

store: bool = …,

request_body: baml.json.json | null = …,

headers: map<string, string> | null = …,

query_params: map<string, string> | null = …,

capture_wire: bool = …,

structured_output: bool = …

) -> openai.ResponsesClient throws never

Creates a client. Construction reads no environment variable, so declaring one is always safe; credentials and endpoints resolve when a request is built.

Parameters

structured_output: send OpenAI Structured Outputs and read the answer strictly (see the field of the same name). The model sees the output type's schema, documentation included, so a prompt need not include ${ctx.output_format()}.

Instance methods

function

resolved_api_key

(

self

) -> string throws baml.errors.Io | baml.errors.ParseError | ai.errors.InvalidRequest

The request-time credential: an explicit value (a literal, or the value of the variable an env.NAME ref points at), else the provider's canonical one. Nothing here runs before the request.

A missing key is a CATCHABLE configuration error, not a panic: baml.env.get_or_panic unwinds past the catch_all + ai.errors.normalize wrapper below, so an unset variable would take the process down instead of surfacing as an ai.errors.Failure.

function

resolved_base_url

(self) -> string | null throws baml.errors.Io | baml.errors.ParseError

The request-time base URL, or null for the provider default.

Implementations

ai.Client for openai.ResponsesClient

Instance methods

function

default_cache_args

(self) -> baml.json.json throws never

What a ${cache()} sends as prompt_cache_breakpoint on the part before it: {"mode": "explicit"}. Null for GPT-5.5 and earlier, which reject the field; a ${cache()} sends nothing there.

function

invoke

(

self,

input: ai.ModelTurnInput

) -> ai.ModelTurn throws reflect.errors.CompilationError | baml.errors.Timeout | baml.errors.UnknownError | ai.errors.Failure

function

provider

(self) -> string throws never

function

render

(

self,

input: ai.ModelTurnInput

) -> baml.http.Request throws reflect.errors.CompilationError | baml.errors.Timeout | baml.errors.UnknownError | ai.errors.Failure

function

requested_model

(self) -> string throws never

Source:<builtin>/openai/responses.bamlbytes 7659–8648

ai.stream.StreamingClient for openai.ResponsesClient

Instance methods

function

invoke_stream

(

self,

input: ai.ModelTurnInput

) -> ai.stream.TurnStream throws reflect.errors.CompilationError | baml.errors.Timeout | baml.errors.UnknownError | ai.errors.Failure

Source:<builtin>/openai/responses.bamlbytes 8654–8938