This is an automated email from the ASF dual-hosted git repository.
kaxil pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 173871e84ee Document what the LLM can and cannot do in retry policies
(#72947)
173871e84ee is described below
commit 173871e84ee6c70fa567a5f01005716ac6305839
Author: Amogh Desai <[email protected]>
AuthorDate: Fri Sep 11 20:37:21 2026 +0530
Document what the LLM can and cannot do in retry policies (#72947)
---
providers/common/ai/docs/retry_policies.rst | 20 ++++++++++++++++++++
1 file changed, 20 insertions(+)
diff --git a/providers/common/ai/docs/retry_policies.rst
b/providers/common/ai/docs/retry_policies.rst
index e059f899a50..30ced02ebff 100644
--- a/providers/common/ai/docs/retry_policies.rst
+++ b/providers/common/ai/docs/retry_policies.rst
@@ -83,6 +83,26 @@ If the LLM call fails (provider down, timeout, bad
credentials), the policy
falls back to ``fallback_rules`` if configured, or to the task's standard
retry behaviour.
+What the model can and cannot do
+--------------------------------
+
+The model answers two questions: retry or not, and how long to wait. It is
+given no tools and there is no way to attach any, so it cannot run code, call
an
+API, read a connection, or reach your data. It sees only the exception's class
+name, the exception message (after redaction and truncation), and the attempt
+count. It returns four fields: ``category``, ``should_retry``,
``suggested_delay_seconds``,
+and ``reasoning``. Of the four fields it returns, only ``should_retry`` and
+``suggested_delay_seconds`` affect the run. ``category`` and ``reasoning`` are
+recorded but nothing branches on them.
+
+Two limits are worth knowing about:
+
+* RETRY cannot give a task more attempts than ``retries`` allows. FAIL,
though, ends the task
+ straight away even when attempts were left, so a wrong classification costs
+ the task the retries it would otherwise have had.
+* ``suggested_delay_seconds`` is used as returned, with no upper limit. If
particular delays
+ matter to you, state them in ``instructions`` as the examples below do.
+
Custom instructions
-------------------
