chore: import upstream snapshot with attribution

contributing/samples/workflows/request_input/README.md

@@ -0,0 +1,66 @@
+# ADK Workflow Request Input Sample
+
+## Overview
+
+This sample demonstrates how to create a **Human-in-the-Loop** workflow in **ADK Workflows** using the `RequestInput` event.
+
+It shows a customer support scenario where an LLM agent (`draft_email`) drafts a response to a customer complaint. The workflow then halts execution and prompts a human user for review (`request_human_review`). Depending on the human's input (`approve`, `reject`, or custom feedback), the workflow either completes, aborts, or loops back to the AI for revisions.
+
+This pattern is crucial for tasks where AI actions require human verification before proceeding.
+
+## Sample Inputs
+
+- `My phone battery drains too fast`
+
+- `I never received my order`
+
+- `The software crashes when I open the settings`
+
+## Graph
+
+```mermaid
+graph TD
+    START --> draft_email
+    draft_email --> request_human_review
+    request_human_review --> handle_human_review
+    handle_human_review -->|revise| draft_email
+    handle_human_review -->|approved| send_email
+    handle_human_review -->|rejected| END_rejected[END rejected]
+```
+
+## How To
+
+1. Yield a `RequestInput` event from a node to halt the workflow and prompt the user for input.
+
+   ```python
+   from google.adk.events import RequestInput
+
+   def request_human_review(draft: str):
+       yield RequestInput(
+           message="Please review the draft...",
+       )
+   ```
+
+1. The subsequent node will receive the user's input as its argument (`node_input`). You can use this input to determine the next routing step.
+
+   ```python
+   def handle_human_review(node_input: str):
+       if node_input == "approve":
+           yield Event(route="approved")
+       elif node_input == "reject":
+           yield Event(route="rejected")
+       else:
+           yield Event(state={"feedback": node_input}, route="revise")
+   ```
+
+1. Define the edges in your workflow to handle the different routes, including looping back for revisions.
+
+   ```python
+   Workflow(
+       name="request_input",
+       edges=[
+           ("START", ..., draft_email, request_human_review, handle_human_review),
+           (handle_human_review, {"revise": draft_email, "approved": send_email}),
+       ],
+   )
+   ```

contributing/samples/workflows/request_input/agent.py

@@ -0,0 +1,82 @@
+# 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 Agent
+from google.adk import Event
+from google.adk import Workflow
+from google.adk.events import RequestInput
+
+
+def process_input(node_input: str):
+  """Takes the initial customer complaint as input and sets it in the state."""
+  yield Event(state={"complaint": node_input, "feedback": ""})
+
+
+draft_email = Agent(
+    name="draft_email",
+    instruction="""
+    Please write a polite, helpful response email to the following customer complaint: "{complaint}"
+
+    If there is any feedback from the manager to revise the draft, please incorporate it: "{feedback?}"
+    """,
+    output_key="draft",
+)
+
+
+def request_human_review(draft: str):
+  yield RequestInput(
+      message=(
+          "Please review the following draft email and provide 'approve',"
+          f" 'reject', or feedback to revise.\n\n---\n{draft}\n---"
+      ),
+  )
+
+
+def handle_human_review(node_input: str):
+  if node_input == "reject":
+    yield Event(route="rejected")
+  elif node_input == "approve":
+    yield Event(route="approved")
+  else:
+    yield Event(state={"feedback": node_input}, route="revise")
+
+
+def reject_email():
+  yield Event(message="Draft rejected.")
+
+
+def send_email(draft: str):
+  yield Event(message="Draft approved and sent successfully.")
+
+
+root_agent = Workflow(
+    name="request_input",
+    edges=[
+        (
+            "START",
+            process_input,
+            draft_email,
+            request_human_review,
+            handle_human_review,
+        ),
+        (
+            handle_human_review,
+            {
+                "revise": draft_email,
+                "approved": send_email,
+                "rejected": reject_email,
+            },
+        ),
+    ],
+)

contributing/samples/workflows/request_input/tests/phone_broke.json

@@ -0,0 +1,238 @@
+{
+  "appName": "request_input",
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "phone broke"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "actions": {
+        "stateDelta": {
+          "complaint": "phone broke",
+          "feedback": ""
+        }
+      },
+      "author": "request_input",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "request_input@1/process_input@1"
+      }
+    },
+    {
+      "actions": {
+        "stateDelta": {
+          "draft": "Subject: Regarding Your Phone Issue - How We Can Help\n\nDear Customer,\n\nWe're very sorry to hear that your phone has broken. We understand how frustrating and disruptive this can be.\n\nTo help us understand what happened and assist you as quickly and efficiently as possible, could you please provide a few more details?\n\nPlease tell us:\n*   **What is the make and model of your phone?** (e.g., iPhone 13, Samsung Galaxy S22)\n*   **When did the phone break, and what happened?** (e.g., dropped it, it got wet, stopped turning on suddenly, screen went blank, etc.)\n*   **When and where was the phone purchased?** (This helps us determine warranty status.)\n*   **Have you already tried any troubleshooting steps?** (e.g., restarting, charging, etc.)\n\nOnce we have this information, we can guide you through the appropriate next steps, which may include troubleshooting, repair options, or warranty claims.\n\nPlease reply to this email with the requested details, or if you prefer to speak with someone directly, you can call our support team at [Your Company Phone Number] during our business hours [Business Hours, e.g., Monday-Friday, 9 AM - 5 PM EST].\n\nWe're here to help get your phone back up and running as quickly as possible.\n\nThank you for your patience.\n\nSincerely,\n\nThe [Your Company Name] Support Team"
+        }
+      },
+      "author": "draft_email",
+      "content": {
+        "parts": [
+          {
+            "text": "Subject: Regarding Your Phone Issue - How We Can Help\n\nDear Customer,\n\nWe're very sorry to hear that your phone has broken. We understand how frustrating and disruptive this can be.\n\nTo help us understand what happened and assist you as quickly and efficiently as possible, could you please provide a few more details?\n\nPlease tell us:\n*   **What is the make and model of your phone?** (e.g., iPhone 13, Samsung Galaxy S22)\n*   **When did the phone break, and what happened?** (e.g., dropped it, it got wet, stopped turning on suddenly, screen went blank, etc.)\n*   **When and where was the phone purchased?** (This helps us determine warranty status.)\n*   **Have you already tried any troubleshooting steps?** (e.g., restarting, charging, etc.)\n\nOnce we have this information, we can guide you through the appropriate next steps, which may include troubleshooting, repair options, or warranty claims.\n\nPlease reply to this email with the requested details, or if you prefer to speak with someone directly, you can call our support team at [Your Company Phone Number] during our business hours [Business Hours, e.g., Monday-Friday, 9 AM - 5 PM EST].\n\nWe're here to help get your phone back up and running as quickly as possible.\n\nThank you for your patience.\n\nSincerely,\n\nThe [Your Company Name] Support Team"
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "messageAsOutput": true,
+        "outputFor": [
+          "request_input@1/draft_email@1"
+        ],
+        "path": "request_input@1/draft_email@1"
+      }
+    },
+    {
+      "author": "request_input",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "interruptId": "fc-1",
+                "message": "Please review the following draft email and provide 'approve', 'reject', or feedback to revise.\n\n---\nSubject: Regarding Your Phone Issue - How We Can Help\n\nDear Customer,\n\nWe're very sorry to hear that your phone has broken. We understand how frustrating and disruptive this can be.\n\nTo help us understand what happened and assist you as quickly and efficiently as possible, could you please provide a few more details?\n\nPlease tell us:\n*   **What is the make and model of your phone?** (e.g., iPhone 13, Samsung Galaxy S22)\n*   **When did the phone break, and what happened?** (e.g., dropped it, it got wet, stopped turning on suddenly, screen went blank, etc.)\n*   **When and where was the phone purchased?** (This helps us determine warranty status.)\n*   **Have you already tried any troubleshooting steps?** (e.g., restarting, charging, etc.)\n\nOnce we have this information, we can guide you through the appropriate next steps, which may include troubleshooting, repair options, or warranty claims.\n\nPlease reply to this email with the requested details, or if you prefer to speak with someone directly, you can call our support team at [Your Company Phone Number] during our business hours [Business Hours, e.g., Monday-Friday, 9 AM - 5 PM EST].\n\nWe're here to help get your phone back up and running as quickly as possible.\n\nThank you for your patience.\n\nSincerely,\n\nThe [Your Company Name] Support Team\n---",
+                "payload": null,
+                "response_schema": null
+              },
+              "id": "fc-1",
+              "name": "adk_request_input"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "id": "e-4",
+      "invocationId": "i-1",
+      "longRunningToolIds": [
+        "fc-1"
+      ],
+      "nodeInfo": {
+        "path": "request_input@1/request_human_review@1"
+      }
+    },
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-1",
+              "name": "adk_request_input",
+              "response": {
+                "result": "shorter"
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-5",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "actions": {
+        "route": "revise",
+        "stateDelta": {
+          "feedback": "shorter"
+        }
+      },
+      "author": "request_input",
+      "id": "e-6",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "request_input@1/handle_human_review@1"
+      }
+    },
+    {
+      "actions": {
+        "stateDelta": {
+          "draft": "Subject: Your Phone Issue - How We Can Help\n\nDear Customer,\n\nWe're sorry to hear your phone has broken. To help us assist you quickly, please provide the following details:\n\n*   **Make and model of your phone?** (e.g., iPhone 13, Samsung Galaxy S22)\n*   **When and how did it break?** (e.g., dropped, got wet, stopped turning on)\n*   **When and where was it purchased?** (This helps with warranty)\n*   **Have you tried any troubleshooting steps?** (e.g., restarting, charging)\n\nOnce we have this information, we can guide you through the appropriate next steps.\n\nPlease reply to this email with the requested details, or call our support team at [Your Company Phone Number] during [Business Hours] if you prefer to speak directly.\n\nWe look forward to helping you.\n\nSincerely,\n\nThe [Your Company Name] Support Team"
+        }
+      },
+      "author": "draft_email",
+      "content": {
+        "parts": [
+          {
+            "text": "Subject: Your Phone Issue - How We Can Help\n\nDear Customer,\n\nWe're sorry to hear your phone has broken. To help us assist you quickly, please provide the following details:\n\n*   **Make and model of your phone?** (e.g., iPhone 13, Samsung Galaxy S22)\n*   **When and how did it break?** (e.g., dropped, got wet, stopped turning on)\n*   **When and where was it purchased?** (This helps with warranty)\n*   **Have you tried any troubleshooting steps?** (e.g., restarting, charging)\n\nOnce we have this information, we can guide you through the appropriate next steps.\n\nPlease reply to this email with the requested details, or call our support team at [Your Company Phone Number] during [Business Hours] if you prefer to speak directly.\n\nWe look forward to helping you.\n\nSincerely,\n\nThe [Your Company Name] Support Team"
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-7",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "messageAsOutput": true,
+        "outputFor": [
+          "request_input@1/draft_email@2"
+        ],
+        "path": "request_input@1/draft_email@2"
+      }
+    },
+    {
+      "author": "request_input",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "interruptId": "fc-2",
+                "message": "Please review the following draft email and provide 'approve', 'reject', or feedback to revise.\n\n---\nSubject: Your Phone Issue - How We Can Help\n\nDear Customer,\n\nWe're sorry to hear your phone has broken. To help us assist you quickly, please provide the following details:\n\n*   **Make and model of your phone?** (e.g., iPhone 13, Samsung Galaxy S22)\n*   **When and how did it break?** (e.g., dropped, got wet, stopped turning on)\n*   **When and where was it purchased?** (This helps with warranty)\n*   **Have you tried any troubleshooting steps?** (e.g., restarting, charging)\n\nOnce we have this information, we can guide you through the appropriate next steps.\n\nPlease reply to this email with the requested details, or call our support team at [Your Company Phone Number] during [Business Hours] if you prefer to speak directly.\n\nWe look forward to helping you.\n\nSincerely,\n\nThe [Your Company Name] Support Team\n---",
+                "payload": null,
+                "response_schema": null
+              },
+              "id": "fc-2",
+              "name": "adk_request_input"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "id": "e-8",
+      "invocationId": "i-1",
+      "longRunningToolIds": [
+        "fc-2"
+      ],
+      "nodeInfo": {
+        "path": "request_input@1/request_human_review@2"
+      }
+    },
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-2",
+              "name": "adk_request_input",
+              "response": {
+                "result": "approve"
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-9",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "actions": {
+        "route": "approved"
+      },
+      "author": "request_input",
+      "id": "e-10",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "request_input@1/handle_human_review@2"
+      }
+    },
+    {
+      "author": "request_input",
+      "content": {
+        "parts": [
+          {
+            "text": "Draft approved and sent successfully."
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-11",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "request_input@1/send_email@1"
+      }
+    }
+  ],
+  "id": "cbd1b977-915d-4000-a8f8-f1c747fd3d0e",
+  "state": {
+    "__session_metadata__": {
+      "displayName": "phone broke"
+    },
+    "complaint": "phone broke",
+    "draft": "Subject: Regarding Your Phone Issue\n\nDear [Customer Name],\n\nI'm sorry to hear your phone has broken. I understand how inconvenient this must be.\n\nTo help us investigate and find the best solution for you, please reply with details about your phone (model, purchase date) and what happened. If you have an order number, please include that too.\n\nWe're ready to assist you further once we have this information.\n\nSincerely,\n[Your Name/Company Support Team]",
+    "feedback": "shorter"
+  },
+  "userId": "user"
+}

contributing/samples/workflows/request_input/tests/phone_broke_reject.json

@@ -0,0 +1,137 @@
+{
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "phone broke"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "actions": {
+        "stateDelta": {
+          "complaint": "phone broke",
+          "feedback": ""
+        }
+      },
+      "author": "request_input",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "request_input@1/process_input@1"
+      }
+    },
+    {
+      "actions": {
+        "stateDelta": {
+          "draft": "Subject: Regarding Your Phone Issue – We're Here to Help\n\nDear Customer,\n\nThank you for reaching out. I'm very sorry to hear that your phone has broken. I understand how disruptive and frustrating it can be when your primary device isn't working as it should.\n\nTo help us understand the best way to assist you with a repair or replacement, could you please provide us with a few more details?\n\n1.  **What is the make and model of your phone?** (e.g., iPhone 13, Samsung Galaxy S22)\n2.  **When did you purchase the phone?** (This helps us check warranty status.)\n3.  **Can you briefly describe what happened or how it broke?** (e.g., dropped, water damage, stopped turning on, screen issues)\n4.  **Have you already tried any troubleshooting steps?** (e.g., restarting, charging)\n\nOnce we have this information, we can guide you through the next steps, which may include:\n*   **Warranty Service:** If your phone is still under warranty and the damage is covered.\n*   **Repair Options:** Providing details on how to send your device for repair.\n*   **Replacement Options:** Discussing potential replacement pathways.\n\nIn the meantime, you can also visit our dedicated support page for common issues and troubleshooting at [Link to your support/repair page, e.g., www.yourcompany.com/support/repairs].\n\nPlease reply to this email with the requested details, or if you prefer to speak with someone directly, you can call us at [Your Customer Service Phone Number] during business hours.\n\nWe appreciate your patience and look forward to helping you get this resolved as quickly as possible.\n\nSincerely,\n\nThe [Your Company Name] Support Team"
+        }
+      },
+      "author": "draft_email",
+      "content": {
+        "parts": [
+          {
+            "text": "Subject: Regarding Your Phone Issue – We're Here to Help\n\nDear Customer,\n\nThank you for reaching out. I'm very sorry to hear that your phone has broken. I understand how disruptive and frustrating it can be when your primary device isn't working as it should.\n\nTo help us understand the best way to assist you with a repair or replacement, could you please provide us with a few more details?\n\n1.  **What is the make and model of your phone?** (e.g., iPhone 13, Samsung Galaxy S22)\n2.  **When did you purchase the phone?** (This helps us check warranty status.)\n3.  **Can you briefly describe what happened or how it broke?** (e.g., dropped, water damage, stopped turning on, screen issues)\n4.  **Have you already tried any troubleshooting steps?** (e.g., restarting, charging)\n\nOnce we have this information, we can guide you through the next steps, which may include:\n*   **Warranty Service:** If your phone is still under warranty and the damage is covered.\n*   **Repair Options:** Providing details on how to send your device for repair.\n*   **Replacement Options:** Discussing potential replacement pathways.\n\nIn the meantime, you can also visit our dedicated support page for common issues and troubleshooting at [Link to your support/repair page, e.g., www.yourcompany.com/support/repairs].\n\nPlease reply to this email with the requested details, or if you prefer to speak with someone directly, you can call us at [Your Customer Service Phone Number] during business hours.\n\nWe appreciate your patience and look forward to helping you get this resolved as quickly as possible.\n\nSincerely,\n\nThe [Your Company Name] Support Team"
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "messageAsOutput": true,
+        "outputFor": [
+          "request_input@1/draft_email@1"
+        ],
+        "path": "request_input@1/draft_email@1"
+      }
+    },
+    {
+      "author": "request_input",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "interruptId": "fc-1",
+                "message": "Please review the following draft email and provide 'approve', 'reject', or feedback to revise.\n\n---\nSubject: Regarding Your Phone Issue – We're Here to Help\n\nDear Customer,\n\nThank you for reaching out. I'm very sorry to hear that your phone has broken. I understand how disruptive and frustrating it can be when your primary device isn't working as it should.\n\nTo help us understand the best way to assist you with a repair or replacement, could you please provide us with a few more details?\n\n1.  **What is the make and model of your phone?** (e.g., iPhone 13, Samsung Galaxy S22)\n2.  **When did you purchase the phone?** (This helps us check warranty status.)\n3.  **Can you briefly describe what happened or how it broke?** (e.g., dropped, water damage, stopped turning on, screen issues)\n4.  **Have you already tried any troubleshooting steps?** (e.g., restarting, charging)\n\nOnce we have this information, we can guide you through the next steps, which may include:\n*   **Warranty Service:** If your phone is still under warranty and the damage is covered.\n*   **Repair Options:** Providing details on how to send your device for repair.\n*   **Replacement Options:** Discussing potential replacement pathways.\n\nIn the meantime, you can also visit our dedicated support page for common issues and troubleshooting at [Link to your support/repair page, e.g., www.yourcompany.com/support/repairs].\n\nPlease reply to this email with the requested details, or if you prefer to speak with someone directly, you can call us at [Your Customer Service Phone Number] during business hours.\n\nWe appreciate your patience and look forward to helping you get this resolved as quickly as possible.\n\nSincerely,\n\nThe [Your Company Name] Support Team\n---",
+                "payload": null,
+                "response_schema": null
+              },
+              "id": "fc-1",
+              "name": "adk_request_input"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "id": "e-4",
+      "invocationId": "i-1",
+      "longRunningToolIds": [
+        "fc-1"
+      ],
+      "nodeInfo": {
+        "path": "request_input@1/request_human_review@1"
+      }
+    },
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-1",
+              "name": "adk_request_input",
+              "response": {
+                "result": "reject"
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-5",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "actions": {
+        "route": "rejected"
+      },
+      "author": "request_input",
+      "id": "e-6",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "request_input@1/handle_human_review@1"
+      }
+    },
+    {
+      "author": "request_input",
+      "content": {
+        "parts": [
+          {
+            "text": "Draft rejected."
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-7",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "request_input@1/reject_email@1"
+      }
+    }
+  ]
+}