Stable and experimental features¶

A stable feature keeps its behaviour across minor releases of this provider, from version 1.0.0 on. An experimental feature is documented and maintained, but can change or be removed in a minor release, as Airflow’s experimental feature policy allows. A breaking change to an experimental feature is announced in the changelog.

Stable features¶

A stable feature keeps its public parameters, their defaults and the behaviour described below until the next major release. A minor release can add an optional parameter. Changing a default, renaming a parameter or narrowing what a feature does needs a major release.

Stability covers behaviour, not wording. Log lines, error messages, tool descriptions and the prompt text this provider sends to a model can change in any release. The toolsets stay Pydantic AI toolsets, but the Pydantic AI class they inherit from can change.

Feature	What stays the same
`@task.llm` and `LLMOperator`	Sends the prompt to the model from `llm_conn_id` and returns the output as the task’s return value: a string by default, or an instance of `output_type`, dumped to a dict when `serialize_output=True`. Before Airflow 3.3 an instance is always dumped to a dict. `decision_policy` is experimental; see below.
`@task.agent` and `AgentOperator`	Runs an agent with the model from `llm_conn_id` and the given toolsets, and returns its output under the same rules as `@task.llm`. `durable`, code mode and per-tool approval are experimental; see below.
`message_history` on `AgentOperator`	Seeds the run with the given conversation, as a list of messages or its JSON form, and publishes the finished conversation under the `message_history` XCom key so a later run can continue it. Cannot be combined with `enable_hitl_review`.
`@task.llm_branch` and `LLMBranchOperator`	The model picks among the task’s direct downstream tasks, one by default or several with `allow_multiple_branches=True`, and only the picked tasks run. The descriptions in `branches`, as strings or as `BranchOption(description=...)`, are sent to the model with the options. `decision_policy` and `BranchOption.min_confidence` are experimental; see below.
`PydanticAIHook` and its connection types	The connection fields documented for each type in Pydantic AI connection, Pydantic AI (AWS Bedrock) connection, Pydantic AI (Google Vertex AI) connection and Pydantic AI (Azure OpenAI) connection keep their meaning, so an existing connection keeps producing the same model.
`SQLToolset`	Exposes `list_tables`, `get_schema`, `query` and `check_query`. Read-only unless `allow_writes=True`. When `allowed_tables` is set, other tables are refused. `query` returns at most `max_rows` rows, and keeps the rows and column names within `max_result_bytes` bytes. When `query` fails or refuses a statement, the model gets the error and can correct it, up to the tool’s retry limit, after which the task fails.
`HookToolset`	Exposes exactly the hook methods in `allowed_methods`, each named after its method with `tool_name_prefix` in front, and raises an error when the toolset is created if a listed method does not exist on the hook. `pinned_arguments` is experimental; see below.
`MCPToolset` and `MCPHook`	Exposes the tools of the MCP server configured by `mcp_conn_id`, each named `<tool_prefix>_<name>` when `tool_prefix` is set. The connection fields for each transport keep their meaning.
`LLMRetryPolicy`	Returns a retry decision from a model’s reading of the exception. Values registered as secrets are masked in the exception text before it reaches the model, unless `redact_exception=False` or a custom `redactor` replaces the masking. If the model call fails, it falls back to `fallback_rules` and then to the task’s own retry settings; it never fails the task itself.
Output review: `require_approval`, `enable_hitl_review` and the review plugin	With `require_approval=True`, the task defers after generating output and returns it only once a person approves it on the Required Actions page. A rejection, or a timeout under the default `on_approval_timeout="fail"`, fails the task, except on `@task.llm_branch`, where it skips the downstream tasks unless `fail_on_reject=True`.

Experimental features¶

Everything this provider ships that is not in the table above is experimental.

Feature	Why it is experimental
`ClassifierRetryPolicy` (Decision models)	The confidence threshold, the fallback order and the behaviour when the classifier is unavailable are still settling.
`DecisionPolicy`, and `min_confidence` on `BranchOption` (Approval gates for LLM operators)	New. The threshold semantics and the recorded decision may change as they are used.
`@task.llm_batch` and batch adapters (Batch processing: LLMBatchOperator)	Submission, re-attachment on retry, cancellation and handling of partial results are still settling, and `BatchAdapter` has no implementation outside this provider yet.
`durable=True` on `AgentOperator` (Durable execution)	Which tool results are replayed on retry will change, so that a tool can declare whether its result may be reused.
Per-tool approval on `AgentOperator` (`tool_approval_timeout`, `on_tool_approval_timeout` and `tool_approval_assigned_users`; Approve an agent’s tool calls)	New, and needs Airflow 3.3. How a paused run resumes may change.
Code mode (Code mode), the Agent Skills toolset (Agent Skills: AgentSkillsToolset) and the `shields` extra (used in Capabilities and guardrails)	Thin integrations of packages outside this provider whose APIs are still changing: `pydantic-ai-harness`, `pydantic-ai-skills` and `pydantic-ai-shields`.
`SandboxToolset` and its backends (Sandboxed execution for agents)	The sandbox runtime belongs to the backend; ownership and cleanup across worker failures are still being designed.
LangChain and LlamaIndex hooks and the LangChain tool bridge (LangChain models: LangChainHook, LangChain tools in both directions, Using LlamaIndex directly: LlamaIndexHook)	Each follows the API of a framework that changes often.
The retrieval operators: `DocumentLoaderOperator`, `LlamaIndexEmbeddingOperator` and `LlamaIndexRetrievalOperator` (Document and RAG pipelines)	New. The shape of the pipeline, from loading documents through embedding to retrieval, has not settled.
`DataFusionToolset` (Files with DataFusion: DataFusionToolset)	Runs on the DataFusion engine of `common.sql`, which pins `datafusion` below 52 and follows its API.
Managed agent toolsets (Vendor-managed agents: ManagedAgentToolset)	A contract for vendor providers that no vendor implements yet.
OpenTelemetry spans (`[common.ai] otel_export_enabled` and `capture_content`; Observability (OpenTelemetry tracing))	Span names and attributes come from Pydantic AI’s instrumentation and the OpenTelemetry GenAI conventions, which are still in development.
`LoggingToolset` used directly (Tool call logging: LoggingToolset)	The wrapper `AgentOperator` applies for `enable_tool_logging`; its constructor may change.
`@task.llm_schema_compare`, `@task.llm_file_analysis` and `@task.llm_sql` (Detect schema drift: LLMSchemaCompareOperator and @task.llm_schema_compare, Analyze files and images: LLMFileAnalysisOperator and @task.llm_file_analysis, Natural language to SQL: LLMSQLQueryOperator and @task.llm_sql)	Each adds its own input handling to `@task.llm`: schema introspection, file sampling, or SQL validation. Their options are still settling.
The framework-neutral tools (`airflow.providers.common.ai.tools`), including the `airflow_tools()` method of the toolsets, the Strands plugin and the ADK toolset (Agent frameworks)	Written against Strands 1.56 and ADK 2.9.1. CI does not run the tests of the two adapters, because both frameworks exclude dependency versions that Airflow’s development environment uses.
`ObjectStorageToolset` (Files on object storage: ObjectStorageToolset)	New; its tools and read limits may change after first use.
`pinned_arguments` on `HookToolset` (Airflow hooks as tools: HookToolset)	New; how a pinned argument is matched to each method’s parameters may change after first use.
The `common_ai.tool_calls` metric and `agent_framework_tracing()` (Observability (OpenTelemetry tracing))	The tracing helper follows the agent frameworks’ own telemetry, which is still changing; the metric’s tags may change as more frameworks get adapters.