feat(workflow): Support state-based resumption for task-mode agent workflow nodes

- Decouple task-mode node execution from default output binding so standard text output does not prematurely finish the node.
- Enhance the runner to automatically resolve and reuse the invocation_id of active suspended task nodes.
- Route incoming plain text resume messages to the active task node by mapping to its isolation scope.
- Enforce strict concurrency serialization by suspending parallel branch execution when a task node is waiting for user input.
- Align schema validation helpers to cleanly handle Content wrapping and raw JSON strings.

Co-authored-by: Shangjie Chen <deanchen@google.com>
PiperOrigin-RevId: 945423735

Author: DeanChensj

contributing/samples/workflows/agent_in_workflow/README.md

@@ -0,0 +1,83 @@
+# Agents In Workflow
+
+This sample demonstrates how to use both `task` mode and `single_turn` mode Agents as nodes within a `Workflow`.
+
+## Overview
+
+The workflow represents a medical lab intake process:
+
+1. **`intake_agent`**: A `task` mode Agent that chats with the user to collect their `name` and `phone_number`. It handles a multi-turn conversation until its `PatientIdentity` output schema is fulfilled.
+1. **`check_identity`**: A regular Python function node that receives the `PatientIdentity`. It mocks checking the database.
+   - If the name is anything other than "Jane Doe", it yields a `retry` route, sending the user back to the `intake_agent`.
+   - If the name is "Jane Doe", it routes to the `generate_instruction` agent.
+1. **`generate_instruction`**: A `single_turn` mode Agent that uses the `find_orders` tool to look up orders. It requires tool confirmation before execution.
+
+## Sample Inputs
+
+- `Hi, I am Jane Doe, my phone number is 555-1234.`
+
+  *The system will process this and return the mock lab orders along with AI-generated instructions on how to prepare.*
+
+- `I'm here for my blood work.`
+
+  *The system will ask for your name and phone number.*
+
+- `My name is John Doe, and my number is 123-456-7890.`
+
+  *The system will fail to find John's orders and route back to the intake agent.*
+
+## Graph
+
+```text
+                  [ START ]
+                      |
+                      v
+              [ intake_agent ] <----.
+                      |             |
+                      v             |
+               [ check_identity ] --- retry
+                      |
+                      | (DEFAULT_ROUTE)
+                      v
+          [ generate_instruction ]
+```
+
+## How To
+
+Within an ADK workflow, you can embed LLM agents directly as nodes. The ADK runner handles them according to their `mode`:
+
+### 1. Task Mode Agents
+
+A `task` agent (`mode="task"`) handles a multi-turn conversation on its own before passing control to the next node. It will continually interact with the user until its specified task is completed.
+
+```python
+class PatientIdentity(BaseModel):
+  name: str
+  phone_number: str
+
+intake_agent = Agent(
+    name="intake_agent",
+    mode="task", # Stops and chats with the user until the schema is populated
+    output_schema=PatientIdentity,
+    instruction="...",
+)
+```
+
+The parsed `output_schema` object is automatically forwarded as the `node_input` to the next node in the graph.
+
+### 2. Single Turn Mode Agents
+
+A `single_turn` agent (the default mode if omitted) executes a single LLM call. It is typically used for inline text generation, summarization, or classification without chatting with the user.
+
+```python
+generate_instruction = Agent(
+    name="generate_instruction",
+    tools=[FunctionTool(find_orders, require_confirmation=True)],
+    instruction="""
+Use the find_orders tool to get the patient's orders.
+List the orders found, and then generate a concise instruction about how to prepare based on those orders.
+""",
+)
+```
+
+In this sample, the `generate_instruction` agent uses the `find_orders` tool to retrieve the orders. It also demonstrates **tool confirmation**, requiring the user to approve the tool call before it executes.

contributing/samples/workflows/agent_in_workflow/agent.py

@@ -0,0 +1,87 @@
+# 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.tools.function_tool import FunctionTool
+from google.adk.workflow import DEFAULT_ROUTE
+from pydantic import BaseModel
+from pydantic import Field
+
+
+class PatientIdentity(BaseModel):
+  """Output schema for the intake agent."""
+
+  name: str = Field(description="The patient's full name.")
+  phone_number: str = Field(description="The patient's phone number.")
+
+
+intake_agent = Agent(
+    name="intake_agent",
+    mode="task",
+    output_schema=PatientIdentity,
+    instruction="""\
+You are a medical lab intake assistant. Your job is to chat with
+the user to get their full name and phone number. Do not make up
+information. Once you have both, finish your task.
+If identity check failed, ask for another name.
+""",
+)
+
+
+def check_identity(node_input: PatientIdentity):
+  """Mocks checking the database for the patient.
+
+  Routes back to intake_agent if the name is not Jane Doe.
+  """
+  if node_input.name.lower() != "jane doe":
+    yield Event(
+        message=(
+            f"Could not find matching records for {node_input.name}. Let's"
+            " try again."
+        ),
+        route="retry",
+    )
+  else:
+    yield Event(
+        message=f"""Hello {node_input.name}! Let me look up your orders."""
+    )
+
+
+def find_orders() -> list[str]:
+  """Finds orders for the patient."""
+  return ["CBC (Complete Blood Count)", "Lipid Panel"]
+
+
+generate_instruction = Agent(
+    name="generate_instruction",
+    tools=[FunctionTool(find_orders, require_confirmation=True)],
+    instruction="""
+Use the find_orders tool to get the patient's orders.
+List the orders found, and then generate a concise instruction about how to prepare based on those orders.
+""",
+)
+
+
+root_agent = Workflow(
+    name="task_in_workflow",
+    edges=[
+        ("START", intake_agent, check_identity),
+        (
+            check_identity,
+            {"retry": intake_agent, DEFAULT_ROUTE: generate_instruction},
+        ),
+    ],
+)