chore: import upstream snapshot with attribution

contributing/samples/workflows/node_output/README.md

@@ -0,0 +1,66 @@
+# ADK Workflow Node Output Sample
+
+## Overview
+
+This sample demonstrates how to manage component outputs and structure data between nodes in an **ADK Workflow**.
+
+When stringing nodes together, it's critical to know how the ADK framework passes data along edges. This sample shows:
+
+1. Returning a raw string (it gets automatically wrapped in an `Event`).
+1. Returning an explicit `Event` for more granular control over routes and state.
+1. Generating a structured dictionary via `Agent(output_schema=MyModel)`.
+1. Automatically coercing that raw dictionary back into a fully formed Pydantic model simply by defining it as a type-hint parameter in the Python function.
+
+## Sample Inputs
+
+- `cyberpunk future`
+
+- `gardening tips for beginners`
+
+## Graph
+
+```mermaid
+graph TD
+    START --> generate_string_output
+    generate_string_output --> generate_event_output
+    generate_event_output --> generate_pydantic_output
+    generate_pydantic_output --> consume_pydantic_output
+```
+
+## How To
+
+1. **Return raw types (string, dict, list):** The node runner will automatically wrap primitives in an `Event(output=...)`.
+
+   ```python
+   def generate_string_output(node_input: str):
+       return "Processed input: " + node_input
+   ```
+
+1. **Return an Event explicitly:** Use this when you also need to emit a `route` or modify `ctx.state`.
+
+   ```python
+   def generate_event_output(node_input: str):
+       return Event(output=f"Wrapped output: {node_input}")
+   ```
+
+1. **Generate structured data from an LLM:** Pass a Pydantic class to the `Agent`'s `output_schema`. The LLM returns a dictionary/JSON matching the structure.
+
+   ```python
+   class TopicDetails(BaseModel):
+       title: str
+       description: str
+       category: str
+
+   generate_pydantic_output = Agent(
+       name="generate_pydantic_output",
+       output_schema=TopicDetails,
+   )
+   ```
+
+1. **Consume structured data in a function:** Simply type-hint the parameter. `FunctionNode` leverages Pydantic to parse the dictionary back into your fully accessible `TopicDetails` class automatically before your function starts running.
+
+   ```python
+   def consume_pydantic_output(node_input: TopicDetails):
+       # Type coercion converts dict to model. Now you have .title, .category, etc.
+       return f"Title: {node_input.title}"
+   ```

contributing/samples/workflows/node_output/agent.py

@@ -0,0 +1,70 @@
+# 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 pydantic import BaseModel
+from pydantic import Field
+
+
+class TopicDetails(BaseModel):
+  title: str = Field(description="The title of the generated topic.")
+  description: str = Field(description="A short description of the topic.")
+  category: str = Field(description="The broad category of the topic.")
+
+
+def generate_string_output(node_input: str):
+  """Returns a simple string. Framework automatically wraps it in an Event."""
+  return f"Processed input: {node_input}"
+
+
+def generate_event_output(node_input: str):
+  """Explicitly returns an Event object for more control."""
+  return Event(output=f"Event wrapped output: {node_input}")
+
+
+generate_pydantic_output = Agent(
+    name="generate_pydantic_output",
+    instruction="Generate a creative topic based on the following input.",
+    output_schema=TopicDetails,
+)
+
+
+def consume_pydantic_output(node_input: TopicDetails):
+  """
+  Relying on the FunctionNode's automatic type parsing.
+  The framework will coerce the dictionary or JSON into a TopicDetails
+  object automatically.
+  """
+  return (
+      "Received Pydantic Model!\n"
+      f"Title: {node_input.title}\n"
+      f"Description: {node_input.description}\n"
+      f"Category: {node_input.category}"
+  )
+
+
+root_agent = Workflow(
+    name="root_agent",
+    edges=[
+        (
+            "START",
+            generate_string_output,
+            generate_event_output,
+            generate_pydantic_output,
+            consume_pydantic_output,
+        ),
+    ],
+)

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

@@ -0,0 +1,86 @@
+{
+  "appName": "node_output",
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "go"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "author": "root_agent",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "outputFor": [
+          "root_agent@1/generate_string_output@1"
+        ],
+        "path": "root_agent@1/generate_string_output@1"
+      },
+      "output": "Processed input: go"
+    },
+    {
+      "author": "root_agent",
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "outputFor": [
+          "root_agent@1/generate_event_output@1"
+        ],
+        "path": "root_agent@1/generate_event_output@1"
+      },
+      "output": "Event wrapped output: Processed input: go"
+    },
+    {
+      "author": "generate_pydantic_output",
+      "content": {
+        "parts": [
+          {
+            "text": "{\"title\": \"The Impulse to Go: Decoding Humanity's Perpetual Motion\", \"description\": \"Investigating the fundamental human drive to 'go' - exploring its manifestations from ancient migrations and pioneering expeditions to the relentless pursuit of progress in science, technology, and personal growth, and what happens when we pause.\", \"category\": \"Human Behavior & Future Studies\"}"
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-4",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "messageAsOutput": true,
+        "outputFor": [
+          "root_agent@1/generate_pydantic_output@1"
+        ],
+        "path": "root_agent@1/generate_pydantic_output@1"
+      }
+    },
+    {
+      "author": "root_agent",
+      "id": "e-5",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "outputFor": [
+          "root_agent@1/consume_pydantic_output@1",
+          "root_agent@1"
+        ],
+        "path": "root_agent@1/consume_pydantic_output@1"
+      },
+      "output": "Received Pydantic Model!\nTitle: The Impulse to Go: Decoding Humanity's Perpetual Motion\nDescription: Investigating the fundamental human drive to 'go' - exploring its manifestations from ancient migrations and pioneering expeditions to the relentless pursuit of progress in science, technology, and personal growth, and what happens when we pause.\nCategory: Human Behavior & Future Studies"
+    }
+  ],
+  "id": "82ce71ce-e580-4ae2-b291-f82e90221bbd",
+  "state": {
+    "__session_metadata__": {
+      "displayName": "go"
+    }
+  },
+  "userId": "user"
+}