chore: import upstream snapshot with attribution

2026-07-13 13:25:13 +08:00
commit ec2b666284
2231 changed files with 491535 additions and 0 deletions
@@ -0,0 +1,86 @@
+# ADK Workflow Request Input Rerun Sample
+
+## Overview
+
+This sample demonstrates an alternative way to handle a **Human-in-the-Loop** workflow in **ADK Workflows** using the `RequestInput` event combined with the `@node(rerun_on_resume=True)` decorator.
+
+Like the standard `request_input` sample, this workflow simulates a customer support scenario where an AI drafts an email and a human reviews it. The key difference lies in *how* the human input is processed when the workflow resumes.
+
+### `request_input` vs `request_input_rerun`
+
+- **Standard (`request_input`):** The workflow pauses after a node yields `RequestInput`. When the user provides input and execution resumes, the input is automatically passed as the argument to the **next node** in the edge definition. This requires two separate nodes: one to request the input and one to handle it.
+- **Rerun (`request_input_rerun`):** The node yielding `RequestInput` is decorated with `@node(rerun_on_resume=True)`. When execution resumes, the workflow **re-runs the exact same node** that asked for the input. The node can then access the provided input via the execution `Context`.
+
+This allows you to combine the requesting and handling of human input into a single, cohesive node.
+
+## Sample Inputs
+
+- `The delivery was a week late`
+
+- `I received the wrong item`
+
+- `My account was charged twice`
+
+## Graph
+
+```mermaid
+graph TD
+    START --> draft_email
+    draft_email --> human_review[human_review <br/>reruns on resume]
+    human_review -->|revise| draft_email
+    human_review -->|approved| send_email
+    human_review -->|rejected| END_rejected[END rejected]
+```
+
+## How To
+
+1. Decorate the node that needs human input with `@node(rerun_on_resume=True)`. Ensure the function signature includes the workflow `Context`.
+
+   ```python
+   from google.adk.workflow import node
+   from google.adk import Context
+
+   @node(rerun_on_resume=True)
+   def human_review(draft: str, ctx: Context):
+       # ...
+   ```
+
+1. Inside the node, check if you are being resumed by looking for the `interrupt_id` in `ctx.resume_inputs`.
+
+   ```python
+   resume_input = ctx.resume_inputs.get('human_review')
+   ```
+
+1. If `resume_input` is missing (i.e., this is the first time the node is executing), yield the `RequestInput` event to pause the workflow. Include an explicit `interrupt_id`.
+
+   ```python
+   if not resume_input:
+       yield RequestInput(
+           interrupt_id="human_review",
+           message="Please review the draft...",
+       )
+       return # Important: Stop execution of this node for now
+   ```
+
+1. If `resume_input` is present (i.e., the workflow was resumed with user input), process the input and yield the appropriate routing events.
+
+   ```python
+   if resume_input == "reject":
+       yield Event(route="rejected")
+   elif resume_input == "approve":
+       yield Event(route="approved")
+   else:
+       yield Event(state={"feedback": resume_input}, route="revise")
+   ```
+
+1. The edge definition is much simpler because the single `human_review` node handles everything:
+
+   ```python
+   Workflow(
+       name="request_input",
+       edges=[
+           ("START", process_input, draft_email, human_review),
+           (human_review, {"revise": draft_email, "approved": send_email}),
+       ],
+   )
+   ```
@@ -0,0 +1,81 @@
+# 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 Context
+from google.adk import Event
+from google.adk import Workflow
+from google.adk.events import RequestInput
+from google.adk.workflow import node
+
+
+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",
+)
+
+
+@node(rerun_on_resume=True)
+def human_review(draft: str, ctx: Context):
+  resume_input = ctx.resume_inputs.get("human_review")
+  if not resume_input:
+    yield RequestInput(
+        interrupt_id="human_review",
+        message=(
+            "Please review the following draft email and provide 'approve',"
+            f" 'reject', or feedback to revise.\n\n---\n{draft}\n---"
+        ),
+    )
+    return
+
+  if resume_input == "reject":
+    yield Event(route="rejected")
+  elif resume_input == "approve":
+    yield Event(route="approved")
+  else:
+    yield Event(state={"feedback": resume_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_rerun",
+    edges=[
+        ("START", process_input, draft_email, human_review),
+        (
+            human_review,
+            {
+                "revise": draft_email,
+                "approved": send_email,
+                "rejected": reject_email,
+            },
+        ),
+    ],
+)
@@ -0,0 +1,238 @@
+{
+  "appName": "request_input_rerun",
+  "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_rerun",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "request_input_rerun@1/process_input@1"
+      }
+    },
+    {
+      "actions": {
+        "stateDelta": {
+          "draft": "Subject: Regarding Your Phone Issue - How We Can Help - [Your Company Name]\n\nDear Valued Customer,\n\nThank you for reaching out to us. We're very sorry to hear that you're experiencing an issue with your phone. We understand how frustrating it can be when your device isn't working as expected, and we're here to help.\n\nTo assist you as quickly and effectively as possible, could you please provide a few more details about the situation? This will help us understand the problem and guide you towards the best solution.\n\nPlease tell us:\n\n1.  **What is the model of your phone?** (e.g., iPhone 15, Samsung Galaxy S24, Google Pixel 8, etc.)\n2.  **When did you purchase the phone?** (Rough date or year is fine if you don't have the exact date.)\n3.  **Could you describe what happened and how the phone \"broke\"?** (e.g., \"It fell and the screen cracked,\" \"It won't turn on,\" \"It got wet,\" \"The battery stopped charging,\" \"It's stuck in a loop,\" etc.)\n4.  **Have you already attempted any troubleshooting steps?** (e.g., restarting the phone, checking charging cables, etc.)\n\nOnce we have this information, our support team will be able to assess the situation, discuss potential solutions such as troubleshooting, repair options, or warranty service, and guide you through the next steps.\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 Phone Number] during our business hours of [Your Business Hours].\n\nWe look forward to helping you resolve this issue soon.\n\nSincerely,\n\nThe Customer Support Team\n[Your Company Name]\n[Your Company Website (Optional)]"
+        }
+      },
+      "author": "draft_email",
+      "content": {
+        "parts": [
+          {
+            "text": "Subject: Regarding Your Phone Issue - How We Can Help - [Your Company Name]\n\nDear Valued Customer,\n\nThank you for reaching out to us. We're very sorry to hear that you're experiencing an issue with your phone. We understand how frustrating it can be when your device isn't working as expected, and we're here to help.\n\nTo assist you as quickly and effectively as possible, could you please provide a few more details about the situation? This will help us understand the problem and guide you towards the best solution.\n\nPlease tell us:\n\n1.  **What is the model of your phone?** (e.g., iPhone 15, Samsung Galaxy S24, Google Pixel 8, etc.)\n2.  **When did you purchase the phone?** (Rough date or year is fine if you don't have the exact date.)\n3.  **Could you describe what happened and how the phone \"broke\"?** (e.g., \"It fell and the screen cracked,\" \"It won't turn on,\" \"It got wet,\" \"The battery stopped charging,\" \"It's stuck in a loop,\" etc.)\n4.  **Have you already attempted any troubleshooting steps?** (e.g., restarting the phone, checking charging cables, etc.)\n\nOnce we have this information, our support team will be able to assess the situation, discuss potential solutions such as troubleshooting, repair options, or warranty service, and guide you through the next steps.\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 Phone Number] during our business hours of [Your Business Hours].\n\nWe look forward to helping you resolve this issue soon.\n\nSincerely,\n\nThe Customer Support Team\n[Your Company Name]\n[Your Company Website (Optional)]"
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "messageAsOutput": true,
+        "outputFor": [
+          "request_input_rerun@1/draft_email@1"
+        ],
+        "path": "request_input_rerun@1/draft_email@1"
+      }
+    },
+    {
+      "author": "request_input_rerun",
+      "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 - [Your Company Name]\n\nDear Valued Customer,\n\nThank you for reaching out to us. We're very sorry to hear that you're experiencing an issue with your phone. We understand how frustrating it can be when your device isn't working as expected, and we're here to help.\n\nTo assist you as quickly and effectively as possible, could you please provide a few more details about the situation? This will help us understand the problem and guide you towards the best solution.\n\nPlease tell us:\n\n1.  **What is the model of your phone?** (e.g., iPhone 15, Samsung Galaxy S24, Google Pixel 8, etc.)\n2.  **When did you purchase the phone?** (Rough date or year is fine if you don't have the exact date.)\n3.  **Could you describe what happened and how the phone \"broke\"?** (e.g., \"It fell and the screen cracked,\" \"It won't turn on,\" \"It got wet,\" \"The battery stopped charging,\" \"It's stuck in a loop,\" etc.)\n4.  **Have you already attempted any troubleshooting steps?** (e.g., restarting the phone, checking charging cables, etc.)\n\nOnce we have this information, our support team will be able to assess the situation, discuss potential solutions such as troubleshooting, repair options, or warranty service, and guide you through the next steps.\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 Phone Number] during our business hours of [Your Business Hours].\n\nWe look forward to helping you resolve this issue soon.\n\nSincerely,\n\nThe Customer Support Team\n[Your Company Name]\n[Your Company Website (Optional)]\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_rerun@1/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_rerun",
+      "id": "e-6",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "request_input_rerun@1/human_review@1"
+      }
+    },
+    {
+      "actions": {
+        "stateDelta": {
+          "draft": "Subject: Regarding Your Phone Issue - How We Can Help - [Your Company Name]\n\nDear Valued Customer,\n\nThank you for contacting us. We're sorry to hear about your phone issue and are ready to help.\n\nTo assist you efficiently, please provide the following details:\n\n1.  **What is the model of your phone?** (e.g., iPhone 15, Samsung Galaxy S24)\n2.  **When did you purchase the phone?** (Rough date or year is fine)\n3.  **How did the phone \"break\"?** (e.g., screen cracked, won't turn on, got wet)\n4.  **Have you attempted any troubleshooting steps?** (e.g., restarting, checking cables)\n\nWith this information, our team can better assess the problem and outline next steps (troubleshooting, repair, warranty).\n\nPlease reply to this email with the details. You can also call us at [Your Phone Number] during [Your Business Hours] if you prefer to speak directly.\n\nWe look forward to helping you resolve this soon.\n\nSincerely,\n\nThe Customer Support Team\n[Your Company Name]\n[Your Company Website (Optional)]"
+        }
+      },
+      "author": "draft_email",
+      "content": {
+        "parts": [
+          {
+            "text": "Subject: Regarding Your Phone Issue - How We Can Help - [Your Company Name]\n\nDear Valued Customer,\n\nThank you for contacting us. We're sorry to hear about your phone issue and are ready to help.\n\nTo assist you efficiently, please provide the following details:\n\n1.  **What is the model of your phone?** (e.g., iPhone 15, Samsung Galaxy S24)\n2.  **When did you purchase the phone?** (Rough date or year is fine)\n3.  **How did the phone \"break\"?** (e.g., screen cracked, won't turn on, got wet)\n4.  **Have you attempted any troubleshooting steps?** (e.g., restarting, checking cables)\n\nWith this information, our team can better assess the problem and outline next steps (troubleshooting, repair, warranty).\n\nPlease reply to this email with the details. You can also call us at [Your Phone Number] during [Your Business Hours] if you prefer to speak directly.\n\nWe look forward to helping you resolve this soon.\n\nSincerely,\n\nThe Customer Support Team\n[Your Company Name]\n[Your Company Website (Optional)]"
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-7",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "messageAsOutput": true,
+        "outputFor": [
+          "request_input_rerun@1/draft_email@2"
+        ],
+        "path": "request_input_rerun@1/draft_email@2"
+      }
+    },
+    {
+      "author": "request_input_rerun",
+      "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: Regarding Your Phone Issue - How We Can Help - [Your Company Name]\n\nDear Valued Customer,\n\nThank you for contacting us. We're sorry to hear about your phone issue and are ready to help.\n\nTo assist you efficiently, please provide the following details:\n\n1.  **What is the model of your phone?** (e.g., iPhone 15, Samsung Galaxy S24)\n2.  **When did you purchase the phone?** (Rough date or year is fine)\n3.  **How did the phone \"break\"?** (e.g., screen cracked, won't turn on, got wet)\n4.  **Have you attempted any troubleshooting steps?** (e.g., restarting, checking cables)\n\nWith this information, our team can better assess the problem and outline next steps (troubleshooting, repair, warranty).\n\nPlease reply to this email with the details. You can also call us at [Your Phone Number] during [Your Business Hours] if you prefer to speak directly.\n\nWe look forward to helping you resolve this soon.\n\nSincerely,\n\nThe Customer Support Team\n[Your Company Name]\n[Your Company Website (Optional)]\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_rerun@1/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_rerun",
+      "id": "e-10",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "request_input_rerun@1/human_review@2"
+      }
+    },
+    {
+      "author": "request_input_rerun",
+      "content": {
+        "parts": [
+          {
+            "text": "Draft approved and sent successfully."
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-11",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "request_input_rerun@1/send_email@1"
+      }
+    }
+  ],
+  "id": "2daf1ec0-1582-419d-95e9-c5be7269e701",
+  "state": {
+    "__session_metadata__": {
+      "displayName": "phone broke"
+    },
+    "complaint": "phone broke",
+    "draft": "Subject: Regarding Your Broken Phone\n\nDear [Customer Name],\n\nWe're very sorry to hear your phone has broken. We understand this is frustrating, and we want to help resolve it for you as quickly as possible.\n\nTo assist you best, please reply with some additional details:\n*   Your phone's model\n*   When you purchased it\n*   A brief description of what happened\n*   Whether it is currently under warranty\n\nYou can also find immediate support and repair options on our website here: [Link to Repair/Support Page]\n\nAlternatively, please feel free to call us directly at [Phone Number] if you prefer to speak with someone.\n\nWe appreciate your patience and look forward to helping.\n\nSincerely,\n\nThe [Your Company Name] Team",
+    "feedback": "shorter"
+  },
+  "userId": "user"
+}