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,59 @@
+# ADK Workflow Dynamic Node Execution Sample
+
+## Overview
+
+This sample demonstrates how to use `ctx.run_node` to execute nodes dynamically during workflow execution in **ADK Workflows**.
+
+In standard workflow execution, the execution path is defined statically by the `edges`. However, there are scenarios where the exact nodes, or the number of times a node runs, cannot be determined until runtime.
+
+In this sample, we handle the dynamic loop scenario: an `orchestrate` Python node acts as the driver. It uses a `while True:` loop to first execute a `generate_headline` agent to create a headline based on a given topic, and then an `evaluate_headline` agent to grade it. If the grade is `"tech-related"`, the loop returns the headline. If `"unrelated"`, the feedback is passed back into the state, and the loop repeats.
+
+This is a rewritten version of the standard `loop` sample, achieved without complex graph edge routing (e.g., without conditional routing functions in `edges`), by instead leveraging native Python control flow (`while` loops) combined with asynchronous `ctx.run_node` calls.
+
+## Sample Inputs
+
+- `flower`
+
+- `quantum mechanics`
+
+- `renewable energy`
+
+## Graph
+
+```mermaid
+graph TD
+    START --> orchestrate[orchestrate <br/>PYTHON FUNCTION]
+    orchestrate -.->|ctx.run_node| generate_headline
+    generate_headline --> evaluate_headline
+    evaluate_headline -.-> orchestrate
+```
+
+## How To
+
+1. **Enable Resumability**: For a python node to use `ctx.run_node`, it must be declared with `@node(rerun_on_resume=True)`. This tells the engine to pause and possibly re-run the orchestrator if any dynamically scheduled node gets interrupted (e.g., waiting for human-in-the-loop).
+
+   ```python
+   from google.adk.workflow import node
+
+   @node(rerun_on_resume=True)
+   async def orchestrate(ctx: Context, node_input: str) -> str:
+       # ...
+   ```
+
+1. **Run Node from Context**: Inject `ctx: Context` into your python node definition and await `ctx.run_node(node_to_run)`. The return value is the final output of that execution. You can also yield events to update the state within the loop before the next iteration.
+
+   ```python
+   @node(rerun_on_resume=True)
+   async def orchestrate(ctx: Context, node_input: str) -> str:
+       yield Event(state={"topic": node_input})
+
+       while True:
+           headline = await ctx.run_node(generate_headline)
+           feedback = Feedback.model_validate(
+               await ctx.run_node(evaluate_headline, node_input=headline)
+           )
+
+           if feedback.grade == "tech-related":
+               yield headline
+               break # or return headline
+   ```
@@ -0,0 +1,78 @@
+# 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 typing import Literal
+
+from google.adk import Agent
+from google.adk import Context
+from google.adk import Event
+from google.adk import Workflow
+from google.adk.workflow import node
+from pydantic import BaseModel
+from pydantic import Field
+
+
+class Feedback(BaseModel):
+  grade: Literal["tech-related", "unrelated"] = Field(
+      description=(
+          "Decide if the headline is related to technology or software"
+          " engineering."
+      ),
+  )
+  feedback: str = Field(
+      description=(
+          "If the headline is unrelated to technology, provide feedback on how"
+          " to make it more tech-focused."
+      ),
+  )
+
+
+generate_headline = Agent(
+    name="generate_headline",
+    instruction="""
+    Write a headline about the topic "{topic}".
+    If feedback is provided, take it into account.
+    The feedback: {feedback?}
+    """,
+)
+
+
+evaluate_headline = Agent(
+    name="evaluate_headline",
+    instruction="""
+    Grade whether the headline is related to technology or software engineering.
+    """,
+    output_schema=Feedback,
+    output_key="feedback",
+)
+
+
+@node(rerun_on_resume=True)
+async def orchestrate(ctx: Context, node_input: str) -> str:
+  yield Event(state={"topic": node_input})
+
+  while True:
+    headline = await ctx.run_node(generate_headline)
+    feedback = Feedback.model_validate(
+        await ctx.run_node(evaluate_headline, node_input=headline)
+    )
+    if feedback.grade == "tech-related":
+      yield headline
+      break
+
+
+root_agent = Workflow(
+    name="root_agent",
+    edges=[("START", orchestrate)],
+)
@@ -0,0 +1,159 @@
+{
+  "appName": "dynamic_nodes",
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "flower"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "actions": {
+        "stateDelta": {
+          "topic": "flower"
+        }
+      },
+      "author": "root_agent",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "root_agent@1/orchestrate@1"
+      }
+    },
+    {
+      "author": "generate_headline",
+      "content": {
+        "parts": [
+          {
+            "text": "A World of Petals"
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "messageAsOutput": true,
+        "outputFor": [
+          "root_agent@1/orchestrate@1/generate_headline@1"
+        ],
+        "path": "root_agent@1/orchestrate@1/generate_headline@1"
+      }
+    },
+    {
+      "actions": {
+        "stateDelta": {
+          "feedback": {
+            "feedback": "This headline sounds like it's about botany, gardening, or a natural theme. To make it more tech-focused, consider incorporating terms like 'AI', 'software', 'virtual reality', 'digital', 'engineering', 'innovation', 'data', or 'development'. For example, 'The AI-Powered World of Digital Petals' or 'Engineering a Virtual Reality of Petals'.",
+            "grade": "unrelated"
+          }
+        }
+      },
+      "author": "evaluate_headline",
+      "content": {
+        "parts": [
+          {
+            "text": "{\"grade\": \"unrelated\", \"feedback\": \"This headline sounds like it's about botany, gardening, or a natural theme. To make it more tech-focused, consider incorporating terms like 'AI', 'software', 'virtual reality', 'digital', 'engineering', 'innovation', 'data', or 'development'. For example, 'The AI-Powered World of Digital Petals' or 'Engineering a Virtual Reality of Petals'.\"}"
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-4",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "messageAsOutput": true,
+        "outputFor": [
+          "root_agent@1/orchestrate@1/evaluate_headline@1"
+        ],
+        "path": "root_agent@1/orchestrate@1/evaluate_headline@1"
+      }
+    },
+    {
+      "author": "generate_headline",
+      "content": {
+        "parts": [
+          {
+            "text": "**Digital Petals: Engineering AI-Enhanced Blooms**"
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-5",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "messageAsOutput": true,
+        "outputFor": [
+          "root_agent@1/orchestrate@1/generate_headline@2"
+        ],
+        "path": "root_agent@1/orchestrate@1/generate_headline@2"
+      }
+    },
+    {
+      "actions": {
+        "stateDelta": {
+          "feedback": {
+            "feedback": "This headline is clearly tech-related, specifically mentioning 'Engineering' and 'AI-Enhanced', which are direct ties to technology and software engineering.",
+            "grade": "tech-related"
+          }
+        }
+      },
+      "author": "evaluate_headline",
+      "content": {
+        "parts": [
+          {
+            "text": "{\"grade\": \"tech-related\", \"feedback\": \"This headline is clearly tech-related, specifically mentioning 'Engineering' and 'AI-Enhanced', which are direct ties to technology and software engineering.\"}"
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-6",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "messageAsOutput": true,
+        "outputFor": [
+          "root_agent@1/orchestrate@1/evaluate_headline@2"
+        ],
+        "path": "root_agent@1/orchestrate@1/evaluate_headline@2"
+      }
+    },
+    {
+      "author": "root_agent",
+      "id": "e-7",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "outputFor": [
+          "root_agent@1/orchestrate@1",
+          "root_agent@1"
+        ],
+        "path": "root_agent@1/orchestrate@1"
+      },
+      "output": "**Digital Petals: Engineering AI-Enhanced Blooms**"
+    }
+  ],
+  "id": "1cf606cf-0c65-4512-96c2-07ccb0181853",
+  "state": {
+    "__session_metadata__": {
+      "displayName": "flower"
+    },
+    "feedback": {
+      "feedback": "This headline is already very tech-focused, mentioning 'AI-Powered' and 'Smart Technology' in the context of innovation.",
+      "grade": "tech-related"
+    },
+    "topic": "flower"
+  },
+  "userId": "user"
+}