Add a note and an example clarifying the usage of DAG-level params (#…

…40541)

(cherry picked from commit 8bdd0e7)

docs/apache-airflow/core-concepts/params.rst

@@ -36,9 +36,10 @@ To add Params to a :class:`~airflow.models.dag.DAG`, initialize it with the ``pa
 Use a dictionary that maps Param names to either a :class:`~airflow.models.param.Param` or an object indicating the parameter's default value.
 
 .. code-block::
-   :emphasize-lines: 6-9
+   :emphasize-lines: 7-10
 
     from airflow import DAG
+    from airflow.decorators import task
     from airflow.models.param import Param
 
     with DAG(
@@ -47,7 +48,34 @@ Use a dictionary that maps Param names to either a :class:`~airflow.models.param
             "x": Param(5, type="integer", minimum=3),
             "my_int_param": 6
         },
-    ):
+    ) as dag:
+
+        @task.python
+        def example_task(params: dict):
+            # This will print the default value, 6:
+            dag.log.info(dag.params['my_int_param'])
+
+            # This will print the manually-provided value, 42:
+            dag.log.info(params['my_int_param'])
+
+            # This will print the default value, 5, since it wasn't provided manually:
+            dag.log.info(params['x'])
+
+        example_task()
+
+    if __name__ == "__main__":
+        dag.test(
+            run_conf={"my_int_param": 42}
+        )
+
+.. note::
+
+   DAG-level parameters are the default values passed on to tasks. These should not be confused with values manually
+   provided through the UI form or CLI, which exist solely within the context of a :class:`~airflow.models.dagrun.DagRun`
+   and a :class:`~airflow.models.taskinstance.TaskInstance`. This distinction is crucial for TaskFlow DAGs, which may
+   include logic within the ``with DAG(...) as dag:`` block. In such cases, users might try to access the manually-provided
+   parameter values using the ``dag`` object, but this will only ever contain the default values. To ensure that the
+   manually-provided values are accessed, use a template variable such as ``params`` or ``ti`` within your task.
 
 Task-level Params
 -----------------