docs: add unit guides for event.py, request_input.py and update adk-unit-guide skill

boyangsvl · copybara-github · commit 7d74a0a0e2ac · 2026-06-12T14:55:34.000-07:00
- Updated request_input.py unit guide to use function node example and removed field table.
- Updated adk-unit-guide skill:
  - Discourage exhaustive API reference tables in guides.
  - Prefer simple Python functions over extending BaseNode for workflow node samples.
- Removed field reference tables from the event guide.

Co-authored-by: Bo Yang &lt;ybo@google.com&gt;
PiperOrigin-RevId: 931347184
diff --git a/.agents/skills/adk-unit-guide/SKILL.md b/.agents/skills/adk-unit-guide/SKILL.md
@@ -51,6 +51,7 @@ Use the following structure and instructions to create the guide for the code un
 - Show enough of the containing classes to make it clear where the code could be used.
 - Use unit test code as a starting point for the code example, if available.
 - When writing a sample agent, do not set the `model` attribute.
+- For workflow node samples, prefer using a simple Python function rather than extending `BaseNode` to demonstrate the node's logic, unless class extension is explicitly required for the use case.
 
 ## How it works
 
@@ -61,7 +62,8 @@ Use the following structure and instructions to create the guide for the code un
 
 ## Configuration options
 
-- If the code unit has configuration options, document them in a table detailing parameters, types, default values, and descriptions.
+- If the code unit has configuration options (e.g., settings, configuration objects), document them in a table detailing parameters, types, default values, and descriptions.
+- **Do NOT** list references of all attributes or methods of the classes. Exhaustive API references belong in auto-generated reference documentation, not in guides. Guides should focus on how to use the code unit.
 
 ## Advanced applications
 
diff --git a/docs/guides/agents/llm_agent/single_turn.md b/docs/guides/agents/llm_agent/single_turn.md
@@ -0,0 +1,164 @@
+# LlmAgent Single-Turn Mode
+
+This guide explains the behavior of `LlmAgent` in `single_turn` mode, both when
+executed as a workflow node and when defined as a sub-agent in a multi-agent
+hierarchy. It covers default stateless execution, delegation mechanics, and how
+to configure history visibility.
+
+--------------------------------------------------------------------------------
+
+## Introduction
+
+In ADK, `mode="single_turn"` is designed for isolated, stateless tasks where the
+agent only needs to process the immediate input without accumulating or
+referencing prior conversation history.
+
+Depending on how the agent is deployed—either as a step in a `Workflow` or as a
+`sub_agent` of another LLM agent—its behavior and interaction patterns differ.
+
+--------------------------------------------------------------------------------
+
+## 1. Single-Turn Mode as a Workflow Node
+
+When building a `Workflow` graph, any `LlmAgent` added to the graph defaults to
+`mode="single_turn"` (unless explicitly configured otherwise).
+
+### Behavior
+
+-   **Stateless by Default**: The node does not see previous conversation turns
+    in the workflow session. Its history visibility (`include_contents`)
+    automatically defaults to `'none'`.
+-   **Isolated Execution**: Each execution of the node is independent.
+
+### Example
+
+```python
+from google.adk.agents import LlmAgent
+from google.adk.workflow import Workflow, build_node
+
+# Defaults to mode="single_turn" when run as a node
+writer_agent = LlmAgent(
+    name="writer",
+    instruction="Write a short story about the input topic."
+)
+
+writer_node = build_node(writer_agent)
+
+wf = Workflow(
+    name="story_generator",
+    edges=[
+        ("START", writer_node),
+        (writer_node, "END")
+    ]
+)
+```
+
+--------------------------------------------------------------------------------
+
+## 2. Single-Turn Mode as a Sub-Agent
+
+You can define hierarchical agent structures by assigning agents to the
+`sub_agents` list of a parent `LlmAgent`.
+
+### Behavior
+
+-   **Exposed as a Tool**: A `single_turn` sub-agent is **not** a transfer
+    target. The parent agent cannot hand over control of the conversation to it.
+    Instead, the framework automatically exposes the sub-agent to the parent as
+    a **Tool** (function).
+-   **Functional Delegation**: The parent agent calls the sub-agent like a
+    function, passing arguments. The sub-agent executes, returns its output to
+    the parent, and the parent continues the conversation.
+-   **Isolated Sub-Branch**: When the parent calls the sub-agent tool, the
+    framework executes the sub-agent in an isolated sub-branch (derived from the
+    parent's branch, e.g., `parent_branch.sub_agent@run_id`).
+-   **Stateless by Default**: Like the workflow node, a `single_turn` sub-agent
+    defaults to `include_contents="none"` and only sees the inputs passed to it
+    in the tool call.
+
+### Example
+
+```python
+from google.adk.agents import LlmAgent
+
+# Define a specialized single-turn sub-agent
+translator_agent = LlmAgent(
+    name="translator",
+    instruction="Translate the input text to Spanish.",
+    mode="single_turn"  # Must be explicit if not auto-wrapped in workflow
+)
+
+# Define the parent agent and assign the sub-agent
+bilingual_writer = LlmAgent(
+    name="bilingual_writer",
+    instruction="Write a poem about the topic, then use the translator tool to translate it.",
+    sub_agents=[translator_agent] # Exposes 'translator' as a tool to bilingual_writer
+)
+```
+
+--------------------------------------------------------------------------------
+
+## How Context Isolation Works
+
+ADK manages history visibility using **branches** and the `include_contents`
+configuration:
+
+1.  **Branch Hierarchy**: When a sub-agent runs, it executes in a sub-branch
+    (e.g., `main.translator@1`).
+    -   A sub-branch is allowed to read events from its parent branch (one-way
+        visibility).
+    -   The parent branch cannot read events from the sub-branch (protecting the
+        parent from sub-agent internal reasoning chatter).
+2.  **History Filtering**:
+    -   **`include_contents="none"`** (Default): The agent bypasses history
+        loading entirely. It only sees the immediate input (the workflow node
+        input or the tool call arguments).
+    -   **`include_contents="default"`**: The agent loads conversation history.
+        Because of the branch hierarchy, a sub-agent with this setting can see
+        the parent agent's conversation history leading up to the tool call.
+
+--------------------------------------------------------------------------------
+
+## Configuration Options
+
+Parameter          | Type                                     | Default                               | Description
+:----------------- | :--------------------------------------- | :------------------------------------ | :----------
+`mode`             | `Literal['single_turn', 'task', 'chat']` | `'single_turn'` (when run as node)    | The execution mode. `single_turn` isolates execution; `task` supports delegation; `chat` preserves full history.
+`include_contents` | `Literal['default', 'none']`             | `'none'` (for `single_turn` if unset) | Controls history visibility. For `single_turn` mode, it defaults to `'none'` (stateless), but can be explicitly set to `'default'` to make the agent context-aware.
+
+--------------------------------------------------------------------------------
+
+## Advanced Applications: Context-Aware Execution
+
+If you want a single-turn agent (node or sub-agent) to have access to the
+conversation history, you must explicitly set `include_contents="default"`.
+
+### Context-Aware Sub-Agent Example
+
+In this setup, the `verifier` sub-agent needs to see the history of the
+conversation to verify the parent's draft against previous user constraints:
+
+```python
+verifier_agent = LlmAgent(
+    name="verifier",
+    instruction="Verify that the draft meets all constraints discussed in the chat.",
+    mode="single_turn",
+    include_contents="default"  # Allows the sub-agent to see the parent's conversation history
+)
+
+editor_agent = LlmAgent(
+    name="editor",
+    instruction="Discuss the draft with the user and use verifier to check constraints.",
+    sub_agents=[verifier_agent]
+)
+```
+
+--------------------------------------------------------------------------------
+
+## Limitations
+
+-   **Difference from Standalone Behavior**: A standalone `LlmAgent` defaults to
+    `include_contents="default"`. When used in a workflow or as a sub-agent, it
+    defaults to `include_contents="none"`.
+-   **No Direct Transfer**: You cannot use `transfer_to_agent` to target a
+    `single_turn` agent. They must be invoked via tool calls.
diff --git a/docs/guides/events/event/index.md b/docs/guides/events/event/index.md
@@ -0,0 +1,112 @@
+# Event and NodeInfo
+
+The `event.py` file defines the `Event` and `NodeInfo` classes, which are the fundamental data structures used in the Agent Development Kit (ADK) to represent interactions, actions, and metadata within a workflow.
+
+## Introduction
+
+In ADK, conversations and workflow executions are modeled as a sequence of events. The `Event` class represents a single unit of this sequence, capturing:
+-   **Content:** Messages exchanged between users and agents (text, function calls, function responses).
+-   **Actions:** Side-effects or instructions, such as state updates, routing decisions, agent transfers, and UI rendering requests.
+-   **Metadata:** Information about who generated the event, when, and from which part of the workflow.
+
+`NodeInfo` specifically carries metadata about the workflow node that generated the event, enabling tracking of execution paths and run IDs.
+
+Key classes depending on `Event` include `Session` (which stores the event history) and `Workflow` / `NodeRunner` (which use events for execution flow and state management).
+
+## Get started
+
+Here is how to create and use `Event` objects.
+
+### Basic Message Event
+
+You can create a simple event with a text message:
+
+```python
+from google.adk.events.event import Event
+
+# Create a user message event
+user_event = Event(author="user", message="Hello, agent!")
+
+# The 'message' argument is a convenience alias for 'content'
+print(user_event.message.parts[0].text)  # Output: Hello, agent!
+```
+
+### Event with State Delta
+
+Events can carry state updates that should be applied to the session state:
+
+```python
+from google.adk.events.event import Event
+
+# Create an agent event that updates the state
+state_event = Event(
+    author="my_agent",
+    message="I've updated the user preference.",
+    state={"user_theme": "dark"}
+)
+
+print(state_event.actions.state_delta)  # Output: {'user_theme': 'dark'}
+```
+
+### Event with Node Metadata
+
+When events are generated within a workflow, they usually include node information.
+
+> [!NOTE]
+> `NodeInfo` is automatically populated by the ADK framework. While you can access these fields, you should not manually construct or modify `node_info` in your application logic.
+
+```python
+from google.adk.events.event import Event, NodeInfo
+
+node_event = Event(
+    author="agent_node",
+    node_path="parent_workflow/child_node@run-123",
+    output="some_result"
+)
+
+print(node_event.node_info.path)  # Output: parent_workflow/child_node@run-123
+print(node_event.node_info.name)  # Output: child_node
+print(node_event.node_info.run_id)  # Output: run-123
+```
+
+## How it works
+
+`Event` inherits from `LlmResponse`, which allows it to directly wrap responses from Gemini models, including content, grounding metadata, and token usage.
+
+### Convenience Kwargs Routing
+
+The `Event` constructor accepts several convenience arguments that are automatically routed to nested Pydantic models:
+-   `message`: Automatically converted to `types.Content` and set to the `content` field.
+-   `state`: Mapped to `actions.state_delta`.
+-   `route`: Mapped to `actions.route`.
+-   `node_path`: Mapped to `node_info.path`.
+
+This routing is handled by the `@model_validator(mode='before')` method `_accept_convenience_kwargs`.
+
+### Serialization
+
+Both `Event` and `NodeInfo` are Pydantic models configured to use camelCase aliases for serialization. When sending events over the wire or saving them, use `model_dump(by_alias=True)` to ensure compatibility with ADK APIs.
+
+### Lifecycle
+
+Every event is assigned a unique UUID `id` and a `timestamp` upon initialization if they are not explicitly provided.
+
+## Advanced applications
+
+### Workflow Routing
+
+Workflows use `Event` to communicate routing decisions. By setting `route` (which maps to `actions.route`), a node can signal to the workflow engine which edge to follow next.
+
+```python
+routing_event = Event(author="router_node", route="success_path")
+```
+
+### Context Isolation
+
+The `isolation_scope` field is used by the Task API to isolate conversations of delegated agents. Events with a specific `isolation_scope` (e.g., `"task:fc-987"`) will only be visible to agents running within that same scope, preventing them from seeing the main conversation history.
+
+## Limitations
+
+-   **NodeInfo Assignment:** The `node_info` field (and the `node_path` constructor argument) is managed and assigned by the ADK framework during workflow execution. Developers should not manually set or modify `node_info` in production code.
+-   **Internal Fields:** The `isolation_scope` field is an internal implementation detail. External developers should not rely on it or modify it directly.
+-   **Mutual Exclusion:** You cannot specify both `message` and `content` in the `Event` constructor; doing so will raise a `ValueError`.
diff --git a/docs/guides/events/request_input/index.md b/docs/guides/events/request_input/index.md
@@ -0,0 +1,53 @@
+# RequestInput
+
+The `RequestInput` class represents a structured request for input from the user, typically used to trigger an interrupt in a workflow (Human-in-the-loop).
+
+## Introduction
+
+In ADK, workflows can be configured to pause and wait for user intervention. The `RequestInput` event is the data structure that represents this interrupt request. It is typically yielded by a workflow node and translated into an `Event` with a special function call (`adk_request_input`) that the client application handles.
+
+Key classes depending on `RequestInput` include `Workflow` (which pauses execution when encountering this event) and various HITL helper utilities (like `create_request_input_event` and `create_request_input_response`) that wrap it. It solves the developer problem of pausing a workflow and gathering structured feedback from a user before resuming.
+
+## Get started
+
+To request input from a user within a workflow, you yield a `RequestInput` object from a node function.
+
+Here is a basic example of a node that requests user details:
+
+```python
+from typing import Any, AsyncGenerator
+from google.adk import Context
+from google.adk.events.request_input import RequestInput
+from pydantic import BaseModel
+
+class UserDetails(BaseModel):
+  name: str
+  age: int
+
+async def request_input_node(
+    ctx: Context,
+    node_input: Any,
+) -> AsyncGenerator[Any, None]:
+  """A simple node that requests input from the user."""
+  # Yield RequestInput to pause and request user details.
+  # The response must conform to UserDetails schema.
+  yield RequestInput(
+      interrupt_id="get-user-details-1",
+      message="Please provide user details.",
+      response_schema=UserDetails,
+  )
+```
+
+## How it works
+
+When a node yields a `RequestInput` object, the following process occurs:
+
+1. **Workflow Pause**: The workflow engine detects the `RequestInput` event and pauses the execution of the workflow.
+2. **Event Translation**: The `RequestInput` is wrapped into an `Event` containing a mock function call named `adk_request_input`. The fields `message`, `payload`, and `response_schema` are passed as arguments to this function call.
+3. **Client Interaction**: The client application receiving this event displays the message to the user (optionally validating the input against the provided `response_schema`).
+4. **Resuming execution**: To resume the workflow, the client sends back a `FunctionResponse` matching the `interrupt_id` (used as the function call `id`) and named `adk_request_input`. The response payload is placed inside the `response` dictionary.
+5. **Resume**: The workflow engine delivers this response back to the node, allowing it to continue execution.
+
+## Limitations
+
+- **Client-Side Validation**: When using `response_schema`, the client application is responsible for validating that the user's input conforms to the schema before sending it back to resume the workflow. ADK handles parsing on resume, but client-side validation is recommended for a better user experience.
