Merge branch 'main' into fix/non-english-eval-rouge

Author: rohityan

.agents/skills/adk-agent-builder/references/advanced-patterns.md

@@ -4,12 +4,14 @@ Nested workflows, dynamic nodes, retry configuration, custom node types, and gra
 
 ## 📋 Agent Verification Checklist (Advanced Patterns)
 Use this checklist when implementing complex workflows:
+
 - [ ] **Validation**: Does your graph follow all 7 validation rules? (e.g., no unconditional cycles)
 - [ ] **Custom Nodes**: If creating a custom node, did you override `get_name()` and `run()`?
 - [ ] **Dynamic Execution**: If using `run_node`, did you follow the rules in the dedicated dynamic-nodes reference?
 - [ ] **Waiting State**: Did you use `wait_for_output=True` if the node should stay in WAITING state until output is yielded?
 
 ## 💡 Quick Reference
+
 - **Retry**: `RetryConfig(max_attempts=5, initial_delay=1.0)`
 - **Custom Node Fields**: `rerun_on_resume`, `wait_for_output`, `retry_config`, `timeout`
 
@@ -46,7 +48,8 @@ The inner workflow receives the predecessor's output as its START input and its
 
 Schedule nodes at runtime using `ctx.run_node()`.
 
-See the dedicated [Dynamic Node Scheduling Reference](file:///Users/deanchen/Desktop/adk-workflow/.agents/skills/adk-workflow/references/dynamic-nodes.md) for detailed rules, examples, and best practices.
+See the dedicated [Dynamic Node Scheduling Reference](dynamic-nodes.md) for
+detailed rules, examples, and best practices.
 
 ## Retry Configuration
 
@@ -80,12 +83,13 @@ delay = min(delay, max_delay)
 delay = delay * (1 + random(0, jitter))
 ```
 
-### Accessing retry count
+### Accessing the attempt count
 
 ```python
 def my_node(ctx: Context, node_input: str) -> str:
-  if ctx.retry_count > 0:
-    print(f"Retry attempt {ctx.retry_count}")
+  # attempt_count is 1 on the first try, ≥2 on retries
+  if ctx.attempt_count > 1:
+    print(f"Retry attempt {ctx.attempt_count}")
   return "result"
 ```
 
@@ -167,6 +171,7 @@ class CollectorNode(BaseNode):
 ```
 
 Nodes with `wait_for_output=True` default:
+
 - `JoinNode`: `True` (waits for all predecessors)
 - `LlmAgentWrapper` (task mode): `True` (set in `model_post_init`)
 - All other nodes: `False`

.agents/skills/adk-agent-builder/references/import-paths.md

@@ -2,6 +2,7 @@
 
 ## 📋 Agent Verification Checklist (Imports)
 Use this checklist to ensure you are using the most idiomatic import paths:
+
 - [ ] **Canonical Imports**: Did you use the short canonical imports where available (e.g., `from google.adk import Agent`) instead of the verbose ones?
 - [ ] **Avoid Deprecated**: Are you avoiding deprecated paths (e.g., use `McpToolset` instead of `MCPToolset`)?
 
@@ -34,16 +35,25 @@ from google.adk.workflow import node, RetryConfig, Edge, JoinNode
 
 ## Workflow Nodes
 
-| Component | Import |
-|-----------|--------|
-| `FunctionNode` | `from google.adk.workflow import FunctionNode` |
-| `_LlmAgentWrapper` (private, auto-used) | `from google.adk.workflow._llm_agent_wrapper import _LlmAgentWrapper` |
-| `AgentNode` | `from google.adk.workflow._agent_node import AgentNode` |
-| `_ToolNode` (private) | `from google.adk.workflow._tool_node import _ToolNode` |
-| `JoinNode` | `from google.adk.workflow import JoinNode` |
-| `ParallelWorker` | `from google.adk.workflow._parallel_worker import ParallelWorker` |
-| `BaseNode`, `START` | `from google.adk.workflow import BaseNode, START` |
-| `@node` decorator | `from google.adk.workflow import node` |
+| Component                           | Import                                 |
+| ----------------------------------- | -------------------------------------- |
+| `FunctionNode`                      | `from google.adk.workflow import       |
+:                                     : FunctionNode`                          :
+| `_LlmAgentWrapper` (private,        | `from                                  |
+: auto-used)                          : google.adk.workflow._llm_agent_wrapper :
+:                                     : import _LlmAgentWrapper`               :
+| `AgentNode`                         | `from google.adk.workflow._agent_node  |
+:                                     : import AgentNode`                      :
+| `_ToolNode` (private)               | `from google.adk.workflow._tool_node   |
+:                                     : import _ToolNode`                      :
+| `JoinNode`                          | `from google.adk.workflow import       |
+:                                     : JoinNode`                              :
+| Parallel-worker behavior (no public | Set `parallel_worker=True` on `@node`  |
+: class)                              : or `LlmAgent`; the framework wraps     :
+:                                     : with an internal `_ParallelWorker`     :
+| `BaseNode`, `START`                 | `from google.adk.workflow import       |
+:                                     : BaseNode, START`                       :
+| `@node` decorator                   | `from google.adk.workflow import node` |
 
 ## Workflow Events and Context
 

.agents/skills/adk-agent-builder/references/llm-agent-nodes.md

@@ -4,12 +4,14 @@ Embed LLM-powered agents as nodes in workflow graphs.
 
 ## 📋 Agent Verification Checklist (LLM Nodes)
 Use this checklist to verify your LLM agent configuration:
+
 - [ ] **Output Type**: If no `output_schema` is set, downstream now receives `str` (auto-extracted from `types.Content`). You can safely type-hint `node_input: str`.
 - [ ] **State Serialization**: If this agent feeds into a `JoinNode`, did you set `output_schema` to avoid non-serializable `types.Content` errors?
 - [ ] **Instructions**: Are `{var}` templates used in instructions resolving ONLY from `ctx.state`? (Not `node_input`)
 - [ ] **Config**: Are instructions, tools, and response schema set on the `LlmAgent` directly, and NOT in `generate_content_config`?
 
 ## 💡 Quick Reference
+
 - **Chat Mode**: Default. Multi-turn, keeps session history.
 - **Single-Turn Mode**: Isolated. Set `mode="single_turn"` or rely on auto-wrapping defaults.
 - **Task Mode**: Multi-turn within a task. Set `mode="task"`.
@@ -70,25 +72,25 @@ agent = Workflow(
 )
 ```
 
-## LLM Agent Output Types (Critical)
+## LLM Agent Output Types
 
-**LlmAgentWrapper auto-extracts text and outputs `str` when no `output_schema` is set.** Previously, it outputted `types.Content` causing type errors. Now, if you type-hint `node_input: str`, it will work correctly for standard text output.
+When an `LlmAgent` runs as a workflow node, `process_llm_agent_output` (in
+`_llm_agent_wrapper.py`) sets `event.output` to:
 
-**Solutions (pick one):**
+-   The **concatenated text** of the model's response (a `str`) — when
+    `output_schema` is not set.
+-   The **validated dict** (`model_dump()` of the Pydantic model) — when
+    `output_schema=MyModel` is set.
 
-1. **Use `Any` and extract text** (recommended for function nodes after LLM agents):
+A downstream function node typed `node_input: str` therefore works in the
+default case, and `node_input: dict` works when `output_schema` is set.
 
-```python
-from typing import Any
-from google.genai import types
-
-def process_llm_output(node_input: Any) -> str:
-  if isinstance(node_input, types.Content):
-    return ''.join(p.text for p in (node_input.parts or []) if p.text)
-  return str(node_input) if node_input is not None else ''
-```
-
-2. **Use `output_schema`** on the LLM agent to get a parsed `dict` instead:
+**Observability caveat:** the value above is set on the event internally and
+forwarded to the next node, but `event.output` is **`None`** when you observe it
+from `runner.run_async(...)` for the LLM agent's own event — the framework
+clears it before the event reaches user code. Don't write tests that assert on
+`event.output` for an LLM agent's event; assert on the downstream node's output,
+on `session.state[output_key]`, or on `event.content.parts[*].text` instead.
 
 ```python
 from pydantic import BaseModel
@@ -104,23 +106,28 @@ writer = LlmAgent(
     output_schema=CodeOutput,
 )
 
-# Downstream node receives dict: {"code": "...", "language": "python"}
+# Downstream node receives a dict: {"code": "...", "language": "python"}
 def process_code(node_input: dict) -> str:
   return node_input["code"]
 ```
 
 **Summary of LLM agent node output types:**
 
-| LLM Agent Config | `node_input` Type for Next Node |
-|-----------------|-------------------------------|
-| No `output_schema` | `types.Content` |
-| With `output_schema` | `dict` (parsed from Pydantic model) |
+LLM Agent Config     | `node_input` Type for Next Node
+-------------------- | -----------------------------------
+No `output_schema`   | `str` (concatenated model text)
+With `output_schema` | `dict` (parsed from Pydantic model)
 
-**State serialization warning:** When LLM agents feed into a `JoinNode`, the JoinNode stores intermediate results in session state. Without `output_schema`, this stores `types.Content` objects which are **not JSON-serializable** and will cause `TypeError` with SQLite/database session services. Always use `output_schema` on LLM agents that feed into a JoinNode.
+**Prefer `output_schema` when downstream nodes need structured access.** Strings
+are fine for pass-through text, but a typed dict is easier to consume and is
+required when the predecessor feeds a `JoinNode` whose results land in a
+persistent session service (raw text is fine; objects that aren't
+JSON-serializable break `DatabaseSessionService`).
 
 ## Auto-Wrapping Behavior
 
 When you place an `LlmAgent` in workflow edges, it is auto-wrapped as `_LlmAgentWrapper`. The wrapper:
+
 - Defaults to `single_turn` mode (agent sees only current input, not session history)
 - Sets `rerun_on_resume=True` (reruns after HITL interrupts)
 - Creates a content branch for isolation between parallel LLM agents
@@ -260,6 +267,7 @@ agent = LlmAgent(
 ```
 
 Tools can be:
+
 - Python functions (auto-wrapped as `FunctionTool`)
 - `BaseTool` instances
 - `BaseToolset` instances (e.g., MCP toolsets)

.agents/skills/adk-agent-builder/references/parallel-and-fanout.md

@@ -4,24 +4,27 @@ Execute multiple nodes concurrently and collect their results.
 
 ## 📋 Agent Verification Checklist (Parallel & Fan-Out)
 Use this checklist when implementing parallel patterns:
+
 - [ ] **JoinNode Serialization**: If LLM agents feed into a `JoinNode`, did you set `output_schema` on them to prevent JSON serialization errors?
 - [ ] **ParallelWorker Usage**: Did you avoid using `parallel_worker=True` on fan-out nodes? (It expects a list input)
 - [ ] **Multi-Trigger vs Join**: Do you understand that Multi-Trigger fires downstream once per branch, while JoinNode waits and fires once with merged dict?
 
 ## 💡 Quick Reference
+
 - **Fan-Out (Tuple)**: `('START', (node_a, node_b))`
 - **Fan-In (JoinNode)**: `((node_a, node_b), join_node)`
 - **List Worker**: `@node(parallel_worker=True)` (Takes list, outputs list)
 
 ## Imports
 
 ```python
-from google.adk.workflow import Workflow
-from google.adk.workflow._parallel_worker import ParallelWorker
-from google.adk.workflow import JoinNode
-from google.adk.workflow import node
+from google.adk.workflow import Workflow, JoinNode, node
 ```
 
+Parallel-worker behavior is opted into via the `parallel_worker=True` flag on
+`@node` or `LlmAgent`. The underlying wrapper class is internal — don't import
+it directly.
+
 ## Fan-Out: Multiple Branches
 
 Send output to multiple nodes simultaneously using tuple syntax:
@@ -91,51 +94,43 @@ def final_processor(node_input: dict) -> str:
 
 **Serialization warning:** JoinNode stores partial inputs in session state while waiting. If predecessors are LLM agents without `output_schema`, the stored values are `types.Content` objects which are **not JSON-serializable**. This causes `TypeError` with SQLite/database session services. Fix: use `output_schema` on LLM agents feeding into a JoinNode.
 
-## ParallelWorker: Process Lists in Parallel
+## Parallel workers: process lists in parallel
 
-Apply the same node to each item in a list concurrently:
+Apply the same node to each item in a list concurrently by setting the
+`parallel_worker=True` flag. The framework wraps the node internally — there is
+no public `ParallelWorker` class to import.
 
 ```python
+from google.adk.workflow import node, Workflow
+
+@node(parallel_worker=True)
 def process_item(node_input: int) -> int:
   return node_input * 2
 
-parallel = ParallelWorker(node(process_item))
-
 def produce_list(node_input: str) -> list:
   return [1, 2, 3, 4, 5]
 
 agent = Workflow(
     name="parallel_processing",
     edges=[
         ('START', produce_list),
-        (produce_list, parallel),
+        (produce_list, process_item),
     ],
 )
 # Output: [2, 4, 6, 8, 10]
 ```
 
-### ParallelWorker Details
+### Behavior
 
 - Input: a **list** (or single item, which gets wrapped in a list)
 - Output: a **list** of results in the same order as inputs
 - Empty list input produces empty list output
 - Each item is processed by a dynamically created worker node
-- Workers are named `{parent_name}__{index}` (e.g., `process_item__0`)
 - Default `rerun_on_resume=True`
 
-### ParallelWorker with @node Decorator
-
-```python
-@node(parallel_worker=True)
-def process_item(node_input: int) -> int:
-  return node_input * 2
-
-# Equivalent to: ParallelWorker(FunctionNode(process_item_fn))
-```
-
-### ParallelWorker with Agents
+### Parallel workers with Agents
 
-Set `parallel_worker=True` directly on an Agent:
+Set `parallel_worker=True` directly on an Agent — no extra wrapping needed:
 
 ```python
 from google.adk import Agent
@@ -155,12 +150,6 @@ agent = Workflow(
 )
 ```
 
-Or wrap manually:
-
-```python
-parallel_analyzer = ParallelWorker(analyzer)
-```
-
 **Do NOT use `parallel_worker=True` on fan-out nodes.** Fan-out edges `(a, (b, c, d))` already run nodes in parallel. Adding `parallel_worker=True` makes the node expect a list input and iterate over it — if it receives a single value or None, it produces no output and the JoinNode gets nothing.
 
 ## Multi-Trigger (Fan-Out to Shared Downstream)

.agents/skills/adk-agent-builder/references/state-and-events.md

@@ -4,12 +4,14 @@ Manage shared state across workflow nodes and understand the event system.
 
 ## 📋 Agent Verification Checklist (State & Events)
 Use this checklist when working with state and events:
+
 - [ ] **State Updates**: Did you use `Event(state=...)` for state updates? (Captures delta in event history)
 - [ ] **Parameter Resolution**: Are custom parameters named after keys in `ctx.state`?
 - [ ] **Output Serialization**: Is `event.output` JSON-serializable? (Required for DB session services)
 - [ ] **Web UI Display**: Did you use `Event(message=...)` for output meant for users?
 
 ## 💡 Quick Reference (Resolution Order)
+
 1. **`ctx`**: Workflow `Context` object.
 2. **`node_input`**: Predecessor output.
 3. **Other names**: Looked up from `ctx.state[param_name]`.
@@ -33,9 +35,9 @@ def my_node(ctx: Context, node_input: str) -> str:
   invocation_id = ctx.invocation_id
 
   # Get node metadata
-  node_path = ctx.node_path        # e.g., "MyWorkflow/my_node"
-  triggered_by = ctx.triggered_by  # Name of predecessor node
-  retry_count = ctx.retry_count    # 0 on first attempt
+  node_path = ctx.node_path          # e.g., "MyWorkflow/my_node"
+  run_id = ctx.run_id                # this node-run's identifier
+  attempt = ctx.attempt_count        # 1 on first attempt, ≥1 thereafter
 
   return f"Processed: {value}"
 ```
@@ -57,21 +59,21 @@ def my_node(ctx: Context, node_input: str) -> str:
 
 ### Workflow-Only Properties
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `node_path` | `str` | Full path of current node (e.g., "WorkflowA/node1") |
-| `execution_id` | `str` | Unique ID for this execution |
-| `triggered_by` | `str` | Name of node that triggered current node |
-| `in_nodes` | `frozenset[str]` | Names of all predecessor nodes |
-| `resume_inputs` | `dict[str, Any]` | Inputs for resuming (keyed by interrupt_id) |
-| `retry_count` | `int` | Number of times this node has been retried |
+| Property        | Type             | Description                           |
+| --------------- | ---------------- | ------------------------------------- |
+| `node_path`     | `str`            | Full path of current node (e.g.,      |
+:                 :                  : "WorkflowA/node1")                    :
+| `run_id`        | `str`            | Identifier for this node-run (e.g.,   |
+:                 :                  : `"1"`, `"2"`)                         :
+| `attempt_count` | `int`            | Retry attempt number (1 on first try) |
+| `resume_inputs` | `dict[str, Any]` | Inputs for resuming (keyed by         |
+:                 :                  : interrupt_id)                         :
 
 ### Workflow-Only Methods
 
 | Method | Returns | Description |
 |--------|---------|-------------|
 | `run_node(node, node_input, *, name)` | `Any` | Execute a node dynamically (requires `rerun_on_resume=True`) |
-| `get_next_child_execution_id(name)` | `str` | Generate a deterministic child execution ID |
 
 ## State Management
 
@@ -92,6 +94,7 @@ def node_a(ctx: Context, node_input: str) -> str:
 ```
 
 **Why `Event(state=...)` is preferred:**
+
 - State deltas are persisted in event history as `event.actions.state_delta`
 - Non-resumable HITL can reconstruct state by replaying events
 - Makes state changes explicit and traceable
@@ -120,6 +123,7 @@ def my_node(node_input: str, user_name: str, threshold: float) -> str:
 ```
 
 Resolution order:
+
 1. `ctx` -> Context object
 2. `node_input` -> predecessor output
 3. Other names -> `ctx.state[param_name]` (with auto type conversion)