Repository navigation
Mark experimental common.ai features ahead of 1.0 - #73896
Merged
Merged
Conversation
Add a stability page listing what stays the same for each stable feature and why the rest is experimental, and note the experimental status on each experimental feature's page and in its class docstring.
kaxil
added this pull request to stack #73905
September 29, 2026 12:49
kaxil
marked this pull request as ready for review
September 29, 2026 13:17
vatsrahul1001
approved these changes
Sep 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Before common.ai reaches 1.0, someone building a production Dag needs to know which features keep their behaviour across minor releases. This adds a Stable and experimental features page. It lists each stable feature with what stays the same about it, and names every experimental feature with the reason it is experimental. The guarantees start at 1.0.0. Experimental features follow Airflow's experimental feature policy: they can change or be removed in a minor release, and the changelog says so.
The pages of experimental features, and their main classes and functions, carry a note that links to the page. Parameters of stable operators that take an experimental value are marked one by one:
durable,code_modeand the per-tool approval parameters onAgentOperator, anddecision_policyonLLMOperatorandLLMBranchOperator.Stability covers behaviour, not wording. Log lines, error messages, tool descriptions and the prompt text sent to a model can change in any release, and so can the Pydantic AI class the toolsets inherit from. Freezing those would block routine fixes without protecting anyone's Dag.
The line is drawn at the parameter where a stable operator takes an experimental type.
LLMBranchOperatorturns every plain-string branch description into aBranchOption, so the descriptions stay stable whileBranchOption.min_confidenceanddecision_policyare experimental.This is the bottom of a stack for the native agent framework work. Each PR above it adds its own row to this page.
The stability page as rendered:
{pr_number}.significant.rst, in airflow-core/newsfragments. You can add this file in a follow-up commit after the PR is created so you know the PR number.