Repository navigation
Correct what clearing a durable agent task replays in common.ai docs - #76860
Merged
Merged
Conversation
The durable execution docs said a clear keeps the agent's journal, so a cleared task replays what its failed attempts recorded. Since Airflow 3.4, clearing a task instance deletes its task state, the journal included, unless keep_task_state is set. Add a "Clearing a task" section that says when a cleared task replays, and point the usage_limits docs at it.
jedcunningham
left a comment
Member
There was a problem hiding this comment.
One more copy of the old claim is outside the diff: durable/replay_usage.py:98 still says a clear "keeps the durable journal".
jedcunningham
approved these changes
Nov 10, 2026
Only an agent run that reached success deletes its journal; marking a failed task success does not, so a later clear that keeps task state still replays it. The replay-usage ledger docstring now says a journal entry from before a clear comes from a clear that kept task state, since from Airflow 3.4 any other task-instance clear deletes it.
Member
Author
|
Fixed the |
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.
The durable execution docs said a clear keeps the agent's journal, so a cleared task replays what its failed attempts recorded. That stopped being true for the common case before the page was written: since #72100, clearing a task instance from the UI or
POST /dags/{dag_id}/clearTaskInstancesdeletes the task's state store entries unlesskeep_task_stateis set, and on Airflow 3.3+ the journal lives in that store. The claim came in with #74385, two weeks after #72100 merged.This adds a "Clearing a task" section to
durable_execution.rstthat says when a cleared task replays. On Airflow 3.4+ a task-instance clear starts the agent over unless "Keep task state and resume" is ticked (orkeep_task_stateis set). A Dag-run clear keeps the journal. Before 3.4 no clear removes it. The section links the core "Retries resume, clearing starts over" section for the full list of clear paths instead of copying it. It also says the 3.4 discard only reaches the default state store backend, which the core_discard_task_state_storedocstring calls out.The
usage_limitsdocs inAgentOperator's docstring andoperators/agent.rstdrop the same claim and point to the new section. They now say that clearing a finished task instance starts a fresh budget: the budget resets whenmax_trieschanges, and clearing a running task instance doesn't bump it, asoperators/agent.rstalready said a few lines up.Checked on a local Airflow (main) with a durable agent whose second tool fails on the first attempt, then cleared three ways. Task log of the rerun:
replayed 2 steps (1 model, 1 tool, 0 other), recorded 2 new stepsreplayed 0 steps (0 model, 0 tool, 0 other), recorded 4 new stepsreplayed 2 steps (1 model, 1 tool, 0 other)Docs only; no behaviour change.