You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by "Lee-W (via GitHub)" <gi...@apache.org> on 2026/07/07 14:45:12 UTC

[PR] Document when to use common.ai vs vendor-specific AI providers [airflow]

Lee-W opened a new pull request, #69551:
URL: https://github.com/apache/airflow/pull/69551

   The common.ai, openai, and anthropic docs landing pages now explain how to choose between the vendor-neutral operators and the native API wrappers — including where the agent loop runs (Airflow worker vs vendor-managed service).
   
    <!-- SPDX-License-Identifier: Apache-2.0
         https://www.apache.org/licenses/LICENSE-2.0 -->
   
   <!--
   Thank you for contributing!
   
   Please provide above a brief description of the changes made in this pull request.
   Write a good git commit message following this guide: http://chris.beams.io/posts/git-commit/
   
   Please make sure that your code changes are covered with tests.
   And in case of new features or big changes remember to adjust the documentation.
   
   For user-facing UI changes, please attach before/after screenshots (or a short
   screen recording) so reviewers can assess the visual impact.
   
   Feel free to ping (in general) for the review if you do not see reaction for a few days
   (72 Hours is the minimum reaction time you can expect from volunteers) - we sometimes miss notifications.
   
   In case of an existing issue, reference it using one of the following:
   
   * closes: #ISSUE
   * related: #ISSUE
   -->
   
   ---
   
   ##### Was generative AI tooling used to co-author this PR?
   
   <!--
   If generative AI tooling has been used in the process of authoring this PR, please
   change below checkbox to `[X]` followed by the name of the tool, uncomment the "Generated-by".
   -->
   
   - [ ] Yes (please specify the tool below)
   
   <!--
   Generated-by: [Tool Name] following [the guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions)
   -->
   
   ---
   
   * Read the **[Pull Request Guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#pull-request-guidelines)** for more information. Note: commit author/co-author name and email in commits become permanently public when merged.
   * For fundamental code changes, an Airflow Improvement Proposal ([AIP](https://cwiki.apache.org/confluence/display/AIRFLOW/Airflow+Improvement+Proposals)) is needed.
   * When adding dependency, check compliance with the [ASF 3rd Party License Policy](https://www.apache.org/legal/resolved.html#category-x).
   * For significant user-facing changes create newsfragment: `{pr_number}.significant.rst`, in [airflow-core/newsfragments](https://github.com/apache/airflow/tree/main/airflow-core/newsfragments). You can add this file in a follow-up commit after the PR is created so you know the PR number.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Document when to use common.ai vs vendor-specific AI providers [airflow]

Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W merged PR #69551:
URL: https://github.com/apache/airflow/pull/69551


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Document when to use common.ai vs vendor-specific AI providers [airflow]

Posted by "kaxil (via GitHub)" <gi...@apache.org>.
kaxil commented on code in PR #69551:
URL: https://github.com/apache/airflow/pull/69551#discussion_r3543165679


##########
providers/common/ai/docs/index.rst:
##########
@@ -19,6 +19,46 @@
 ``apache-airflow-providers-common-ai``
 ##################################################
 
+When to use this provider

Review Comment:
   A reader landing here to answer "which package do I install?" tends to scan before reading. Today that answer is split across prose on three pages, so they have to open all three and derive the rule themselves. A short feature-to-package table on this page (embeddings / batch / responses -> the vendor package; portable generation and worker-run agents with toolsets -> common.ai; managed server-side agents -> the vendor package) would let them decide at a glance, with the prose below as the "why". The prose is good, it just isn't scannable yet.



##########
providers/common/ai/docs/index.rst:
##########
@@ -19,6 +19,46 @@
 ``apache-airflow-providers-common-ai``
 ##################################################
 
+When to use this provider
+--------------------------
+
+``common.ai`` is the vendor-neutral way to put LLM and agent steps in a Dag. It is built on

Review Comment:
   A reader who already has LangChain or LlamaIndex code may read "built on pydantic-ai" as "not for me" and move on. Since the provider ships a LangChain toolset (the `langchain` extra), one sentence noting that existing LangChain tools can be called from a common.ai agent would keep that reader engaged, without overstating support.



##########
providers/anthropic/docs/index.rst:
##########
@@ -19,6 +19,41 @@
 ``apache-airflow-providers-anthropic``
 ======================================
 
+When to use this provider

Review Comment:
   Placement: on this page the section renders above the one-line description of what the provider actually is (that line sits lower, in the generated block). So a first-time visitor meets a comparison before a definition. A short lead-in sentence naming what the provider is, or placing this section just under the provider tagline, would orient them first.



##########
providers/openai/docs/index.rst:
##########
@@ -19,6 +19,41 @@
 ``apache-airflow-providers-openai``
 ======================================
 
+When to use this provider
+--------------------------
+
+Use ``openai`` when a Dag needs OpenAI's native API surface — thin wrappers over
+OpenAI-specific endpoints and options:
+
+* ``OpenAIEmbeddingOperator`` — call the Embeddings API directly, e.g. to feed a vector
+  store.
+* ``OpenAIResponseOperator`` — call the
+  `Responses API <https://platform.openai.com/docs/api-reference/responses>`__ with
+  OpenAI-specific parameters.
+* ``OpenAITriggerBatchOperator`` and ``OpenAIHook`` — submit a

Review Comment:
   Two small things on this bullet:
   
   1. `OpenAIHook` is the general client, not batch-specific, so listing it under "submit a Batch API job ... and wait for it to complete" reads as if the hook is a batch tool. Consider dropping it here, or mentioning it separately as the low-level access path.
   2. This says what the batch operator does (async bulk) but not why a reader would reach for it over running the step in the worker. The Batch API runs at roughly half the per-token cost on a ~24h turnaround, and that cost-vs-latency tradeoff is the decision the reader is making on this page. One clause about it turns "what it is" into "when to pick it".



##########
providers/openai/docs/index.rst:
##########
@@ -19,6 +19,41 @@
 ``apache-airflow-providers-openai``
 ======================================
 
+When to use this provider

Review Comment:
   Placement: on this page the section renders above the one-line description of what the provider actually is (that line sits lower, in the generated block). So a first-time visitor meets a comparison before a definition. A short lead-in sentence naming what the provider is, or placing this section just under the provider tagline, would orient them first.



##########
providers/common/ai/docs/index.rst:
##########
@@ -19,6 +19,46 @@
 ``apache-airflow-providers-common-ai``
 ##################################################
 
+When to use this provider
+--------------------------
+
+``common.ai`` is the vendor-neutral way to put LLM and agent steps in a Dag. It is built on
+`pydantic-ai <https://ai.pydantic.dev/>`__, so the model vendor (OpenAI, Anthropic, Google,
+Bedrock, …) is picked by the connection ``llm_conn_id`` points at — switching providers later
+is a connection change, not a Dag rewrite. The AI step is orchestrated by Airflow: the model
+calls, the agent loop, and any tools all run in the Airflow worker, where they get retries,
+logging, and observability like any other task.
+
+Use it when a Dag needs:
+
+* **Generation, classification, summarization, or structured extraction** —
+  :doc:`LLMOperator and @task.llm <operators/llm>`, with Pydantic-typed output pushed to XCom.
+* **Branching on a model's decision** — :doc:`LLMBranchOperator <operators/llm_branch>`.
+* **Agents with tools** — :doc:`AgentOperator <operators/agent>` runs a multi-turn agent loop

Review Comment:
   Toolsets are the clearest thing separating a worker-run agent from a plain LLM call, but they appear here only as a parenthetical. A reader comparing this against a managed-agent service is exactly who needs that capability made visible, so it is worth linking to the Toolsets page (``:doc:`toolsets` ``) rather than leaving it inline.
   
   Minor: "durable step replay" isn't glossed here. The AgentOperator link does explain it further down, so this is optional, but a few words of context would help a reader who doesn't click through.



##########
providers/anthropic/docs/index.rst:
##########
@@ -19,6 +19,41 @@
 ``apache-airflow-providers-anthropic``
 ======================================
 
+When to use this provider
+--------------------------
+
+Use ``anthropic`` when a Dag needs Anthropic's native API surface — services Anthropic runs
+for you, which no vendor-neutral operator wraps:
+
+* ``AnthropicBatchOperator`` and ``AnthropicBatchSensor`` — submit a Claude

Review Comment:
   This describes what the batch operator does (async bulk) but not why a reader would reach for it over running the step in the worker. The Message Batches API runs at roughly half the per-token cost on a ~24h turnaround, and that cost-vs-latency tradeoff is the actual decision on this page. Adding that clause turns "what it is" into "when to pick it".



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Document when to use common.ai vs vendor-specific AI providers [airflow]

Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #69551:
URL: https://github.com/apache/airflow/pull/69551#discussion_r3550622994


##########
providers/openai/docs/index.rst:
##########
@@ -19,6 +19,41 @@
 ``apache-airflow-providers-openai``
 ======================================
 
+When to use this provider
+--------------------------
+
+Use ``openai`` when a Dag needs OpenAI's native API surface — thin wrappers over
+OpenAI-specific endpoints and options:
+
+* ``OpenAIEmbeddingOperator`` — call the Embeddings API directly, e.g. to feed a vector
+  store.
+* ``OpenAIResponseOperator`` — call the
+  `Responses API <https://platform.openai.com/docs/api-reference/responses>`__ with
+  OpenAI-specific parameters.
+* ``OpenAITriggerBatchOperator`` and ``OpenAIHook`` — submit a

Review Comment:
   1. dropped it
   2. Added a short description https://github.com/apache/airflow/pull/69649
   
   <img width="1944" height="210" alt="image" src="https://github.com/user-attachments/assets/1a6347a2-58f4-4e79-a272-16cea926d203" />
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Document when to use common.ai vs vendor-specific AI providers [airflow]

Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #69551:
URL: https://github.com/apache/airflow/pull/69551#discussion_r3550629794


##########
providers/anthropic/docs/index.rst:
##########
@@ -19,6 +19,41 @@
 ``apache-airflow-providers-anthropic``
 ======================================
 
+When to use this provider
+--------------------------
+
+Use ``anthropic`` when a Dag needs Anthropic's native API surface — services Anthropic runs
+for you, which no vendor-neutral operator wraps:
+
+* ``AnthropicBatchOperator`` and ``AnthropicBatchSensor`` — submit a Claude

Review Comment:
   Added a clause on the tradeoff for `AnthropicBatchOperator`/`AnthropicBatchSensor` (from the figures are already documented on the operators page)
   
   <img width="1944" height="260" alt="image" src="https://github.com/user-attachments/assets/5219553e-a097-457c-8a2c-d126827f3d25" />
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Document when to use common.ai vs vendor-specific AI providers [airflow]

Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #69551:
URL: https://github.com/apache/airflow/pull/69551#discussion_r3550598459


##########
providers/common/ai/docs/index.rst:
##########
@@ -19,6 +19,46 @@
 ``apache-airflow-providers-common-ai``
 ##################################################
 
+When to use this provider
+--------------------------
+
+``common.ai`` is the vendor-neutral way to put LLM and agent steps in a Dag. It is built on
+`pydantic-ai <https://ai.pydantic.dev/>`__, so the model vendor (OpenAI, Anthropic, Google,
+Bedrock, …) is picked by the connection ``llm_conn_id`` points at — switching providers later
+is a connection change, not a Dag rewrite. The AI step is orchestrated by Airflow: the model
+calls, the agent loop, and any tools all run in the Airflow worker, where they get retries,
+logging, and observability like any other task.
+
+Use it when a Dag needs:
+
+* **Generation, classification, summarization, or structured extraction** —
+  :doc:`LLMOperator and @task.llm <operators/llm>`, with Pydantic-typed output pushed to XCom.
+* **Branching on a model's decision** — :doc:`LLMBranchOperator <operators/llm_branch>`.
+* **Agents with tools** — :doc:`AgentOperator <operators/agent>` runs a multi-turn agent loop

Review Comment:
   <img width="1944" height="366" alt="image" src="https://github.com/user-attachments/assets/0987ccd2-b5db-49c4-9c2b-6f8111d45ad1" />
   
   added both in https://github.com/apache/airflow/pull/69649/changes



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Document when to use common.ai vs vendor-specific AI providers [airflow]

Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #69551:
URL: https://github.com/apache/airflow/pull/69551#discussion_r3550608176


##########
providers/openai/docs/index.rst:
##########
@@ -19,6 +19,41 @@
 ``apache-airflow-providers-openai``
 ======================================
 
+When to use this provider

Review Comment:
   
   <img width="1960" height="856" alt="image" src="https://github.com/user-attachments/assets/4143cfaf-a33f-404b-a0d0-9dbede28edaf" />
   
   
   we now have a short description before the comparison in https://github.com/apache/airflow/pull/69649



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Document when to use common.ai vs vendor-specific AI providers [airflow]

Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #69551:
URL: https://github.com/apache/airflow/pull/69551#discussion_r3550596832


##########
providers/common/ai/docs/index.rst:
##########
@@ -19,6 +19,46 @@
 ``apache-airflow-providers-common-ai``
 ##################################################
 
+When to use this provider
+--------------------------
+
+``common.ai`` is the vendor-neutral way to put LLM and agent steps in a Dag. It is built on

Review Comment:
   <img width="1944" height="314" alt="image" src="https://github.com/user-attachments/assets/557fafae-03f4-4c27-aa8e-4a62ac2bbc33" />
   
   I added it to the middle of this paragraph in https://github.com/apache/airflow/pull/69649/changes. let me know if it's better to move it or extend it



##########
providers/common/ai/docs/index.rst:
##########
@@ -19,6 +19,46 @@
 ``apache-airflow-providers-common-ai``
 ##################################################
 
+When to use this provider

Review Comment:
   <img width="1970" height="1248" alt="image" src="https://github.com/user-attachments/assets/ec2e9c8f-e140-4448-9b1f-9554514d8fb0" />
   
   added a table in https://github.com/apache/airflow/pull/69649/changes



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Document when to use common.ai vs vendor-specific AI providers [airflow]

Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #69551:
URL: https://github.com/apache/airflow/pull/69551#discussion_r3550605368


##########
providers/anthropic/docs/index.rst:
##########
@@ -19,6 +19,41 @@
 ``apache-airflow-providers-anthropic``
 ======================================
 
+When to use this provider

Review Comment:
   <img width="1958" height="1010" alt="image" src="https://github.com/user-attachments/assets/1f89289c-17ae-4670-9f02-699362f7067c" />
   
   we now have a short description before the comparison in https://github.com/apache/airflow/pull/69649



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org