This is an automated email from the ASF dual-hosted git repository. kaxil pushed a commit to branch commonai-durable-stable in repository https://gitbox.apache.org/repos/asf/airflow.git
commit 871b1879616fdb046d16f00b47bc6654572a0c35 Author: Kaxil Naik <[email protected]> AuthorDate: Wed Oct 14 09:23:58 2026 +0100 Graduate durable agent execution to stable in Common AI AirflowDurability (#74385) let a toolset declare whether its calls may be replayed, which was the reason durable=True stayed experimental in #74679. --- providers/common/ai/docs/durable_execution.rst | 5 ----- providers/common/ai/docs/stability.rst | 20 +++++++++++++++----- .../airflow/providers/common/ai/operators/agent.py | 2 +- 3 files changed, 16 insertions(+), 11 deletions(-) diff --git a/providers/common/ai/docs/durable_execution.rst b/providers/common/ai/docs/durable_execution.rst index 10555ab20e1..59d4aaa7408 100644 --- a/providers/common/ai/docs/durable_execution.rst +++ b/providers/common/ai/docs/durable_execution.rst @@ -20,11 +20,6 @@ Durable execution ================= -.. note:: - - Experimental: this can change or be removed in a minor release of this provider. - See :ref:`howto/stability`. - An agent task makes several model calls and tool calls. When it fails partway (a network error, a timeout, a provider outage), a plain Airflow retry runs every one of them again: the model calls are paid for twice and the tools' side effects happen diff --git a/providers/common/ai/docs/stability.rst b/providers/common/ai/docs/stability.rst index 79ec4e8fe50..f614bb8a278 100644 --- a/providers/common/ai/docs/stability.rst +++ b/providers/common/ai/docs/stability.rst @@ -50,12 +50,25 @@ Pydantic AI toolsets, but the Pydantic AI class they inherit from can change. always dumped to a dict. ``decision_policy`` is experimental; see below. * - ``@task.agent`` and :class:`~airflow.providers.common.ai.operators.agent.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. + returns its output under the same rules as ``@task.llm``. 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``. + * - ``durable=True`` on ``AgentOperator`` and ``@task.agent``, and + :class:`~airflow.providers.common.ai.durable.AirflowDurability` + (:doc:`durable_execution`) + - On a retry the agent runs from the start, and each model request and tool call an + earlier attempt recorded is replayed from the journal kept for the task instance, + without calling the model or running the tool again, as long as it matches the step + recorded at the same point; from the first step that differs, every step runs live. + The journal is kept in the task state store on Airflow 3.3 and later, and under + ``[common.ai] durable_cache_path`` before. With ``durable=True``, replayed steps + count nothing against ``usage_limits`` or in the ``usage`` XCom, the agent's + ``run_id`` stays the first attempt's, and the journal is deleted when the task + succeeds. In a plain ``@task``, ``AirflowDurability`` deletes a run's steps when + that run succeeds. * - ``@task.llm_branch`` and :class:`~airflow.providers.common.ai.operators.llm_branch.LLMBranchOperator` - The model picks among the task's direct downstream tasks, one by default or several @@ -179,9 +192,6 @@ Everything this provider ships that is not in the table above is experimental. (:doc:`operators/llm_batch`) - No package outside this provider implements the contract yet, so it has not been tested by a second implementation. - * - ``durable=True`` on ``AgentOperator`` (:doc:`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``; :doc:`tool_approval`) diff --git a/providers/common/ai/src/airflow/providers/common/ai/operators/agent.py b/providers/common/ai/src/airflow/providers/common/ai/operators/agent.py index 0da729eedcd..cb73736e0f7 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/operators/agent.py +++ b/providers/common/ai/src/airflow/providers/common/ai/operators/agent.py @@ -314,7 +314,7 @@ class AgentOperator(CancellableAgentRunMixin, BaseOperator, HITLReviewMixin, Usa :ref:`the cross-attempt usage budget <agent-usage-budget>` for how it is persisted, reset, and how ``durable`` replay and HITL regeneration interact with it. - :param durable: Experimental. When ``True``, attaches + :param durable: When ``True``, attaches :class:`~airflow.providers.common.ai.durable.AirflowDurability`, which records each step the agent completes -- model responses, tool calls from any toolset or capability, tool discovery, and other capabilities'
