Skip to content

Correct what clearing a durable agent task replays in common.ai docs - #76860

Merged
kaxil merged 2 commits into
mainfrom
durable-clear-docs
Nov 11, 2026
Merged

kaxil merged 2 commits into
mainfrom
durable-clear-docs

Conversation

@kaxil

@kaxil kaxil commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

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}/clearTaskInstances deletes the task's state store entries unless keep_task_state is 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.rst that 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 (or keep_task_state is 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_store docstring calls out.

The usage_limits docs in AgentOperator's docstring and operators/agent.rst drop 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 when max_tries changes, and clearing a running task instance doesn't bump it, as operators/agent.rst already 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:

How it was cleared Rerun's durable summary line
Task instance, "Keep task state and resume" ticked replayed 2 steps (1 model, 1 tool, 0 other), recorded 2 new steps
Task instance, box not ticked replayed 0 steps (0 model, 0 tool, 0 other), recorded 4 new steps
Whole Dag run (REST) replayed 2 steps (1 model, 1 tool, 0 other)

Docs only; no behaviour change.

Rerun after a task-instance clear with Keep task state ticked: replayed 2 steps

Rerun after a task-instance clear without it: replayed 0 steps, recorded 4 new

Rerun after a Dag-run clear: replayed 2 steps

Clear dialog with Keep task state and resume ticked

Clear dialog with the box unticked

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 jedcunningham left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One more copy of the old claim is outside the diff: durable/replay_usage.py:98 still says a clear "keeps the durable journal".

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.
@kaxil

kaxil commented Nov 11, 2026

Copy link
Copy Markdown
Member Author

Fixed the replay_usage.py docstring in the same commit. #76863 had the same claim in a line it adds ("When the task succeeds, its journal is deleted"), so that one now says the agent run instead.

@kaxil
kaxil merged commit 5081d28 into main Nov 11, 2026
120 checks passed
@kaxil
kaxil deleted the durable-clear-docs branch November 11, 2026 14:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants