chore: import upstream snapshot with attribution

contributing/samples/workflows/loop_self/README.md

@@ -0,0 +1,44 @@
+# ADK Workflow Loop Self Sample
+
+## Overview
+
+This sample demonstrates how a node can repeatedly loop back to itself based on a specific route condition in **ADK Workflows**.
+
+It takes a user-provided target number (between 0 and 10), and uses a `guess_number` function to randomly generate guesses. If the guess is incorrect, the function yields a specific route (`guessed_wrong`). The workflow is configured such that this route directs the execution right back to the `guess_number` node, creating a loop that continues until the correct number is guessed.
+
+In ADK Workflows, you can create self-referential loops or iterative processes by routing a node's output back to itself.
+
+## Sample Inputs
+
+- `5`
+
+- `0`
+
+- `10`
+
+## Graph
+
+```mermaid
+graph TD
+    START --> validate_input
+    validate_input --> guess_number
+    guess_number -->|guessed_wrong| guess_number
+    guess_number -->|correct| END[Loop ends]
+```
+
+## How To
+
+1. From within your node (agent or function), yield a specific `Event` with a route name when you determine the node needs to be executed again:
+
+   ```python
+   def guess_number(target_number: int):
+     # ...
+     if guess != target_number:
+       yield Event(route='guessed_wrong')
+   ```
+
+1. In the `Workflow` edges definition, create a conditional edge where the source and target are the same node, using a routing map dict:
+
+   ```python
+   (guess_number, {'guessed_wrong': guess_number})
+   ```

contributing/samples/workflows/loop_self/agent.py

@@ -0,0 +1,45 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import random
+
+from google.adk import Event
+from google.adk import Workflow
+
+
+def validate_input(node_input: str):
+  parsed_number = int(node_input)
+  if parsed_number > 10 or parsed_number < 0:
+    yield Event(message='Please provide a number between 0 and 10.')
+    raise ValueError('Invalid input.')
+  else:
+    yield Event(state={'target_number': parsed_number})
+
+
+def guess_number(target_number: int):
+  guess = random.randint(0, 10)
+  yield Event(message=f'Guessing {guess}...')
+  if guess == target_number:
+    yield Event(message='Correct!')
+  else:
+    yield Event(route='guessed_wrong')
+
+
+root_agent = Workflow(
+    name='root_agent',
+    edges=[
+        ('START', validate_input, guess_number),
+        (guess_number, {'guessed_wrong': guess_number}),
+    ],
+)

contributing/samples/workflows/loop_self/tests/3.json

@@ -0,0 +1,191 @@
+{
+  "appName": "loop_self",
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "3"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "actions": {
+        "stateDelta": {
+          "target_number": 3
+        }
+      },
+      "author": "root_agent",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "root_agent@1/validate_input@1"
+      }
+    },
+    {
+      "author": "root_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "Guessing 10..."
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "root_agent@1/guess_number@1"
+      }
+    },
+    {
+      "actions": {
+        "route": "guessed_wrong"
+      },
+      "author": "root_agent",
+      "id": "e-4",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "root_agent@1/guess_number@1"
+      }
+    },
+    {
+      "author": "root_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "Guessing 1..."
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-5",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "root_agent@1/guess_number@2"
+      }
+    },
+    {
+      "actions": {
+        "route": "guessed_wrong"
+      },
+      "author": "root_agent",
+      "id": "e-6",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "root_agent@1/guess_number@2"
+      }
+    },
+    {
+      "author": "root_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "Guessing 0..."
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-7",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "root_agent@1/guess_number@3"
+      }
+    },
+    {
+      "actions": {
+        "route": "guessed_wrong"
+      },
+      "author": "root_agent",
+      "id": "e-8",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "root_agent@1/guess_number@3"
+      }
+    },
+    {
+      "author": "root_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "Guessing 4..."
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-9",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "root_agent@1/guess_number@4"
+      }
+    },
+    {
+      "actions": {
+        "route": "guessed_wrong"
+      },
+      "author": "root_agent",
+      "id": "e-10",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "root_agent@1/guess_number@4"
+      }
+    },
+    {
+      "author": "root_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "Guessing 3..."
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-11",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "root_agent@1/guess_number@5"
+      }
+    },
+    {
+      "author": "root_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "Correct!"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-12",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "root_agent@1/guess_number@5"
+      }
+    }
+  ],
+  "id": "1f627a81-1341-43b7-b971-c8809ff8f6d1",
+  "mocks": {
+    "random.randint": [
+      10,
+      1,
+      0,
+      4,
+      3
+    ]
+  },
+  "state": {
+    "__session_metadata__": {
+      "displayName": "3"
+    },
+    "target_number": 3
+  },
+  "userId": "user"
+}