chore: import upstream snapshot with attribution

contributing/samples/workflows/state/README.md

@@ -0,0 +1,60 @@
+# ADK Workflow State Sample
+
+## Overview
+
+This sample demonstrates different ways to manage state in an **ADK Workflow**. State is a dictionary shared across all nodes in the workflow execution, useful for gathering information across multiple steps without passing everything directly from one node's output to another's input.
+
+In this sample, we show four techniques:
+
+1. Updating state via direct dictionary mutation: `ctx.state["key"] = "value"`
+1. Updating state by yielding an event: `yield Event(state={"key": "value"})`
+1. Reading state via direct dictionary access: `ctx.state["key"]`
+1. Reading state via automatic parameter injection: `def func(key: str): ...`
+
+## Sample Inputs
+
+- `Hello ADK!`
+
+- `Testing state management.`
+
+## Graph
+
+```mermaid
+graph TD
+    START --> process_initial_input
+    process_initial_input --> update_state_via_event
+    update_state_via_event --> read_state_via_ctx
+    read_state_via_ctx --> read_state_via_param
+```
+
+## How To
+
+1. **Update state via direct mutation:** Access the context and modify `ctx.state` directly.
+
+   ```python
+   def process_initial_input(ctx, node_input: str):
+       ctx.state["original_text"] = node_input
+   ```
+
+1. **Update state via Event:** Yield an `Event` object with a `state` delta dictionary.
+
+   ```python
+   def update_state_via_event(node_input: str):
+       yield Event(
+           state={"uppercased_text": node_input.upper()}
+       )
+   ```
+
+1. **Read state via context:** Retrieve values from `ctx.state`.
+
+   ```python
+   def read_state_via_ctx(ctx):
+       original = ctx.state["original_text"]
+   ```
+
+1. **Read state via parameter injection:** Declare a function parameter that matches the key in the workflow state, and ADK will automatically populate it.
+
+   ```python
+   def read_state_via_param(appended_text: str):
+       return f"Final Result: {appended_text}!"
+   ```

contributing/samples/workflows/state/agent.py

@@ -0,0 +1,57 @@
+# 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.
+
+
+from google.adk import Event
+from google.adk import Workflow
+
+
+def process_initial_input(ctx, node_input: str):
+  """Takes initial input and sets it in state via direct dict modification."""
+  ctx.state["original_text"] = node_input
+  return node_input
+
+
+def update_state_via_event(node_input: str):
+  """Returns an Event that implicitly updates the shared workflow state."""
+  yield Event(state={"uppercased_text": node_input.upper()})
+
+
+def read_state_via_ctx(ctx):
+  """Reads a state variable via direct dictionary access and appends to it."""
+  original = ctx.state["original_text"]
+  uppercased = ctx.state["uppercased_text"]
+
+  result = f"{uppercased} (Original was: {original})"
+  ctx.state["appended_text"] = result
+  return result
+
+
+def read_state_via_param(appended_text: str):
+  """Reads a state variable via automatic parameter injection."""
+  return f"Final Result: {appended_text}!"
+
+
+root_agent = Workflow(
+    name="state_sample",
+    edges=[
+        (
+            "START",
+            process_initial_input,
+            update_state_via_event,
+            read_state_via_ctx,
+            read_state_via_param,
+        ),
+    ],
+)

contributing/samples/workflows/state/tests/go.json

@@ -0,0 +1,91 @@
+{
+  "appName": "state",
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "go"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "actions": {
+        "stateDelta": {
+          "original_text": "go"
+        }
+      },
+      "author": "state_sample",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "outputFor": [
+          "state_sample@1/process_initial_input@1"
+        ],
+        "path": "state_sample@1/process_initial_input@1"
+      },
+      "output": "go"
+    },
+    {
+      "actions": {
+        "stateDelta": {
+          "uppercased_text": "GO"
+        }
+      },
+      "author": "state_sample",
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "state_sample@1/update_state_via_event@1"
+      }
+    },
+    {
+      "actions": {
+        "stateDelta": {
+          "appended_text": "GO (Original was: go)"
+        }
+      },
+      "author": "state_sample",
+      "id": "e-4",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "outputFor": [
+          "state_sample@1/read_state_via_ctx@1"
+        ],
+        "path": "state_sample@1/read_state_via_ctx@1"
+      },
+      "output": "GO (Original was: go)"
+    },
+    {
+      "author": "state_sample",
+      "id": "e-5",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "outputFor": [
+          "state_sample@1/read_state_via_param@1",
+          "state_sample@1"
+        ],
+        "path": "state_sample@1/read_state_via_param@1"
+      },
+      "output": "Final Result: GO (Original was: go)!"
+    }
+  ],
+  "id": "89d894be-5d57-4d5c-9a29-ccc15b3b5eb7",
+  "state": {
+    "__session_metadata__": {
+      "displayName": "go"
+    },
+    "appended_text": "GO (Original was: go)",
+    "original_text": "go",
+    "uppercased_text": "GO"
+  },
+  "userId": "user"
+}