docs(samples): Add streaming message example

boyangsvl · boyangsvl · commit 1d59974cf4ad · 2026-03-28T16:25:22.000-07:00
Update message workflow sample to demonstrate streaming token chunks using Event(message=..., partial=True).

Change-Id: Iaa44a293dda1aec1a689b26997b83e4e17ae31ef
diff --git a/contributing/workflow_samples/message/README.md b/contributing/workflow_samples/message/README.md
@@ -7,6 +7,7 @@ This sample demonstrates different ways to send a message to a user using `Event
 1. **String Messages**: Standard string text replies.
 1. **Multi-modal Messages**: Returning mixed modality inputs, such as a string combined with an inline image.
 1. **Multiple Messages**: Emitting multiple full messages from the same node with a delay between them.
+1. **Streaming Messages**: Simulating an LLM streaming response by breaking a message into chunks and yielding them with the `partial=True` flag at intervals.
 
 ## Sample Inputs
 
@@ -27,6 +28,9 @@ This workflow executes sequentially and successfully without any expected user i
             [ multiple_messages ]
                       |
                       v
+             [ stream_sentence ]
+                      |
+                      v
                  (Workflow Ends)
 ```
 
@@ -69,3 +73,19 @@ To send messages in an ADK node, yield an `Event` object with the `message` argu
 
      yield Event(message="Done processing.")
    ```
+
+1. **Stream a message in chunks**:
+   Provide the `partial=True` flag for intermediate chunks. This provides a better user experience by allowing the UI to show the response in a streaming fashion, thereby lowering the latency to see the first word. ADK automatically accumulates all partial messages and merges them into a final message for you for session storage.
+
+   > **Note**: To stream multiple messages or tokens smoothly, your node function **must be an asynchronous generator** (`async def`). This allows ADK to yield messages to the client immediately without blocking.
+
+   ```python
+   import asyncio
+
+   async def stream_sentence(node_input: str):
+       yield Event(message="How ", partial=True)
+       await asyncio.sleep(0.5)
+       yield Event(message="may I", partial=True)
+       await asyncio.sleep(0.5)
+       yield Event(message=" help you?", partial=True)
+   ```
diff --git a/contributing/workflow_samples/message/agent.py b/contributing/workflow_samples/message/agent.py
@@ -23,7 +23,7 @@
 
 def send_string(node_input: Any = None):
   """Sends a single string message."""
-  yield Event(message="1. This is a simple string message.")
+  yield Event(message="#1 This is a simple string message.")
 
 
 def send_multimodal(node_input: Any = None):
@@ -36,7 +36,7 @@ def send_multimodal(node_input: Any = None):
       message=[
           types.Part.from_text(
               text=(
-                  "2. Here is a multi-modal message with an inline image (red"
+                  "#2 Here is a multi-modal message with an inline image (red"
                   " square):"
               )
           ),
@@ -47,13 +47,34 @@ def send_multimodal(node_input: Any = None):
 
 async def multiple_messages(node_input: Any = None):
   """Sends multiple complete messages from the same node with an interval."""
-  yield Event(message="3. Processing step 1...")
+  yield Event(message="#3 Multiple messages")
   await asyncio.sleep(1.0)
 
-  yield Event(message="3. Processing step 2...")
+  yield Event(message="Processing step 1...")
   await asyncio.sleep(1.0)
 
-  yield Event(message="3. Done processing.")
+  yield Event(message="Processing step 2...")
+  await asyncio.sleep(1.0)
+
+  yield Event(message="Done processing.")
+
+
+async def stream_sentence(node_input: Any = None):
+  """
+  Demonstrates streaming by sending a sentence in chunks.
+  The `partial=True` flag tells the UI that this is part of an ongoing message.
+  """
+  yield Event(message="#4 Starting to stream...")
+  sentence = """\
+This is a streaming message sent in chunks.
+
+You need to enable 'Token Streaming' in the UI to see this message in chunks.
+"""
+
+  for i in range(0, len(sentence), 5):
+    chunk = sentence[i : i + 5]
+    yield Event(message=chunk, partial=True)
+    await asyncio.sleep(0.2)
 
 
 root_agent = Workflow(
@@ -64,6 +85,7 @@ async def multiple_messages(node_input: Any = None):
             send_string,
             send_multimodal,
             multiple_messages,
+            stream_sentence,
         ),
     ],
 )
