kaxil · Sep 29, 2026 · Sep 24, 2026
@@ -85,6 +85,11 @@ list does not take effect.
 Reviewing uncertain output
 --------------------------
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 A classifier model such as TypeSafe's reports a confidence for every field
 of a structured output, in ``provider_details`` on the model response. It is a
 summary of how concentrated the model's probability distribution was, not the

@@ -18,6 +18,11 @@
 Classifier models
 =================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 Every other model in this provider writes text. A classifier model does not: you give it
 some text and a typed question, and it answers with a value from a set you named in
 advance, plus a confidence. Ask it for a string and the request is refused before it

@@ -20,6 +20,11 @@
 Code mode
 =========
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 Set ``code_mode=True`` to collapse the agent's tools into a single ``run_code``
 tool powered by the `Monty <https://github.com/pydantic/monty>`__ sandbox (via
 pydantic-ai-harness). Instead of one model round-trip per tool call, the model

@@ -20,6 +20,11 @@
 LangChain connection
 ====================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 The ``langchain`` connection type configures access to LLM providers via
 `LangChain <https://python.langchain.com/>`__'s universal
 ``init_chat_model`` / ``init_embeddings`` entry points. It backs

@@ -20,6 +20,11 @@
 LlamaIndex connection
 =====================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 The ``llamaindex`` connection type configures access to LLM and embedding
 providers for `LlamaIndex <https://docs.llamaindex.ai/>`__. It backs
 :class:`~airflow.providers.common.ai.hooks.llamaindex.LlamaIndexHook` (see

@@ -20,6 +20,11 @@
 Durable execution
 =================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 Agent tasks can involve multiple LLM calls and tool invocations. If a task
 fails mid-run (network error, timeout, transient API failure), a plain retry
 re-executes every LLM call and tool call from scratch -- repeating work that

@@ -48,6 +48,12 @@ Guardrail capabilities use the same passthrough pattern. This example uses
 ``InputGuard`` from ``pydantic-ai-shields`` to reject a prompt before the agent
 run starts.
 
+.. note::
+
+    Experimental: the ``shields`` extra can change or be removed in a minor release of this
+    provider.
+    See :ref:`howto/stability`.
+
 .. exampleinclude:: /../../ai/src/airflow/providers/common/ai/example_dags/example_agent_capabilities.py
     :language: python
     :start-after: [START howto_operator_agent_capabilities_input_guard]

@@ -20,6 +20,11 @@
 LangChain models: ``LangChainHook``
 ===================================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 .. toctree::
     :titlesonly:
     :hidden:

@@ -20,6 +20,11 @@
 Using LlamaIndex directly: ``LlamaIndexHook``
 =============================================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 Use :class:`~airflow.providers.common.ai.hooks.llamaindex.LlamaIndexHook` to
 bridge an Airflow connection to `LlamaIndex <https://docs.llamaindex.ai/>`__
 chat and embedding models. The hook reads credentials (API key, optional

@@ -119,6 +119,7 @@ waits for the result, use that vendor's provider.
 
     Example Dags <examples>
     Configuration <configurations-ref>
+    Stable and experimental features <stability>
     Python API <_api/airflow/providers/common/ai/index>
 
 .. toctree::

@@ -18,6 +18,12 @@
 Observability (OpenTelemetry tracing)
 =====================================
 
+.. note::
+
+    Experimental: the spans and their attributes can change in a minor release of this
+    provider.
+    See :ref:`howto/stability`.
+
 pydantic-ai ships native OpenTelemetry instrumentation that emits GenAI spans
 for each agent run, model call, and tool call, following the
 `OpenTelemetry GenAI semantic conventions <https://opentelemetry.io/docs/specs/semconv/gen-ai/>`__.

@@ -20,6 +20,11 @@
 Load documents: ``DocumentLoaderOperator``
 ==========================================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 Use :class:`~airflow.providers.common.ai.operators.document_loader.DocumentLoaderOperator`
 to parse files into ``list[dict(text, metadata)]`` for downstream embedding
 pipelines. The operator bridges Airflow's connectivity layer (hooks that

@@ -20,6 +20,11 @@
 Embed documents: ``LlamaIndexEmbeddingOperator``
 ================================================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 Chunk a ``list[dict]`` of documents and produce embedding vectors using
 LlamaIndex. Designed to feed the output of
 :class:`~airflow.providers.common.ai.operators.document_loader.DocumentLoaderOperator`

@@ -20,6 +20,11 @@
 Retrieve context: ``LlamaIndexRetrievalOperator``
 =================================================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 Load a persisted LlamaIndex index and run similarity search. Designed to
 sit between
 :class:`~airflow.providers.common.ai.operators.llamaindex_embedding.LlamaIndexEmbeddingOperator`

@@ -212,6 +212,11 @@ reviewer. The full guide, including timeouts, notifiers and assigned reviewers,
 Reviewing uncertain output
 --------------------------
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 A ``decision_policy`` with a confidence bar sends output the model is unsure about to the
 same review flow. See :doc:`../approval_gates`.
 

@@ -20,6 +20,11 @@
 Batch processing: ``LLMBatchOperator``
 ======================================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 Use :class:`~airflow.providers.common.ai.operators.llm_batch.LLMBatchOperator` to run many
 prompts through a provider's **batch API** instead of one synchronous call per prompt:
 roughly half the per-token cost of :class:`~airflow.providers.common.ai.operators.llm.LLMOperator`,

@@ -171,6 +171,11 @@ behaviour are inherited from :ref:`LLMOperator <howto/operator:llm>`.
 Reviewing Uncertain Picks
 -------------------------
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 A classifier model such as TypeSafe's returns a confidence with every pick,
 a number from 0 to 1 that summarizes how concentrated its probability
 distribution was: near 1 when one branch stood out, low when two or more

@@ -20,6 +20,11 @@
 Analyze files and images: ``LLMFileAnalysisOperator``
 =====================================================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 Use :class:`~airflow.providers.common.ai.operators.llm_file_analysis.LLMFileAnalysisOperator`
 or the ``@task.llm_file_analysis`` decorator to analyze files from object storage
 or local storage with a single prompt.

@@ -20,6 +20,11 @@
 Detect schema drift: ``LLMSchemaCompareOperator``
 =================================================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 Use :class:`~airflow.providers.common.ai.operators.llm_schema_compare.LLMSchemaCompareOperator`
 to compare schemas across different database systems and detect drift using LLM reasoning.
 

@@ -20,6 +20,11 @@
 Natural language to SQL: ``LLMSQLQueryOperator``
 ================================================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 Use :class:`~airflow.providers.common.ai.operators.llm_sql.LLMSQLQueryOperator` to generate
 SQL queries from natural language using an LLM.
 

@@ -20,6 +20,11 @@
 Document and RAG pipelines
 ==========================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 A retrieval pipeline in this provider is three ordinary tasks. :doc:`operators/document_loader`
 parses files (text, CSV, JSON, PDF, DOCX) into a list of ``{"text", "metadata"}`` dicts with
 no AI framework involved. :doc:`operators/llamaindex_embedding` chunks those documents and

@@ -159,6 +159,11 @@ an attempt is a separate mechanism on the connection; see
 ClassifierRetryPolicy
 ---------------------
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 ``ClassifierRetryPolicy`` takes the retry decision away from the model. Its
 ``categories`` maps a category name to an
 :class:`~airflow.providers.common.ai.policies.retry.ErrorCategory`: what

@@ -18,6 +18,11 @@
 Sandbox backends
 ================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 .. _sandbox-backend-modal:
 
 Modal (hosted)

@@ -18,6 +18,11 @@
 Sandbox configuration and lifecycle
 ===================================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 .. _sandbox-configuring:
 
 Configuring a sandbox

@@ -20,6 +20,11 @@
 Sandboxed execution for agents
 ==============================
 
+.. note::
+
+    Experimental: this can change or be removed in a minor release of this provider.
+    See :ref:`howto/stability`.
+
 An agent that is asked to do open-ended work writes code, and then something has
 to run that code. By default that something is the Airflow worker: a skill
 script, a hand-written tool that shells out, or generated glue in