This is an automated email from the ASF dual-hosted git repository.
Lee-W pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 9ecc914fbd0 Document the Responses API options OpenAIResponseOperator
can pass through (#72049)
9ecc914fbd0 is described below
commit 9ecc914fbd00d72617e0b8d107f04d6563d7bbda
Author: Wei Lee <[email protected]>
AuthorDate: Tue Sep 15 17:24:57 2026 +0800
Document the Responses API options OpenAIResponseOperator can pass through
(#72049)
---
providers/openai/docs/operators/openai.rst | 64 ++++++++++++++++++++++
.../airflow/providers/openai/operators/openai.py | 5 ++
2 files changed, 69 insertions(+)
diff --git a/providers/openai/docs/operators/openai.rst
b/providers/openai/docs/operators/openai.rst
index bfb2fd8dee9..b6bd4ab5b3f 100644
--- a/providers/openai/docs/operators/openai.rst
+++ b/providers/openai/docs/operators/openai.rst
@@ -58,6 +58,70 @@ specify the OpenAI connection to use, and
``response_kwargs`` to pass through op
:start-after: [START howto_operator_openai_response]
:end-before: [END howto_operator_openai_response]
+Passing Responses API options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+See the `Responses API reference
+<https://platform.openai.com/docs/api-reference/responses/create>`__ for the
authoritative list
+of parameters. ``response_kwargs`` passes straight through to the underlying
``create_response``
+call, so most keyword arguments the Responses API accepts can be set there,
with the exceptions
+noted below. What actually works also depends on the ``openai`` package
version installed in the
+environment, not the reference page above: ``Responses.create`` accepts no
arbitrary keyword
+arguments, so passing one the installed package doesn't recognize raises
``TypeError`` before any
+request is sent. Use ``extra_body`` as a fallback to pass a parameter the
installed package doesn't
+know about yet. Options worth knowing about:
+
+- ``background``: run the response asynchronously on OpenAI's side. See the
note on ``background``
+ below before using this with ``OpenAIResponseOperator``.
+- ``stream``: return a stream of response events instead of a single completed
response. Do not set
+ this on ``OpenAIResponseOperator``: ``execute`` reads ``response.status`` and
+ ``response.output_text``, neither of which exists on the streamed response
object, so the task
+ raises ``AttributeError``. Stream responses from a ``@task`` using
+ :class:`~airflow.providers.openai.hooks.openai.OpenAIHook` instead.
+- ``store``: whether the response is retained on OpenAI's side, for example so
it can later be used
+ as a ``previous_response_id``. Through ``OpenAIResponseOperator``,
``execute`` only passes
+ ``response.id`` to the task log and returns ``response.output_text``, so
nothing downstream of
+ this operator's task can retrieve a stored response's id — this only matters
when the response
+ is created via ``OpenAIHook`` directly.
+- ``previous_response_id``: the id of a prior response to continue a
multi-turn conversation from.
+ Cannot be used together with ``conversation`` — pass one or the other, not
both.
+- ``reasoning``: configuration for reasoning models, for example ``{"effort":
...}``. The example
+ Dag above (and the operator's own default) uses ``gpt-4o-mini``, which is
not a reasoning model,
+ so this option only takes effect if ``model`` is also set to a reasoning
model.
+- ``service_tier``: the processing tier the request is served from.
+- ``prompt_cache_key``: an identifier used to route requests to the same
prompt cache. How long a
+ cache entry is retained is a separate option whose name depends on the
installed package:
+ ``prompt_cache_retention`` at the 2.37.0 floor, deprecated in later releases
in favor of
+ ``prompt_cache_options.ttl``.
+- ``safety_identifier``: a stable identifier for the end user, used for safety
and abuse detection.
+- ``truncation``: one of ``'auto'`` or ``'disabled'`` (the default). Under
``'disabled'``, a
+ request whose input exceeds the model's context window fails with a 400
error; ``'auto'``
+ shortens the input to fit instead.
+- ``include``: additional output fields to include in the response, such as
encrypted reasoning
+ content. These fields land on ``response.output``, but
``response.output_text`` only aggregates
+ ``message``/``output_text`` content, so anything ``include`` adds is fetched
and then discarded
+ by ``execute``. Use ``OpenAIHook`` directly to access it.
+- ``metadata``: a mapping of key-value pairs attached to the response for your
own bookkeeping.
+- ``max_output_tokens``: an upper bound on the number of tokens the model can
generate, including
+ reasoning tokens as well as visible output tokens.
+- ``max_tool_calls``: an upper bound on the number of built-in tool calls the
model can make.
+
+.. note::
+
+ OpenAI does not expose a spend or cost ceiling parameter on the Responses
API.
+ ``max_output_tokens`` and ``max_tool_calls`` are token and call-count
limits, not a way to cap
+ the dollar cost of a run; controlling spend means bounding those counts
yourself.
+
+.. note::
+
+ ``background=True`` starts the response running asynchronously on OpenAI's
side and returns
+ before the response finishes. ``OpenAIResponseOperator`` is synchronous:
it makes one
+ ``create_response`` call and returns ``response.output_text`` immediately,
so a response
+ started with ``background=True`` comes back incomplete, and the operator
logs its own warning
+ because ``response.status`` is not yet ``"completed"``. Do not set
``background=True`` on
+ ``OpenAIResponseOperator``. If you need a background response, create it
from a ``@task``
+ using :class:`~airflow.providers.openai.hooks.openai.OpenAIHook`'s
``create_response`` directly.
+
Using the OpenAIHook for Responses and Conversations
=====================================================
diff --git a/providers/openai/src/airflow/providers/openai/operators/openai.py
b/providers/openai/src/airflow/providers/openai/operators/openai.py
index dfed6e48d51..1f12593e23b 100644
--- a/providers/openai/src/airflow/providers/openai/operators/openai.py
+++ b/providers/openai/src/airflow/providers/openai/operators/openai.py
@@ -93,6 +93,11 @@ class OpenAIResponseOperator(BaseOperator):
:param model: The OpenAI model to use.
:param response_kwargs: Additional keyword arguments to pass to the OpenAI
``create_response``
method (for example ``instructions``, ``tools``, ``conversation`` or
``previous_response_id``).
+ Do not set ``background`` or ``stream`` here: ``background=True``
returns before the response
+ completes, so this operator logs a warning and the returned output
text may be empty, while
+ ``stream=True`` returns an object without ``status`` or
``output_text``, so the task raises
+ ``AttributeError``. See :ref:`howto/operator:OpenAIResponseOperator`
for these and other
+ options this operator can pass through, such as ``truncation`` and
``max_output_tokens``.
.. seealso::
For more information on how to use this operator, take a look at the
guide:
